Package 'PhysioMoCap'

Description

Computes the standard reach-to-grasp kinematics for one ADL arm transport and labels it with the ADL task and its ICF code. Works directly on the end-effector (hand) speed profile, so it needs no full marker set; derive the speed from a trajectory with computeSpeed() or pass a hand-sensor speed.

Usage

adlReachTask(
  speed,
  sampling_rate,
  task = c("reaching", "drinking", "feeding", "dressing", "grooming"),
  onset_threshold = 0.05
)

Arguments

Value

an adl_reach_task list: task, icf_code, and the kinematics movement_time, peak_velocity, time_to_peak_frac, movement_units (submovements; 1 = a single smooth transport), sparc and ldlj (smoothness; less negative = smoother).

References

Rohrer B, et al. (2002) J Neurosci 22:8297-8304 (movement units); Balasubramanian S, et al. (2015) IEEE TBME 62:2137-2147 (SPARC).

See Also

reachingKinematics(), movementUnits(), sparc()

Examples

# a single smooth (minimum-jerk) reach: one movement unit
fs <- 100; tt <- seq(0, 1, 1 / fs)
v <- 30 * (tt^2) * (1 - tt)^2                 # bell-shaped speed
adlReachTask(v, fs, task = "drinking")$movement_units

Description

Align EMG to motion-capture sampling grid

Usage

alignEMGtoMoCap(
  emg,
  emg_sampling_rate,
  mocap_length,
  mocap_sampling_rate,
  method = "linear",
  emg_start_time = 0,
  mocap_start_time = 0,
  outside = c("extend", "NA", "error")
)

Arguments

Value

Matrix of aligned EMG data with mocap_length rows.

References

Merletti R, Parker PA (2004). "Electromyography: Physiology, Engineering, and Non-Invasive Applications." IEEE Press/Wiley.

See Also

integrateEMGMoCap() for full EMG-MoCap integration, resampleSignal() for general signal resampling.

Examples

emg <- matrix(rnorm(2000), ncol = 2)
emg_aligned <- alignEMGtoMoCap(emg, 1000, mocap_length = 200,
                               mocap_sampling_rate = 100)

Description

Convenience wrapper that filters GRF components and computes COP, loading rate, and impulse summaries.

Usage

analyzeForcePlate(
  forces,
  moments = NULL,
  sampling_rate,
  cutoff = 20,
  threshold = 20,
  order = 4,
  filter_method = c("butterworth", "moving_average"),
  origin = c(0, 0, 0)
)

Arguments

Value

A list with elements: filtered_forces, cop, loading_rate, impulse, and summary.

References

Winter DA (2009). "Biomechanics and Motor Control of Human Movement." 4th ed. John Wiley & Sons.

See Also

filterGRF() for ground reaction force filtering, calculateCOP() for center of pressure computation, computeLoadingRate() for loading rate analysis, analyzeForcePlatePE() for PhysioExperiment-based analysis.

Examples

f <- cbind(Fx = rep(0, 1000), Fy = rep(0, 1000),
           Fz = c(rep(0, 200), abs(sin(seq(0, pi, length.out = 600))) * 800,
                  rep(0, 200)))
out <- analyzeForcePlate(f, sampling_rate = 1000)

Description

Convenience wrapper for analyzeForcePlate() when force and moment components are stored in PhysioExperiment assays.

Usage

analyzeForcePlatePE(
  pe,
  force_assay = "grf",
  moment_assay = NULL,
  plate_index = 1L,
  sampling_rate = NULL,
  ...
)

Arguments

Value

A forceplate_analysis object (single plate) or forceplate_analysis_multi (when plate_index = "all").

References

Winter DA (2009). "Biomechanics and Motor Control of Human Movement." 4th ed. John Wiley & Sons.

See Also

analyzeForcePlate() for matrix-based force plate analysis, print.forceplate_analysis() for displaying results.

Examples

n <- 500
z <- matrix(0, n, 1, dimnames = list(NULL, "fp1"))
fz <- matrix(c(rep(0, 100), rep(700, 300), rep(0, 100)), n, 1,
             dimnames = list(NULL, "fp1"))
pe <- PhysioExperiment(assays = S4Vectors::SimpleList(
    force_x = z, force_y = z, force_z = fz,
    moment_x = matrix(50, n, 1, dimnames = list(NULL, "fp1")),
    moment_y = matrix(-100, n, 1, dimnames = list(NULL, "fp1")),
    moment_z = z),
  colData = S4Vectors::DataFrame(label = "fp1", type = "forceplate"),
  samplingRate = 1000)
out <- analyzeForcePlatePE(pe, threshold = 20, cutoff = 20,
  filter_method = "moving_average")
out

Description

The regularity of a time series: the (negative) log-likelihood that patterns close for m samples stay close for m + 1. Lower = more regular/predictable, higher = more irregular. The ApEn complement to the package's sample entropy (ApEn includes self-matches and is more biased for short series, but is the classical measure).

Usage

approximateEntropy(x, m = 2L, r = NULL)

Arguments

Value

the approximate entropy (scalar).

References

Pincus SM (1991) PNAS 88:2297-2301.

See Also

recurrenceQuantification(), sampleEntropy()

Examples

t <- seq(0, 20 * pi, length.out = 500)
approximateEntropy(sin(t))                          # low (regular)
set.seed(1); approximateEntropy(rnorm(500))         # high (irregular)

Description

Performs a compact quality and metadata checklist so beginners can quickly identify missing requirements before running kinematics or kinetics.

Usage

assessMoCapReadiness(
  pe,
  required_assays = c("position_x", "position_y", "position_z"),
  min_frames = 100,
  min_markers = 5,
  min_sampling_rate = 50,
  max_missing_rate = 0.05
)

Arguments

Value

An S3 object of class "mocap_readiness" with score, grade, checks, and summary metrics.

References

Winter DA (2009). "Biomechanics and Motor Control of Human Movement." 4th ed. John Wiley & Sons.

See Also

print.mocap_readiness() for formatted display of readiness results, quickStartMoCap() for complete getting-started workflow, demoMoCapData() for generating demo data.

Examples

demo <- demoMoCapData(seed = 1)
report <- assessMoCapReadiness(demo$mocap)
report

Description

Loads an OpenSim session and performs batch movement analysis using a TaskSchema for event detection and normalization.

Usage

batch_analyze_opensim(
  session_dir,
  schema,
  signal_mapping = list(),
  trials = NULL,
  normalize_method = NULL,
  ...
)

Arguments

Details

Requires a native OpenSim installation (SystemRequirements: OpenSim) and setup/model files, so the example cannot run offline and is not executed.

Value

A list containing:

• trials: List of normalized trial data

• events: List of detected events per trial

• phases: List of phase timing per trial

• summary: Summary statistics across trials

References

Delp SL, Anderson FC, Arnold AS, Loan P, Habib A, John CT, Guendelman E, Thelen DG (2007). "OpenSim: Open-Source Software to Create and Analyze Dynamic Simulations of Movement." IEEE Transactions on Biomedical Engineering, 54(11), 1940-1950.

See Also

create_schema_from_opensim() for creating task schemas from OpenSim models.

Examples

## Not run: 
library(signalIO)

# Load session and analyze
results <- batch_analyze_opensim(
  "subject01/",
  schema = schema_gait,
  signal_mapping = list(vGRF = "ground_force_vy_r")
)

# Access normalized trials
trial1 <- results$trials[[1]]

# View summary
print(results$summary)

## End(Not run)

Description

Normalizes multiple trials and returns them in a consistent format.

Usage

batchNormalize(
  trials,
  method = "cycle",
  norm_length = 101L,
  schema = NULL,
  ...
)

Arguments

Value

3D array (time x channels x trials) or list

References

Winter DA (2009). "Biomechanics and Motor Control of Human Movement." 4th ed. Wiley.

See Also

normalizeMovement(), normalizedTimeAxis(), combineTrials()

Examples

set.seed(1)
trials <- list(matrix(rnorm(200), 100, 2), matrix(rnorm(180), 90, 2))
norm <- batchNormalize(trials, method = "cycle")
dim(norm[[1]])

