Prepare mNIRS Data for Kinetics Analysis — prepare_kinetics

Processes a list of one or more dataframes of class "mnirs.data" representing distinct or ensembled kinetics events for further analysis.

Usage

prepare_kinetics_data(
  data,
  nirs_channels = NULL,
  time_channel = NULL,
  event_channel = NULL,
  event_times = NULL,
  event_labels = NULL,
  event_indices = NULL,
  group_events = list("distinct", "ensemble"),
  fit_span = list(c(30, 180)),
  time_from_zero = TRUE,
  verbose = TRUE,
  ...
)

Arguments

data: A data frame of class "mnirs.data" containing at least one column with numeric time or sample values, and one column with numeric mNIRS values, along with metadata.
nirs_channels: A character vector indicating the mNIRS data channels to be processed from your dataframe. Must match data column names exactly. Will be taken from metadata if not defined explicitly.
time_channel: A character string indicating the time or sample channel name. Must match column names in data exactly. Will be taken from metadata if not defined explicitly.
event_channel: A character string indicating the event or lap channel name. Must match column names in data exactly. Will be taken from metadata if not defined explicitly.
event_times: An optional numeric vector corresponding to values of time_channel indicating the start of kinetic events. i.e., by time value or sample number.
event_labels: An optional character vector corresponding to values of event_channel indicating the start of kinetics events. i.e., by an event label such as "end work".
event_indices: An optional numeric vector indicating the starting row indices of kinetics events. i.e., to identify the start of kinetic events by row number.
group_events: Indicates how kinetics events should be analysed. Typically either "distinct" (the default) or "ensemble", but can be manually specified as a list of event numbers (see Details).
fit_span: A list of two-element numeric vectors in the form c(before, after) in units of time_channel, defining the window around each kinetics events (in sequence) to include in the model fitting process (default fit_span = list(c(30, 180))). fit_span will be coerced from a vector to a list, and the last vector specified will be carried forward in case more events are observed than fit_span is specified for.
time_from_zero: A logical. TRUE (the default) will resample time_channel to start from zero at the kinetic event. FALSE will return the original numeric values of time_channel. Grouping multiple events together will always resample to zero.
verbose: A logical to return (the default) or silence warnings and messages which can be used for data error checking. Abort errors will always be returned.
...: Additional arguments (not currently used).

Value

A list of tibbles of class "mnirs.data" with metadata available with attributes().

Details

fit_span defines the widest extent of data before and after the kinetics event which may be included in the modelling process, in units of the x-axis time_channel variable. e.g. fit_span = c(30, 180) specifies a window from 30-seconds before to 3-minutes after the expected kinetics event. Negative values are ignored.

fit_span can be specified as a single two-element numeric vector, carried forward to all events, or as a list with uniquely values for each event. The sequence of fit_span should match the sequence of events observed in the data and specified by group_events. If fewer fit_span values are specified than events, the last value will be carried forward. If more fit_span values are specified than events, the remaining values will be ignored.

group_events indicates how kinetics events should be analysed, either separately, or grouped and ensemble averaged similar to oxygen uptake kinetics.

group_events = "distinct": Will prepare a list of unique dataframes for each kinetics event (default).
group_events = "ensemble": Will prepare one dataframe with the ensemble-averaged data from all mNIRS kinetics events.
group_events = list(c(1, 2), c(3, 4)): Will group kinetics events together in sequence of appearance, and prepare a list of ensemble-averaged dataframes for each group. Any kinetic events detected in the data but not explicitly defined here will return as a distinct dataframe.