spiro {spiro}

Import and process raw data from metabolic carts/spiroergometric measures

Description

spiro() wraps multiple functions to import and process raw data from metabolic carts into a data.frame.

Usage

spiro(
  file,
  device = NULL,
  bodymass = NULL,
  hr_file = NULL,
  hr_offset = 0,
  protocol = NULL,
  anonymize = TRUE
)

Arguments

file

The absolute or relative path of the file that contains the gas exchange data.

device

A character string, specifying the device for measurement. By default the device type is guessed by the characteristics of the file. This can be overridden by setting the argument to "cortex", "cosmed", "vyntus" or "zan".

bodymass

Numeric value for the individual's body mass, if the default value saved in the file should be overridden.

hr_file

The absolute or relative path of a *tcx file that contains additional heart rate data.

hr_offset

An integer, corresponding to the temporal offset of the heart-rate file. By default the start of the heart rate measurement is linked to the start of the gas exchange measurement. A positive value means, that the heart rate measurement started after the begin of the gas exchange measurements; a negative value means it started before.

protocol

A data.frame by set_protocol or set_protocol_manual containing the test protocol. This is automatically guessed by default. Set to NA to skip protocol guessing.

anonymize

Whether meta data should be anonymized during import. Defaults to TRUE. See get_anonid for more information.

Details

This function performs multiple operations on raw data from metabolic carts. It imports the raw data from a file, which might be complemented by an additional .tcx file with heart rate data.

After using this function, you may summarize the resulting data frame with spiro_summary and spiro_max, or plot it with spiro_plot.

Value

A data.frame of the class spiro with cardiopulmonary parameters interpolated to seconds and the corresponding load data.

The attribute "protocol" provides additional information on the underlying testing protocol. The attribute "info" contains additional meta data from the original raw data file. The attribute "raw" gives the imported raw data (without interpolation, similar to calling spiro_raw).

Import

Different metabolic carts yield different output formats for their data. By default, this function will guess the used device based on the characteristics of the given file. This behavior can be overridden by explicitly stating the device argument.

The currently supported metabolic carts are:

• CORTEX (.xlsx, .xls or files .xml in English or German language)

• COSMED (.xlsx or .xls files, in English or German language)

• Vyntus (.txt files in French, German or Norwegian language)

• ZAN (.dat files in German language, usually with names in the form of "EXEDxxx")

The spiro function can import personal meta data (name, sex, birthday, ...). By default this data is anonymized with anonymize = TRUE, see get_anonid for more information.

Processing

Breath-by-breath data is linearly interpolated to get data points for every full second. Based on the given load data, the underlying exercise protocol is guessed and applied to the data. If no load data is available or the protocol guess turns wrong, you can manually specify the exercise protocol by using set_protocol or set_protocol_manual. If you want to skip the automated protocol guessing without providing an alternative, set protocol = NA. Note that in this case, some functions relying on load data (such as spiro_summary) will not work.

Additional variables of gas exchange are calculated for further analysis. Per default the body mass saved in the file's metadata is used for calculating relative measures. It is possible to specify bodymass manually to the function, overriding that value.

Protocols, heart rate data and body mass information can also be given in a piping coding style using the functions add_protocol, add_hr and add_bodymass (see examples).

Examples

# get example file
file <- spiro_example("zan_gxt")

out <- spiro(file)
head(out)

# import with user-defined test profile
p <- set_protocol(pt_pre(60), pt_steps(300, 2, 0.4, 9, 30))
out2 <- spiro(file, protocol = p)
head(out2)

# import with additional heart rate data
oxy_file <- spiro_example("zan_ramp")
hr_file <- spiro_example("hr_ramp.tcx")

out3 <- spiro(oxy_file, hr_file = hr_file)
head(out3)

# use the add_* functions in a pipe
# Note: base R pipe requires R version 4.1 or greater)
## Not run: 
spiro(file) |>
  add_hr(hr_file = hr_file, hr_offset = 0) |>
  add_bodymass(68.2)

## End(Not run)