% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/read_mnirs.R
\name{read_mnirs}
\alias{read_mnirs}
\title{Read \emph{{mnirs}} data from file}
\usage{
read_mnirs(
  file_path,
  nirs_channels = NULL,
  time_channel = NULL,
  event_channel = NULL,
  sample_rate = NULL,
  add_timestamp = FALSE,
  zero_time = FALSE,
  keep_all = FALSE,
  verbose = TRUE
)
}
\arguments{
\item{file_path}{Path of the data file to import. Supported file extensions
are \code{".xlsx"}, \code{".xls"}, and \code{".csv"}.}

\item{nirs_channels}{A character vector of one or more column names
containing mNIRS signals to import. Names must match the file header
exactly.
\itemize{
\item If \code{NULL} (default), \code{read_mnirs()} attempts to detect the device from
the file contents and use a known \code{nirs_channel} name.
\item A \emph{named} character vector can be used to rename columns on import, in
the form \code{c(renamed = "original_name")}.
}}

\item{time_channel}{A character string giving the name of the time
(or sample) column to import. The name must match the file header exactly.
\itemize{
\item If \code{NULL} (default), \code{read_mnirs()} attempts to identify a time-like
column automatically (by known device defaults and/or time-formatted
values).
\item A \emph{named} character vector can be used to rename the column on import,
in the form \code{c(time = "original_name")}.
}}

\item{event_channel}{An \emph{optional} character string giving the name of an
event/lap column to import. Names must match the file header exactly.
A named character vector can be used to rename the column on import in
the form \code{c(event = "original_name")}.}

\item{sample_rate}{An \emph{optional} numeric sample rate in Hz. If left blank
(\code{NULL}), the sample rate is estimated from \code{time_channel} (see \emph{Details}).}

\item{add_timestamp}{A logical. Default is \code{FALSE}. If \code{TRUE} and if the
source data contain an absolute date-time (POSIXct) time value, will add
a \code{"timestamp"} column in addition to the specified \code{time_channel} as a
numeric time column.}

\item{zero_time}{Logical. Default is \code{FALSE}. If \code{TRUE}, re-calculates
numeric \code{time_channel} values to start from zero.}

\item{keep_all}{Logical. Default is \code{FALSE}. Will keep only the channels
explicitly specified in \code{nirs_channels}, \code{time_channel}, and
\code{event_channel}. If \code{TRUE} will keep all columns found in the file
data table.
\itemize{
\item If no \code{nirs_channels} are specified and the file format is recognised,
all columns in the file data table will be returned, as an exploratory
option.
}}

\item{verbose}{Logical. Default is \code{TRUE}. Display or silence (if \code{FALSE})
warnings and information messages helpful for troubleshooting. Ad
global default can be set via \code{options(mnirs.verbose = FALSE)}.}
}
\value{
A \link[tibble:tibble-package]{tibble} of class \code{"mnirs"}. Metadata are stored
as attributes and can be accessed with \code{attributes(data)}.
}
\description{
Import time-series data exported from common muscle NIRS (mNIRS) devices and
return a tibble of class \code{"mnirs"} with the selected signal channels and
metadata.
}
\details{
\subsection{Header detection}{

\code{read_mnirs()} searches the file for a header row containing the requested
channel names. The header row does not need to be the first row in the file.
\itemize{
\item If duplicate column names exist, columns are matched in the order they
appear and renamed with unique strings.
\item Columns without a header name in the source file will be renamed to
\verb{col_*}, where \code{*} is the numeric column number in which they appear in
the file (e.g. \code{col_6}). This applies to \emph{Artinis Oxysoft} event label
columns, which do not have a column header and must be identified manually.
}
}

\subsection{Renaming channels}{

A named character vector can be specified to rename \code{nirs_channels},
\code{time_channel}, and \code{event_channel}, in the form
\code{c(renamed = "original_name")}. The \code{"original_name"} must match the
contents of the file data table header row exactly.
}

\subsection{Time parsing}{

\code{time_channel} will be converted to numeric for analysis.
\itemize{
\item If \code{time_channel} is a date-time (POSIXct) format, it will be converted
to numeric and re-based to start from 0, regardless of \code{zero_time}.
\item Some devices export a sample index rather than time values. In those
cases, if an export \code{sample_rate} is detected in the file metadata (e.g.
\emph{Artinis Oxysoft} exports), \code{read_mnirs()} will create or overwrite a
\code{"time"} column in seconds derived from the sample index and the detected
\code{sample_rate}.
}
}

\subsection{Sample rate}{

If \code{sample_rate} is not specified, it is estimated from differences in
\code{time_channel}. If \code{time_channel} is actually a sample index, as described
above, this may erroneously be estimated at 1 Hz. \code{sample_rate} should be
specified explicitly in this case.
}

\subsection{Data cleaning}{

Entirely empty rows and columns are removed. Invalid values (e.g.
\code{c(NaN, Inf)}) are standardized to \code{NA}. A warning will be displayed when
irregular sampling is detected (e.g. non-monotonic, repeated, or unequal
time values), if \code{verbose = TRUE}.
}
}
\examples{
read_mnirs(
    file_path = example_mnirs("moxy_ramp"), ## call an example data file
    nirs_channels = c(
        smo2_left = "SmO2 Live",            ## identify and rename channels
        smo2_right = "SmO2 Live(2)"
    ),
    time_channel = c(time = "hh:mm:ss"),    ## date-time format will be converted to numeric
    event_channel = NULL,                   ## leave blank if unused
    sample_rate = NULL,                     ## if blank, will be estimated from time_channel
    add_timestamp = FALSE,                  ## omit a date-time timestamp column
    zero_time = TRUE,                       ## recalculate time values from zero
    keep_all = FALSE,                       ## return only the specified data channels
    verbose = TRUE                          ## show warnings & messages
)

}
