pymovements.Participants.verify_bids

Participants.verify_bids(level: Literal['REQUIRED', 'RECOMMENDED'] = 'REQUIRED') → list[str]

Verify BIDS conformity of participant data.

Parameters:

level (Literal['REQUIRED', 'RECOMMENDED']) – Level of BIDS compliance to verify. REQUIRED: Check required fields only. RECOMMENDED: Check required fields plus recommended fields.

Returns:

List of warning messages for each non-conformity found. Empty list if data is BIDS conformant.

Return type:

list[str]

Examples

Verify BIDS compliance at REQUIRED level (default):

>>> import polars as pl
>>> from pymovements import Participants
>>> data = pl.DataFrame({
...     "participant_id": ["sub-01", "sub-02"],
...     "age": [34, 12],
...     "sex": ["M", "F"],
... })
>>> participants = Participants(data, verify_bids=False)
>>> warnings = participants.verify_bids("REQUIRED")
>>> print(warnings)
[]

Verify at RECOMMENDED level with non-conformant data:

>>> data = pl.DataFrame({
...     "participant_id": ["01", "sub-02"],
...     "age": [34, 100],  # age over 89
...     "sex": ["M", "invalid"],
... })
>>> participants = Participants(data, verify_bids=False)
>>> warnings = participants.verify_bids("RECOMMENDED")
>>> for w in warnings:
...     print(w)
participant_id values must match 'sub-<label>' pattern. Invalid values: ['01']
Recommended column 'handedness' is missing
age should be capped at 89, found 100.0
sex must be one of ['F', 'FEMALE', 'Female', 'M', 'MALE', 'Male', 'O', 'OTHER', 'Other',
'f', 'female', 'm', 'male', 'o', 'other'], found: ['invalid']

Using verify_bids=True during initialisation raises an exception:

>>> data = pl.DataFrame({"participant_id": ["01"]})
>>> try:
...     participants = Participants(data, verify_bids=True)
... except ValueError as e:
...     print(str(e)[:50])
BIDS non-conformities found: participant_id values

Using verify_bids='REQUIRED' emits warnings but continues:

>>> import warnings as warn
>>> data = pl.DataFrame({"participant_id": ["01"]})
>>> with warn.catch_warnings(record=True) as w:
...     warn.simplefilter("always")
...     participants = Participants(data, verify_bids="REQUIRED")
...     print(str(w[0].message))
participant_id values must match 'sub-<label>' pattern. Invalid values: ['01']