Description

Computes per-variable metrics (RMSE, MAE, bias, correlation, R2, ICC, Bland-Altman LoA width) between prediction and reference data.

Usage

benchmarkAgreement(
  prediction,
  reference,
  trial_id = "trial_1",
  thresholds = defaultBenchmarkThresholds("balanced"),
  alignment = c("truncate", "resample")
)

Arguments

Value

Object of class "benchmark_agreement" with metrics, summary, and thresholds.

References

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

Bland JM, Altman DG (1986). "Statistical Methods for Assessing Agreement Between Two Methods of Clinical Measurement." Lancet, 327(8476), 307-310.

See Also

defaultBenchmarkThresholds() for threshold configuration, runBenchmarkSuite() for multi-trial benchmarking, blandAltman() for Bland-Altman agreement analysis.

Examples

ref <- data.frame(a = sin(seq(0, 1, length.out = 100)))
pred <- ref + rnorm(100, sd = 0.01)
out <- benchmarkAgreement(pred, ref, trial_id = "demo")
out$summary

Description

Produces a template data.frame describing benchmark trials and file paths.

Usage

benchmarkManifestTemplate(n = 1L)

Arguments

Value

A data.frame manifest template.

References

Bland JM, Altman DG (1986). "Statistical Methods for Assessing Agreement Between Two Methods of Clinical Measurement." Lancet, 327(8476), 307-310.

See Also

writeBenchmarkManifest() for writing the template to CSV, validateBenchmarkManifest() for validating manifest structure.

Examples

benchmarkManifestTemplate(2)

Description

Designs a Butterworth IIR filter and applies it using zero-phase filtering (forward-backward) to avoid phase distortion.

Usage

butterworthFilter(
  x,
  cutoff,
  sampling_rate,
  type = c("lowpass", "highpass", "bandpass", "bandstop"),
  order = 4
)

Arguments

Details

Requires the signal package. NAs in the input are temporarily interpolated before filtering and restored afterward.

Value

Filtered data with the same dimensions as x.

References

Butterworth S (1930). "On the Theory of Filter Amplifiers." Wireless Engineer, 7, 536-541.

See Also

filterSignals() for filtering PhysioExperiment objects, savgolFilter() for Savitzky-Golay polynomial smoothing.

Examples

if (requireNamespace("signal", quietly = TRUE)) {
  x <- sin(2 * pi * 2 * seq(0, 1, length.out = 120)) + rnorm(120, 0, 0.1)
  xf <- butterworthFilter(x, cutoff = 6, sampling_rate = 120)
  length(xf)
}

Description

Converts the EVENT parameter group retained by readC3D() into a table of seconds relative to the first stored point sample. The event clock must be declared explicitly. Header events are not read by this function.

Usage

c3dEventTable(
  x,
  event_time_reference,
  first_frame = NULL,
  snap = c("none", "point"),
  tolerance = 1e-05,
  outside = c("error", "keep")
)

Arguments

Details

Point rate must match samplingRate(x). A trial origin is never silently replaced with zero. ACTUAL_START_FIELD comprises two unsigned 16-bit words, low word first; signed 16-bit storage is decoded as unsigned. Snapping is opt-in because a continuous event need not lie on a point frame. This adapter does not change the signals or their local sample grid. Applying it after cropping requires updating the first frame to match the stored samples.

Operates on a parsed C3D object from the optional c3dr package, built from a binary .c3d file, so the example cannot run offline and is not executed.

Value

A data frame in original event order with event_index, label, context, raw_minutes, raw_seconds, raw_time, time, snap_residual_s, recording_origin, first_frame, event_time_reference, snap, and in_recording. time is relative to the recording start; raw_time is the declared event clock. Residual is raw minus snapped time on that clock, or zero when snapping is disabled. No-event files return a typed empty table. No sorting, event detection, or gait-cycle inference is performed. Event accuracy and the declared clock remain caller concerns.

References

C3D.org, EVENT:TIMES: https://www.c3d.org/HTML/Documents/eventtimes1.htm

See Also

readC3D(), segmentCohortCycles()

Examples

## Not run: 
# `x` is a C3D object read via the c3dr package from a .c3d file.
c3dEventTable(x, event_time_reference = "trial_start")

## End(Not run)

Description

Computes the whole-body center of mass (COM) at each time frame from 3D (or 2D) marker position data and body segment inertial parameters.

Usage

calculateCOM(pe, body_mass, skeleton = NULL, bsip = NULL, marker_map = NULL)

Arguments

Details

The algorithm proceeds as follows:

1. For each body segment, compute the segment COM position as:

   $COM_{seg} = P_{prox} + f \times (P_{dist} - P_{prox})$

   where $f$ is the COM proximal fraction from the BSIP table.

2. Compute the whole-body COM as the mass-weighted average of all segment COMs:

   $COM_{body} = \frac{\sum_i m_i \times COM_i}{M}$

   where $m_i = M \times f_i$ is the segment mass and $M$ is the total body mass.

Value

A PhysioExperiment object with additional assays com_x, com_y, and (if 3D) com_z. Each assay is a single-column matrix with column name "COM" and the same number of rows as the input.

References

Winter DA (2009). "Biomechanics and Motor Control of Human Movement." 4th ed. John Wiley & Sons.

Zatsiorsky VM (2002). "Kinetics of Human Motion." Human Kinetics.

See Also

segmentParameters() for body segment inertial parameters, calculateSegmentCOM() for individual segment center of mass, symmetryIndex() for bilateral symmetry assessment.

Examples

n <- 50
mk <- function(v) { m <- matrix(v, n, 3); colnames(m) <- c("A", "B", "C"); m }
pe <- PhysioExperiment(
  assays = S4Vectors::SimpleList(position_x = mk(1), position_y = mk(2),
                                 position_z = mk(0)),
  colData = S4Vectors::DataFrame(label = c("A", "B", "C"),
                                 type = rep("marker", 3)),
  samplingRate = 100)
bsip <- data.frame(segment = c("s1", "s2"), mass_fraction = c(50, 50),
  com_proximal_fraction = c(0.5, 0.5),
  proximal_marker = c("A", "B"), distal_marker = c("B", "C"),
  stringsAsFactors = FALSE)
pe_com <- calculateCOM(pe, body_mass = 70, bsip = bsip,
  marker_map = list(s1 = c("A", "B"), s2 = c("B", "C")))
SummarizedExperiment::assayNames(pe_com)

Description

Computes COP coordinates from force and moment components using standard force-plate equations (assuming a vertical Z axis).

Usage

calculateCOP(forces, moments, origin = c(0, 0, 0), min_vertical_force = 20)

Arguments

Value

A data.frame with columns cop_x, cop_y, cop_z, free_moment, and vertical_force.

References

Winter DA (2009). "Biomechanics and Motor Control of Human Movement." 4th ed. John Wiley & Sons.

See Also

analyzeForcePlate() for comprehensive force plate analysis, calculateCOM() for whole-body center of mass computation.

Examples

f <- cbind(Fx = rep(0, 10), Fy = rep(0, 10), Fz = rep(1000, 10))
m <- cbind(Mx = rep(100, 10), My = rep(-200, 10), Mz = rep(0, 10))
cop <- calculateCOP(f, m)

Description

Computes temporal and spatial gait parameters from detected gait events. Temporal parameters include stride time, step time, stance/swing durations, double support time, and cadence. Spatial parameters (step length, stride length, step width, walking speed) require position data in the PhysioExperiment assays.

Usage

calculateGaitParameters(
  pe,
  events,
  body_height = NULL,
  side = c("right", "left", "both")
)

Arguments

Details

Events must use one of the recognised naming conventions:

• "HS_R", "HS_L" / "TO_R", "TO_L"

• "right_heel_strike", "left_heel_strike" / "right_toe_off", "left_toe_off"

The events data.frame may use either event_name or event for the event name column, and either time (in sample indices) or time_sec (in seconds) for timing.

Value

