Read mNIRS Data From File — read

Read files exported from most commercially available mNIRS devices and return a data frame of class "mnirs.data" with recorded time series data and metadata.

Usage

read_data(
  file_path,
  nirs_channels,
  time_channel = NULL,
  event_channel = NULL,
  sample_rate = NULL,
  time_to_numeric = TRUE,
  time_from_zero = FALSE,
  keep_all = FALSE,
  verbose = TRUE
)

Arguments

file_path: The file path including extension (either ".xlsx", ".xls", or ".csv") to import.
nirs_channels: A character vector indicating the mNIRS data columns to import from the file. Must match column names in the data file exactly. A named character vector can be used to rename columns in the form: c(new_name = "old_name") (see Details).
time_channel: An optional character string indicating the time or sample data column to import from the file. Must match column names in the data file exactly. A named character vector can be used to rename columns in the form: c(new_name = "old_name") (see Details).
event_channel: An optional character string indicating the event or lap data column to import from the file. Must match column names in the data file exactly. A named character vector can be used to rename columns in the form: c(new_name = "original_name") (see Details).
sample_rate: An optional numeric value for the exported sample rate in Hz. If not defined explicitly, will be estimated from the data (see Details).
time_to_numeric: A logical. TRUE (the default) will convert a date-time formatted time_channel to numeric values in seconds. FALSE will return time_channel in the format of the original file.
time_from_zero: A logical. TRUE will re-calculate time_channel to start from zero. FALSE (the default) will return the original values of time_channel.
keep_all: A logical. TRUE will include all columns detected from the file. FALSE (the default) will only include the explicitly specified data columns.
verbose: A logical. TRUE (the default) will display warnings and messages which can be used for troubleshooting. FALSE will silence these messages. Abort error messages will always be displayed.

Value

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

Details

Channel names are matched to a single row, representing the header row for data columns anywhere in the data file, not necessarily the top row of the file.

Channels can be renamed in the format c(new_name = "original_name"), where "original_name" should exactly match the column names found in the file.

If there are duplicate column names in the file, the channel names will attempt to match them in the order in which they appear. You may want to confirm that the correct columns have been assigned to each channel as intended.

time_channel will typically represent time values in seconds. However, some NIRS devices (for example, Artinis devices recorded with Oxysoft) export the sample index (i.e. integer row numbers). If this is recognised and sample_rate is detected or specified, a "time" column will be added converting the sample indices to time values in seconds.

If time_channel is not specified, then a "time" column will be added from sample indices (row numbers) and converted to time values in seconds as long as sample_rate is specified. If sample_rate is not specified, then this "time" column will remain as sample indices.

If time_channel contains unequal sampling (i.e., repeated values or unordered samples) a warning will be displayed suggesting the user confirm the file data manually.

When the time_channel is provided in date-time format (e.g. hh:mm:ss), this can be converted back to numeric values by time_to_numeric = TRUE. In this case, values will be re-calculated with the first sample starting from zero.

sample_rate is required for certain {mnirs} functions to work properly and can be carried forward in the data frame metadata. If it is not defined explicitly, it will be estimated from the differences between values in the time_channel. As above, in certain cases where the time_channel represents sample indices rather than time values, sample_rate will be estimated at 1 Hz. In such cases, sample_rate should be defined explicitly.

Columns and rows which contain entirely missing data (NA) are omitted.