Biometrics

The biometrics modality is a PRISM extension designed for physiological assessments that do not fit into standard BIDS beh or physio categories. Examples include VO2max tests, plank tests, balance assessments, or anthropometric measurements.

File Name Structure

Biometric data files MUST follow this naming convention:

sub-<label>[_ses-<label>]_task-<label>_biometrics.<extension>

Entity	Description
sub	Required. The subject identifier.
ses	Optional. The session identifier.
task	Required. The name of the biometric task (e.g., task-ukk, task-plank).
biometrics	Required. The suffix indicating the modality.
extension	Required. Typically .tsv.

Example: sub-001_ses-01_task-ukk_biometrics.tsv

Sidecar JSON (*_biometrics.json)

Each biometric data file MUST be associated with metadata in a JSON sidecar. This file contains metadata about the assessment protocol.

PRISM follows the BIDS inheritance principle for biometrics sidecars:

• Preferred (inherited): one dataset-level sidecar per task, named task-<task>_biometrics.json in the dataset root.

• Override (if metadata truly differs): a subject/session-specific sidecar next to the TSV (e.g., sub-01_ses-01_task-<task>_biometrics.json).

Top-Level Objects

The JSON structure is divided into three main objects to organize metadata logically.

Object	Requirement	Description
Technical	REQUIRED	Technical details about the data acquisition.
Study	REQUIRED	Scientific context, protocol details, and references.
Metadata	REQUIRED	Administrative metadata about the file itself.

Technical Object Fields

Key	Requirement	Type	Description
StimulusType	REQUIRED	string	MUST be "Biometrics".
FileFormat	REQUIRED	string	The format of the data file (e.g., "tsv").
Equipment	REQUIRED	string	The device or equipment used (e.g., “Stopwatch”, “Cycle Ergometer”).
Supervisor	OPTIONAL	string	Who supervised the test. Allowed: "investigator", "physician", "trainer", "self".

Study Object Fields

Key	Requirement	Type	Description
BiometricName	REQUIRED	string	Short alphanumeric identifier (e.g., "ukk").
OriginalName	REQUIRED	string	Full human-readable name (e.g., "UKK Walk Test").
Description	REQUIRED	string	Detailed description of the procedure.
Instructions	RECOMMENDED	string	Instructions given to the participant.
Protocol	OPTIONAL	string	Reference to the specific protocol used.
Author	OPTIONAL	string	Author(s) of the test protocol.
DOI	OPTIONAL	string	DOI of the reference publication.
Reference	OPTIONAL	string	Full citation.
EstimatedDuration	OPTIONAL	string	Typical duration (e.g., "15 min").
TargetPopulation	OPTIONAL	string	Intended demographic (e.g., "Adults 18-65").
ExclusionCriteria	OPTIONAL	string	Contraindications.

Metadata Object Fields

Key	Requirement	Type	Description
SchemaVersion	REQUIRED	string	Version of the schema used (e.g., "1.0.0").
CreationDate	REQUIRED	string	Date of file creation in YYYY-MM-DD format.
Creator	OPTIONAL	string	Tool or person who created the file.

Metric (Column) Definitions

In addition to the three top-level objects, a biometrics sidecar typically contains one object per TSV column (the column name is the JSON key). These entries document how to interpret and validate each metric.

Common fields for each metric:

Key	Requirement	Type	Description
Description	REQUIRED	string	Human-readable description of the metric/column.
Units	REQUIRED	string	Unit of measurement (e.g., cm, sec, percent, score).
DataType	OPTIONAL	string	Expected type: string, integer, float.
MinValue / MaxValue	OPTIONAL	number	Hard bounds for valid values.
AllowedValues	OPTIONAL	array	Enumerated allowed values (numbers/strings).
Levels	OPTIONAL	object	Mapping of coded values to labels (e.g., Likert scale).
SessionHint	OPTIONAL	string	Optional session hint for repeated assessments (e.g., ses-1).
RunHint	OPTIONAL	string	Optional run hint for repeated assessments (e.g., run-2).

Example metric with labeled levels:

"rpe_scale": {
  "Description": "Rate of perceived exertion",
  "Units": "score",
  "DataType": "integer",
  "AllowedValues": [0, 1, 2, 3],
  "Levels": {
    "0": "selten oder überhaupt nicht",
    "1": "manchmal",
    "2": "öfter",
    "3": "meistens"
  }
}

Generating Templates from Excel

You can generate biometrics JSON templates from a single-sheet Excel codebook (no data required) using prism_tools.py biometrics import-excel. See docs/PRISM_TOOLS.rst for the full column list and an example.

Example Sidecar

{
  "Technical": {
    "StimulusType": "Biometrics",
    "FileFormat": "tsv",
    "Equipment": "Stopwatch, Heart Rate Monitor"
  },
  "Study": {
    "BiometricName": "ukk",
    "OriginalName": "UKK 2km Walk Test",
    "Description": "Participants walk 2km as fast as possible. HR and time are recorded.",
    "Instructions": "Walk 2km at a steady, fast pace. Do not run.",
    "Reference": "Oja et al. (1991)",
    "EstimatedDuration": "15-20 min"
  },
  "Metadata": {
    "SchemaVersion": "1.0.0",
    "CreationDate": "2025-11-27"
  }
}