by_time: Specify interval boundaries by time, label, lap, or sample

In mnirs: Muscle Near-Infrared Spectroscopy Processing and Analysis

Specify interval boundaries by time, label, lap, or sample

Description

Helper functions to define interval start or end boundaries for extract_intervals().

Usage

by_time(...)

by_label(..., ignore_case = FALSE, fixed = FALSE)

by_lap(...)

by_sample(...)

Arguments

...	Specify start or end boundaries. by_time(...) Numeric time values in units of time_channel. by_label(...) Character strings to match in event_channel. Matched as regular expressions by default; see ignore_case and fixed. All matching occurrences are returned. by_lap(...) Integer lap numbers to match in event_channel. For start, resolves to the first sample of each lap. For end, resolves to the last sample. by_sample(...) Integer sample indices (row numbers).
ignore_case	For by_label(). If TRUE, match case-insensitive labels. Default FALSE.
fixed	For by_label(). If TRUE, treat labels as fixed strings rather than regular expressions. Useful when labels contain regex metacharacters (., *, (, etc.). Default FALSE.

Details

These helpers can be used explicitly for arguments start/end, or raw values can be passed directly:

• Numeric -> by_time()

• Character -> by_label(),

• Explicit integer (e.g. 2L) -> by_lap().

• Use by_sample() explicitly for sample indices.

Multiple specification types can be combined for a single boundary with list() (e.g. list(by_time(30), by_label("go"))). Resolved boundary times are concatenated in the order supplied. Combined specifications must use the by_ helpers directly: raw values are ignored with a warning.

Value

An object of class "mnirs_interval" for use with the start and end arguments of extract_intervals().

Examples

## read example data
data <- read_mnirs(
    example_mnirs("train.red"),
    nirs_channels = c(
        smo2_left = "SmO2 unfiltered",
        smo2_right = "SmO2 unfiltered"
    ),
    time_channel = c(time = "Timestamp (seconds passed)"),
    event_channel = c(lap = "Lap/Event"),
    zero_time = TRUE,
    verbose = FALSE
)

## start and end by time
extract_intervals(data, start = by_time(66), end = by_time(357))

## start by lap
extract_intervals(data, start = by_lap(2, 4), span = 0)

## combine multiple specification types
extract_intervals(
    data,
    start = list(by_lap(2), by_time(400)),
    end = by_sample(1500)
)

## simulate event_channel with character label match
data$event <- NA_character_
data$event[c(1000, 1001)] <- c("start", "lap.1")
data <- create_mnirs_data(data, event_channel = "event")

## case-insensitive label match
extract_intervals(data, start = by_label("START", ignore_case = TRUE))

## literal-string label match (regex metacharacters treated as text)
extract_intervals(data, start = by_label("lap.1", fixed = TRUE))

mnirs documentation built on Sept. 13, 2026, 1:06 a.m.