Package 'trackdf' reference manual

Title:	Data Frame Class for Tracking Data
Description:	Data frame class for storing collective movement data (e.g. fish schools, ungulate herds, baboon troops) collected from GPS trackers or computer vision tracking software.
Authors:	Simon Garnier [aut, cre]
Maintainer:	Simon Garnier <[email protected]>
License:	GPL-3
Version:	0.3.2
Built:	2024-10-16 03:47:45 UTC
Source:	https://github.com/swarm-lab/trackdf

Compute The Mode(s) Of A Discrete Distribution

Description

This is an internal utility function to compute the mode(s) of a discrete distribution.

Usage

.Mode(x, na.rm = TRUE)
.Mode(x, na.rm = TRUE)

Arguments

`x`	A vector or matrix of discrete values.
`na.rm`	A logical value indicating whether NA values should be stripped before the computation proceeds (default: TRUE).

Value

A vector of values corresponding to the mode(s) of x.

Author(s)

Simon Garnier, [email protected]

Maintain Class After Modification

Description

Copy class and attributes from the original version of an object to a modified version.

Usage

.reclass(x, result)
.reclass(x, result)

Arguments

`x`	The original object, which has a class/attributes to copy
`result`	The modified object, which is/might be missing the class/attributes.

Value

result, now with class/attributes restored.

Author(s)

Simon Garnier, [email protected]

Extract or Replace Parts of a Track Table

Description

