trackeRdata: 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, cycling = FALSE, sessionThreshold = 2,
  correctDistances = FALSE, country = NULL, mask = TRUE,
  fromDistances = TRUE, lgap = 30, lskip = 5, m = 11, silent = FALSE)

Arguments

dat

A data frame.

units

A data frame containing the unit of measurement for all variables. See Details.

cycling

Logical. Do the data stem from cycling instead of running? If so, the default unit of measurement for cadence is set to rev_per_min instead of steps_per_min and power is imputed with 0, else with NA.

sessionThreshold

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

correctDistances

Logical. Should the distances be corrected for elevation?

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 neighboring countries (FALSE)?

fromDistances

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

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.

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

The units argument takes a data frame with two variables named variable and unit. Possible options include:

variables latitude and longitude with unit degree
variables altitude, distance with unit m, km, mi or ft
variable heart.rate with unit bpm
variable speed with unit m_per_s, km_per_h, ft_per_min, ft_per_s or mi_per_h
variable cadence with unit steps_per_min or rev_per_min
variable power with unit W or kW.

If the argument units is NULL, the default units are used. These are the first options, i.e., m for variables altitude and distance, m_per_s for variable speed as well as W for variable power. The default for variable cadence depends on the value of argument cycling.

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.

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

Examples

Run this code

# NOT RUN {
## read raw data
filepath <- system.file("extdata", "2013-06-08-090442.TCX", package = "trackeR")
run <- readTCX(file = filepath, timezone = "GMT")

## turn into trackeRdata object
run <- trackeRdata(run, units = data.frame(variable = c("latitude", "longitude",
    "altitude", "distance", "heart.rate", "speed", "cadence", "power"),
    unit = c("degree", "degree", "m", "m", "bpm", "m_per_s", "steps_per_min", "W"),
    stringsAsFactors = FALSE))

## alternatively
run <- readContainer(filepath, type = "tcx", timezone = "GMT")
# }