An S3 object of class "gait_parameters" inheriting from data.frame. Each row is one stride cycle. Columns include:

side

Side label ("right" or "left")

stride

Stride number (sequential within side)

stride_time

Time between consecutive ipsilateral heel strikes (s)

step_time

Time from contralateral to ipsilateral heel strike (s)

stance_time

Heel strike to toe off on the same side (s)

swing_time

Toe off to next heel strike on the same side (s)

stance_percent

Stance as percentage of stride time

swing_percent

Swing as percentage of stride time

double_support_time

Time with both feet on the ground (s)

cadence

Steps per minute (60 / step_time)

step_length

AP distance between feet at consecutive heel strikes (m)

stride_length

AP distance between ipsilateral heel strikes (m)

step_width

ML distance between feet at heel strike (m)

walking_speed

Stride length / stride time (m/s)

References

Winter DA (2009). "Biomechanics and Motor Control of Human Movement." 4th ed. John Wiley & Sons.

Perry J, Burnfield JM (2010). "Gait Analysis: Normal and Pathological Function." 2nd ed. SLACK Incorporated.

See Also

calculateStepSymmetry() for symmetry analysis of gait parameters, summarizeGaitParameters() for descriptive statistics of gait data, plotGaitCycle() for gait cycle visualization.

Examples

# See test file for worked examples with synthetic data

Description

Computes joint angles from 3D (or 2D) position data stored in a PhysioExperiment object. Each joint is defined by three points: proximal, joint (vertex), and distal. The angle at the vertex is computed using the specified convention.

Usage

calculateJointAngles(
  pe,
  joints,
  convention = c("3point", "ISB", "groodsuntay"),
  degrees = TRUE,
  signed = FALSE,
  plane_normal = NULL
)

Arguments

Details

For the "3point" convention, the angle is computed at the vertex (joint point) between the proximal-to-joint and distal-to-joint direction vectors:

$\theta = \arccos\left(\frac{v_1 \cdot v_2}{|v_1| |v_2|}\right)$

where $v_1 = \text{proximal} - \text{joint}$ and $v_2 = \text{distal} - \text{joint}$.

The result is clamped to $[0, \pi]$ (or $[0, 180]$ in degrees). If any of the three points contain NA for a given frame, the angle for that frame is NA.

Value

A PhysioExperiment with a "joint_angles" assay. For "3point" this is ⁠n_frames x n_joints⁠ (one angle per joint: unsigned in $[0, 180]$, or signed in $(-180, 180]$ when signed = TRUE). For "groodsuntay" / "ISB" it is ⁠n_frames x (3 * n_joints)⁠: three columns per joint (⁠<joint>_flexion⁠, ⁠<joint>_abduction⁠, ⁠<joint>_rotation⁠) with colData carrying the joint and axis labels.

Signed vertex angles

The unsigned vertex angle cannot tell flexion from hyperextension: a knee flexed 10 degrees and a knee hyperextended 10 degrees both give an included angle of 170 degrees, because $\arccos$ discards which side of the proximal segment the distal segment lies on. With signed = TRUE the angle is instead

$\theta = \mathrm{atan2}\left((v_1' \times v_2') \cdot \hat{n},\; v_1' \cdot v_2'\right)$

where $\hat{n}$ is the unit plane_normal and $v_i'$ is $v_i$ with its $\hat{n}$ component removed. The magnitude is the same included angle as before whenever the three points lie in the plane; the sign is positive when the rotation from $v_1$ to $v_2$ follows the right-hand rule about $\hat{n}$, and flips when the distal segment crosses to the other side of the proximal segment. Choose (or negate) plane_normal so that this direction is flexion, giving the clinical flexion(+) / extension(-) convention; the corresponding deviation from the straight (anatomically neutral) position is 180 - abs(theta).

Because the range is $(-180, 180]$, the signed angle wraps at exactly the straight configuration - the pose whose two sides the sign is there to tell apart. A joint that moves through full extension therefore steps from +180 to -180, and differentiating that series directly gives a spurious spike. Work with 180 - abs(theta) (which is continuous through the neutral pose) or unwrap the series before differentiating.

For 2D data (no position_z assay) the default normal is the global z axis, so a positive angle means the distal vector is counter-clockwise from the proximal vector in the x-y plane. For 3D data with plane_normal = NULL the normal is the least-variance direction of the two joint vectors over all frames (a best-fit plane), which is only defined up to a global flip; the function warns in that case because the flexion(+) direction is then a property of the data rather than a clinical convention. Because $v_i$ is projected onto the plane, out-of-plane motion makes the signed magnitude smaller than the unsigned 3D angle; the two agree exactly for planar motion.

For "groodsuntay" / "ISB", a proximal and distal anatomical frame are built for each joint (via jointCoordinateSystem()) and the three signed angles are extracted with groodSuntayAngles(). This is a sequence- dependent Grood-Suntay floating-axis (Z-X-Y Cardan) decomposition: flexion (about the proximal medio-lateral axis) is extracted first and internal/ external rotation (about the distal long axis) last.

References

Winter DA (2009). "Biomechanics and Motor Control of Human Movement." 4th ed. Wiley.

Grood ES, Suntay WJ (1983). "A joint coordinate system for the clinical description of three-dimensional motions: application to the knee." Journal of Biomechanical Engineering, 105(2), 136-144.

See Also

vectorAngle(), quaternionToEuler(), eulerToQuaternion()

Examples

demo <- demoMoCapData(seed = 1)
pe_ang <- calculateJointAngles(demo$mocap,
  joints = list(knee_r = list(proximal = "Pelvis_R",
                              joint = "Knee_R", distal = "Ankle_R")))
SummarizedExperiment::assayNames(pe_ang)

Description

Lower-level function that computes the center of mass for individual body segments from marker position data.

Usage

calculateSegmentCOM(pe, proximal_markers, distal_markers, com_fractions)

Arguments

Value

A named list of matrices, one per segment. Each matrix has dimensions (n_frames x 2) for 2D data or (n_frames x 3) for 3D data, with columns named "x", "y", and (optionally) "z".

References

Winter DA (2009). "Biomechanics and Motor Control of Human Movement." 4th ed. John Wiley & Sons.

See Also

calculateCOM() for whole-body center of mass, segmentParameters() for body segment inertial parameters.

Examples

n <- 50
mk <- function(v) { m <- matrix(v, n, 3); colnames(m) <- c("A", "B", "C"); m }
pe <- PhysioExperiment(
  assays = S4Vectors::SimpleList(position_x = mk(1), position_y = mk(2),
                                 position_z = mk(0)),
  colData = S4Vectors::DataFrame(label = c("A", "B", "C"),
                                 type = rep("marker", 3)),
  samplingRate = 100)
seg_com <- calculateSegmentCOM(pe, proximal_markers = "A",
  distal_markers = "B", com_fractions = 0.5)
names(seg_com)
head(seg_com[[1]])

Description

Computes symmetry metrics comparing left and right sides. Includes the Robinson Symmetry Index and the left/right ratio for each parameter.

Usage

calculateStepSymmetry(gait_params)

Arguments

Details

A Symmetry Index (SI) of 0 indicates perfect symmetry. Values above 10 are generally considered clinically asymmetric.

Value

A data.frame with columns:

parameter

Name of the gait parameter

left_mean

Mean value for the left side

right_mean

Mean value for the right side

SI

Robinson Symmetry Index: |L - R| / (0.5 * (L + R)) * 100

ratio

Left / Right ratio

References

Winter DA (2009). "Biomechanics and Motor Control of Human Movement." 4th ed. John Wiley & Sons.

See Also

calculateGaitParameters() for computing gait temporal-spatial parameters, symmetryIndex() for general symmetry index computation, plotSymmetry() for symmetry visualization.

Examples

# See test file for worked examples

Description

Estimates accelerometer and gyroscope biases from data recorded during a static (motionless) period. The accelerometer bias is computed relative to the expected gravity vector, and the gyroscope bias is the mean angular velocity during the static period.

Usage

calibrateIMU(accel_static, gyro_static)

Arguments

Details

