trip-methods: Function to handle animal track data, organized as `trip` objects

Description

Create an object of class trip, extending the basic functionality of SpatialPointsDataFrame-class by specifying the data columns that define the "TimeOrdered" quality of the records.

Usage

trip(obj, TORnames, correct_all = TRUE)
trip(obj) <- value
# S4 method for trip
split(x, f, drop = FALSE, ...)
# S4 method for trip,ANY,ANY,ANY
[(x, i, j, ..., drop = TRUE)

Arguments

obj

A data frame, a grouped data frame or a SpatialPointsDataFrame-class containing at least two columns with the DateTime and ID data as per TORnames. See Details.

TORnames

Either a TimeOrderedRecords object, or a 2-element character vector specifying the DateTime and ID column of obj

correct_all

logical value, if TRUE the input data is corrected for common problems

value

A 4-element character vector specifying the X, Y, DateTime coordinates and ID of obj.

trip object

grouping vector as per split()

drop

unused but necessary for method consistency

i, j, …

indices specifying elements to extract

Value

A trip object, with the usual slots of a SpatialPointsDataFrame-class and the added TimeOrderedRecords. For the most part this can be treated as a data.frame with Spatial coordinates.

Methods

Most of the methods available are by virtue of the sp package. Some, such as split.data.frame have been added to SPDF so that trip has the same functionality.

trip: signature(obj="SpatialPointsDataFrame", TORnames="ANY")
trip: signature(obj="SpatialPointsDataFrame", TORnames="TimeOrderedRecords")
trip: signature(obj="ANY", TORnames="TimeOrderedRecords"): create a trip object from a data frame.
trip: signature(obj="trip", TORnames="ANY"): (Re)-create a trip object using a character vector for TORnames.
trip: signature(obj="trip", TORnames="TimeOrderedRecords"): (re)-create a trip object using a TimeOrderedRecords object.

Details

The original form of trip() required very strict input as a 'SpatialPointsDataFrame' and specifying which were the time and ID columns, but the input can be more flexible. If the object is a grouped data frame ('dplyr-style') then the (first) grouping is assumed to define individual trips and that columns 1, 2, 3 are the x-, y-, time-coordinates in that order. It can also be a trip object for redefining TORnames.

The trip() function can ingest track_xyt, telemetry, SpatialPointsDataFrame, sf, trackeRdata, grouped_df, data.frame, tbl_df, mousetrap, and in some cases lists of those objects. Please get in touch if you think something that should work does not.

Track data often contains problems, with missing values in location or time, times out of order or with duplicated times. The correct_all argument is set to TRUE by default and will report any inconsistencies. Data really should be checked first rather than relying on this auto-cleanup. The following problems are common:

duplicated records (every column with the same value in another row)
duplicated date-time values
missing date-time values, or missing x or y coordinates
records out of order within trip ID

For some data types there's no formal structure, but a simple convention such as a set of names in a data frame. For example, the VTrack package has AATAMS1 which may be turned into a trip with trip(AATAMS1 %>% dplyr::select(longitude, latitude, timestamp, tag.ID, everything()) In time we can add support for all kinds of variants, detected by the names and contents.

See Chapter 2 of the trip thesis for more details.

Examples

Run this code

# NOT RUN {

d <- data.frame(x=1:10, y=rnorm(10), tms=Sys.time() + 1:10, id=gl(2, 5))

## the simplest way to create a trip is by order of columns

trip(d)

## or a grouped data frame can be used, the grouping is used as the trip ID
## library(dplyr)
## # use everything() to keep all other columns
## d %>% group_by(id) %>% select(x, y, tms, everything())

sp::coordinates(d) <- ~x+y
## this avoids complaints later, but these are not real track data (!)
sp::proj4string(d) <- sp::CRS("+proj=laea +ellps=sphere", doCheckCRSArgs = FALSE)
(tr <- trip(d, c("tms", "id")))

 ## real world data in CSV
mi_dat <- read.csv(system.file("extdata/MI_albatross_sub10.csv", package = "trip"),
            stringsAsFactors = FALSE)
## installed subset because the data is quite dense
## mi_dat <- mi_dat[seq(1, nrow(mi_dat), by = 10), ]
mi_dat$gmt <- as.POSIXct(mi_dat$gmt, tz = "UTC")
mi_dat$sp_id <-  sprintf("%s%s_%s_%s", mi_dat$species,
         substr(mi_dat$breeding_status, 1, 1), mi_dat$band, mi_dat$tag_ID)
sp::coordinates(mi_dat) <- c("lon", "lat")
## there are many warnings, but the outcome is fine
## (sp_id == 'WAi_14030938_2123' has < 3 locations as does LMi_12143650_14257)
mi_dat <- trip(mi_dat, c("gmt", "sp_id") )
plot(mi_dat, pch = ".")
#lines(mi_dat)  ## ugly

mi_dat_polar <- reproj(mi_dat, "+proj=stere +lat_0=-90 +lon_0=154 +datum=WGS84")
plot(mi_dat_polar, pch = ".")
lines(mi_dat_polar)


# }

Run the code above in your browser using DataLab

Last chance! 50% off unlimited learning