Configuration Reference¶

The entire pipeline is driven by a single YAML file (default path config/pipeline_config.yaml). This page documents every section and key.

The config is parsed and validated with Pydantic. Unknown keys are silently ignored at every level (a warning lists unknown top-level keys), so a typo in a key name means your value is dropped rather than applied — watch the logs. Loading is done by PipelineConfig.from_yaml(path), which raises a ConfigurationError if the file is missing, unparseable, empty, or fails validation.

Top-level structure¶

bids: { ... }                  # BIDS metadata defaults
sampling_frequencies: { ... }  # expected Hz per system
system_descriptions: { ... }   # sidecar TaskDescription per system
input: { ... }                 # where to read from
output: { ... }                # where to write to
session_mappings: [ ... ]      # source folder → subject/session
device: { ... }                # hardware metadata
systems: { ... }               # enable/disable each system
validation: { ... }            # quality checks
preprocessing: { ... }         # masking & time columns
report: { ... }                # HTML report

bids, input, output, device, validation, preprocessing, report, sampling_frequencies, and system_descriptions are required sections. session_mappings and systems may be omitted (they default to empty).

input¶

Where to read session data and how to find each file. All five keys are required.

Patterns are resolved per session folder; if several files match, the most recent (by modification time) is used. See Input Data Format.

output¶

Where the BIDS dataset is written. All keys required.

session_mappings¶

A list mapping each source folder to BIDS identifiers. If omitted or empty, the pipeline auto-discovers every subfolder of data_dir containing a metadata file and numbers subjects sequentially (01, 02, …) with session 01.

session_mappings:
  - source_dir: "Demo_Data/Binary/2026.06.10_18-22"
    subject_id: "01"
    session_label: "01"
    age: "27"
    sex: "F"
    handedness: "R"

device¶

Hardware metadata for the BIDS sidecars.

systems¶

Enable or disable each tracking system. A system absent from this map defaults to enabled. A system is only emitted if it is enabled here, enabled in the recording's metadata flags, and has data columns present.

systems:
  Head:        { enabled: true }
  Hands:       { enabled: true }
  Eyes:        { enabled: true }
  Face:        { enabled: true }
  Body:        { enabled: false }
  Controllers: { enabled: false }

enabled is a strict boolean and is required for each listed system.

sampling_frequencies¶

Expected sampling rate (Hz) per system. Required for every system you emit — splitting a system with no entry raises a ConfigurationError. Values must be floats (90.0, not 90).

sampling_frequencies:
  Head: 72.0
  Hands: 90.0
  Eyes: 30.0
  Face: 30.0
  Body: 72.0
  Controllers: 90.0

The expected rate is written as SamplingFrequency; the pipeline also measures the effective rate from the data and writes it as SamplingFrequencyEffective. The sampling_rate check compares the two.

system_descriptions¶

Human-readable description per system, written to each motion.json as TaskDescription (unless overridden by device.task_description).

system_descriptions:
  Head: "Head position and rotation tracking from Meta Quest VR headset"
  Hands: "Hand and finger tracking from Meta Quest VR headset including 26 joints per hand"
  Eyes: "Eye gaze tracking from Meta Quest VR headset"
  Face: "Facial expression tracking using FACS blend shapes from Meta Quest VR headset"
  Body: "Full body joint tracking from Meta Quest VR headset"
  Controllers: "VR controller position and rotation tracking"

bids¶

BIDS dataset metadata. All keys required except authors and readme_text.

bids.reference_frame¶

Describes the global coordinate system; emitted into every channels.json sidecar. All four keys required.

reference_frame:
  description: "Global VR playspace coordinate system. Positive X is right, Y is up (superior), Z is forward (anterior)"
  rotation_rule: "left-hand"
  rotation_order: "ZXY"
  spatial_axes: "RSA"

validation¶

Configures which quality checks run and their thresholds. See Validation & Quality Checks for the full behavior of each check.

validation.column_groups¶

Each group has a name (required), columns (required, list of column names), and optional description. Group names must be unique. Checks request their groups by name; if no groups are configured, a check falls back to a single default group containing all of the stream's columns.

column_groups:
  - name: "Left Hand"
    description: "Left hand wrist position and rotation"
    columns:
      - Left_XRHand_Wrist_x
      - Left_XRHand_Wrist_y
      - Left_XRHand_Wrist_z
      - Left_XRHand_Wrist_Rotation_x
      - Left_XRHand_Wrist_Rotation_y
      - Left_XRHand_Wrist_Rotation_z
  - name: "Right Hand"
    description: "Right hand wrist position and rotation"
    columns:
      - Right_XRHand_Wrist_x
      # ...

validation.settings¶

Common keys (each consumed by a specific check; defaults apply when the key is absent):

settings:
  sampling_rate_tolerance: 0.10
  sampling_cv_threshold: 0.5
  eyes_closed_threshold: 0.9
  eyes_closed_min_duration: 0.1
  check_column_groups:
    hands_tracking_loss:
      - "Left Hand"
      - "Right Hand"

preprocessing¶

Controls optional quality masking and per-system time columns.

alternate_time_columns¶

By default every stream uses the global engine clock as its timestamp. Some streams carry their own clock (e.g. hands sampled on a separate thread). Mapping a system to its own time column makes the splitter use that column as the stream's timestamp and preserve the global clock as timeSinceStartup. At export these become latency (per-system) and latency_global respectively — see LATENCY channels.

alternate_time_columns:
  Head: "Node_Head_Time"
  Hands: "Node_HandLeft_Time"
  Eyes: "Eyes_Time"
  Face: "Face_Time"
  Body: "Body_Time"
  Controllers: "Node_ControllerLeft_Time"

Leave it as {} to use the global clock for all systems.

report¶

See Quality Reports.