The function assumes the sensor is stationary. The accelerometer bias is estimated by subtracting the expected gravity contribution from the mean accelerometer reading. Gravity direction is inferred from the mean acceleration direction, and its expected magnitude is 9.81 m/s^2.

The gyroscope bias is simply the mean of the gyroscope readings during the static period (should be near zero for a stationary sensor).

Value

A list with components:

accel_bias

Numeric vector of length 3. Mean accelerometer bias for each axis. For a perfectly calibrated sensor at rest, this would be (0, 0, 0) after accounting for gravity.

gyro_bias

Numeric vector of length 3. Mean gyroscope bias for each axis (rad/s). A stationary sensor should read zero; any offset is the bias.

References

Madgwick SOH, Harrison AJL, Vaidyanathan R (2011). "Estimation of IMU and MARG orientation using a gradient descent algorithm." IEEE International Conference on Rehabilitation Robotics.

See Also

estimateOrientation(), removeGravity()

Examples

# Simulate static IMU data with known biases
n <- 500
accel_bias_true <- c(0.05, -0.03, 0.02)
gyro_bias_true <- c(0.001, -0.002, 0.0015)
accel <- matrix(rep(c(0, 0, -9.81), each = n), ncol = 3) +
  matrix(rep(accel_bias_true, each = n), ncol = 3)
gyro <- matrix(rep(gyro_bias_true, each = n), ncol = 3)
cal <- calibrateIMU(accel, gyro)

Description

Runs each applicable detector on the supplied gait-cycle waveforms and returns a per-pattern flag and severity. A pattern is evaluated only when its input variable is present in variables.

Usage

classifyGaitPatterns(variables, params = list())

Arguments

Value

A data frame (class gait_pattern_classification) with columns pattern, flagged, severity, metric, threshold, one row per evaluated pattern.

See Also

gaitPatternLibrary()

Examples

vars <- list(knee_flexion = 60 * sin(seq(0, pi, length.out = 101)))
classifyGaitPatterns(vars)

Description

Combine multiple trials with segmented phases

Usage

combineTrials(..., labels = NULL)

Arguments

Value

A multi_trial_phases object

References

Winter DA (2009). "Biomechanics and Motor Control of Human Movement." 4th ed. Wiley.

See Also

segmentPhases(), batchNormalize(), normalizeMovement()

Examples

set.seed(123)
data <- matrix(rnorm(200), 100, 2)
events <- data.frame(
  event = c("hs1","ff","ms","ho","to","hs2"),
  label = c("Heel Strike","Foot Flat","Midstance","Heel Off","Toe Off","Heel Strike 2"),
  index = c(1, 13, 31, 41, 61, 100), time = c(0, .12, .30, .40, .60, 1.0),
  percent = c(0, 12, 30, 40, 60, 100), method = rep("manual", 6),
  confidence = rep(1, 6), stringsAsFactors = FALSE)
class(events) <- c("detected_events", "data.frame")
attr(events, "sampling_rate") <- 100
phases <- segmentPhases(data, events, schema_gait)
combineTrials(phases, phases, labels = c("t1", "t2"))

Description

Computes acceleration (second derivative) from position or velocity assays. If velocity assays already exist, differentiates those (first derivative of velocity). Otherwise, computes the second derivative of position directly.

Usage

computeAcceleration(
  pe,
  assay_names = NULL,
  method = "central",
  sampling_rate = NULL
)

Arguments

Value

PhysioExperiment with new accel_x, accel_y, accel_z assays added.

References

Winter DA (2009). "Biomechanics and Motor Control of Human Movement." 4th ed. John Wiley & Sons.

See Also

computeVelocity() for first-order derivatives, computeJerk() for third-order derivatives, differentiate() for general-purpose numerical differentiation.

Examples

demo <- demoMoCapData(seed = 1)
pe_acc <- computeAcceleration(demo$mocap)
SummarizedExperiment::assayNames(pe_acc)

Description

Integrates vertical force over detected stance phases using trapezoidal integration.

Usage

computeImpulse(
  force,
  sampling_rate,
  threshold = 20,
  subtract_threshold = FALSE
)

Arguments

Value

For vector input: data.frame with one row per stance and columns including impulse (force*time units). For matrix input: same structure plus channel.

References

Winter DA (2009). "Biomechanics and Motor Control of Human Movement." 4th ed. John Wiley & Sons.

See Also

analyzeForcePlate() for comprehensive force plate analysis, computeLoadingRate() for loading rate computation.

Examples

grf <- c(rep(0, 50), rep(600, 100), rep(0, 50))
computeImpulse(grf, sampling_rate = 1000)

Description

Computes jerk (third derivative of position) from position assays.

Usage

computeJerk(pe, method = "central", sampling_rate = NULL)

Arguments

Value

PhysioExperiment with new jerk_x, jerk_y, jerk_z assays added.

References

Winter DA (2009). "Biomechanics and Motor Control of Human Movement." 4th ed. John Wiley & Sons.

See Also

computeAcceleration() for second-order derivatives, computeVelocity() for first-order derivatives, differentiate() for general-purpose numerical differentiation.

Examples

demo <- demoMoCapData(seed = 1)
pe_jerk <- computeJerk(demo$mocap)
SummarizedExperiment::assayNames(pe_jerk)

Description

Joint power is the product of the net joint moment and the joint angular velocity. Positive power (generation) reflects concentric muscle action doing work on the segment; negative power (absorption) reflects eccentric action absorbing energy. Set split = TRUE to return the generation and absorption components alongside the total.

Usage

computeJointPower(moment, angular_velocity, split = FALSE)

Arguments

Value

If split = FALSE, a numeric vector of joint power (W). If split = TRUE, a data frame with columns power, generation, and absorption (each in W); generation + absorption == power elementwise.

References

Winter DA (2009). "Biomechanics and Motor Control of Human Movement." 4th ed. John Wiley & Sons.

See Also

inverseDynamics2D() for computing joint moments in 2D, inverseDynamics3D() for computing joint moments in 3D, jointWork() for integrating power into concentric/eccentric work, labelPowerBursts() for Winter power-burst nomenclature.

Examples

computeJointPower(c(10, 12, 8), c(2, 1.5, 1))
computeJointPower(c(10, -12, 8), c(2, 1.5, -1), split = TRUE)

Description

Detects stance phases from a vertical GRF signal and computes loading rate from initial contact to peak force for each stance.

Usage

computeLoadingRate(
  vgrf,
  sampling_rate,
  threshold = 20,
  method = c("instantaneous", "average")
)

Arguments

Value

For vector input: a data.frame with one row per stance. For matrix input: same data.frame with an added channel column.

References

Winter DA (2009). "Biomechanics and Motor Control of Human Movement." 4th ed. John Wiley & Sons.

See Also

analyzeForcePlate() for comprehensive force plate analysis, computeImpulse() for impulse computation.

Examples

grf <- c(rep(0, 100), seq(0, 800, length.out = 150),
         seq(800, 0, length.out = 150), rep(0, 100))
computeLoadingRate(grf, sampling_rate = 1000)

Description

Compute moving RMS envelope of EMG

Usage

computeRMSEnvelope(x, window_samples = 50L, center = TRUE)

Arguments

Value

RMS envelope with the same dimensions as x.

References

Merletti R, Parker PA (2004). "Electromyography: Physiology, Engineering, and Non-Invasive Applications." IEEE Press/Wiley.

See Also

rectifyEMG() for signal rectification, normalizeEMG() for MVC or peak normalization, processEMG() for complete EMG processing pipeline.

Examples

set.seed(1)
sig <- rnorm(1000)
env <- computeRMSEnvelope(sig, window_samples = 50)

Description

Computes the magnitude of the velocity vector (Euclidean norm) at each time point for each marker/keypoint.

Usage

computeSpeed(pe, velocity_assays = NULL)

Arguments

Value

PhysioExperiment with a new "speed" assay containing the scalar speed: sqrt(vx^2 + vy^2 + vz^2).

References

Winter DA (2009). "Biomechanics and Motor Control of Human Movement." 4th ed. John Wiley & Sons.

