Skip to contents

Re-sample an mnirs data frame

Source: R/resample_mnirs.R
resample_mnirs.Rd

Up- or down-sample an "mnirs" data frame to a new sample rate, filling new samples via nearest-neighbour matching or interpolation.

Usage

resample_mnirs(
  data,
  time_channel = NULL,
  sample_rate = NULL,
  resample_rate = sample_rate,
  method = c("locf", "linear", "none"),
  verbose = TRUE
)

Arguments

data

A data frame of class "mnirs" containing time series data and metadata.

time_channel

A character string giving the name of the time or sample column. Must match a column name in data exactly.

  • If NULL (default), the time_channel metadata attribute of data is used.

sample_rate

A numeric sample rate in Hz.

  • If NULL (default), the sample_rate metadata attribute of data will be used if detected, or the sample rate will be estimated from time_channel.

resample_rate

An optional sample rate (Hz) for the output data frame. If NULL (default) resamples to the existing sample_rate, which regularises any irregular samples without changing the rate.

method

A character string specifying how new samples are filled. Default is "locf" (see Details for more on each method):

"locf"

("Last observation carried forward"). Fills new and missing samples with the most recent valid non-NA value to the left, or the nearest valid value to the right for leading NAs. Safe for numeric, integer, and character columns.

"linear"

Fills new and missing samples via linear interpolation using stats::approx(). Suitable for numeric columns only; non-numeric columns will fall back to "locf" behaviour.

"none"

Matches each new sample to the nearest original time_channel value within half a sample-interval tolerance, without any interpolation. New samples that fall between original values are returned as NA.

verbose

Logical. Default is TRUE. Will display or silence (if FALSE) warnings and information messages helpful for troubleshooting. A global default can be set via options(mnirs.verbose = FALSE).

Value

A tibble of class "mnirs". Metadata are stored as attributes and can be accessed with attributes(data).

Details

This function uses replace_missing() (based on stats::approx()) to interpolate across new samples in the resampled data range.

Sample rate and time channel

time_channel and sample_rate are retrieved automatically from data of class "mnirs" which has been processed with {mnirs}, if not defined explicitly.

Otherwise, sample_rate will be estimated from the values in time_channel. However, this may return unexpected values, and it is safer to define sample_rate explicitly.

Default behaviour

When resample_rate is omitted, the output has the same sample_rate as the input but with a regular, evenly-spaced time_channel. This is useful for regularising data that contains missing or repeated samples without changing the nominal rate.

Column handling

Numeric columns are interpolated according to method (see ?replace_missing). Non-numeric columns (character event labels, integer lap numbers) are always filled by last-observation-carried-forward, regardless of method:

  • When down-sampling, the first non-NA value in each output bin is used.

  • When up-sampling or regularising, the most recent original value is carried forward into new samples.

  • For method = "none", existing rows are matched to the nearest original values of time_channel without interpolation or filling, meaning newly created samples and any NAs in the original data are returned as NA.

Examples

## read example data
data <- read_mnirs(
    file_path = example_mnirs("moxy_ramp"),
    nirs_channels = c(smo2 = "SmO2 Live"),
    time_channel = c(time = "hh:mm:ss"),
    verbose = TRUE
)
#> ! Estimated `sample_rate` = 2 Hz.
#> ℹ Define `sample_rate` explicitly to override.
#> Warning: ! Duplicate or irregular `time_channel` samples detected.
#> ℹ Investigate at `time` = 211.99 and 1184.
#> ℹ Re-sample with `mnirs::resample_mnirs()`.

## note warning about irregular sampling
data
#> # A tibble: 2,203 × 2
#>     time  smo2
#>    <dbl> <dbl>
#>  1 0        54
#>  2 0.400    54
#>  3 0.960    54
#>  4 1.51     54
#>  5 2.06     54
#>  6 2.61     54
#>  7 3.16     54
#>  8 3.71     57
#>  9 4.26     57
#> 10 4.81     57
#> # ℹ 2,193 more rows

data_resampled <- resample_mnirs(
    data,
    resample_rate = 2,  ## blank channels will be retrieved from metadata
    method = "linear",  ## blank by default will resample to `sample_rate`
    verbose = TRUE      ## linear interpolation across resampled indices
)
#> ℹ Output is resampled at 2 Hz.

## note the altered `time` values resolving the above warning
data_resampled
#> # A tibble: 2,419 × 2
#>     time  smo2
#>    <dbl> <dbl>
#>  1   0    54  
#>  2   0.5  54  
#>  3   1    54  
#>  4   1.5  54  
#>  5   2    54  
#>  6   2.5  54  
#>  7   3    54  
#>  8   3.5  55.9
#>  9   4    57  
#> 10   4.5  57  
#> # ℹ 2,409 more rows