format data by mapping supplied variable names to those expected by fit_ssm(), and ensuring variables are put into the expected order. Can be run manually by user as a data pre-processing step prior to calling fit_ssm() or can be called automatically by fit_ssm(). In the latter case, any custom variable names must be declared as arguments to fit_ssm(); see examples, below.

format_data(
  x,
  id = "id",
  date = "date",
  lc = "lc",
  coord = c("lon", "lat"),
  epar = c("smaj", "smin", "eor"),
  sderr = c("x.sd", "y.sd"),
  tz = "UTC"
)

Arguments

x

input data

id

the name (as a quoted character string) of id variable: a unique identifier for individual (animal) track data sets.

date

the name (as a quoted character string)of the date/time variable: date and time (as YYYY-MM-DD HH:MM:SS) of each observation.

lc

the name (as a quoted character string) of the location quality class variable: Argos location quality class (values in the set: 3,2,1,0,"A","B","Z"). Can also include "G" for GPS data and/or "GL" for light-level geolocation (GLS) and other data types.

coord

the names (as quoted character strings) of the location coordinate variables: defaults are c("lon","lat"), but could also be c("x","y") for planar coordinates; or if input data is an sf object then "geometry". If input data is an sf object then coord is set to "geometry" by default.

epar

the names (as quoted character strings) of the Argos error ellipse parameters: defaults are "smaj" (ellipse semi-major axis), "smin" (ellipse semi-minor axis), and "eor" (ellipse orientation). Ignored if these variables are missing from the input data.

sderr

the names (as quoted character strings) of provided standard errors for lon,lat or x,y: default names are x.sd, y.sd. Typically, these are only provided for generic location data such as processed light-level geolocations, or high-resolution acoustic detections. The argument is ignored if these variables are missing from the input data.

tz

the timezone the applies to the data/time variable if they are not in tz = 'UTC'. A list of valid timezone names can be viewed via OlsonNames()

Value

a data.frame or sf-tibble of input data in expected aniMotum format. Additional columns required by fit_ssm(), if missing, will be added to the formatted tibble: smaj, smin, eor, x.sd, and y.sd.

Examples

## as a data pre-processing step
data(sese2_n)
head(sese2_n, 5)
#> # A tibble: 5 × 5
#>   longitude latitude time                lc    id       
#>       <dbl>    <dbl> <chr>               <fct> <chr>    
#> 1      72.5    -50.2 2009-02-01 17:50:46 A     ct36-E-09
#> 2      73.0    -50.4 2009-02-02 03:30:26 A     ct36-E-09
#> 3      73.8    -50.8 2009-02-02 17:50:48 B     ct36-E-09
#> 4      74.6    -51.2 2009-02-03 07:39:08 A     ct36-E-09
#> 5      74.9    -51.4 2009-02-03 15:29:59 A     ct36-E-09
d <- format_data(sese2_n, date = "time", coord = c("longitude","latitude"), 
tz = "America/Halifax")
fit <- fit_ssm(d, model = "crw", time.step = 24)
#> fitting crw SSM to 2 tracks...
#> 
 pars:   1 1 0 0 -1.83815 0      
 pars:   0.58822 0.47049 -0.39448 -0.58757 -2.05502 0.04656      
 pars:   0.24142 -0.08857 0.17073 -0.22123 -2.16295 0.36573      
 pars:   -0.25485 -0.61181 -0.39281 -0.55381 -2.30537 0.5431      
 pars:   -0.95996 -1.05417 0.05433 -0.3315 -2.16562 0.73866      
 pars:   -1.52441 -1.28179 -0.24338 -0.09273 -1.48444 0.87986      
 pars:   -1.15677 -1.14532 -0.15766 -0.32371 -1.9606 0.78088      
 pars:   -1.2591 -1.23906 -0.00914 -0.54176 -1.74795 0.73881      
 pars:   -1.28632 -1.23923 -0.06489 -0.37148 -1.72418 0.71526      
 pars:   -1.37476 -1.3354 -0.03139 -0.43287 -1.62519 0.66829      
 pars:   -1.43518 -1.36913 -0.07069 -0.36322 -1.49214 0.59704      
 pars:   -1.50537 -1.39061 -0.03715 -0.40209 -1.33302 0.57215      
 pars:   -1.55804 -1.48577 -0.11287 -0.42946 -1.21264 0.53812      
 pars:   -1.53464 -1.42687 -0.0852 -0.38865 -1.29386 0.558      
 pars:   -1.54606 -1.47357 -0.04788 -0.37299 -1.26878 0.5154      
 pars:   -1.54606 -1.47357 -0.04788 -0.37299 -1.26878 0.5154      