See Also

computeVelocity() for computing velocity components, computeAcceleration() for computing acceleration.

Examples

demo <- demoMoCapData(seed = 1)
pe_speed <- computeSpeed(computeVelocity(demo$mocap))
SummarizedExperiment::assayNames(pe_speed)

Description

Computes velocity (first derivative) from position assays in a PhysioExperiment object using finite differences.

Usage

computeVelocity(
  pe,
  assay_names = NULL,
  method = "central",
  sampling_rate = NULL
)

Arguments

Value

PhysioExperiment with new velocity assays added. For 3D marker data, assays named velocity_x, velocity_y, velocity_z. For 2D keypoint data, assays named velocity_kp_x, velocity_kp_y.

References

Winter DA (2009). "Biomechanics and Motor Control of Human Movement." 4th ed. John Wiley & Sons.

See Also

computeAcceleration() for second-order derivatives, computeSpeed() for scalar speed from velocity components, differentiate() for general-purpose numerical differentiation.

Examples

demo <- demoMoCapData(seed = 1)
pe_vel <- computeVelocity(demo$mocap)
SummarizedExperiment::assayNames(pe_vel)

Description

The phase-plane coordination measure (Hamill et al. 2000): each joint angle is mapped to a phase angle from its (normalised) phase portrait, and the continuous relative phase is their difference through the movement. Its mean absolute value (MARP) summarises whether the joints move more in-phase (near 0) or out-of-phase (near 180).

Usage

continuousRelativePhase(angle1, angle2, normalize = TRUE)

Arguments

Value

a crp_result list: crp (degrees, wrapped to +/-180), phase1, phase2 (phase angles, degrees) and marp (mean absolute relative phase).

References

Hamill J, et al. (2000) Clin Biomech 15:S31-S39.

See Also

vectorCoding(), coordinationVariability()

Examples

t <- seq(0, 2 * pi, length.out = 101)
continuousRelativePhase(sin(t), sin(t))$marp        # in-phase ~ 0

Description

Integrates torque over time to obtain angular impulse and, when angle or angular velocity is available, integrates torque over angular displacement to obtain mechanical work.

Usage

contractionWork(
  torque,
  sampling_rate,
  angle = NULL,
  angular_velocity = NULL,
  reps = NULL,
  onset_threshold = 7.5,
  body_mass = NULL
)

Arguments

Value

A contraction_work data frame with angular impulse (N m s), work (J), and optional mass-normalised values for each repetition.

References

Winter DA (2009). Biomechanics and Motor Control of Human Movement. 4th ed. John Wiley & Sons.

Examples

torque <- c(seq(0, 100, length.out = 51), seq(98, 0, length.out = 50))
contractionWork(torque, sampling_rate = 100,
                reps = list(rep1 = seq_along(torque)))

Description

The trial-to-trial (cycle-to-cycle) variability of the coordination measure – the deviation phase for continuous relative phase (linear SD) or the coupling- angle circular SD for vector coding – computed at each point of the (time-normalised) cycle. Coordination variability is a motor-control marker: abnormally high or low values accompany injury and neurological disease.

Usage

coordinationVariability(
  angle1_cycles,
  angle2_cycles,
  method = c("crp", "vector_coding")
)

Arguments

Value

a coordination_variability list: method, variability (per-point), mean_variability and measure (the per-cycle coordination matrix).

References

Hamill (2000); Needham (2014).

See Also

continuousRelativePhase(), vectorCoding()

Examples

m <- matrix(sin(seq(0, 2 * pi, length.out = 50)), nrow = 5, ncol = 50,
            byrow = TRUE)
coordinationVariability(m, m)$mean_variability      # identical cycles -> 0

Description

Computes the pressure-weighted centroid at each frame. Grid columns define the mediolateral (cop_x) direction and rows define the anteroposterior (cop_y) direction, matching calculateCOP() and swayMetrics().

Usage

copFromPressure(pm, contact_threshold = 0)

Arguments

Value

A data frame with time, cop_x, cop_y, total_force, and contact_area. CoP coordinates are in mm and force is in N.

References

Pataky TC (2012). Spatial resolution in plantar pressure measurement revisited. Journal of Biomechanics, 45:2116-2124.

See Also

swayMetrics(), calculateCOP()

Examples

x <- array(0, c(3, 3, 2))
x[2, 3, ] <- 100
copFromPressure(pressureMovie(x, 100, dx = 5, dy = 5))

Description

Repairs marker trajectories by swapping the data columns of detected swap pairs from the swap frame onward.

Usage

correctSwaps(pe, swaps, assay_prefix = "position", min_confidence = 0.5)

Arguments

Value

A PhysioExperiment with corrected position assays.

See Also

detectSwaps(), trackMarkers()

Examples

demo <- demoMoCapData(seed = 1)
swaps <- detectSwaps(demo$mocap)
pe_fixed <- correctSwaps(demo$mocap, swaps)
pe_fixed

Description

Generates a TaskSchema based on an OpenSim model's markers and available signal channels. This function creates appropriate event definitions that can be used with detectEvents() for automatic event detection.

Usage

create_schema_from_opensim(
  model,
  task_type = c("gait", "running", "jump", "generic"),
  available_signals = NULL,
  side = "right"
)

Arguments

Details

This function analyzes the model's markers and the available signals to generate an appropriate TaskSchema. For gait analysis, it prefers GRF-based detection if available, falling back to marker-based or kinematic detection.

Requires a native OpenSim installation (SystemRequirements: OpenSim) and setup/model files, so the example cannot run offline and is not executed.

Value

A TaskSchema object configured for the specified task type

References

Delp SL, Anderson FC, Arnold AS, Loan P, Habib A, John CT, Guendelman E, Thelen DG (2007). "OpenSim: Open-Source Software to Create and Analyze Dynamic Simulations of Movement." IEEE Transactions on Biomedical Engineering, 54(11), 1940-1950.

See Also

batch_analyze_opensim() for batch processing of OpenSim sessions, detectEvents() for event detection using task schemas.

Examples

## Not run: 
library(signalIO)

# Load OpenSim model
model <- read_osim("gait2354.osim")

# Load IK results
ik <- read_mot("ik_results.mot")
ik_channels <- rownames(ik)

# Create gait schema with available channels
schema <- create_schema_from_opensim(model, "gait", ik_channels)
print(schema)

# Use schema for event detection
events <- detectEvents(data, schema)

## End(Not run)

Description

Generates prediction/reference CSV pairs and a manifest for dry-run validation benchmarking when external data are not yet available.

Usage

createBenchmarkExample(
  output_dir = tempdir(),
  n_trials = 3L,
  n_samples = 300L,
  variables = c("hip_angle", "knee_angle", "ankle_angle"),
  noise_sd = 0.02,
  seed = 1
)

Arguments

Value

A list with manifest, manifest_path, and data_dir.

References

Bland JM, Altman DG (1986). "Statistical Methods for Assessing Agreement Between Two Methods of Clinical Measurement." Lancet, 327(8476), 307-310.

See Also

runBenchmarkSuite() for running the benchmark suite, benchmarkManifestTemplate() for creating empty manifest templates.

Examples

ex <- createBenchmarkExample(n_trials = 2, seed = 1)
runBenchmarkSuite(ex$manifest, data_dir = ex$data_dir)

Description

Returns a named list of threshold values used by benchmark pass/fail logic.

Usage

defaultBenchmarkThresholds(profile = c("balanced", "strict", "lenient"))

Arguments

Value

Named list with threshold fields: rmse_max, mae_max, bias_abs_max, cor_min, icc_min.

References

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

See Also

benchmarkAgreement() for computing agreement metrics, runBenchmarkSuite() for running a full benchmark suite.

Examples

defaultBenchmarkThresholds()

Description

Factory function that returns a SkeletonModel for a well-known pose estimation or motion capture marker set.

Usage

define_skeleton(model_name)

Arguments

Value

A SkeletonModel object.

References

Winter DA (2009). "Biomechanics and Motor Control of Human Movement." 4th ed. Wiley.

