trackeRdata {trackeR}

Create a trackeRdata object

Description

Create a trackeRdata object from a data frame with observations being divided in separate training sessions. For breaks within a session observations are imputed.

Usage

trackeRdata(
  dat,
  units = NULL,
  sport = NULL,
  session_threshold = 2,
  correct_distances = FALSE,
  smooth_elevation_gain = TRUE,
  from_distances = TRUE,
  country = NULL,
  mask = TRUE,
  lgap = 30,
  lskip = 5,
  m = 11,
  silent = FALSE
)

Arguments

dat

A data.frame object.

units

The output of generate_units.

sport

What sport does dat contain data of? Either 'cycling', 'running', 'swimming' or NULL (default), in which case the sport is directly extracted from the dat. See Details.

session_threshold

The threshold in hours for the time difference between consecutive timestamps above which they are considered to belong to different training sessions.

correct_distances

Logical. Should the distances be corrected for elevation? Default is FALSE.

smooth_elevation_gain

Logical. Should the elevation gain be smoothed before computing elevation gain? Default is TRUE.

from_distances

Logical. Should the speeds be calculated from the distance recordings instead of taken from the speed recordings directly?

country

ISO3 country code for downloading altitude data. If NULL, country is derived from longitude and latitude

mask

Logical. Passed on to getData. Should only the altitudes for the specified country be extracted (TRUE) or also those for the neighbouring countries (FALSE)?

lgap

Time in seconds corresponding to the minimal sampling rate.

lskip

Time in seconds between the last observation before a small break and the first imputed speed or the last imputed speed and the first observation after a small break.

m

Number of imputed observations in each small break.

silent

Logical. Should warnings be generated if any of the sanity checks on the data are triggered?

Details

During small breaks within a session, e.g., because the recording device was paused, observations are imputed the following way: 0 for speed, last known position for latitude, longitude and altitude, NA or 0 power for running or cycling session, respectively, and NA for all other variables. Distances are (re-)calculated based on speeds after imputation.

trackeRdata assumes that all observations in dat are from the same sport, even if dat ends up having observations from different sessions (also depending on the value of session_threshold.

if attr(dat, 'sport') is NA then the current implementation of trackeRdata returns an error.

More details about the resulting trackeRdata object are available in the package vignette, which is an up-to-date version of Frick & Kosmidis (2017).

References

Frick, H., Kosmidis, I. (2017). trackeR: Infrastructure for Running and Cycling Data from GPS-Enabled Tracking Devices in R. Journal of Statistical Software, 82(7), 1–29. doi:10.18637/jss.v082.i07

See Also

readContainer for reading .tcx and .db3 files directly into trackeRdata objects, and get_elevation_gain for details on the computation of the elevation gain.

Examples

## read raw data
filepath <- system.file('extdata/tcx/', '2013-06-08-090442.TCX.gz', package = 'trackeR')
run0 <- readTCX(file = filepath, timezone = 'GMT')

## turn into trackeRdata object
units0 <- generate_units()
run0 <- trackeRdata(run0, units = units0)