#> 
 pars:   1 1 0 0 -1.35869 0      
 pars:   0.26969 0.48413 0.13062 0.37138 -1.50855 0.15196      
 pars:   -1.92124 -1.06346 0.52247 1.48551 -1.95813 0.60783      
 pars:   -3.94772 -2.40713 -0.47652 -1.45121 -2.46454 1.06517      
 pars:   -2.05317 -1.14577 0.37728 1.06076 -1.99643 0.6397      
 pars:   -2.24177 -1.28178 0.31364 0.65504 -2.04218 0.69747      
 pars:   -2.61685 -1.51707 0.42349 0.63143 -2.07707 0.83261      
 pars:   -3.26866 -1.92596 0.61438 0.59039 -2.13769 1.06746      
 pars:   -4.1194 -2.03377 -0.24849 1.01778 -1.97888 1.21674      
 pars:   -3.31866 -1.88614 0.45421 0.68271 -2.10153 1.06158      
 pars:   -3.44366 -1.81523 0.38836 0.67524 -1.98086 1.06261      
 pars:   -3.53173 -1.85375 0.53088 0.65662 -1.88523 1.03885      
 pars:   -3.63928 -1.97209 0.44911 0.66534 -1.80171 1.02159      
 pars:   -3.67057 -1.9039 0.47921 0.72471 -1.6359 0.97625      
 pars:   -3.68464 -1.93999 0.44261 0.64383 -1.6141 0.983      
 pars:   -3.68464 -1.93999 0.44261 0.64383 -1.6141 0.983      

## called automatically within fit_ssm()
fit <- fit_ssm(sese2_n, date = "time", coord = c("longitude", "latitude"), 
tz = "America/Halifax", model = "crw", time.step = 24)
#> fitting crw SSM to 2 tracks...
#> 
 pars:   1 1 0 0 -1.83815 0      
 pars:   0.58822 0.47049 -0.39448 -0.58757 -2.05502 0.04656      
 pars:   0.24142 -0.08857 0.17073 -0.22123 -2.16295 0.36573      
 pars:   -0.25485 -0.61181 -0.39281 -0.55381 -2.30537 0.5431      
 pars:   -0.95996 -1.05417 0.05433 -0.3315 -2.16562 0.73866      
 pars:   -1.52441 -1.28179 -0.24338 -0.09273 -1.48444 0.87986      
 pars:   -1.15677 -1.14532 -0.15766 -0.32371 -1.9606 0.78088      
 pars:   -1.2591 -1.23906 -0.00914 -0.54176 -1.74795 0.73881      
 pars:   -1.28632 -1.23923 -0.06489 -0.37148 -1.72418 0.71526      
 pars:   -1.37476 -1.3354 -0.03139 -0.43287 -1.62519 0.66829      
 pars:   -1.43518 -1.36913 -0.07069 -0.36322 -1.49214 0.59704      
 pars:   -1.50537 -1.39061 -0.03715 -0.40209 -1.33302 0.57215      
 pars:   -1.55804 -1.48577 -0.11287 -0.42946 -1.21264 0.53812      
 pars:   -1.53464 -1.42687 -0.0852 -0.38865 -1.29386 0.558      
 pars:   -1.54606 -1.47357 -0.04788 -0.37299 -1.26878 0.5154      
 pars:   -1.54606 -1.47357 -0.04788 -0.37299 -1.26878 0.5154      
#> 
 pars:   1 1 0 0 -1.35869 0      
 pars:   0.26969 0.48413 0.13062 0.37138 -1.50855 0.15196      
 pars:   -1.92124 -1.06346 0.52247 1.48551 -1.95813 0.60783      
 pars:   -3.94772 -2.40713 -0.47652 -1.45121 -2.46454 1.06517      
 pars:   -2.05317 -1.14577 0.37728 1.06076 -1.99643 0.6397      
 pars:   -2.24177 -1.28178 0.31364 0.65504 -2.04218 0.69747      
 pars:   -2.61685 -1.51707 0.42349 0.63143 -2.07707 0.83261      
 pars:   -3.26866 -1.92596 0.61438 0.59039 -2.13769 1.06746      
 pars:   -4.1194 -2.03377 -0.24849 1.01778 -1.97888 1.21674      
 pars:   -3.31866 -1.88614 0.45421 0.68271 -2.10153 1.06158      
 pars:   -3.44366 -1.81523 0.38836 0.67524 -1.98086 1.06261      
 pars:   -3.53173 -1.85375 0.53088 0.65662 -1.88523 1.03885      
 pars:   -3.63928 -1.97209 0.44911 0.66534 -1.80171 1.02159      
 pars:   -3.67057 -1.9039 0.47921 0.72471 -1.6359 0.97625      
 pars:   -3.68464 -1.93999 0.44261 0.64383 -1.6141 0.983      
 pars:   -3.68464 -1.93999 0.44261 0.64383 -1.6141 0.983