Read mNIRS Data From File

Will read files exported from most commercially available mNIRS devices and return a dataframe of class "mNIRS.data" with recorded data and metadata.

Usage

read_data(
  file_path,
  nirs_columns,
  sample_column = NULL,
  event_column = NULL,
  sample_rate = NULL,
  numeric_time = TRUE,
  keep_all = FALSE,
  verbose = TRUE
)

Arguments

file_path

The file path including extension (either ".xlsx", ".xls", or ".csv") to import.

nirs_columns

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).

sample_column

An optional character scalar 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_column

An optional character scalar 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 scalar for the sample rate in Hz. If not defined explicitly, will be estimated from the data (see Details).

numeric_time

A logical. TRUE (the default) will convert a date-time formatted sample_column to numeric values in seconds. FALSE will return sample_column in the format of the original file.

keep_all

A logical. FALSE (the default) will only include the explicitly specified data columns. TRUE will include all columns detected from the file.

verbose

A logical. TRUE (the default) will return warnings and messages which can be used for troubleshooting. FALSE will silence these messages. Errors will always be returned.

Value

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

Details

Column names are matched to a single row, anywhere in the data file, not necessarily the top row of the file.

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

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

If sample_column is not specified, then an index column will be added from the row numbers. If the specified sample_column contains unequal sampling (i.e., repeated values or unordered samples) a warning will be given suggesting the user confirm the file data manually.

When the sample_column is provided in date-time format (e.g. hh:mm:ss), this can be converted back to numeric values by numeric_time = TRUE. In this case, values will be recalculated as starting from 0 at the first sample.

sample_column will typically represent time values in seconds. However, some NIRS devices export the sample index. This can be converted to time values if the sample_rate is known.

sample_rate is required for certain {mNIRS} functions to work properly. If it is not defined explicitly, it will be estimated based on the mean difference between values in the sample_column. If sample_column is not defined, then sample_rate will be set to 1 Hz. If sample_column in the data file contains integer row numbers, then sample_rate will be incorrectly estimated to be 1 Hz, and should be defined explicitly.

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