Package 'PhysioExperiment'

Description

x[c(start, end), streams] is shorthand for timeWindow(x, start, end, streams).

Usage

## S4 method for signature 'MultiPhysioExperiment,ANY,ANY,ANY'
x[i, j, ..., drop = FALSE]

Arguments

Details

This is the former PhysioCrossModal [ method. Its meaning is preserved, with one deliberate correction: the old implementation computed indices as floor(t * rate) + 1 from the rate alone, which ignored each stream's start offset and could admit one sample lying before start. Selection is now made on each sample's actual time on the shared clock. For windows whose bounds land on sample times - including all zero-offset data with grid-aligned bounds - the selection is unchanged.

Value

A MultiPhysioExperiment.

Description

Extracts a subset of the PhysioExperiment by row (time) and/or column (channel) indices, preserving metadata and appending a processing-history entry with the supplied indices and input/output dimensions. Missing indices select the full corresponding axis.

Usage

## S4 method for signature 'PhysioExperiment,ANY,ANY,ANY'
x[i, j, ..., drop = FALSE]

Arguments

Value

A PhysioExperiment object containing only the selected time points and/or channels, with updated rowData and colData.

References

Huber, W., et al. (2015). "Orchestrating high-throughput genomic analysis with Bioconductor." Nature Methods, 12(2), 115-121. doi:10.1038/nmeth.3252

Morgan, M., et al. (2022). "S4Vectors: Foundation of vector-like and list-like containers in Bioconductor." R package.

See Also

extractWindow for subsetting by time in seconds, pickChannels for subsetting by channel name, dropChannels for removing specific channels

Examples

pe <- PhysioExperiment(
  assays = list(raw = matrix(rnorm(400), nrow = 100, ncol = 4)),
  samplingRate = 100
)

# Subset by time
pe_subset <- pe[1:50, ]
dim(pe_subset)  # 50 4

# Subset by channels
pe_channels <- pe[, 1:2]
dim(pe_channels)  # 100 2

Description

Add events to a PhysioExperiment object

Usage

addEvents(x, onset, duration = 0, type = "event", value = "")

Arguments

Value

The modified PhysioExperiment object.

References

Delorme A, Makeig S (2004). "EEGLAB: an open source toolbox for analysis of single-trial EEG dynamics." Journal of Neuroscience Methods, 134(1), 9-21.

Oostenveld R, Fries P, Maris E, Schoffelen JM (2011). "FieldTrip: Open source software for advanced analysis of MEG, EEG, and invasive electrophysiological data." Computational Intelligence and Neuroscience, 2011, 156869.

See Also

setEvents for replacing all events, removeEvents for removing events, getEvents for retrieving events, nEvents for event count

Examples

pe <- PhysioExperiment(
  assays = list(raw = matrix(rnorm(1000), nrow = 100)),
  samplingRate = 100
)

# Add stimulus events
pe <- addEvents(pe, onset = c(1, 2, 3), type = "stimulus")

# Add response events
pe <- addEvents(pe, onset = c(1.5, 2.5), type = "response", value = c("hit", "hit"))
nEvents(pe)  # 5 events total

Description

A thin convenience over logStep that records an append-only provenance entry on the object's metadata log (never dropping prior entries), optionally capturing an integer seed in the entry parameters so the step is reproducible under a fixed seed.

Usage

addProvenance(
  pe,
  step,
  params = list(),
  seed = NULL,
  package = NA_character_,
  version = NA_character_
)

Arguments

Value

pe with the entry appended to its provenance log.

See Also

logStep, provenance

Examples

pe <- PhysioExperiment(
  S4Vectors::SimpleList(raw = matrix(rnorm(20), 10, 2)), samplingRate = 100)
pe <- addProvenance(pe, "conformalInterval", seed = 42)
provenance(pe)

Description

Appends a session and re-sorts the container into chronological order by days_from_baseline.

Usage

addSession(
  x,
  label,
  pe,
  days_from_baseline,
  condition = NA_character_,
  session_id = label
)

Arguments

Value

The updated PhysioLongitudinal, re-sorted chronologically.

See Also

PhysioLongitudinal

Description

Add a subject to a PhysioCohort

Usage

addSubject(x, id, subject, group = NA_character_, meta = list())

Arguments

Value

The updated PhysioCohort.

See Also

PhysioCohort

Description

Summarizes scalar features while preserving observation identity. Higher targets are reached one level at a time: cycles to trials, trials to sessions, sessions to subjects, and subjects to a cohort. With the default mean, each immediate child receives equal weight, regardless of how many observations contributed to that child. These are descriptive summaries, not models or estimates of sampling uncertainty.

Usage

aggregatePhysioFeatures(
  x,
  level,
  features = NULL,
  strata = NULL,
  FUN = mean,
  na.rm = FALSE,
  ...
)

Arguments

Details

Repeated session/trial names in different parents remain distinct. Duplicate full observation keys, including strata, are rejected. Identifiers are normalized to character. Group order follows first appearance in the input.

To give trials equal weight, the mean of a session with trial means 1 and 9 is 5 even if the trials contain different numbers of cycles. Requesting a subject or cohort directly performs the same intervening steps as chaining results with the same FUN and arguments. For nonlinear FUN, this is a nested summary (e.g. a median of trial medians), not a pooled summary. Custom functions should be deterministic and depend only on their supplied inputs; recorded function text does not capture external state or closure values.

Features must have compatible units and meaning within each group; this function cannot infer those from numeric columns. It does not align or average raw waveforms, construct trial containers, infer missing IDs, or establish statistical independence. Absent trials are not counted; only supplied rows and their missing feature values can be audited.

For a modality returned by PhysioMoCap's summarizeCycleFeatures(), combine its key table and feature block with cbind(z$keys$emg, z$blocks$emg) and specify the feature names and strata = "side". Different modalities can be summarized separately using the same hierarchy and strata.

Value

A physio_aggregation list with data (one row per target unit and stratum), features, strata, level, source (the retained original input table), and source_rows (a list mapping each output row to rows of source, including rows with missing features). steps records each reached level's data, source mapping, method text, arguments and missing-value policy. Each step's counts has output-row and feature identifiers, n_units (immediate children), n_used, n_missing, and n_source (mapped original rows, not an effective sample size). counts also exposes the final step. A checksum detects changed data or lineage before further aggregation.

Examples

cycles <- data.frame(subject_id = "person1", session_id = "session1",
  trial_id = c("trial1", "trial1", "trial2"),
  cycle_id = c("cycle1", "cycle2", "cycle1"), amplitude = c(0, 2, 9))
trials <- aggregatePhysioFeatures(cycles, "trial", "amplitude")
sessions <- aggregatePhysioFeatures(trials, "session")
sessions$data                         # mean(c(1, 9)) = 5
sessions$counts                       # two trials, three original cycles
aggregatePhysioFeatures(cycles, "session", "amplitude")$data

Description

Selects rows from the trial table and hands them to aggregatePhysioFeatures. The aggregation itself - the equal weighting of immediate children at each level, the link back to source rows, the checksum - is unchanged: choosing which trials take part is a selection of input rows, not a reweighting.

Usage

aggregateTrials(
  x,
  level,
  features = NULL,
  include = "complete",
  rule = "nominal",
  gap_factor = 1.5,
  ...
)

Arguments

Details

Each trial is classified before anything is averaged, because averaging a truncated trial together with whole ones silently mixes different amounts of evidence:

"complete"

Every stream the trial names covers it fully.

"partial"

A stream covers less of the interval than it asks for. The interval was cut by a window, or it runs past the end of the recording, or streamCoverage reports a dropout inside it.

"unknown"

Completeness cannot be decided here. Coverage is undecidable; or a gap an earlier window recorded cannot be re-derived under this query's rate or gap_factor, so the dropout can be neither confirmed nor ruled out; or the stream holds more samples in the interval than its declared rate predicts – nothing is missing, but the grid does not describe it. None of these is the same as complete.

"undescribed"

No interval is recorded for the trial, so nothing describes its extent. Excluded by default: a trial table of per-trial values with no intervals is a job for aggregatePhysioFeatures directly, or ask for include = "undescribed" here.

Every judgement comes from streamCoverage – the shortfall, the dropout it reports, and what it says it could not re-derive – so a trial is excluded by the same rule that reports the problem rather than by a second definition of it.

The states are decided in that order: shown to be short, then unable to tell, then shown to be whole. Losing the evidence for a gap therefore never promotes a trial to "complete" – a question that can no longer be answered is not an answer of yes – while a shortfall this query can still demonstrate outranks a record it cannot reuse.

Value

A list with aggregate (the aggregation result), counts (one entry per state plus n_included / n_excluded), states (the state of every trial) and excluded.

See Also

aggregatePhysioFeatures, trialIntervals, streamCoverage

Description

Evaluates one stream on an explicitly supplied trial-relative grid, then averages trials, sessions and subjects with equal weight at each level. Measured sample times take priority over reconstructed sampling times.

Usage

aggregateTrialWaveforms(
  x,
  stream,
  grid,
  align = c("start", "phase"),
  level = c("session", "subject", "cohort"),
  assay = "raw",
  channels = NULL,
  strata = NULL,
  anchors = NULL,
  include = "complete",
  gap_factor = 1.5,
  na.rm = FALSE
)

Arguments

Details

Linear interpolation uses adjacent finite samples inside the selected stream's trial interval. There is no extrapolation, interpolation across reported gaps, or skipping over missing signal values. Exact samples at gap boundaries remain usable. Included trials with unusable retained gap evidence are refused. The output is an interpolated representation, not antialias filtering; preprocess signals appropriately before choosing a coarser grid.

Channel names establish correspondence, not compatible units or physiology. The caller must provide comparable assays and units. Source hashes include times, selected signal values, channel metadata and interval/trial tables. Interpolation indices refer to rows in the input recording, including when that recording was previously windowed. Inputs themselves are not modified.

aggregatePhysioFeatures performs the hierarchy and preserves intermediate results and source-row links. The waveform SD or a confidence interval is not estimated: trials are not treated as independent participants.

Value

A list with data (mean waveform by output unit, channel and grid point), counts (immediate-child counts and n_trials, the number of finite contributing original trial values), aggregate (the full hierarchical result), aligned (selected trial values), sample_map (record, stream, channel, bracketing original row indices, interpolation weight and missingness reason for each aligned row), trials (all trial states and selections), anchors, settings, source hashes, and a result checksum.

See Also

aggregateTrials, streamTimeIndex

Examples

pe <- PhysioExperiment(assays = list(raw = matrix(0:30, ncol = 1,
  dimnames = list(NULL, "signal"))), samplingRate = 10)
m <- MultiPhysioExperiment(sensor = pe)
trials(m) <- data.frame(subject_id = "P1", session_id = "S1",
                         trial_id = c("T1", "T2"))
trialIntervals(m) <- data.frame(trials(m)[1:3], recording_id = "R1",
  stream = "sensor", start = c(0, 2), end = c(1, 3))
z <- aggregateTrialWaveforms(m, "sensor", grid = c(0, 0.5, 1))
z$data
z$counts

Description

Convenience wrapper for resampleToCommon(x, reference_rate) using the shared clock's reference rate.

Usage

alignStreams(x)

Arguments

Value

A single-rate PhysioExperiment.

See Also

resampleToCommon

Description

Construct an AnalysisResult

Usage

AnalysisResult(
  type,
  result = list(),
  parameters = list(),
  provenance = data.frame(),
  estimate = NULL,
  uncertainty = list(),
  method = NA_character_,
  estimand = list()
)

Arguments

Value

An AnalysisResult object.

Examples

AnalysisResult("hrv_time", result = list(sdnn = 42, rmssd = 30))
AnalysisResult("rom", estimate = 118,
  uncertainty = list(type = "conformal", level = 0.9, lower = 104,
                     upper = 132),
  estimand = list(population = "post-op knee", summary_measure = "median"))

Description

Accessors for analysis results

Usage

resultType(x)

## S4 method for signature 'AnalysisResult'
resultType(x)

resultValue(x)

## S4 method for signature 'AnalysisResult'
resultValue(x)

## S4 method for signature 'PhysioBiomarker'
resultValue(x)

biomarkerValue(x)

## S4 method for signature 'PhysioBiomarker'
biomarkerValue(x)

Arguments

Value

resultType() the type tag; resultValue() the payload (or scalar value for a biomarker); biomarkerValue() the scalar value.

Examples

res <- AnalysisResult("hrv_time", result = list(sdnn = 42, rmssd = 30))
resultType(res)
resultValue(res)

bm <- PhysioBiomarker("SDNN", 42, unit = "ms")
biomarkerValue(bm)

Description

Estimand / uncertainty carrier accessors

Usage

estimateOf(x)

## S4 method for signature 'AnalysisResult'
estimateOf(x)

uncertaintyOf(x)

## S4 method for signature 'AnalysisResult'
uncertaintyOf(x)

provenanceOf(x)

## S4 method for signature 'AnalysisResult'
provenanceOf(x)

estimandOf(x)

## S4 method for signature 'AnalysisResult'
estimandOf(x)

Arguments

Value

estimateOf() the point estimate; uncertaintyOf() the interval list; provenanceOf() the provenance; estimandOf() the ICH E9(R1) estimand list.

Examples

r <- AnalysisResult("rom", estimate = 118,
  uncertainty = list(type = "conformal", level = 0.9, lower = 104,
                     upper = 132))
estimateOf(r)
uncertaintyOf(r)

Description

A lightweight S4 container so every analysis (HRV, synergies, gait indices, ...) returns a consistently-shaped object that reporting and downstream code can consume uniformly.

Usage

## S4 method for signature 'AnalysisResult'
show(object)

Arguments

Value

The show methods return NULL invisibly and are called for the side effect of printing a compact summary.

Slots

type

Character tag identifying the analysis (e.g. "hrv_time").

result

Named list holding the payload.

parameters

Named list of parameters used to produce the result.

provenance

Optional data.frame lineage (see provenance).

estimate

The point estimate the result carries (any type).

uncertainty

Named list describing the interval, with a type in none, conformal, bayes, bootstrap, ncp or analytic, plus (typically) level, lower and upper.

method

Character label of the estimation method.

estimand

Named list of ICH E9(R1) estimand attributes (population, treatment, endpoint / variable, summary measure, intercurrent-event handling).

See Also

PhysioBiomarker

Description

Appends one PROV activity to the object's audit trail. Two forms are supported: a high-level form that builds a full PROV-O record from named fields, and a low-level form that appends a pre-built entry list.

Usage

appendProvenance(
  x,
  entry = NULL,
  activity = NULL,
  params = list(),
  input_assay = NA_character_,
  output_assay = NA_character_,
  agent = NA_character_,
  software_version = NA_character_,
  package = NA_character_
)

Arguments

Value

x with the activity appended to its provenance log.

Examples

pe <- PhysioExperiment(
  S4Vectors::SimpleList(raw = matrix(rnorm(20), 10, 2)), samplingRate = 100)
pe <- appendProvenance(pe, activity = "filterSignals",
                       params = list(low = 1, high = 40),
                       input_assay = "raw", output_assay = "filtered")
provenance(pe)$activity

Description

Applies a standard electrode montage (e.g., 10-20 system).

Usage

applyMontage(x, system = c("10-20", "10-10", "10-5"))

Arguments

Value

Modified PhysioExperiment object with electrode positions.

References

Oostenveld R, Fries P, Maris E, Schoffelen JM (2011). "FieldTrip: Open source software for advanced analysis of MEG, EEG, and invasive electrophysiological data." Computational Intelligence and Neuroscience, 2011, 156869.

See Also

setElectrodePositions for custom positions, getElectrodePositions for reading positions, channelNames for channel labels, setReference for reference electrode

Examples

pe <- PhysioExperiment(
  assays = list(raw = matrix(rnorm(400), nrow = 100, ncol = 4)),
  colData = S4Vectors::DataFrame(label = c("Fz", "Cz", "Pz", "Oz")),
  samplingRate = 100
)

# Apply 10-20 system positions
pe <- applyMontage(pe, "10-20")
getElectrodePositions(pe)

Description

Converts the default assay of a PhysioExperiment to a data.frame with a time column (in seconds) followed by one column per channel.

Usage

## S4 method for signature 'PhysioExperiment'
as.data.frame(x, row.names = NULL, optional = FALSE, ...)

Arguments

Value

A data.frame with a time column and one column per channel. For 3D arrays, only the first sample (third dimension index 1) is returned. Returns an empty data.frame if no assays are present.

References

Huber, W., et al. (2015). "Orchestrating high-throughput genomic analysis with Bioconductor." Nature Methods, 12(2), 115-121. doi:10.1038/nmeth.3252

Morgan, M., et al. (2022). "S4Vectors: Foundation of vector-like and list-like containers in Bioconductor." R package.

See Also

summary,PhysioExperiment-method for summary statistics, timeIndex for the time vector, channelNames for column names

Examples

pe <- PhysioExperiment(
  assays = list(raw = matrix(rnorm(12), nrow = 3, ncol = 4)),
  colData = S4Vectors::DataFrame(label = c("Fz", "Cz", "Pz", "Oz")),
  samplingRate = 100
)
df <- as.data.frame(pe)
head(df)

Description

Flattens every field - value, unit, CI, reference range, reliability (ICC/SEM/MDC), and provenance (assay/band/method/software version) - into a single row so biomarkers tabulate and round-trip losslessly.

Usage

## S3 method for class 'PhysioBiomarker'
as.data.frame(x, row.names = NULL, optional = FALSE, ...)

Arguments

Value

A one-row data.frame with the flattened fields.

Description

Builds the per-visit metric matrix and wraps it as an MSKLongitudinalTracker (its activation_series), so PhysioMSKNet's mskMinimalDetectableChange() and mskRecoveryTrajectoryFit() can consume the container output directly (metrics play the role of "muscles", visits the role of timepoints).

Usage

asMSKTracker(long, metric_fn, metric_name = "metric")

Arguments

Value

An object of class "MSKLongitudinalTracker" carrying the metric-by-visit matrix.

See Also

changeScores

Examples

mk <- function(m) PhysioExperiment(
  S4Vectors::SimpleList(raw = matrix(m, 10, 2)), samplingRate = 100)
pl <- PhysioLongitudinal(baseline = mk(1), mid = mk(2), discharge = mk(3))
tr <- asMSKTracker(pl, function(e) mean(SummarizedExperiment::assay(e, "raw")))
dim(tr$activation_series)

Description

Requires the MultiAssayExperiment package. Each session becomes an experiment (named by session_id); the design schema and subject metadata are stored in the result's metadata().

Usage

asMultiAssayExperiment(x)

Arguments

Value

A MultiAssayExperiment.

See Also

PhysioLongitudinal

Description

Returns the sampling rate associated with each assay of a PhysioExperiment. If no per-assay rates have been recorded, all assays are assumed to share the object's main samplingRate.

Usage

assaySamplingRates(x)

Arguments

Details

For genuinely multi-rate acquisitions (streams of different length) prefer the MultiRatePhysioExperiment container; assaySamplingRates() is the lightweight per-assay tag for single-object, equal-length assays.

Value

A named numeric vector of sampling rates (Hz), one per assay.

References

Crochiere, R. E. & Rabiner, L. R. (1983). Multirate Digital Signal Processing. Prentice Hall.

See Also

setAssaySamplingRate, MultiRatePhysioExperiment

Examples

pe <- PhysioExperiment(
  S4Vectors::SimpleList(raw = matrix(rnorm(20), 10, 2)), samplingRate = 100)
assaySamplingRates(pe)

Description

Performs a Bland-Altman analysis comparing two measurement methods or two time points. Computes the bias (mean difference), limits of agreement, and confidence interval for the bias.

Usage

blandAltman(x, y, confidence = 0.95)

Arguments

Details

The Bland-Altman method assesses agreement between two measurements by plotting their difference against their mean. The limits of agreement are:

$LoA = \bar{d} \pm z \times SD_d$

where $\bar{d}$ is the mean difference (bias) and $SD_d$ is the SD of differences.

Value

A list with components:

bias

Mean difference (x - y)

lower_loa

Lower limit of agreement

upper_loa

Upper limit of agreement

sd_diff

Standard deviation of differences

ci_bias

Two-element vector with lower and upper CI for the bias

References

Bland JM, Altman DG (1986). Statistical methods for assessing agreement between two methods of clinical measurement. Lancet, 327(8476), 307-310.

See Also

icc() for intraclass correlation reliability analysis, benchmarkAgreement() for benchmark validation agreement metrics, and plotBlandAltman() in the PhysioMoCap package to visualize the agreement.

Examples

set.seed(42)
method1 <- rnorm(30, mean = 50, sd = 10)
method2 <- method1 + rnorm(30, mean = 0, sd = 3)
result <- blandAltman(method1, method2)
result$bias
result$lower_loa
result$upper_loa

Description

Combines two PhysioExperiment objects by concatenating along the channel (column) dimension. Both objects must have the same number of time points and matching sampling rates.

Usage

cbindPhysio(x, y)

Arguments

Value

A PhysioExperiment object with channels from both x and y, combined colData, and metadata from x.

References

Huber, W., et al. (2015). "Orchestrating high-throughput genomic analysis with Bioconductor." Nature Methods, 12(2), 115-121. doi:10.1038/nmeth.3252

Morgan, M., et al. (2022). "S4Vectors: Foundation of vector-like and list-like containers in Bioconductor." R package.

See Also

rbindPhysio for combining along the time axis, pickChannels for selecting specific channels, dropChannels for removing channels

Examples

pe1 <- PhysioExperiment(
  assays = list(raw = matrix(rnorm(200), nrow = 100, ncol = 2)),
  colData = S4Vectors::DataFrame(label = c("Fz", "Cz")),
  samplingRate = 100
)
pe2 <- PhysioExperiment(
  assays = list(raw = matrix(rnorm(200), nrow = 100, ncol = 2)),
  colData = S4Vectors::DataFrame(label = c("Pz", "Oz")),
  samplingRate = 100
)

# Combine channels
pe_combined <- cbindPhysio(pe1, pe2)
nChannels(pe_combined)  # 4

Description

Applies a user metric to every session of a PhysioLongitudinal and reports each visit's change from the baseline visit, optionally flagged against a minimal-detectable-change (MDC) threshold.

Usage

changeScores(
  long,
  metric_fn,
  baseline = NULL,
  method = c("absolute", "percent", "z"),
  mdc = NULL,
  metric_name = "metric"
)

Arguments

Value

A tidy DataFrame with columns subject, visit, days_from_baseline, metric, value, delta_from_baseline, exceeds_mdc.

References

Beckerman, H., et al. (2001). Smallest real difference, a link between reproducibility and responsiveness. Quality of Life Research, 10(7), 571-578.

See Also

asMSKTracker, PhysioLongitudinal

Examples

mk <- function(m) PhysioExperiment(
  S4Vectors::SimpleList(raw = matrix(m, 10, 2)), samplingRate = 100)
pl <- PhysioLongitudinal(
  baseline = mk(1), discharge = mk(3),
  design = S4Vectors::DataFrame(
    session_id = c("baseline", "discharge"),
    visit_label = c("baseline", "discharge"),
    days_from_baseline = c(0, 42)))
changeScores(pl, function(e) mean(SummarizedExperiment::assay(e, "raw")))

Description

Functions for managing channel metadata including labels, types, units, and electrode positions. Get channel information

Usage

channelInfo(x)

Arguments

Details

Returns channel metadata as a DataFrame. Channel information is stored in colData (columns = channels).

Value

A DataFrame with channel information.

References

Oostenveld R, Fries P, Maris E, Schoffelen JM (2011). "FieldTrip: Open source software for advanced analysis of MEG, EEG, and invasive electrophysiological data." Computational Intelligence and Neuroscience, 2011, 156869.

See Also

channelNames for channel labels, nChannels for channel count, setChannelTypes for assigning channel types

Examples

pe <- PhysioExperiment(
  assays = list(raw = matrix(rnorm(400), nrow = 100, ncol = 4)),
  colData = S4Vectors::DataFrame(
    label = c("Fz", "Cz", "Pz", "Oz"),
    type = rep("EEG", 4)
  ),
  samplingRate = 100
)

# Get channel information
channelInfo(pe)

# Get channel names
channelNames(pe)

# Get number of channels
nChannels(pe)

Description

Updates channel metadata. Channel information is stored in colData (columns = channels).

Usage

channelInfo(x) <- value

Arguments

Value

Modified PhysioExperiment object.

References

Oostenveld R, Fries P, Maris E, Schoffelen JM (2011). "FieldTrip: Open source software for advanced analysis of MEG, EEG, and invasive electrophysiological data." Computational Intelligence and Neuroscience, 2011, 156869.

See Also

channelInfo for reading channel metadata, channelNames for channel labels, setChannelTypes for assigning channel types

Examples

pe <- PhysioExperiment(
  assays = list(raw = matrix(rnorm(400), nrow = 100, ncol = 4)),
  samplingRate = 100
)

# Set channel info
channelInfo(pe) <- S4Vectors::DataFrame(
  label = c("Fz", "Cz", "Pz", "Oz"),
  type = rep("EEG", 4)
)

Description

Get channel names/labels

Usage

channelNames(x)

Arguments

Value

Character vector of channel names.

References

Oostenveld R, Fries P, Maris E, Schoffelen JM (2011). "FieldTrip: Open source software for advanced analysis of MEG, EEG, and invasive electrophysiological data." Computational Intelligence and Neuroscience, 2011, 156869.

See Also

channelInfo for full channel metadata, renameChannels for renaming channels, nChannels for channel count

Examples

pe <- PhysioExperiment(
  assays = list(raw = matrix(rnorm(400), nrow = 100, ncol = 4)),
  colData = S4Vectors::DataFrame(label = c("Fz", "Cz", "Pz", "Oz")),
  samplingRate = 100
)
channelNames(pe)  # c("Fz", "Cz", "Pz", "Oz")

Description

Set channel names/labels

Usage

channelNames(x) <- value

Arguments

Value

Modified PhysioExperiment object.

References

Oostenveld R, Fries P, Maris E, Schoffelen JM (2011). "FieldTrip: Open source software for advanced analysis of MEG, EEG, and invasive electrophysiological data." Computational Intelligence and Neuroscience, 2011, 156869.

See Also

channelNames for reading channel labels, renameChannels for renaming specific channels, channelInfo for full channel metadata

Examples

pe <- PhysioExperiment(
  assays = list(raw = matrix(rnorm(400), nrow = 100, ncol = 4)),
  samplingRate = 100
)
channelNames(pe) <- c("Fz", "Cz", "Pz", "Oz")
channelNames(pe)

Description

Validates assay data for NA values and reports statistics.

Usage

checkNA(x, action = c("warn", "error", "none"))

Arguments

Value

Invisibly returns a list with NA statistics.

References

Oostenveld R, Fries P, Maris E, Schoffelen JM (2011). "FieldTrip: Open source software for advanced analysis of MEG, EEG, and invasive electrophysiological data." Computational Intelligence and Neuroscience, 2011, 156869.

See Also

hasNA for quick NA presence check, naSummary for per-assay NA statistics, handleNA for NA replacement strategies

Examples

pe <- PhysioExperiment(
  assays = list(raw = matrix(c(1, NA, 3, 4), nrow = 2)),
  samplingRate = 100
)
checkNA(pe)

Description

The association between an angular variable (e.g. a coupling angle or relative phase) and a linear one (e.g. speed, force, a clinical score). Symmetric under rotation of the angle.

Usage

circularLinearCorrelation(theta, x, units = c("degrees", "radians"))

Arguments

Value

an htest: the circular-linear correlation r (estimate), the test statistic n * r^2 ~ chi-square(2) and its p.value.

References

Mardia KV (1976); Zar JH (1999) eq. 27.19.

See Also

circularSummary()

Examples

set.seed(3); th <- runif(60, 0, 360); y <- cos(th * pi / 180) + rnorm(60, 0, 0.3)
circularLinearCorrelation(th, y)$estimate            # strong association

Description

The mean direction of a set of angles and its circular spread, computed via the resultant vector (so the wrap-around at 0/360 is handled correctly).

Usage

circularSummary(angles, units = c("degrees", "radians"))

Arguments

Value

a circular_summary list: mean (mean direction), R (resultant length), rbar (mean resultant length in [0,1]), variance (1 - rbar), sd (circular SD), kappa (von Mises concentration), all in the input units where applicable.

References

Zar JH (1999) Biostatistical Analysis, ch. 26-27.

See Also

rayleighTest(), circularLinearCorrelation()

Examples

circularSummary(c(10, 20, 350, 355))$mean        # ~ 0, not ~180

Description

Computes Cohen's d effect size for comparing two groups or conditions, with confidence intervals and qualitative interpretation.

Usage

cohensD(x, y, paired = FALSE, pooled = TRUE)

Arguments

Details

For independent groups with pooled = TRUE, the pooled SD is:

$SD_{pooled} = \sqrt{\frac{(n_1 - 1) s_1^2 + (n_2 - 1) s_2^2}{n_1 + n_2 - 2}}$

For paired data, the denominator is the SD of the within-pair differences.

Interpretation thresholds follow Cohen (1988):

• |d| < 0.2: negligible

• 0.2 <= |d| < 0.5: small

• 0.5 <= |d| < 0.8: medium

• |d| >= 0.8: large

Value

A list with components:

d

Cohen's d value

ci_lower

Lower bound of 95 percent confidence interval

ci_upper

Upper bound of 95 percent confidence interval

interpretation

Qualitative label: "negligible", "small", "medium", or "large"

References

Cohen J (1988). Statistical Power Analysis for the Behavioral Sciences. Lawrence Erlbaum Associates.

See Also

etaSquared() for ANOVA-based effect sizes, plotEffectSizeForest() for forest plot visualization of effect sizes.

Examples

set.seed(42)
x <- rnorm(30, mean = 10, sd = 2)
y <- rnorm(30, mean = 8, sd = 2)
result <- cohensD(x, y)
result$d
result$interpretation

Description

Subject-level metadata table of a PhysioCohort

Usage

cohortData(x)

## S4 method for signature 'PhysioCohort'
cohortData(x)

cohortData(x) <- value

## S4 replacement method for signature 'PhysioCohort'
cohortData(x) <- value

Arguments

Value

cohortData() the subject-level DataFrame.

Description

Flattens the whole cohort into one tidy data.frame with a row per (subject, session): subject_id, any subject-level colData (e.g. group), and the session's session_id, visit_label, days_from_baseline and condition. This is the iteration unit for pipelines, longitudinal models and trial analyses.

Usage

cohortDesign(x)

Arguments

Value

A data.frame, one row per subject-session.

See Also

PhysioCohort, cohortData

Description

Lists the trials of every subject, carrying both the subject and the session. The same trial_id under two subjects has to stay distinguishable, which is why the subject travels with the row rather than being inferred.

Usage

cohortTrials(x)

Arguments

Value

A data frame of trials with subject and session columns.

See Also

subjectTrials

Description

The shared clock

Usage

commonClock(x)

Arguments

Value

The clock list (t0, reference_rate, offsets, offsets_assumed, schema).

Description

Returns the name of the first assay in the PhysioExperiment object, which is treated as the default assay for operations that do not specify an assay explicitly.

Usage

defaultAssay(x)

Arguments

Value

Character scalar naming the first assay, or NA_character_ when no assays are present.

References

Huber, W., et al. (2015). "Orchestrating high-throughput genomic analysis with Bioconductor." Nature Methods, 12(2), 115-121. doi:10.1038/nmeth.3252

Morgan, M., et al. (2022). "S4Vectors: Foundation of vector-like and list-like containers in Bioconductor." R package.

See Also

PhysioExperiment for the constructor, samplingRate for the sampling rate accessor, timeIndex for time point vector

Examples

pe <- PhysioExperiment(
  assays = list(raw = matrix(rnorm(100), nrow = 10), filtered = matrix(0, 10, 10)),
  samplingRate = 250
)
defaultAssay(pe)

Description

Usage

deprecate_physio(
  when,
  what,
  with = NULL,
  details = NULL,
  severity = c("warn", "stop"),
  id = NULL
)

Arguments

Details

A thin, ecosystem-wide wrapper over lifecycle::deprecate_warn() and lifecycle::deprecate_stop() so every Physio package signals deprecations the same way. Use severity = "warn" during the deprecation window and switch to severity = "stop" once the item is defunct. See the ecosystem DEPRECATION.md policy for the lifecycle stages and the minimum window.

Value

Called for its side effect (a warning or an error); invisibly returns NULL.

See Also

lifecycle::deprecate_warn(), lifecycle::deprecate_stop()

Examples

old_fn <- function(x) {
  deprecate_physio("0.3.0", "old_fn()", with = "new_fn()")
  x
}
# Warnings are shown once per session by default; force them for testing with
# options(lifecycle_verbosity = "warning").

Description

A method for the BiocGenerics design generic, so it composes cleanly with the rest of the Bioconductor ecosystem.

Usage

## S4 method for signature 'PhysioLongitudinal'
design(object, ...)

## S4 replacement method for signature 'PhysioLongitudinal'
design(object, ...) <- value

Arguments

Value

design() the design DataFrame.

Description

A step between consecutive sample times larger than gap_factor times the nominal period counts as a gap. The factor is an adopted criterion – it separates acquisition jitter from a dropped sample; it does not prove that no gap exists – and it is the same criterion PhysioCrossModal uses to refuse interpolating across one.

Usage

detectGaps(times, rate, gap_factor = 1.5, window = NULL, tolerance = NULL)

Arguments

Details

Detection runs on the whole series before any window is applied, and the window then selects which gaps to report. Selecting samples first and differencing afterwards loses exactly the gaps that matter most: a dropout straddling a window's edge has one of its two bounding samples outside the window, so the step across it is never formed and the window looks intact.

A gap that only touches an endpoint of the window is not in it. On a closed interval the two share a single instant, and the recording does cover that instant – the same reading of "touching is not overlapping" that trialIntervals uses.

Value

A data frame of start and end – the sample times the gap lies between, in the original series, not clipped to window.

See Also

streamCoverage, timeWindow

Examples

detectGaps(c(0, 0.1, 0.2, 0.4, 0.5), rate = 10)
# the same gap, found from a window whose edge cuts through it
detectGaps(c(0, 0.1, 0.2, 0.4, 0.5), rate = 10, window = c(0.25, 0.45))

Description

Returns the dimensions of the default assay.

Usage

## S4 method for signature 'PhysioExperiment'
dim(x)

Arguments

Value

An integer vector of dimensions (time points by channels by samples for 3D data), or NULL if no assays are present.

References

Huber, W., et al. (2015). "Orchestrating high-throughput genomic analysis with Bioconductor." Nature Methods, 12(2), 115-121. doi:10.1038/nmeth.3252

Morgan, M., et al. (2022). "S4Vectors: Foundation of vector-like and list-like containers in Bioconductor." R package.

See Also

length,PhysioExperiment-method for time point count, nChannels for channel count, defaultAssay for the assay being queried

Examples

pe <- PhysioExperiment(
  assays = list(raw = matrix(rnorm(400), nrow = 100, ncol = 4)),
  samplingRate = 100
)
dim(pe)  # 100 4

Description

Creates a new PhysioExperiment without specified channels.

Usage

dropChannels(x, channels)

Arguments

Value

A new PhysioExperiment without specified channels.

References

Oostenveld R, Fries P, Maris E, Schoffelen JM (2011). "FieldTrip: Open source software for advanced analysis of MEG, EEG, and invasive electrophysiological data." Computational Intelligence and Neuroscience, 2011, 156869.

See Also

pickChannels for keeping specific channels, getChannelsByType for finding channels by type, nChannels for channel count

Examples

pe <- PhysioExperiment(
  assays = list(raw = matrix(rnorm(400), nrow = 100, ncol = 4)),
  colData = S4Vectors::DataFrame(label = c("Fz", "Cz", "Pz", "Oz")),
  samplingRate = 100
)

# Drop by index
pe_dropped <- dropChannels(pe, 1)
nChannels(pe_dropped)  # 3

# Drop by name
pe_dropped <- dropChannels(pe, c("Fz", "Oz"))

Description

Computes the total duration of the signal in seconds from the number of time points and the sampling rate.

Usage

duration(x)

Arguments

Value

Numeric scalar giving the signal duration in seconds, or NA_real_ if the sampling rate is not set.

References

Huber, W., et al. (2015). "Orchestrating high-throughput genomic analysis with Bioconductor." Nature Methods, 12(2), 115-121. doi:10.1038/nmeth.3252

Morgan, M., et al. (2022). "S4Vectors: Foundation of vector-like and list-like containers in Bioconductor." R package.

See Also

samplingRate for the sampling rate, length,PhysioExperiment-method for time point count, timeIndex for the time vector, extractWindow for time-based subsetting

Examples

pe <- PhysioExperiment(
  assays = list(raw = matrix(rnorm(1000), nrow = 1000, ncol = 4)),
  samplingRate = 100
)
duration(pe)  # 10 seconds

Description

Returns the seconds between the starts of two independently recorded trials.

Usage

elapsedBetweenTrials(x, from, to)

Arguments

Details

This is refused unless the recordings are actually placed relative to one another. Declaring time_correspondence = "measured" is not enough: the rows must also carry a reference and an offset, and both trials must be measured against the same reference, since offsets on different references are not comparable. "order_only" and "unknown" are refused outright - the order in which recordings were made is not a duration, and turning one into the other would fabricate a measurement.

An absent absolute origin (clock$t0 of NA) is a different matter and does not block this: what is needed is the correspondence between recordings, not an absolute time.

Value

Numeric seconds from from to to.

See Also

recordingMap

Description

Computes eta-squared, partial eta-squared, and omega-squared from a one-way between-subjects comparison.

Usage

etaSquared(x, groups)

Arguments

Details

Eta-squared is the proportion of total variance explained by group membership:

$\eta^2 = \frac{SS_{between}}{SS_{total}}$

Omega-squared provides a less biased estimate:

$\omega^2 = \frac{SS_{between} - df_{between} \cdot MS_{within}}{SS_{total} + MS_{within}}$

For one-way designs, partial eta-squared equals eta-squared.

Value

A list with components:

eta_sq

Eta-squared (SS_between / SS_total)

partial_eta_sq

Partial eta-squared (SS_between / (SS_between + SS_within))

omega_sq

Omega-squared (bias-corrected effect size)

References

Cohen J (1988). "Statistical Power Analysis for the Behavioral Sciences." Lawrence Erlbaum Associates.

See Also

cohensD() for pairwise effect sizes, plotEffectSizeForest() for forest plot visualization.

Examples

set.seed(42)
x <- c(rnorm(20, 10, 2), rnorm(20, 12, 2), rnorm(20, 14, 2))
groups <- rep(c("A", "B", "C"), each = 20)
result <- etaSquared(x, groups)
result$eta_sq

Description

Create an EventQuery from a PhysioExperiment

Usage

eventQuery(x)

Arguments

Value

An EventQuery object

Examples

pe <- PhysioExperiment(assays = list(raw = matrix(rnorm(400), 100, 4)),
                       samplingRate = 100)
pe <- addEvents(pe, onset = c(1, 2, 3), type = "stimulus")
q <- eventQuery(pe)

Description

EventQuery class for composable event filtering

Slots

source

PhysioExperiment object

filters

List of filter functions to apply

resolved

Cached resolved events (NULL if not yet resolved)

Description

Applies named feature functions to each selected trial and channel. Accepts the same recording and hierarchy inputs as aggregateTrialWaveforms(). Trial selection, time-based sample selection, channel matching and assembly of the feature table are performed together. Pass the returned object to aggregatePhysioFeatures() to obtain session, subject or cohort summaries.

Usage

extractTrialFeatures(
  x,
  stream,
  FUN,
  assay = "raw",
  channels = NULL,
  strata = NULL,
  include = "complete",
  gap_factor = 1.5,
  ...
)

Arguments

Details

Sample membership uses the measured time index and the same boundary tolerance as timeWindow(). Samples are neither interpolated nor resampled. For explicitly included partial trials, features describe the available samples inside the retained interval; these can differ in duration between trials. Included trials with unusable retained gap evidence are refused. Trials lacking the requested stream or interval are recorded as excluded. A recording without a trial table, ambiguous identity, an incompatible assay/channel set, an empty selected interval, or a failed feature function causes an error.

Temporal coverage does not establish signal quality. Missing values are passed to the feature function; returned NA values remain in the table and require explicit handling when aggregating. Infinite input samples and infinite feature results are rejected. Feature-function text and supplied arguments are recorded, but arbitrary external state used by a callback is not captured; use self-contained functions and explicit arguments.

Correspondence is established by channel names. Comparable units and feature definitions remain the caller's responsibility. The returned checksum detects modification of the extraction result before aggregation, and references are preserved when continuing aggregation through further levels.

Value

A physio_trial_features list containing data (one row per selected trial and channel), trials (all trial selections and reasons), source_map (one entry per feature-table row: recording, interval, original sample indices and sample times), source_hashes (full input recording hashes), features, strata, settings and checksum. Input containers are not modified.

See Also

aggregatePhysioFeatures, aggregateTrials, aggregateTrialWaveforms

Examples

pe <- PhysioExperiment(assays = list(raw = matrix(0:30, ncol = 1,
  dimnames = list(NULL, "signal"))), samplingRate = 10)
m <- MultiPhysioExperiment(sensor = pe)
trials(m) <- data.frame(subject_id = "P1", session_id = "S1",
                        trial_id = c("T1", "T2"))
trialIntervals(m) <- data.frame(trials(m)[1:3], recording_id = "R1",
  stream = "sensor", start = c(0, 2), end = c(1, 3))
f <- extractTrialFeatures(m, "sensor", FUN = list(amplitude = mean))
f$data
aggregatePhysioFeatures(f, "session")$data # mean(c(5, 25)) = 15

Description

Extracts a time window from the signal based on start and end times in seconds.

Usage

extractWindow(x, tmin, tmax)

Arguments

Value

A PhysioExperiment object containing only the samples within the specified time window, with preserved channel and event metadata.

References

Huber, W., et al. (2015). "Orchestrating high-throughput genomic analysis with Bioconductor." Nature Methods, 12(2), 115-121. doi:10.1038/nmeth.3252

Morgan, M., et al. (2022). "S4Vectors: Foundation of vector-like and list-like containers in Bioconductor." R package.

See Also

duration for total signal duration, timeIndex for the time vector, [ forindex-based subsetting, timeToSamples for converting times to indices

Examples

pe <- PhysioExperiment(
  assays = list(raw = matrix(rnorm(1000), nrow = 1000, ncol = 4)),
  samplingRate = 100
)

# Extract 2 to 5 seconds
pe_window <- extractWindow(pe, tmin = 2, tmax = 5)
duration(pe_window)  # approximately 3 seconds

Description

Fills NA values at the beginning and end of a signal that may result from filtering operations.

Usage

fillEdgeNA(x, method = c("extend", "zero"))

Arguments

Value

Vector with edge NA values filled.

References

Oostenveld R, Fries P, Maris E, Schoffelen JM (2011). "FieldTrip: Open source software for advanced analysis of MEG, EEG, and invasive electrophysiological data." Computational Intelligence and Neuroscience, 2011, 156869.

See Also

handleNA for general NA handling strategies, replaceNA for NA handling in PhysioExperiment assays

Examples

x <- c(NA, NA, 1, 2, 3, NA, NA)
fillEdgeNA(x, method = "extend")

Description

Filter events by type

Usage

filterType(q, types)

Arguments

Value

Modified EventQuery

Examples

pe <- PhysioExperiment(assays = list(raw = matrix(rnorm(400), 100, 4)),
                       samplingRate = 100)
pe <- addEvents(pe, onset = c(1, 2, 3),
                type = c("stimulus", "response", "stimulus"))
q <- filterType(eventQuery(pe), "stimulus")
resolveQuery(q)

Description

Filter events by value

Usage

filterValue(q, values)

Arguments

Value

Modified EventQuery

Examples

pe <- PhysioExperiment(assays = list(raw = matrix(rnorm(400), 100, 4)),
                       samplingRate = 100)
pe <- addEvents(pe, onset = c(1, 2, 3), type = "stimulus",
                value = c("target", "distractor", "target"))
q <- filterValue(eventQuery(pe), "target")
resolveQuery(q)

Description

Format a PhysioBiomarker as a compact string

Usage

## S3 method for class 'PhysioBiomarker'
format(x, ...)

Arguments

Value

A length-1 character string "name = value unit [ci]".

Description

Functions for functional data analysis including functional PCA (fPCA), functional regression, and curve registration. These methods treat biomechanical waveforms as continuous functions. Functional Principal Component Analysis (fPCA)

Usage

fPCA(x, n_components = 5, smooth = FALSE, smooth_param = 10)

Arguments

Details

Performs functional PCA on waveform data to identify the main modes of variation in movement patterns.

fPCA decomposes waveform variability into orthogonal modes. In gait analysis, PC1 often represents overall amplitude, PC2 timing/phase shifts, and subsequent PCs capture more subtle shape variations.

Value

A list of class "fpca_result" containing:

References

Ramsay JO, Silverman BW (2005). "Functional Data Analysis." 2nd ed. Springer.

See Also

reconstructFPCA() for waveform reconstruction from fPCA results, plotFPCA() (in PhysioMoCap) for visualization of fPCA results, registerCurves() for separating phase and amplitude variation.

Examples

# Simulate gait angle data (100 time points x 30 subjects)
set.seed(123)
t <- seq(0, 100, length.out = 100)
base_curve <- sin(2 * pi * t / 100) * 30

# Add subject variability
data <- sapply(1:30, function(i) {
  amplitude <- rnorm(1, 1, 0.2)
  phase <- rnorm(1, 0, 5)
  base_curve * amplitude + rnorm(100, 0, 2)
})

pe <- PhysioExperiment(assays = list(values = data), samplingRate = 100)
fpca_result <- fPCA(pe, n_components = 4)

Description

Returns indices of channels matching specified types.

Usage

getChannelsByType(x, types)

Arguments

Value

Integer vector of matching channel indices.

References

Oostenveld R, Fries P, Maris E, Schoffelen JM (2011). "FieldTrip: Open source software for advanced analysis of MEG, EEG, and invasive electrophysiological data." Computational Intelligence and Neuroscience, 2011, 156869.

See Also

setChannelTypes for assigning channel types, pickChannels for subsetting by channel, dropChannels for removing channels

Examples

pe <- PhysioExperiment(
  assays = list(raw = matrix(rnorm(400), nrow = 100, ncol = 4)),
  colData = S4Vectors::DataFrame(
    label = c("Fz", "EOG1", "EMG1", "Oz"),
    type = c("EEG", "EOG", "EMG", "EEG")
  ),
  samplingRate = 100
)

# Get EEG channels
eeg_idx <- getChannelsByType(pe, "EEG")  # c(1, 4)

Description

Get electrode positions

Usage

getElectrodePositions(x)

Arguments

Value

A data.frame with x, y, z columns or NULL if not set.

References

Oostenveld R, Fries P, Maris E, Schoffelen JM (2011). "FieldTrip: Open source software for advanced analysis of MEG, EEG, and invasive electrophysiological data." Computational Intelligence and Neuroscience, 2011, 156869.

See Also

setElectrodePositions for setting positions, applyMontage for standard electrode layouts, channelNames for channel labels

Examples

pe <- PhysioExperiment(
  assays = list(raw = matrix(rnorm(300), nrow = 100, ncol = 3)),
  colData = S4Vectors::DataFrame(label = c("Fz", "Cz", "Pz")),
  samplingRate = 100
)
pe <- applyMontage(pe, "10-20")
getElectrodePositions(pe)

Description

Get events from a PhysioExperiment object

Usage

getEvents(x, type = NULL)

Arguments

Value

A PhysioEvents object or DataFrame of events.

References

Delorme A, Makeig S (2004). "EEGLAB: an open source toolbox for analysis of single-trial EEG dynamics." Journal of Neuroscience Methods, 134(1), 9-21.

Oostenveld R, Fries P, Maris E, Schoffelen JM (2011). "FieldTrip: Open source software for advanced analysis of MEG, EEG, and invasive electrophysiological data." Computational Intelligence and Neuroscience, 2011, 156869.

See Also

setEvents for attaching events, addEvents for appending events, removeEvents for removing events, nEvents for event count

Examples

# Create PhysioExperiment with events
pe <- PhysioExperiment(
  assays = list(raw = matrix(rnorm(1000), nrow = 100)),
  samplingRate = 100
)
events <- PhysioEvents(
  onset = c(1, 2, 3),
  type = c("stimulus", "response", "stimulus")
)
pe <- setEvents(pe, events)

# Get all events
getEvents(pe)

# Get only stimulus events
getEvents(pe, type = "stimulus")

Description

Get reference electrode

Usage

getReference(x)

Arguments

Value

Character string of reference electrode or NULL.

References

Oostenveld R, Fries P, Maris E, Schoffelen JM (2011). "FieldTrip: Open source software for advanced analysis of MEG, EEG, and invasive electrophysiological data." Computational Intelligence and Neuroscience, 2011, 156869.

See Also

setReference for setting the reference, channelInfo for full channel metadata

Examples

pe <- PhysioExperiment(
  assays = list(raw = matrix(rnorm(400), nrow = 100, ncol = 4)),
  samplingRate = 100
)
pe <- setReference(pe, "Cz")
getReference(pe)  # "Cz"

Description

Provides various strategies for handling NA values in signal data.

Usage

handleNA(
  x,
  method = c("interpolate", "omit", "zero", "mean", "locf", "none"),
  ...
)

Arguments

Value

Data with NA values handled according to the specified method.

References

Oostenveld R, Fries P, Maris E, Schoffelen JM (2011). "FieldTrip: Open source software for advanced analysis of MEG, EEG, and invasive electrophysiological data." Computational Intelligence and Neuroscience, 2011, 156869.

See Also

replaceNA for handling NA in PhysioExperiment assays, fillEdgeNA for edge-specific NA filling, checkNA for NA validation

Examples

x <- c(1, NA, 3, NA, 5)

# Linear interpolation
handleNA(x, method = "interpolate")

# Replace with mean
handleNA(x, method = "mean")

# Last observation carried forward
handleNA(x, method = "locf")

Description

Convenience wrapper that runs harmonizeChannels, harmonizeReference and harmonizeMontage in turn. Pass ref = NULL or system = NULL to skip a step.

Usage

harmonize(
  long,
  target_labels = NULL,
  rename = NULL,
  ref = "average",
  system = "10-20"
)

Arguments

Value

A fully harmonized PhysioLongitudinal.

See Also

harmonizeReport

Description

Intersects and reorders the channels of every session of a PhysioLongitudinal so they share one common channel set in identical order. Channels absent from any session are dropped; an optional rename map first unifies differing label conventions.

Usage

harmonizeChannels(long, target_labels = NULL, rename = NULL)

Arguments

Value

The PhysioLongitudinal with harmonized sessions; each session records the kept/dropped/renamed channels and a provenance activity.

See Also

harmonize, harmonizeReport, pickChannels

Examples

mk <- function(labs) PhysioExperiment(
  S4Vectors::SimpleList(raw = matrix(rnorm(50 * length(labs)), 50, length(labs))),
  colData = S4Vectors::DataFrame(label = labs), samplingRate = 100)
pl <- PhysioLongitudinal(
  baseline = mk(c("Fz", "Cz", "Pz", "Oz")),
  discharge = mk(c("Cz", "Fz", "Pz")))
h <- harmonizeChannels(pl)
channelNames(session(h, "baseline"))

Description

Applies a consistent electrode montage to every session (building on applyMontage).

Usage

harmonizeMontage(long, system = c("10-20", "10-10", "10-5"))

Arguments

Value

The PhysioLongitudinal with a common montage and a provenance activity on each session.

See Also

harmonize, applyMontage

Description

Records a common reference on every session (building on setReference), so that getReference is identical across sessions.

Usage

harmonizeReference(long, ref)

Arguments

Value

The PhysioLongitudinal with a common reference and a provenance activity on each session.

See Also

harmonize, setReference

Description

Report the channels dropped / renamed per session by harmonization

Usage

harmonizeReport(long)

Arguments

Value

A named list (one entry per session) with kept, dropped and renamed channels.

See Also

harmonizeChannels

Description

Regular streams put sample i at offset + (i - 1) / rate. A stream that carries measured timestamps - because the acquisition reported them, or because it has gaps or drift - is not on that grid, and operations that can only work with a regular grid must say so rather than approximate.

Usage

hasMeasuredTimes(x, stream = NULL)

Arguments

Value

Logical, named when stream is NULL.

See Also

streamTimeIndex

Description

Quick check for NA presence in PhysioExperiment data.

Usage

hasNA(x, assay_name = NULL)

Arguments

Value

Logical indicating presence of NA values.

References

Oostenveld R, Fries P, Maris E, Schoffelen JM (2011). "FieldTrip: Open source software for advanced analysis of MEG, EEG, and invasive electrophysiological data." Computational Intelligence and Neuroscience, 2011, 156869.

See Also

checkNA for detailed NA statistics, naSummary for per-assay NA summary, replaceNA for handling NA values

Examples

pe <- PhysioExperiment(
  assays = list(raw = matrix(1:4, nrow = 2)),
  samplingRate = 100
)
hasNA(pe)

Description

Computes the ICC using ANOVA-based methods following Shrout & Fleiss (1979). Supports one-way and two-way random/mixed models, agreement and consistency types, and single or average unit measures.

Usage

icc(
  ratings,
  model = c("twoway", "oneway"),
  type = c("agreement", "consistency"),
  unit = c("single", "average")
)

Arguments

Details

The function implements the six ICC forms from Shrout & Fleiss (1979):

• ICC(1,1): One-way random, single measures

• ICC(1,k): One-way random, average measures

• ICC(2,1): Two-way random, absolute agreement, single measures

• ICC(2,k): Two-way random, absolute agreement, average measures

• ICC(3,1): Two-way mixed, consistency, single measures

• ICC(3,k): Two-way mixed, consistency, average measures

Value

A list with components:

icc

ICC value

ci_lower

Lower bound of 95 percent confidence interval

ci_upper

Upper bound of 95 percent confidence interval

f_value

F statistic from ANOVA

p_value

p-value for testing ICC = 0

model

Model used

type

Agreement type used

References

Shrout PE, Fleiss JL (1979). Intraclass correlations: Uses in assessing rater reliability. Psychological Bulletin, 86(2), 420-428.

See Also

sem() for standard error of measurement based on ICC, mdc() for minimal detectable change, blandAltman() for agreement analysis between methods.

Examples

# Test-retest reliability
ratings <- matrix(c(
  9, 2, 5, 8,
  6, 1, 3, 2,
  8, 4, 6, 8,
  7, 1, 2, 6,
  10, 5, 6, 9,
  6, 2, 4, 7
), nrow = 6, ncol = 4, byrow = TRUE)

result <- icc(ratings, model = "twoway", type = "agreement")
result$icc

Description

Test whether an object is a PhysioBiomarker

Usage

is.PhysioBiomarker(x)

Arguments

Value

TRUE if x is a PhysioBiomarker, otherwise FALSE.

See Also

physioBiomarker()

Examples

is.PhysioBiomarker(physioBiomarker(1, "x"))
is.PhysioBiomarker(42)

Description

Returns the number of time points (rows) in the default assay.

Usage

## S4 method for signature 'PhysioExperiment'
length(x)

Arguments

Value

Integer scalar giving the number of time points (rows) in the default assay, or 0L if no assays are present.

References

Huber, W., et al. (2015). "Orchestrating high-throughput genomic analysis with Bioconductor." Nature Methods, 12(2), 115-121. doi:10.1038/nmeth.3252

Morgan, M., et al. (2022). "S4Vectors: Foundation of vector-like and list-like containers in Bioconductor." R package.

See Also

dim,PhysioExperiment-method for full dimensions, nChannels for the number of channels, duration for duration in seconds

Examples

pe <- PhysioExperiment(
  assays = list(raw = matrix(rnorm(400), nrow = 100, ncol = 4)),
  samplingRate = 100
)
length(pe)  # 100

Description

Appends a timestamped, agent-attributed PROV activity. Call this from any operation that returns a modified PhysioExperiment.

Usage

logStep(
  x,
  step,
  params = list(),
  package = NA_character_,
  version = NA_character_
)

Arguments

Value

x with the step appended (the input is unchanged; a modified copy is returned).

Examples

pe <- PhysioExperiment(
  S4Vectors::SimpleList(raw = matrix(rnorm(20), 10, 2)), samplingRate = 100)
pe <- logStep(pe, "filterSignals", params = list(low = 1, high = 40))
provenance(pe)

Description

Computes the minimal detectable change from the standard error of measurement.

Usage

mdc(sem_value, confidence = 0.95)

Arguments

Details

MDC is computed as:

$MDC = SEM \times z \times \sqrt{2}$

where $z = \Phi^{-1}(1 - (1 - confidence)/2)$.

At 95\

Value

Numeric MDC value.

References

Shrout PE, Fleiss JL (1979). "Intraclass Correlations: Uses in Assessing Rater Reliability." Psychological Bulletin, 86(2), 420-428.

See Also

sem() for computing standard error of measurement, icc() for computing intraclass correlation coefficients.

Examples

sem_val <- 2.5
mdc(sem_val, confidence = 0.95)

Description

Rebuilds a container saved when the multimodal class carried experiments / alignment / sampleMap / couplingResults into the unified MultiPhysioExperiment.

Usage

migrateContainer(object, verbose = TRUE)

## S4 method for signature 'MultiPhysioExperiment'
updateObject(object, ..., verbose = FALSE)

Arguments

Details

Two things are deliberately not converted:

• The old model had no absolute origin, so clock$t0 is set to NA rather than to a fabricated zero.

• sampleMap and the cached couplingResults have no counterpart in the unified model. They are carried into clock$migrated_from with their origin rather than dropped, and the cache is not reused: it was keyed without reference to the signals or the clock, so nothing here can show it still matches its inputs.

The declared sampling rates in the old alignment table are checked against the real streams; a disagreement is reported rather than silently resolved.

Value

A MultiPhysioExperiment.

See Also

readPhysioRDS

Examples

# round-trips a current object unchanged
m <- MultiPhysioExperiment(a = PhysioExperiment(
  assays = list(raw = matrix(0, 10, 2)), samplingRate = 10))
identical(migrateContainer(m), m)

Description

These are the names the container carried when it lived in PhysioCrossModal. They are kept so existing code runs unchanged and return the same types they always did: experiments() a plain named list (not a SimpleList), modalities() a character vector, samplingRates() a named numeric, nModalities() an integer.

Usage

experiments(x)

## S4 method for signature 'MultiPhysioExperiment'
experiments(x)

experiments(x) <- value

## S4 replacement method for signature 'MultiPhysioExperiment'
experiments(x) <- value

modalities(x)

## S4 method for signature 'MultiPhysioExperiment'
modalities(x)

samplingRates(x)

## S4 method for signature 'MultiPhysioExperiment'
samplingRates(x)

nModalities(x)

## S4 method for signature 'MultiPhysioExperiment'
nModalities(x)

alignment(x)

## S4 method for signature 'MultiPhysioExperiment'
alignment(x)

alignment(x) <- value

## S4 replacement method for signature 'MultiPhysioExperiment'
alignment(x) <- value

Arguments

Details

alignment() is a view computed from the clock, not a stored second copy. Assigning to it writes back into the clock, so the two can never disagree.

Value

As described above; setters return the modified object.

Description

Holds several PhysioExperiment streams on one shared clock. Nothing is resampled and no synchronisation is estimated.

MultiRatePhysioExperiment() is the former name, kept as a compatibility entry point. It builds the same container and returns the legacy subclass so that existing is() tests keep passing.

Usage

MultiPhysioExperiment(
  streams = list(),
  ...,
  t0 = 0,
  offsets = NULL,
  reference_rate = NULL,
  clock = NULL,
  experiments = NULL,
  alignment = NULL
)

MultiRatePhysioExperiment(
  streams = list(),
  ...,
  t0 = 0,
  offsets = NULL,
  reference_rate = NULL,
  clock = NULL,
  experiments = NULL,
  alignment = NULL
)

Arguments

Details

Omitting offsets declares that the streams started together; that assumption is recorded in the clock (offsets_assumed) rather than being indistinguishable from a measured alignment. A partially specified offsets is an error rather than being completed with zeros.

Value

A MultiPhysioExperiment.

See Also

streamRates, timeWindow, resampleToCommon

Examples

kin <- PhysioExperiment(
  S4Vectors::SimpleList(raw = matrix(rnorm(100 * 3), 100, 3)), samplingRate = 100)
emg <- PhysioExperiment(
  S4Vectors::SimpleList(raw = matrix(rnorm(2000 * 2), 2000, 2)), samplingRate = 2000)
mpe <- MultiPhysioExperiment(kinematics = kin, emg = emg)
streamRates(mpe)

# a measured alignment: EMG started 137 ms after the clock origin
MultiPhysioExperiment(streams = list(kinematics = kin, emg = emg),
                      offsets = c(kinematics = 0, emg = 0.137))

Description

MultiPhysioExperiment holds several PhysioExperiment streams recorded together - the classic motion-capture situation of, say, 100 Hz kinematics alongside 1000 Hz force-plate analog and 2000 Hz EMG, or the NWB TimeSeries / LSL-XDF / C3D POINT+ANALOG pattern. Streams that happen to share a sampling rate use the same class; nothing about it is specific to mixed rates.

Details

Each stream keeps its own sampling rate and length. The container adds one thing: a shared clock that says how the streams line up in time. There is deliberately no second alignment table - the clock is the single source of truth, and alignment is a view derived from it.

Construction never resamples and never estimates synchronisation. Holding the time correspondence and converting the signals onto a common grid (resampleToCommon) are separate steps.

Slots

streams

A SimpleList of named PhysioExperiment objects.

clock

A list describing the shared clock (see above).

The clock

t0

Origin of the shared clock, in seconds. NA means the recording has no known absolute origin; that absence is preserved rather than replaced by a fabricated zero.

offsets

Named numeric, one entry per stream, giving where each stream starts in seconds relative to t0. Negative values are allowed (a stream that started before the origin).

reference_rate

Default grid rate used when the signals are explicitly converted to a common rate. It never overrides a stream's own sampling rate.

offsets_assumed

TRUE when the offsets were not supplied and simultaneous start was assumed. A known common clock and an assumed one are different claims, so they are recorded differently.

schema

Integer schema version, for migration.

Extra elements are preserved untouched, which is where measured timestamps, gap records or drift corrections belong.

Sample i of a stream sits at offset + (i - 1) / samplingRate seconds relative to t0. streamTimeIndex returns exactly that and does not add t0.

See Also

MultiPhysioExperiment for the constructor, timeWindow, resampleToCommon, alignStreams

Description

Display, size and stream-extraction methods for MultiPhysioExperiment

Usage

## S4 method for signature 'MultiPhysioExperiment'
length(x)

## S4 method for signature 'MultiPhysioExperiment'
names(x)

## S4 method for signature 'MultiPhysioExperiment,ANY,ANY'
x[[i, j, ...]]

## S4 method for signature 'MultiPhysioExperiment'
dim(x)

## S4 method for signature 'MultiPhysioExperiment'
show(object)

Arguments

Value

length() the number of streams; dim() a matrix of per-stream c(nsamples, nchannels); [[ the selected PhysioExperiment stream; show() is called for its side effect.

Description

MultiRatePhysioExperiment is the former name of what is now MultiPhysioExperiment-class. It survives as an empty subclass so that objects saved under the old name keep loading, validating and dispatching, and so that code testing is(x, "MultiRatePhysioExperiment") keeps working. It adds no slots and no second clock model.

Details

New code should use MultiPhysioExperiment.

Description

Convenience wrapper around .fitMVAR that optionally selects the model order automatically via mvarOrderSelect.

Usage

mvarFit(
  X,
  order = NULL,
  method = c("ols", "yulewalker", "nuttall-strand"),
  max_order = 20L,
  criterion = c("bic", "aic")
)

Arguments

Value

An object of class "mvar": a list with A, Sigma, order, method, and n_channels.

See Also

mvarTransfer, mvarOrderSelect

Examples

set.seed(1)
X <- matrix(rnorm(600), ncol = 3)
fit <- mvarFit(X, order = 2)
dim(fit$A)

Description

Fits MVAR models over a range of orders and returns the order minimising the Akaike (AIC) or Bayesian (BIC) information criterion. For an m-channel model of order p with n effective samples the criteria are n log det(Sigma_p) + 2 m^2 p (AIC) and n log det(Sigma_p) + log(n) m^2 p (BIC).

Usage

mvarOrderSelect(
  X,
  max_order = 20L,
  criterion = c("bic", "aic"),
  method = c("ols", "yulewalker", "nuttall-strand")
)

Arguments

Value

A list with the selected order, the chosen criterion, and a data.frame criteria of order, aic, bic.

See Also

.fitMVAR, mvarFit

Description

Convenience wrapper around .mvarSpectral for a fitted "mvar" model.

Usage

mvarTransfer(fit, freqs, sr)

Arguments

Value

A list as returned by .mvarSpectral (H, S, A, frequencies).

See Also

mvarFit

Examples

set.seed(1)
X <- matrix(rnorm(600), ncol = 3)
fit <- mvarFit(X, order = 2)
sp <- mvarTransfer(fit, freqs = seq(1, 40, by = 1), sr = 100)
dim(sp$H)

Description

Returns a summary of NA values across all assays.

Usage

naSummary(x)

Arguments

Value

A data.frame with NA statistics for each assay.

References

Oostenveld R, Fries P, Maris E, Schoffelen JM (2011). "FieldTrip: Open source software for advanced analysis of MEG, EEG, and invasive electrophysiological data." Computational Intelligence and Neuroscience, 2011, 156869.

See Also

hasNA for quick NA check, checkNA for detailed NA validation, replaceNA for handling NA values

Examples

pe <- PhysioExperiment(
  assays = list(
    raw = matrix(c(1, NA, 3, 4), nrow = 2),
    filtered = matrix(1:4, nrow = 2)
  ),
  samplingRate = 100
)
naSummary(pe)

Description

Get number of channels

Usage

nChannels(x)

Arguments

Value

Integer number of channels.

References

Oostenveld R, Fries P, Maris E, Schoffelen JM (2011). "FieldTrip: Open source software for advanced analysis of MEG, EEG, and invasive electrophysiological data." Computational Intelligence and Neuroscience, 2011, 156869.

See Also

channelNames for channel labels, channelInfo for full channel metadata, pickChannels for subsetting channels

Examples

pe <- PhysioExperiment(
  assays = list(raw = matrix(rnorm(400), nrow = 100, ncol = 4)),
  samplingRate = 100
)
nChannels(pe)  # 4

Description

Get number of events

Usage

nEvents(x)

Arguments

Value

Integer count of events.

References

Delorme A, Makeig S (2004). "EEGLAB: an open source toolbox for analysis of single-trial EEG dynamics." Journal of Neuroscience Methods, 134(1), 9-21.

See Also

getEvents for retrieving events, PhysioEvents for the event constructor, addEvents for appending events

Examples

events <- PhysioEvents(onset = c(1, 2, 3), type = "stimulus")
nEvents(events)

Description

Compares an observed marker to seeded published normative reference values (read from inst/extdata/normative/*.csv), returning a z-score and percentile. This is a scaffold seeded with a few quantitative-EEG markers (delta-alpha ratio, brain symmetry index); extend the CSVs to add markers. When the marker, age band, or montage is unknown the z-score and percentile are returned as NA without raising an error.

Usage

normativeLookup(marker, age = NULL, montage = NULL)

Arguments

Value

A named list: marker, value, mean, sd, unit, source, z_score, percentile, and matched (logical). Unknown lookups return NA fields with matched = FALSE.

See Also

physioBiomarker(), NormativeReference(), zScore()

Examples

bm <- physioBiomarker(2.35, "DAR")
normativeLookup(bm, age = 40)
normativeLookup("UNKNOWN_MARKER")   # returns NA fields, no error

Description

Construct a NormativeReference

Usage

NormativeReference(
  metric,
  strata,
  source = NA_character_,
  version = NA_character_,
  unit = NA_character_
)

Arguments

Value

A NormativeReference object.

Examples

ref <- NormativeReference(
  "gait_speed",
  strata = data.frame(
    sex = c("M", "F"), mean = c(1.34, 1.24), sd = c(0.20, 0.19), n = c(50, 50)
  ),
  source = "Bohannon 2011", unit = "m/s"
)
zScore(ref, 1.10, by = list(sex = "M"))