Gait Metrics

Gait Metrics Reference

Overview

The gait analysis pipeline detects walking segments from kinematic reconstructions, extracts gait events (foot contacts), and computes spatiotemporal metrics, joint kinematics, and the Gait Deviation Index (GDI). It works with both multi-camera (MMC) and monocular (PBL) data.

Schemas: project_body_models_gait_cycles (walking detection, gait events) and project_gdi (GDI computation)

Source: BodyModels/body_models/datajoint/gait/ and BodyModels/body_models/biomechanics_mjx/gait/

Finding Valid Walking Segments

Walking segments are detected by GaitTransformer (MMC) and GaitTransformerMonocular (PBL). Both use a GaitTransformer neural network + Kalman filter pipeline to identify when a person is walking.

Detection Pipeline

1. Keypoint extraction from sites (17 keypoints mapped to GastNet order)
2. GaitTransformer inference produces 8-channel gait phase output
3. Kalman filter smoothing refines phase estimates, produces error signal
4. Walking probability = prob_err * prob_speed where:
   • prob_err = exp(-errors * 2) (Kalman filter prediction error)
   • prob_speed = sigmoid of phase velocity * consistency with median
5. Hysteresis thresholding (0.35/0.65) + median filter deglitching
6. Minimum segment length filter (>100 frames)

Querying Walking Segments

from body_models.datajoint.gait.gait_cycles_dj import GaitTransformer, GaitTransformerMonocular

# Get the longest walking segment for a trial
key = {
    'participant_id': '104', 'session_date': date(2023, 7, 21),
    'kinematic_reconstruction_settings_num': 137,
    'transformer_method_name': 'default',
}

# WalkingSegment part table has aggregate stats per segment
segments = (GaitTransformer.WalkingSegment & key).fetch(as_dict=True, order_by='num_frames DESC')
best_segment = segments[0]  # Longest segment

# Aggregate stats available per segment:
#   num_frames, cadence, velocity,
#   stance_left, stance_right, ss_left, ss_right, dst,
#   length_left, length_right, width_left, width_right,
#   cycles_left, cycles_right (interpolated gait cycles, 100 timepoints each)

Filtering for Walking Trials

from multi_camera.datajoint.annotation import VideoActivity

# Only trials annotated as walking
walking_trials = (
    GaitTransformer
    & (VideoActivity & {'video_activity': 'Overground Walking'})
    & {'kinematic_reconstruction_settings_num': 137}
)

# From a specific project
from multi_camera.datajoint.multi_camera_dj import MultiCameraRecording
walking_controls = walking_trials & (MultiCameraRecording & {'video_project': 'GAIT_CONTROLS'})

Monocular Walking Segments

from portable_biomechanics_sessions.session_annotations import VideoActivity as PBLVideoActivity

monocular_walking = (
    GaitTransformerMonocular
    & (PBLVideoActivity & {'video_activity': 'Overground Walking'})
    & {'monocular_reconstruction_settings_num': -108}
)

Gait Events

GaitTransformer stores four event arrays as longblobs:

events = (GaitTransformer & key).fetch1()
left_down = events['left_down']    # numpy array of timestamps
right_down = events['right_down']

# Filter events to longest walking segment
timestamps = (KinematicReconstruction.Trial & key).fetch1('timestamps')
start, end = (GaitTransformer.WalkingSegment & key).fetch(
    'segment_start', 'segment_end', order_by='num_frames DESC', limit=1
)
t0, te = timestamps[start[0]], timestamps[end[0]]
valid_left_down = [t for t in left_down if t0 <= t <= te]

Gait Cycle Definition

A gait cycle runs from one foot contact to the next same-foot contact:

• Stride = foot_down[i] to foot_down[i+1] (one full cycle)
• Stance phase = foot_down to foot_up (foot on ground)
• Swing phase = foot_up to next foot_down (foot in air)
• Step = contralateral foot_down to ipsilateral foot_down

Spatiotemporal Metrics

Step-by-Step Metrics (Steps Part Table)

GaitTransformer.Steps stores per-step metrics:

steps = (GaitTransformer.Steps & key).fetch(as_dict=True)

Computing Detailed Metrics from Raw Data

For more detailed analysis beyond the stored tables, use gait_analysis.py:

from body_models.datajoint.gait.gait_analysis import compute_gait_analysis, summarize_gait_metrics

results = compute_gait_analysis(key)
# Returns dict with: timestamps, reoriented_qpos, reoriented_joints, events_raw, metrics

# metrics contains DataFrames:
#   step_metrics: step_time, step_length per step
#   gait_cycle_metrics: cycle_time, stride_length, walking_speed per cycle
#   phase_metrics: stance%, swing% per cycle
#   joint_rom: ROM per joint per cycle (radians)
#   knee_swing_rom: knee ROM during swing only
#   ankle_at_foot_down: ankle angle at each foot contact

summary = summarize_gait_metrics(results)
# Returns DataFrame with Mean/Std per side + asymmetry indices

Or use the standalone function (does not require GaitTransformer table):

from body_models.biomechanics_mjx.gait.gait_metrics import compute_gait_analysis

results = compute_gait_analysis(key, remove_first_cycle=True)
# metrics dict: step_metrics, phase_metrics, cycle_rom, phase_rom, ankle_at_foot_down

Metric Definitions

Step Metrics

Phase Metrics

Joint Angles Analyzed

Asymmetry Index

asymmetry = |left_mean - right_mean| / max(left_mean, right_mean) * 100

Computed for: step time, step length, cycle time, stride length, walking speed, stance phase, hip flexion ROM, knee angle ROM.

Gait Deviation Index (GDI)