See Also

SkeletonModel(), get_bone_connections(), get_limb_pairs()

Examples

sk <- define_skeleton("BODY_25")
print(sk)

sk_coco <- define_skeleton("COCO")
get_bone_connections(sk_coco)

Description

Generates synthetic motion capture, force, and EMG data so first-time users can run package workflows without external files.

Usage

demoMoCapData(
  n_frames = 300,
  sampling_rate = 120,
  n_markers = 8,
  emg_sampling_rate = 1000,
  seed = 123
)

Arguments

Value

A named list with:

mocap

A PhysioExperiment with position_x, position_y, position_z assays.

grf

Numeric vector of synthetic vertical GRF.

forces

Matrix with force_x, force_y, force_z columns.

joints

Data frame with 2D joint-center coordinates for ankle, knee, and hip.

joint_angles

Data frame with ankle/knee/hip joint angles (radians).

emg

Matrix of synthetic EMG channels.

sampling_rate

MoCap sampling rate (Hz).

emg_sampling_rate

EMG sampling rate (Hz).

References

Winter DA (2009). "Biomechanics and Motor Control of Human Movement." 4th ed. John Wiley & Sons.

See Also

quickStartMoCap() for a complete getting-started workflow, assessMoCapReadiness() for data quality assessment.

Examples

demo <- demoMoCapData(seed = 1)
demo$mocap
head(demo$joints)

Description

Circumduction is a lateral (outward) swing of the foot/hip used to advance a functionally long limb (e.g. with stiff knee or drop foot). It is quantified as the peak lateral excursion of the foot (or hip) during swing relative to the stance-phase baseline.

Usage

detectCircumduction(
  foot_ml,
  swing = c(60, 100),
  stance = c(0, 55),
  threshold = 0.04,
  severe = 0.12,
  lateral_sign = 1
)

Arguments

Value

A gait_pattern_flag object.

References

Perry J, Burnfield JM (2010); Kerrigan DC, et al. (2000).

See Also

classifyGaitPatterns()

Examples

pct <- seq(0, 100, length.out = 101)
foot_ml <- rep(0, 101)
swing <- pct >= 60
foot_ml[swing] <- 0.10 * sin(pi * (pct[swing] - 60) / 40)
detectCircumduction(foot_ml)

Description

Automatically detects events defined in a TaskSchema based on signal data.

Usage

detectEvents(
  x,
  schema,
  signals = NULL,
  method = c("auto", "manual", "hybrid", "zeni"),
  sampling_rate = NULL,
  ...
)

Arguments

Value

A data.frame with columns:

• event - Event name

• label - Human-readable label

• index - Sample index of event

• time - Time in seconds

• percent - Percent of movement (if applicable)

• method - Detection method used

• confidence - Detection confidence (0-1)

References

Winter DA (2009). "Biomechanics and Motor Control of Human Movement." 4th ed. Wiley.

See Also

manualEvents(), segmentPhases(), TaskSchema()

Examples

# Create synthetic gait data
set.seed(123)
n <- 1000
t <- seq(0, 1, length.out = n)
vGRF <- c(rep(0, 100), sin(seq(0, pi, length.out = 500)) * 800, rep(0, 400))
vGRF <- vGRF + rnorm(n, 0, 10)

signals <- list(vGRF = vGRF)
events <- detectEvents(as.matrix(vGRF), schema_gait,
                       signals = signals, sampling_rate = 1000)

Description

Implements the coordinate-based gait-event detector of Zeni, Richards & Higginson (2008). Heel strike (initial contact, IC) occurs when a heel marker reaches its most anterior position relative to a pelvis/COM reference; toe off (TO) occurs when a toe marker reaches its most posterior position relative to the same reference. Because events are keyed to the foot marker relative to the pelvis, the method works on treadmill trials where the body does not translate in the lab frame, and it returns per-stride IC/TO for both sides across a full trial.

Usage

detectEventsZeni(
  pe,
  markers,
  reference = "sacrum",
  ap_axis = NULL,
  direction = NULL,
  body_mass = NULL,
  min_separation = NULL,
  sampling_rate = NULL
)

Arguments

Details

The result is a detected_events data frame compatible with calculateGaitParameters(); heel-strike/toe-off rows are named left_heel_strike/right_heel_strike/left_toe_off/right_toe_off and carry an explicit side column.

Value

A detected_events data frame with one row per detected event (columns event, label, index, time, percent, method, confidence, side), sorted by frame index.

References

Zeni JA, Richards JG, Higginson JS (2008). "Two simple methods for determining gait events during treadmill and overground walking." Gait & Posture 27(4):710-714.

See Also

detectEvents() (use method = "zeni"), calculateGaitParameters(), calculateCOM().

Examples

demo <- demoMoCapData(seed = 1)
ev <- detectEventsZeni(demo$mocap,
  markers = list(heel_right = "Ankle_R", toe_right = "Toe_R",
                 heel_left = "Ankle_L", toe_left = "Toe_L"),
  reference = "Pelvis_R")
head(ev)

Description

Identifies threshold-based contact windows from vertical GRF signals.

Usage

detectForcePlateContacts(vgrf, threshold = 20, sampling_rate = NULL)

Arguments

Value

A data.frame with one row per detected contact and columns: plate, stance, onset, offset, duration_samples, duration_s, and peak_force.

References

Winter DA (2009). "Biomechanics and Motor Control of Human Movement." 4th ed. John Wiley & Sons.

See Also

analyzeForcePlate() for comprehensive force plate analysis, analyzeForcePlatePE() for PhysioExperiment-based analysis.

Examples

v <- cbind(
  fp1 = c(rep(0, 100), rep(500, 200), rep(0, 100)),
  fp2 = c(rep(0, 200), rep(700, 100), rep(0, 100))
)
detectForcePlateContacts(v, threshold = 20, sampling_rate = 1000)

Description

Scans the specified assay of a PhysioExperiment object for contiguous runs of NA values and returns a data.frame describing each gap.

Usage

detectGaps(pe, assay_name = "position_x")

Arguments

Value

A data.frame with columns:

• channel - Channel (column) name or index

• start - Start index of the gap (1-based)

• end - End index of the gap (1-based)

• size - Number of consecutive NA values

References

Federolf PA (2013). "A novel approach to solve the 'missing marker problem' in marker-based motion analysis that does not require additional assumptions about the biodynamic model." Journal of Biomechanics, 46(13), 2173-2178.

See Also

reportGaps(), fillGaps(), fillGapsLinear()

Examples

pe <- PhysioExperiment::PhysioExperiment(
  assays = S4Vectors::SimpleList(position_x = matrix(c(1, NA, NA, 4), ncol = 1)),
  colData = S4Vectors::DataFrame(label = "M1", type = "marker"),
  samplingRate = 120
)
gaps <- detectGaps(pe, assay_name = "position_x")

Description

Reduced ankle plantarflexor push-off is quantified from the peak positive ankle power in late stance (the A2 burst; normal $\approx 3-4$ W/kg) or, equivalently, the peak late-stance plantarflexor moment.

Usage

detectPushOffDeficit(
  ankle_power,
  window = c(40, 62),
  normal_peak = 3.5,
  threshold = 2,
  metric_name = "peak_ankle_A2_power"
)

Arguments

Value

A gait_pattern_flag object.

References

Perry J, Burnfield JM (2010); Winter DA (2009).

See Also

classifyGaitPatterns()

Examples

pct <- seq(0, 100, length.out = 101)
ankle_power <- -0.6 * exp(-((pct - 15) / 8)^2)
push <- pct > 40 & pct < 62
ankle_power[push] <- 1.0 * sin(pi * (pct[push] - 40) / 22)
detectPushOffDeficit(ankle_power)

Description

Flags the stationary (foot-flat) samples of a foot-mounted IMU trace, used as zero-velocity-update (ZUPT) anchors by strapdownIntegrate() and footImuGait(). The default "magnitude" detector marks a sample as stance when the accelerometer magnitude is close to gravity and the gyroscope magnitude is small; the "shoe" detector is the SHOE (Stance Hypothesis Optimal Estimation) generalised-likelihood-ratio test of Skog et al. (2010).