Accessing columns, rows, or cells via $, [[, or [ is mostly similar to regular data frames. However, the behavior is sometimes different for track tables based on tibble and data.table. For more info, refer to tibble's and data.table's subsetting documentation.

Usage

## S3 method for class 'track'
x[...]

## S3 replacement method for class 'track'
x[...] <- value
## S3 method for class 'track'
x[...]

## S3 replacement method for class 'track'
x[...] <- value

Arguments

`x`	A track table.
`...`	Other parameters to be passed to the extracting/subsetting functions of `data.frame`, `tibble`, and `data.table`.
`value`	A suitable replacement value: it will be repeated a whole number of times if necessary and it may be coerced: see the 'Coercion' section in `data.frame`. If 'NULL', deletes the column if a single column is selected.

Value

A subset of the track table is [ is called, or a modified version of the track table if [<- is called.

Author(s)

Simon Garnier, [email protected]

Examples

data(short_tracks)

short_tracks[1]
short_tracks[1, ]
short_tracks[1, 1]
short_tracks$id[short_tracks$id == "1"] <- "0"
short_tracks[short_tracks[, 1] == "0", 1] <- "1"

data(short_tracks)

short_tracks[1]
short_tracks[1, ]
short_tracks[1, 1]
short_tracks$id[short_tracks$id == "1"] <- "0"
short_tracks[short_tracks[, 1] == "0", 1] <- "1"

Bind Multiple Track Tables by Row

Description

bind_tracks uses data.table::rbindlist to combine track tables by rows, but makes sure that you cannot bind together two tables with different projections or time zones, that the projection attribute is inherited by the resulting track table, and that track tables based on different table classes are coerced to the same table class.

Usage

bind_tracks(...)
bind_tracks(...)

Arguments

...

A list containing track table objects, or the names of track table objects separated by commas. The track tables must have the same projection and time zone.

Value

A track table.

Author(s)

Simon Garnier, [email protected]

Examples

data(short_tracks)

bind_tracks(short_tracks, short_tracks)
bind_tracks(list(short_tracks, short_tracks))

data(short_tracks)

bind_tracks(short_tracks, short_tracks)
bind_tracks(list(short_tracks, short_tracks))

Convert a Track Table to/from Other Formats

Description

The following methods will convert track tables to and from other common formats used for processing tracking and spatial data.

Usage

as_track(x, table = "df", ...)

## S3 method for class 'MoveStack'
as_track(x, table = "df", ...)

## S3 method for class 'Move'
as_track(x, table = "df", ...)

as_move(x, ...)

## S3 method for class 'track'
as_move(x, ...)

## S3 method for class 'SpatialPointsDataFrame'
as_track(x, table = "df", ...)

as_sp(x, ...)

## S3 method for class 'track'
as_sp(x, ...)

## S3 method for class 'ltraj'
as_track(x, table = "df", ...)

as_ltraj(x, ...)

## S3 method for class 'track'
as_ltraj(x, ...)

## S3 method for class 'telemetry'
as_track(x, table = "df", ...)

## S3 method for class 'list'
as_track(x, table = "df", ...)

as_telemetry(x, ...)

## S3 method for class 'track'
as_telemetry(x, ...)

## S3 method for class 'moveData'
as_track(x, table = "df", type = c("LL", "UTM"), ...)

as_moveHMM(x, ...)

## S3 method for class 'track'
as_moveHMM(x, ...)
as_track(x, table = "df", ...)

## S3 method for class 'MoveStack'
as_track(x, table = "df", ...)

## S3 method for class 'Move'
as_track(x, table = "df", ...)

as_move(x, ...)

## S3 method for class 'track'
as_move(x, ...)

## S3 method for class 'SpatialPointsDataFrame'
as_track(x, table = "df", ...)

as_sp(x, ...)

## S3 method for class 'track'
as_sp(x, ...)

## S3 method for class 'ltraj'
as_track(x, table = "df", ...)

as_ltraj(x, ...)

## S3 method for class 'track'
as_ltraj(x, ...)

## S3 method for class 'telemetry'
as_track(x, table = "df", ...)

## S3 method for class 'list'
as_track(x, table = "df", ...)

as_telemetry(x, ...)

## S3 method for class 'track'
as_telemetry(x, ...)

## S3 method for class 'moveData'
as_track(x, table = "df", type = c("LL", "UTM"), ...)

as_moveHMM(x, ...)

## S3 method for class 'track'
as_moveHMM(x, ...)

Arguments

`x`	An object to convert.
`table`	A string indicating the class of the table on which the track table should be built. It can be a `data.frame` ("df", the default), a `tibble` ("tbl"), or a `data.table` ("dt").
`...`	Other parameters to be passed to: `track_df`, `track_tbl` or `track_dt` if `as_track` is used. `moveVis::df2move` if `as_move` is used. `sp::SpatialPointsDataFrame` if `as_sp` is used. `adehabitatLT::as.ltraj` if `as_ltraj` is used. `ctmm::as.telemetry` if `as_telemetry` is used. `moveHMM::prepData` if `as_moveHMM` is used.
`type`	For converting `moveHMM::moveData` to track table only, a character string indicating the type of coordinates stored in the `moveHMM::moveData` object: "LL" if longitude/latitude (default), "UTM" if easting/northing.

Value

The coordinates converted in the chosen format.

Author(s)

Simon Garnier, [email protected]

Examples

## Not run: 
data(short_tracks)

if (requireNamespace("moveVis", quietly = TRUE)) {
  mv <- as_move(short_tracks)
  as_track(mv)
}

if (requireNamespace("sp", quietly = TRUE)) {
  sp <- as_sp(short_tracks)
  as_track(sp)
}

if (requireNamespace("adehabitatLT", quietly = TRUE)) {
  lt <- as_ltraj(short_tracks)
  as_track(lt)
}

if (requireNamespace("ctmm", quietly = TRUE)) {
  tl <- as_telemetry(short_tracks)
  as_track(tl)
}

if (requireNamespace("moveHMM", quietly = TRUE)) {
  hhm <- as_moveHMM(short_tracks, type = "LL")
  as_track(hhm)
}

## End(Not run)

## Not run: 
data(short_tracks)

if (requireNamespace("moveVis", quietly = TRUE)) {
  mv <- as_move(short_tracks)
  as_track(mv)
}

if (requireNamespace("sp", quietly = TRUE)) {
  sp <- as_sp(short_tracks)
  as_track(sp)
}

if (requireNamespace("adehabitatLT", quietly = TRUE)) {
  lt <- as_ltraj(short_tracks)
  as_track(lt)
}

if (requireNamespace("ctmm", quietly = TRUE)) {
  tl <- as_telemetry(short_tracks)
  as_track(tl)
}

if (requireNamespace("moveHMM", quietly = TRUE)) {
  hhm <- as_moveHMM(short_tracks, type = "LL")
  as_track(hhm)
}

## End(Not run)

Dplyr Methods For Track Tables

Description

dplyr methods for track tables objects.

Usage

## S3 method for class 'track'
select(.data, ...)

## S3 method for class 'track'
rename(.data, ...)

## S3 method for class 'track'
filter(.data, ...)

## S3 method for class 'track'
arrange(.data, ...)

## S3 method for class 'track'
mutate(.data, ...)

## S3 method for class 'track'
transmute(.data, ...)

## S3 method for class 'track'
summarise(.data, ...)

## S3 method for class 'track'
summarize(.data, ...)

## S3 method for class 'track'
group_by(.data, ...)

## S3 method for class 'track'
ungroup(x, ...)

## S3 method for class 'track'
slice_sample(.data, ...)

## S3 method for class 'track'
do(.data, ...)

## S3 method for class 'track'
slice(.data, ...)

## S3 method for class 'track'
semi_join(x, ...)

## S3 method for class 'track'
anti_join(x, ...)

## S3 method for class 'track'
inner_join(x, ...)

## S3 method for class 'track'
left_join(x, ...)

## S3 method for class 'track'
right_join(x, ...)

## S3 method for class 'track'
full_join(x, ...)

## S3 method for class 'track'
nest_join(x, ...)

## S3 method for class 'track'
distinct(.data, ...)

## S3 method for class 'track'
rowwise(data, ...)
## S3 method for class 'track'
select(.data, ...)

## S3 method for class 'track'
rename(.data, ...)

## S3 method for class 'track'
filter(.data, ...)

## S3 method for class 'track'
arrange(.data, ...)

## S3 method for class 'track'
mutate(.data, ...)

## S3 method for class 'track'
transmute(.data, ...)

## S3 method for class 'track'
summarise(.data, ...)

## S3 method for class 'track'
summarize(.data, ...)

## S3 method for class 'track'
group_by(.data, ...)

## S3 method for class 'track'
ungroup(x, ...)

## S3 method for class 'track'
slice_sample(.data, ...)

## S3 method for class 'track'
do(.data, ...)

## S3 method for class 'track'
slice(.data, ...)

## S3 method for class 'track'
semi_join(x, ...)

## S3 method for class 'track'
anti_join(x, ...)

## S3 method for class 'track'
inner_join(x, ...)

## S3 method for class 'track'
left_join(x, ...)

## S3 method for class 'track'
right_join(x, ...)

## S3 method for class 'track'
full_join(x, ...)

## S3 method for class 'track'
nest_join(x, ...)

## S3 method for class 'track'
distinct(.data, ...)

## S3 method for class 'track'
rowwise(data, ...)

Arguments

`...`	Additional arguments to be passed to the corresponding `dplyr` method.
`data`, `.data`, `x`	A track table.

Find Duplicated Data in a Track Table

Description

This function attempts to automatically detect duplicated data in track tables.

Usage

duplicated_data(x, type = "txy")
duplicated_data(x, type = "txy")

Arguments

`x`	`track` table as produced by the `track` function.
`type`	A character string or a vector of character strings indicating the type of duplications to look for. The strings can be any combination of `"t"` (for time duplications) and `"x"`, `"y"`, `"z"` (for coordinate duplications). For instance, the string `"txy"` will return data with duplicated time stamps and duplicated x and y coordinates.

Value

A track table of all observations that are duplicated, as per the duplication rule defined by type.

Note

Incomplete data (that is, data containing "NAs") are ignored.

Author(s)

Simon Garnier, [email protected]

Examples

# Create data set with duplicated data
data(short_tracks)
t_df <- track(x = short_tracks$x, y = short_tracks$y, t = short_tracks$t,
              id = short_tracks$id, proj = "+proj=longlat",
              tz = "Africa/Windhoek", table = "df")
t_df <- bind_tracks(t_df, t_df[1:10, ], t_df[100:110, ])

# Find duplicated timestamps
duplicated <- duplicated_data(t_df)

# Create data set with duplicated data
data(short_tracks)
t_df <- track(x = short_tracks$x, y = short_tracks$y, t = short_tracks$t,
              id = short_tracks$id, proj = "+proj=longlat",
              tz = "Africa/Windhoek", table = "df")
t_df <- bind_tracks(t_df, t_df[1:10, ], t_df[100:110, ])

# Find duplicated timestamps
duplicated <- duplicated_data(t_df)

Subset rows using column values

Description

This is a re-export of the filter function in the dplyr package. See the help

Arguments

`.data`	See `filter` for an explanation.
`...`	Other args

Find Inconsistent Locations in a Track Table

Description

This function attempts to automatically detect inconsistent locations (for instance due to a writing error or GPS inaccuracies) in track tables.

Usage

inconsistent_data(x, s = 15)
inconsistent_data(x, s = 15)

Arguments

`x`	`track` table as produced by the `track` function.
`s`	The discrimination threshold for the outlier detection algorithm. Higher values correspond to less outliers.

Value

A track table of all inconsistent data.

Author(s)

Simon Garnier, [email protected]

Examples

# Create data set with inconsistent data
data(tracks)
t_df <- track(x = tracks$x, y = tracks$y, t = tracks$t,
              id = tracks$id, proj = "+proj=longlat",
              tz = "Africa/Windhoek", table = "df")
t_df$x[1000] <- t_df$x[1000] * 1.0001
t_df$y[4000] <- t_df$y[4000] * 1.00001

# Find inconsistent data
inconsistent <- inconsistent_data(t_df)

# Create data set with inconsistent data
data(tracks)
t_df <- track(x = tracks$x, y = tracks$y, t = tracks$t,
              id = tracks$id, proj = "+proj=longlat",
              tz = "Africa/Windhoek", table = "df")
t_df$x[1000] <- t_df$x[1000] * 1.0001
t_df$y[4000] <- t_df$y[4000] * 1.00001

# Find inconsistent data
inconsistent <- inconsistent_data(t_df)

Check if Track Table Uses Geographic Coordinates

Description

Track tables produced by track_df can use a cartesian (x, y, z) or a geographic (latitude, longitude, altitude) coordinate system. This function helps determine which is being used in a particular table.

Usage

is_geo(x)
is_geo(x)

Arguments

`x`	A track data table as produced by `track_df`.

Value

A logical.

Author(s)

Simon Garnier, [email protected]

Examples

data(short_tracks)

is_geo(short_tracks)

data(short_tracks)

is_geo(short_tracks)

Check Validity of Track Table

Description

Test whether a variable contains a track table as produced by track_df, track_tbl, or track_dt.

Usage

is_track(x)
is_track(x)

Arguments

`x`	An object to test.

Value

A logical indicating whether the variable contains a track table (TRUE) or not (FALSE).

Author(s)

Simon Garnier, [email protected]

Examples

data(short_tracks)

is_track(short_tracks)

data(short_tracks)

is_track(short_tracks)

Find Missing Data in a Track Table

Description

This function attempts to automatically detect missing data (for instance due to writing errors) in track tables.

Usage

missing_data(x, begin = NULL, end = NULL, step = NULL)
missing_data(x, begin = NULL, end = NULL, step = NULL)

Arguments

`x`	A `track` table as produced by the `track` function.
`begin`	A full time stamp (date+time) in `POSIXct` format corresponding to the time from which the missing data should be looked for. If not set, the first time stamp of the track table will be used.
`end`	A full time stamp (date+time) in `POSIXct` format corresponding to the time until which the missing data should be looked for. If not set, the last time stamp of the track table will be used.
`step`	A `difftime` object representing the expected time between two consecutive locations of the trajectory. If not set, it is set to the most common time difference between successive locations in `x`.

Value

A track table of all observations with missing data. The missing data is indicated with NA.

Author(s)

Simon Garnier, [email protected]

Examples

# Create data set with missing time stamps
data(short_tracks)
t_df <- track(x = short_tracks$x, y = short_tracks$y, t = short_tracks$t,
              id = short_tracks$id, proj = "+proj=longlat",
              tz = "Africa/Windhoek", table = "df")
t_df <- t_df[-c(10, 100), ]

# Find missing data
missing <- missing_data(t_df)

# Create data set with missing time stamps
data(short_tracks)
t_df <- track(x = short_tracks$x, y = short_tracks$y, t = short_tracks$t,
              id = short_tracks$id, proj = "+proj=longlat",
              tz = "Africa/Windhoek", table = "df")
t_df <- t_df[-c(10, 100), ]

# Find missing data
missing <- missing_data(t_df)

Number of Spatial Dimensions of a Track Table

Description

Track tables produced by track_df can have 2 (x,y) or 3 (x, y, z) spatial dimensions. This function returns the number of spatial dimensions of a track table.

Usage

n_dims(x)
n_dims(x)

Arguments

`x`	A track data table as produced by `track_df`.

Value

A numeric value.

Author(s)

Simon Garnier, [email protected]

Examples

data(short_tracks)

n_dims(short_tracks)

data(short_tracks)

n_dims(short_tracks)

Number of Tracks in a Track Table

Description

Track tables produced by track_df can contain multiple tracks (e.g., from different animals). This function returns the number of tracks in a track table.

Usage

n_tracks(x)
n_tracks(x)

Arguments

`x`	A track data table as produced by `track_df`.

Value

A numeric value.

Author(s)

Simon Garnier, [email protected]

Examples

data(short_tracks)

n_tracks(short_tracks)

data(short_tracks)

n_tracks(short_tracks)

Access/Modify the Projection of a Track Table

Description

Functions to access or modify the projection of a data table. Changing the projection will trigger automatically the conversion of the locations in the new coordinate system.

Usage

projection(x)

projection(x) <- value

project(x, value)
projection(x)

projection(x) <- value

project(x, value)

Arguments

`x`	A track table.
`value`	A character string or a `terra::crs` object representing the projection of the coordinates. `"+proj=longlat"` is suitable for the outputs of most GPS trackers.

Value

A track table.

Note

It is not possible to modify the projection if missing coordinates are present.

Author(s)

Simon Garnier, [email protected]

Examples

data(short_tracks)

projection(short_tracks)
tracks_projected <- project(short_tracks, "+proj=somerc")
projection(tracks_projected)
projection(tracks_projected) <- "+proj=longlat"
projection(tracks_projected)

data(short_tracks)

projection(short_tracks)
tracks_projected <- project(short_tracks, "+proj=somerc")
projection(tracks_projected)
projection(tracks_projected) <- "+proj=longlat"
projection(tracks_projected)

Trajectories of Two Goats Through the Namibian Desert (short version)

Description

A dataset containing the trajectories of two goats through the Namibian desert.

Usage

short_tracks
short_tracks

Format

A track table with 18 rows and 4 variables:

id: Identity of the goat
t: Time of the observation
x: Longitude
y: Latitude

Build a Track Table

Description

track constructs track tables based on data.frame (the default), tibble, or data.table. track is a convenience function that executes track_df, track_tbl, or track_dt based on the value of the 'table' parameter. Track tables can be used like the data structure they are build upon but with a notable difference: they have an extra attribute to store the projection of the track coordinates, and modifying the projection will automatically trigger the appropriate conversion of the coordinates.

Usage

track(x, y, z, t, id, ..., proj, origin, period, tz, format, table = "df")

track_df(x, y, z, t, id, ..., proj, origin, period, tz, format)

track_tbl(x, y, z, t, id, ..., proj, origin, period, tz, format)

track_dt(x, y, z, t, id, ..., proj, origin, period, tz, format)
track(x, y, z, t, id, ..., proj, origin, period, tz, format, table = "df")

track_df(x, y, z, t, id, ..., proj, origin, period, tz, format)

track_tbl(x, y, z, t, id, ..., proj, origin, period, tz, format)

track_dt(x, y, z, t, id, ..., proj, origin, period, tz, format)

Arguments

`x`, `y`, `z`	Numeric vectors representing the coordinates of the locations. `x` and `y` are required. `z` can be ignored if the trajectories are 2-dimensional. Note: if the vectors are not of the same length, the shorter ones will be recycled to match the length of the longer one.
`t`	A numeric vector or a vector of objects that can be coerced to date-time objects by `as_datetime` representing the times (or frames) at which each location was recorded. If numeric, the origin and period of the time points can be set using `origin` and `period` below.
`id`	A vector that can be coerced to a character vector by `as.character` representing the identity of the individual to which each location belong.
`...`	A set of name-value pairs. Arguments are evaluated sequentially, so you can refer to previously created elements. These arguments are processed with `rlang::quos()` and support unquote via `!!` and unquote-splice via `!!!`. Use `:=` to create columns that start with a dot.
`proj`	A character string or a `crs` object (see `st_crs` for more information) representing the projection of the coordinates. Leave empty if the coordinates are not projected (e.g., output of video tracking). `"+proj=longlat"` is suitable for the output of most GPS trackers.
`origin`	Something that can be coerced to a date-time object by `as_datetime` representing the start date and time of the observations when `t` is a numeric vector.
`period`	A character vector in a shorthand format (e.g. "1 second") or ISO 8601 specification. This is used when `t` is a numeric vector to represent time unit of the observations. All unambiguous name units and abbreviations are supported, "m" stands for months, "M" for minutes unless ISO 8601 "P" modifier is present (see examples). Fractional units are supported but the fractional part is always converted to seconds. See `period` for more details.
`tz`	A time zone name. See `OlsonNames`.
`format`	A character string indicating the formatting of 't'. See `strptime` for how to specify this parameter. When supplied parsing is performed by strptime(). For this reason consider using specialized parsing functions in lubridate.
`table`	A string indicating the class of the table on which the track table should be built. It can be a `data.frame` ("df", the default), a `tibble` ("tbl"), or a `data.table` ("dt").

Value

A track table, which is a colloquial term for an object of class track.

Author(s)

Simon Garnier, [email protected]

Examples

data(short_tracks)

t_df <- track(x = short_tracks$x, y = short_tracks$y, t = short_tracks$t,
  id = short_tracks$id, proj = "+proj=longlat", tz = "Africa/Windhoek", table = "df")

t_df <- track_df(x = short_tracks$x, y = short_tracks$y, t = short_tracks$t,
  id = short_tracks$id, proj = "+proj=longlat", tz = "Africa/Windhoek")

t_tbl <- track_tbl(x = short_tracks$x, y = short_tracks$y, t = short_tracks$t,
id = short_tracks$id, proj = "+proj=longlat", tz = "Africa/Windhoek")

t_dt <- track_dt(x = short_tracks$x, y = short_tracks$y, t = short_tracks$t,
  id = short_tracks$id, proj = "+proj=longlat", tz = "Africa/Windhoek")

data(short_tracks)

t_df <- track(x = short_tracks$x, y = short_tracks$y, t = short_tracks$t,
  id = short_tracks$id, proj = "+proj=longlat", tz = "Africa/Windhoek", table = "df")

t_df <- track_df(x = short_tracks$x, y = short_tracks$y, t = short_tracks$t,
  id = short_tracks$id, proj = "+proj=longlat", tz = "Africa/Windhoek")

t_tbl <- track_tbl(x = short_tracks$x, y = short_tracks$y, t = short_tracks$t,
id = short_tracks$id, proj = "+proj=longlat", tz = "Africa/Windhoek")

t_dt <- track_dt(x = short_tracks$x, y = short_tracks$y, t = short_tracks$t,
  id = short_tracks$id, proj = "+proj=longlat", tz = "Africa/Windhoek")

Trajectories of Two Goats Through the Namibian Desert

Description

A dataset containing the trajectories of two goats through the Namibian desert.

Usage

tracks
tracks

Format

A track table with 7194 rows and 4 variables:

id: Identity of the goat
t: Time of the observation
x: Longitude
y: Latitude

Package 'trackdf'

Help Index

Compute The Mode(s) Of A Discrete Distribution

Description

Usage

Arguments

Value

Author(s)

Maintain Class After Modification

Description

Usage

Arguments

Value

Author(s)

Extract or Replace Parts of a Track Table

Description

Usage

Arguments

Value

Author(s)

See Also

Examples

Bind Multiple Track Tables by Row

Description

Usage

Arguments

Value

Author(s)

Examples

Convert a Track Table to/from Other Formats

Description

Usage

Arguments

Value

Author(s)

See Also

Examples

Dplyr Methods For Track Tables

Description

Usage

Arguments

See Also

Find Duplicated Data in a Track Table

Description

Usage

Arguments

Value

Note

Author(s)

See Also

Examples

Subset rows using column values

Description

Arguments

Find Inconsistent Locations in a Track Table

Description

Usage

Arguments

Value

Author(s)

See Also

Examples

Check if Track Table Uses Geographic Coordinates

Description

Usage

Arguments

Value

Author(s)

Examples

Check Validity of Track Table

Description

Usage

Arguments

Value

Author(s)

See Also

Examples

Find Missing Data in a Track Table

Description

Usage