% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/shift_mnirs.R
\name{shift_mnirs}
\alias{shift_mnirs}
\title{Shift data range}
\usage{
shift_mnirs(
  data,
  nirs_channels = list(),
  time_channel = NULL,
  to = NULL,
  by = NULL,
  width = NULL,
  span = NULL,
  position = c("min", "max", "first"),
  verbose = TRUE
)
}
\arguments{
\item{data}{A data frame of class \emph{"mnirs"} containing time series data and
metadata.}

\item{nirs_channels}{A character vector giving the names of mNIRS columns to
operate on. Must match column names in \code{data} exactly.
\itemize{
\item If \code{NULL} (default), the \code{nirs_channels} metadata attribute of \code{data} is
used.
}}

\item{time_channel}{A character string naming the time or sample column.
Must match a column name in \code{data} exactly.
\itemize{
\item If \code{NULL} (default), the \code{time_channel} metadata attribute of \code{data} is
used.
}}

\item{to}{A numeric value in units of \code{nirs_channels} to which the data
channels will be shifted, e.g. shift the minimum value to zero.}

\item{by}{A numeric value in units of \code{nirs_channels} by which the data
channels will be shifted, e.g. shift all values up by 10 units.}

\item{width}{An integer defining the local window in number of samples
centred on \code{idx}, between
\verb{[idx - floor(width/2), idx + floor(width/2)]}.}

\item{span}{A numeric value defining the local window time span around
\code{idx} in units of \code{time_channel} or \code{t}, between
\verb{[t - span/2, t + span/2]}.}

\item{position}{Indicates where the reference values will be shifted from.
\describe{
\item{\code{"min"}}{(The \emph{default}) will shift the minimum value(s) \code{to}
or \code{by} the specified value.}
\item{\code{"max"}}{Will shift the maximum value(s) \code{to} or \code{by} the
specified values.}
\item{\code{"first"}}{Will shift first value(s) \code{to} or \code{by} the specified
values.}
}}

\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{
Move the range of data channels in a data frame up or down, while preserving
the absolute amplitude/dynamic range of each channel, and the relative
scaling across channels. e.g. shift the minimum data value to zero for all
positive values, or shift the mean of the first time span in a recording
to zero.
}
\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
shifted to a common value, and the relative scaling within that group
will be preserved.
\item Channels in separate list vectors (e.g. \code{list("A", "B")}) will be
shifted 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} and \code{time_channel} 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.

Only one of either \code{to} or \code{by} and one of either \code{width} or \code{span} should
be defined. If both of either pairing are defined, \code{to} will be preferred
over \code{by}, and \code{width} will be preferred over \code{span}.
}
\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
) |>
    shift_mnirs(        ## un-grouped nirs channels to shift separately 
        nirs_channels = list(smo2_left, smo2_right), 
        to = 0,         ## NIRS values will be shifted to zero
        span = 120,     ## shift the *first* 120 sec of data to zero
        position = "first"
    )

data

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

}