GDI quantifies overall gait pathology by comparing joint angle patterns to a control group using PCA.

Schema: project_gdi

Tables

Computing GDI

from body_models.biomechanics_mjx.gait.gdi import get_gdi_matrix_session, pca_gdi

# Get control group matrix (aggregate per session)
ctrl_keys = (GDICyclesMethod & {'video_project': 'GAIT_CONTROLS'}).fetch('KEY')
ctrl_matrix, ctrl_session_keys = get_gdi_matrix_session(ctrl_keys)

# Get treatment group matrix
trtmt_keys = (GDICyclesMethod & {'video_project': 'PROSTHETIC_GAIT'}).fetch('KEY')
trtmt_matrix, trtmt_session_keys = get_gdi_matrix_session(trtmt_keys)

# Compute GDI scores
gdi_ctrl, gdi_trtmt, ctrl_pca, trtmt_pca, n_components = pca_gdi(ctrl_matrix, trtmt_matrix)
# GDI ~ 100 = normal, lower = more pathological (each 10-point drop = 1 SD from normal)

GDI Interpretation

Walking Segment Validation

Stride Length Filter

gait_analysis.py filters cycles by minimum stride length (default 0.1m) using pelvis displacement. It also discards the first valid cycle per side to remove gait initiation artifacts.

# Internal logic in _filter_events_by_valid_cycles:
# 1. For each foot-down-to-foot-down cycle, compute pelvis displacement
# 2. Keep cycles where displacement >= 0.1m (walking forward)
# 3. Drop first valid cycle per side (initiation artifact)

Quality Filtering with MultiTrackingDetection

from multi_camera.datajoint.quality_metrics import MultiTrackingDetection

# Filter for trials with no tracking breaks
good_track = (MultiTrackingDetection & "top_down_method=12 and reconstruction_method=2") & "num_breaks=0"
clean_gait = GaitTransformer & good_track

GaitAnalytics (Per-Step/Cycle Detail)

Schema: idjuraskovic_gait_analytics Source: BodyModels/body_models/datajoint/gait/gait_analytics_dj.py Branch: gait_metrics_rebase (in development, not merged to main)

GaitAnalytics stores detailed per-step and per-cycle metrics in normalized part tables. Preferred over StepMetrics when available — provides individual step/cycle data rather than trial-level aggregates.

Table Structure

GaitAnalytics (master) → KinematicReconstruction.Trial, steps_count

Querying GaitAnalytics

from body_models.datajoint.gait.gait_analytics_dj import GaitAnalytics

key = {'participant_id': '104', 'session_date': date(2023, 7, 21),
       'kinematic_reconstruction_settings_num': 137}

# Per-step data
steps = (GaitAnalytics.Steps & key).fetch(as_dict=True)

# Phase breakdown per cycle
phases = (GaitAnalytics.PhaseMetrics & key).fetch(as_dict=True)

# Joint ROM per cycle
rom = (GaitAnalytics.CycleROM & key).fetch(as_dict=True)

Utility Functions

from body_models.utils.gait_analytics_utils import (
    fetch_all_gait_analytics,          # All part tables as dict of DataFrames
    compute_step_summary_statistics,    # Median/std/min/max per side
    compute_all_asymmetry_indices,      # Signed: 100 * (R - L) / avg(L, R)
    compute_normative_step_statistics,  # Control group step stats
    compute_normative_walking_speed,    # Control group walking speed
    highlight_outliers,                 # Styler coloring outside normative range
)

# Fetch everything for a trial
data = fetch_all_gait_analytics(key)
# Returns: {'steps': df, 'phases': df, 'cycle_rom': df, 'phase_rom': df, 'ankle_at_foot_down': df}

# Summary statistics
summary = compute_step_summary_statistics(data['steps'], aggregation='median')

# Asymmetry (signed: positive = right > left)
asym = compute_all_asymmetry_indices(data['steps'], data['phases'], aggregation='median')

Control group filter: participant_id LIKE '6%'

Quick Reference: Imports

# Walking detection tables
from body_models.datajoint.gait.gait_cycles_dj import (
    GaitTransformer, GaitTransformerMonocular,
    TransformerMethod, TransformerMethodMonocular,
    TransformerMethodLookup,
)

# GDI tables
from body_models.datajoint.gait.gdi_dj import (
    GDICycles, GDICyclesMonocular,
    GDICyclesMethod, GDICyclesMethodMonocular,
    GDIJointsLookup,
)

# Detailed gait analysis (DataJoint-based, uses GaitTransformer)
from body_models.datajoint.gait.gait_analysis import (
    compute_gait_analysis, summarize_gait_metrics, plot_gait_analysis, StepMetrics,
)

# Standalone gait metrics (direct from KinematicReconstruction)
from body_models.biomechanics_mjx.gait.gait_metrics import (
    compute_gait_analysis as compute_gait_analysis_standalone,
    calculate_step_metrics,
)

# GDI computation
from body_models.biomechanics_mjx.gait.gdi import (
    get_gdi_matrix_session, get_gdi_matrix_steps, pca_gdi,
)

# GaitAnalytics tables (branch: gait_metrics_rebase, not merged)
from body_models.datajoint.gait.gait_analytics_dj import GaitAnalytics
from body_models.utils.gait_analytics_utils import (
    fetch_all_gait_analytics, compute_step_summary_statistics,
    compute_all_asymmetry_indices, compute_normative_step_statistics,
    compute_normative_walking_speed, highlight_outliers,
)

# Walking activity annotations
from multi_camera.datajoint.annotation import VideoActivity
from portable_biomechanics_sessions.session_annotations import VideoActivity as PBLVideoActivity

Common Mistakes