format_data: Coerce input data into expected 'aniMotum' format

In ianjonsen/foieGras: Fit Continuous-Time State-Space and Latent Variable Models for Quality Control of Argos Satellite (and Other) Telemetry Data and for Estimating Changes in Animal Movement

Coerce input data into expected aniMotum format

Description

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.

Usage

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)
d <- format_data(sese2_n, date = "time", coord = c("longitude","latitude"), 
tz = "America/Halifax")
fit <- fit_ssm(d, model = "crw", time.step = 24)

## called automatically within fit_ssm()
fit <- fit_ssm(sese2_n, date = "time", coord = c("longitude", "latitude"), 
tz = "America/Halifax", model = "crw", time.step = 24)

ianjonsen/foieGras documentation built on Jan. 17, 2025, 11:15 p.m.