Usage

detectStanceZUPT(
  accel,
  gyro,
  sampling_rate,
  g = 9.81,
  method = c("magnitude", "shoe"),
  accel_threshold = 0.6,
  gyro_threshold = 0.6,
  sigma_a = 0.05,
  sigma_g = 0.05,
  gamma = 10000,
  window = NULL,
  min_stance = NULL
)

Arguments

Value

A logical vector of length n, TRUE at stance samples.

References

Skog I, Handel P, Nilsson J-O, Rantakokko J (2010). "Zero-velocity detection – an algorithm evaluation." IEEE Trans Biomed Eng 57(11):2657-2666.

See Also

strapdownIntegrate(), footImuGait().

Examples

set.seed(1)
g <- 9.81
stance_block <- matrix(rep(c(0, 0, -g), each = 60), 60, 3)
swing_block <- matrix(rnorm(40 * 3, 0, 3), 40, 3)
accel <- rbind(stance_block, swing_block, stance_block, swing_block, stance_block)
gyro <- rbind(matrix(0, 60, 3), matrix(rnorm(40 * 3, 0, 1.5), 40, 3),
              matrix(0, 60, 3), matrix(rnorm(40 * 3, 0, 1.5), 40, 3),
              matrix(0, 60, 3))
det <- detectStanceZUPT(accel, gyro, sampling_rate = 200)
sum(det)

Description

