% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/rescale_mnirs.R
\name{rescale_mnirs}
\alias{rescale_mnirs}
\title{Re-scale data range}
\usage{
rescale_mnirs(
  data,
  nirs_channels = list(),
  range,
  verbose = TRUE
)
}
\arguments{
\item{data}{A data frame of class \emph{"mnirs"} containing time series data and
metadata.}

\item{nirs_channels}{A \code{list()} of character vectors indicating grouping
structure of mNIRS channel names to operate on (see \emph{Details}). Must
match column names in \code{data} exactly. Retrieved from metadata if not
defined explicitly.
\describe{
\item{\code{list("A", "B", "C")}}{Will operate on each channel independently,
losing the relative scaling between channels.}
\item{\code{list(c("A", "B", "C"))}}{Will operate on all channels together,
preserving the relative scaling between channels.}
\item{\code{list(c("A", "B"), c("C", "D"))}}{Will operate on channels \code{A}
& \code{B} in one group, and \code{C} & \code{D} in another group, preserving
relative scaling within, but not between groups.}
}}

\item{range}{A numeric vector in the form \code{c(min, max)}, indicating the
range of output values to which data channels will be re-scaled.}

\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 \emph{"mnirs"} with metadata
available with \code{attributes()}.
}
\description{
Expand or reduce the range (min and max values) of data channels to a new
amplitude/dynamic range, e.g. re-scale the range of NIRS data to \code{c(0, 100)}.
}
\details{
\code{nirs_channels = list()} can be used to group data channels (column names)
to preserve absolute or relative scaling.
\itemize{
\item Channels grouped together in a vector (e.g. \code{list(c("A", "B"))}) will be
re-scaled to a common range, and the relative scaling within that group
will be preserved.
\item Channels in separate list vectors (e.g. \code{list("A", "B")}) will be
re-scaled independently, and relative scaling between groups will be lost.
\item A single vector of channel names (e.g. \code{c("A", "B")}) will group
channels together.
\item Channels (columns) in \code{data} not explicitly defined in \code{nirs_channels}
will be passed through untouched to the output data frame.
}

\code{nirs_channels} can be retrieved automatically from \code{data} of class
\emph{"mnirs"} which has been processed with \code{{mnirs}}, if not defined
explicitly. This will default to returning all \code{nirs_channels} grouped
together, and should be defined explicitly for other grouping arrangements.
}
\examples{
## read example data
data <- read_mnirs(
    file_path = example_mnirs("moxy_ramp"),
    nirs_channels = c(smo2_left = "SmO2 Live",
                      smo2_right = "SmO2 Live(2)"),
    time_channel = c(time = "hh:mm:ss"),
    verbose = FALSE
) |>
    rescale_mnirs(        ## un-grouped nirs channels to rescale separately 
        nirs_channels = list(smo2_left, smo2_right), 
        range = c(0, 100) ## rescale to a 0-100\% functional exercise range
    )

data

\donttest{
    if (requireNamespace("ggplot2", quietly = TRUE)) {
        plot(data, time_labels = TRUE) +
            ggplot2::geom_hline(yintercept = c(0, 100), linetype = "dotted")
    }
}

}
