as.telemetry: Import, coerce, summarize, and combine MoveBank data

In ctmm: Continuous-Time Movement Modeling

Import, coerce, summarize, and combine MoveBank data

Description

Functions to import MoveBank csv files, data.frame, and Move objects, coerce them into telemetry objects, summarize them, and combine data from multiple tracking devices.

Usage

as.telemetry(object,timeformat="auto",timezone="UTC",projection=NULL,datum="WGS84",
             dt.hot=NA,timeout=Inf,na.rm="row",mark.rm=FALSE,keep=FALSE,drop=TRUE,...)

## S3 method for class 'character'
as.telemetry(object,timeformat="auto",timezone="UTC",projection=NULL,datum="WGS84",
             dt.hot=NA,timeout=Inf,na.rm="row",mark.rm=FALSE,keep=FALSE,drop=TRUE,...)

## S3 method for class 'data.frame'
as.telemetry(object,timeformat="auto",timezone="UTC",projection=NULL,datum="WGS84",
             dt.hot=NA,timeout=Inf,na.rm="row",mark.rm=FALSE,keep=FALSE,drop=TRUE,...)

## S3 method for class 'Move'
as.telemetry(object,timeformat="auto",timezone="UTC",projection=NULL,datum="WGS84",
             dt.hot=NA,timeout=Inf,na.rm="row",mark.rm=FALSE,keep=FALSE,drop=TRUE,...)

## S3 method for class 'telemetry'
summary(object,...)

head(x,...)

## S3 method for class 'telemetry'
head(x,n=6L,...)

tail(x,...)

## S3 method for class 'telemetry'
tail(x,n=6L,...)

tbind(...)

Arguments

object	A MoveBank CSV filename, MoveBank data.frame object, or Move object to coerce, or a telemetry object to summarize.
timeformat	Format argument for strptime, corresponding to the input data. Alternatively timeformat="auto" will attempt to infer the timestamp format with parse_date.
timezone	Timezone argument for strptime, corresponding to the input data.
projection	Optional PROJ projection argument for the output telemetry object.
datum	Optional argument to specify the input longitude-latitude or UTM datum. The default is WGS84.
dt.hot	Time-interval threshold at which GPS location fixes can be considered as “hot” and location estimate precisions may be smaller (regardless of DOP value) for assigning "hot" and "cold" location classes.
timeout	GPS location fix timeout value (seconds) for assigning a "timed-out" location class.

na.rm	If some values are NA in the data frame, are the rows (times) deleted or are the columns (data types) deleted.
mark.rm	Delete Movebank manually marked outliers. Also see outlie.
keep	Retain additonal columns after coercion. keep=TRUE retains all columns, while individual columns to retain can be specified by name.
drop	Only return a telemetry object for one individual if TRUE. Always return a list of telemetry objects if FALSE.
...	telemetry objects or a list of such objects, for tbind(). Optional arguments to be fed to fread or read.csv, in the case of compressed files, for as.telemetry().
x	telemetry object.
n	Number of rows to return, if positive, or number of rows to omit, if negative.

Details

For data that have not been corralled throuh Movebank, timestamps either need to be provided in a POSIX format (see the output of Sys.time()) or supplied with a timeformat argument for interpretation (see strptime). Alternatively, you can try your luck with timeformat="auto", and parse_date will attempt to infer the format.

If no projection argument is specified, a two-point equidistant projection is calculated that should be good for most range resident and migratory species. Global migrations that are not along one geodesic (locally straight line) will probably suffer distortion.

as.telemetry() assumes Movebank naming conventions. Sufficient MoveBank columns include individual.local.identifier (or tag.local.identifier), timestamp, location.long and location.lat, while the optional Movebank columns include (e-obs) eobs.horizontal.accuracy.estimate, (Telonics) GPS.Horizontal.Error, GPS.HDOP, (Argos) Argos.orientation, Argos.semi.minor and Argos.semi.major or Argos.location.class, etc.. To have all columns detected and not overwrite eachother's information, it is best to have only one tracking device model per file imported. Multiple deployments on a single individual can be merged afterwards, using tbind().

Value

as.telemetry returns a single telemetry object or list of telemetry objects if multiple animals are identified.

as.telemetry will always report the smallest sampling interval, as a message, and the number repeating timestamps, as a warning. Tiny sampling intervals (and repeating timestamps) can sometimes result from misformated timestamps or an incorrect timeformat argument. However, even if geniune, they can necessitate data cleaning (outlie) or location-error modeling (vignette('error')).

Note

Prior to v1.1.1, datum was required to be a full PROJ string, but starting with v1.1.1 datum is just taken to be the PROJ datum argument.

Author(s)

C. H. Fleming, X. Dong, B. Kranstauber, G. Péron, and K. Safi.

See Also

plot.telemetry, SpatialPoints.telemetry, uere.

ctmm documentation built on Sept. 24, 2023, 1:06 a.m.