Stiff-knee gait is marked by reduced peak knee flexion in swing (normal $\approx 60^{\circ}$ near 73\ (Perry & Burnfield; Goldberg et al. 2006).

Usage

detectStiffKnee(
  knee_flexion,
  swing = c(60, 100),
  normal_peak = 60,
  threshold = 45,
  severe_floor = 10,
  delay_threshold = 80
)

Arguments

Value

A gait_pattern_flag object.

References

Perry J, Burnfield JM (2010); Goldberg SR, et al. (2006).

See Also

classifyGaitPatterns(), gaitPatternLibrary()

Examples

# normal knee flexion peaks ~60 deg in swing
k <- c(seq(5, 18, length.out = 30), seq(18, 5, length.out = 30),
       60 * sin(seq(0, pi, length.out = 41)))
detectStiffKnee(k)

Description

Identifies frames where two or more marker trajectories abruptly swap positions, indicating a labelling error. Swaps are detected by velocity spikes that exceed median + 5 * MAD and show a cross-over pattern between marker pairs.

Usage

detectSwaps(pe, threshold = NULL, window = 5, assay_prefix = "position")

Arguments

Value

A data.frame with columns:

frame

Frame index where the swap was detected.

marker_a

Name or index of the first marker in the swap pair.

marker_b

Name or index of the second marker.

velocity_a

Velocity of marker_a at the swap frame.

velocity_b

Velocity of marker_b at the swap frame.

confidence

Confidence score (0-1) based on how closely the cross-over distances match.

If no swaps are detected, an empty data.frame with the same columns is returned.

See Also

trackMarkers(), correctSwaps()

Examples

demo <- demoMoCapData(seed = 1)
swaps <- detectSwaps(demo$mocap)
swaps

Description

A Trendelenburg gait reflects hip-abductor weakness on the stance limb: the contralateral (swing-side) pelvis drops during single-limb stance beyond the normal small obliquity ($\approx 4-5^{\circ}$).

Usage

detectTrendelenburg(
  pelvic_obliquity,
  stance = c(10, 50),
  threshold = 5,
  severe = 15,
  drop_sign = 1
)

Arguments

Value

A gait_pattern_flag object.

References

Perry J, Burnfield JM (2010).

See Also

classifyGaitPatterns()

Examples

pct <- seq(0, 100, length.out = 101)
pelvic_obliquity <- rep(0, 101)
pelvic_obliquity[pct >= 10 & pct <= 50] <- 12
detectTrendelenburg(pelvic_obliquity)

Description

Low-level function to compute numerical derivatives of arbitrary order using finite difference methods.

Usage

differentiate(x, dt, method = c("central", "forward", "backward"), order = 1L)

Arguments

Details

For method = "central" with order = 1:

$f'(i) = (x[i+1] - x[i-1]) / (2 \cdot dt)$

For method = "central" with order = 2:

$f''(i) = (x[i+1] - 2 x[i] + x[i-1]) / dt^2$

For higher orders, the derivative is computed by repeated application of the first-order formula.

Value

Differentiated data with same dimensions as input. Boundary values where the stencil cannot be applied are set to NA.

References

Winter DA (2009). "Biomechanics and Motor Control of Human Movement." 4th ed. John Wiley & Sons.

See Also

computeVelocity() for computing velocity from PhysioExperiment, computeAcceleration() for second-order derivatives, savgolFilter() for smoothed differentiation via Savitzky-Golay.

Examples

# Differentiate sin to get cos
t <- seq(0, 2 * pi, length.out = 200)
x <- sin(t)
dx <- differentiate(x, dt = t[2] - t[1], method = "central", order = 1)
# dx should approximate cos(t)

Description

Dimensionless jerk of a speed profile

Usage

dimensionlessJerk(speed, fs)

Arguments

Value

The (positive) dimensionless jerk. See ldlj for the log form.

Examples

set.seed(1)
speed <- abs(sin(seq(0, pi, length.out = 200))) + 0.01
dimensionlessJerk(speed, fs = 120)

Description

Learns the forcing term of a DMP from one demonstrated trajectory, so it can later be regenerated (and generalised to a new goal or duration) by dmpGenerate().

Usage

dmpFit(y, times = NULL, n_basis = 25L, alpha_z = 25)

Arguments

Value

a dmp object: learned weights (⁠n_basis x D⁠), goal, start, duration, and parameters.

References

Ijspeert AJ, et al. (2013) Neural Comput 25:328-373.

See Also

dmpGenerate(), promFit()

Examples

t <- seq(0, 1, length.out = 100)
y <- 10 * (10*t^3 - 15*t^4 + 6*t^5)               # min-jerk demo
d <- dmpFit(y); rg <- dmpGenerate(d)
max(abs(rg$y[, 1] - y))                            # reproduces the demo

Description

Integrates a fitted dmpFit() DMP, optionally generalising to a new goal, start or duration (temporal scaling) while preserving the movement's shape and guaranteeing convergence to the goal.

Usage

dmpGenerate(dmp, goal = NULL, start = NULL, tau = NULL, n = 100L)

Arguments

Value

a dmp_trajectory: time, y, yd (⁠n x D⁠).

See Also

dmpFit()

Examples

t <- seq(0, 1, length.out = 100)
y <- 10 * (10 * t^3 - 15 * t^4 + 6 * t^5)   # minimum-jerk demo
d <- dmpFit(y)
rollout <- dmpGenerate(d)
dim(rollout$y)

Description

Downloads the subject-specific, scaled OpenSim model (.osim) that OpenCap produced for a session. This model is the input the local OpenSim toolchain needs (runOpenSimFromMarkers / runOpenSimFromOpenCap): OpenCap builds and scales it in the cloud from the neutral/calibration trial, and PhysioOpenSim provides no scaling tool of its own, so the model must come from OpenCap.

Usage

downloadOpenCapModel(
  session_id,
  trial_id = NULL,
  api_key = NULL,
  base_url = "https://app.opencap.ai/api",
  dest = NULL
)

Arguments

Details

Requires the httr package and an OpenCap API key (see readOpenCap). The model URL is taken from the session metadata when present and otherwise constructed from the documented session endpoint.

Requires the OpenCap web API (network access and an API key), so the example cannot run offline and is not executed.

Value

The local path to the downloaded .osim model (invisibly).

References

Uhlrich SD, Falisse A, Kidzinski L, Muccini J, Ko M, Chaudhari AS, Hicks JL, Delp SL (2023). "OpenCap: Human movement dynamics from smartphone videos." PLoS Computational Biology, 19(10), e1011462.

See Also

readOpenCap(), runOpenSimFromOpenCap(), runOpenSimFromMarkers()

Examples

## Not run: 
osim <- downloadOpenCapModel("abcd1234-5678-90ab-cdef-1234567890ab")

## End(Not run)

Description

Computes the average waveform using DTW Barycenter Averaging, which accounts for time warping in the averaging process.

Usage

dtwAverage(x, init = "medoid", max_iter = 30, tol = 1e-04, window_size = NULL)

Arguments

Value

A list containing:

References

Sakoe H, Chiba S (1978). "Dynamic programming algorithm optimization for spoken word recognition." IEEE Transactions on Acoustics, Speech, and Signal Processing, 26(1), 43-49.

Petitjean F, Ketterlin A, Gancarski P (2011). "A global averaging method for dynamic time warping, with applications to clustering." Pattern Recognition, 44(3), 678-693.

See Also

dtwDistance(), dtwDistanceMatrix(), dtwClustering()

Examples

# Average multiple gait cycles with timing variation
set.seed(123)
t <- seq(0, 100, length.out = 100)
data <- sapply(1:20, function(i) {
  phase <- rnorm(1, 0, 10)
  sin(2 * pi * (t + phase) / 100) * 30 + rnorm(100, 0, 2)
})

avg <- dtwAverage(data)
plot(avg$average, type = "l")

Description

Clusters waveforms using DTW distance with hierarchical or k-medoids method.

Usage

dtwClustering(
  x,
  k = 2,
  method = c("hierarchical", "kmedoids"),
  linkage = "ward.D2",
  window_size = NULL
)

Arguments

Value

A list containing:

References

Sakoe H, Chiba S (1978). "Dynamic programming algorithm optimization for spoken word recognition." IEEE Transactions on Acoustics, Speech, and Signal Processing, 26(1), 43-49.

See Also

dtwDistance(), dtwDistanceMatrix(), dtwAverage()

Examples

# Cluster gait patterns
set.seed(123)
t <- seq(0, 100, length.out = 100)

# Generate two groups with different patterns
group1 <- sapply(1:15, function(i) {
  sin(2 * pi * t / 100) * 30 + rnorm(100, 0, 3)
})
group2 <- sapply(1:15, function(i) {
  sin(2 * pi * t / 100 + pi/4) * 20 + rnorm(100, 0, 3)
})
data <- cbind(group1, group2)

result <- dtwClustering(data, k = 2)
table(result$clusters)

Description

Functions for Dynamic Time Warping analysis including distance computation, alignment, averaging, and clustering of biomechanical waveforms. Compute DTW distance between two time series

Usage

dtwDistance(
  x,
  y,
  window_size = NULL,
  step_pattern = c("symmetric2", "symmetric1", "asymmetric"),
  normalize = TRUE
)

Arguments

Details

Calculates the Dynamic Time Warping distance and alignment path between two waveforms, allowing for non-linear time alignment.

DTW finds the optimal alignment between two time series by warping the time axis. It's useful for comparing movements that may occur at different speeds or with timing differences.

Value

A list of class "dtw_result" containing:

References

Sakoe H, Chiba S (1978). "Dynamic programming algorithm optimization for spoken word recognition." IEEE Transactions on Acoustics, Speech, and Signal Processing, 26(1), 43-49.

See Also

dtwDistanceMatrix(), dtwAverage(), dtwClustering(), dtwWarp()

Examples

# Two gait cycles with different timing
t <- seq(0, 100, length.out = 100)
x <- sin(2 * pi * t / 100) * 30
y <- sin(2 * pi * (t + 10) / 100) * 30  # Phase shifted

result <- dtwDistance(x, y)
print(result$distance)

Description

Computes pairwise DTW distances between all columns of a matrix or between observations in a PhysioExperiment.

Usage

dtwDistanceMatrix(x, window_size = NULL, normalize = TRUE, parallel = FALSE)

Arguments

Value

A symmetric distance matrix.

References

Sakoe H, Chiba S (1978). "Dynamic programming algorithm optimization for spoken word recognition." IEEE Transactions on Acoustics, Speech, and Signal Processing, 26(1), 43-49.

See Also

dtwDistance(), dtwAverage(), dtwClustering()

Examples

# Create matrix of 10 gait cycles
set.seed(123)
t <- seq(0, 100, length.out = 100)
data <- sapply(1:10, function(i) {
  phase <- rnorm(1, 0, 10)
  sin(2 * pi * (t + phase) / 100) * 30 + rnorm(100, 0, 2)
})

dist_matrix <- dtwDistanceMatrix(data)

Description

Applies a DTW alignment path to warp one waveform to match another.

Usage

dtwWarp(x, dtw_result, to = c("query", "reference"))

Arguments

Value

Warped waveform.

References

Sakoe H, Chiba S (1978). "Dynamic programming algorithm optimization for spoken word recognition." IEEE Transactions on Acoustics, Speech, and Signal Processing, 26(1), 43-49.

See Also

dtwDistance(), dtwAverage(), normalizeMovement()

Examples

x <- sin(seq(0, pi, length.out = 100)) * 30
y <- sin(seq(0, pi, length.out = 100) + 0.3) * 30
dr <- dtwDistance(x, y)
warped <- dtwWarp(x, dr)
length(warped)

Description

Computes constant, variable, absolute, and root-mean-square endpoint error. Variable error uses the population RMS distance about the endpoint centroid, preserving the identity RMSE^2 = constant_error^2 + variable_error^2.

Usage

endpointError(endpoints, target)

Arguments

Value

A reaching_endpoint_error object with constant, variable, absolute, RMS, and Fitts effective-width errors.

References

Hancock GR, Butler MS, Fischman MG (1995). On the problem of two-dimensional error scores: measures and analyses of accuracy, bias, and consistency. Journal of Motor Behavior, 27:241-250.

Fitts PM (1954). The information capacity of the human motor system in controlling the amplitude of movement. Journal of Experimental Psychology, 47:381-391. doi:10.1037/h0055392

Examples

endpointError(c(11, 12, 13, 12), target = 10)

Description

Fuses accelerometer, gyroscope, and optionally magnetometer data to estimate 3D orientation over time. Returns both quaternion and Euler angle representations.

Usage

estimateOrientation(
  accel,
  gyro,
  mag = NULL,
  method = c("madgwick", "complementary"),
  beta = 0.1,
  sampling_rate
)

Arguments

Details

The Madgwick filter uses a gradient-descent algorithm to correct gyroscope drift using accelerometer (and optionally magnetometer) measurements. The beta parameter controls the correction strength.

The complementary filter blends gyroscope integration (high-pass) with accelerometer tilt estimation (low-pass). The beta parameter serves as the alpha coefficient, controlling the balance between gyroscope and accelerometer contributions.

Value

A data.frame with columns:

time

Time in seconds from start.

roll

Roll angle (degrees), rotation about X axis.

pitch

Pitch angle (degrees), rotation about Y axis.

yaw

Yaw angle (degrees), rotation about Z axis.

q_w

Quaternion scalar component.

q_x

Quaternion x component.

q_y

Quaternion y component.

q_z

Quaternion z component.

References

Madgwick SOH, Harrison AJL, Vaidyanathan R (2011). "Estimation of IMU and MARG orientation using a gradient descent algorithm." IEEE International Conference on Rehabilitation Robotics.

See Also

removeGravity(), calibrateIMU(), quaternionToEuler()

Examples

# Simulate static IMU data (sensor resting with gravity along -Z)
n <- 100
accel <- matrix(c(rep(0, n), rep(0, n), rep(-9.81, n)), ncol = 3)
gyro <- matrix(0, nrow = n, ncol = 3)
result <- estimateOrientation(accel, gyro, sampling_rate = 100)
head(result)

Description

Builds foot/shank/thigh inertial parameters from body mass and segment lengths using De Leva-style coefficients.

Usage

estimateSegmentInertia(
  body_mass,
  segment_lengths = NULL,
  body_height = NULL,
  model = c("deLeva_male", "deLeva_female")
)

Arguments