[akhanf]

Proposed changes

Adds support for selecting participants based on the dataset's participants.tsv, and exposes the table on BidsDataset.

Filtering

• New participant_filter argument to generate_inputs() and --participant-filter CLI flag (in BidsArgs), e.g. --participant-filter "age > 60 and group == 'patient'".
• The query is evaluated with pandas.DataFrame.query. The subject label (without sub-) can be referenced as subject.
• The selected labels are fed into the existing subject post-filter, so the filter intersects with --participant-label and combines with --exclude-participant-label. Custom-path components are filtered too.
• Subjects on disk but missing from participants.tsv are excluded, with a warning listing them. A warning is also logged if no participants match. Requesting a filter on a dataset without participants.tsv raises a ConfigError, as does an invalid query (the error lists the available columns).

BidsDataset.participants

• The full contents of participants.tsv as a DataFrame indexed by subject label, or None if the file is absent. It is not filtered; participants.loc[dataset.subjects] selects the subjects in the dataset.
• participant_id is read as text (keeps leading zeros) and n/a is read as missing.
• Because the table is read on every generate_inputs() call, a malformed participants.tsv only logs a warning unless a filter was requested.

Remote datasets

• The file is read through universal-pathlib (already required by pybids), so gs://, s3:// and other fsspec locations work. universal-pathlib is now a direct dependency.

Other

• pandas-stubs added to the dev group, since pyright runs in strict mode.
• get_subjects added to the local BIDSLayout stub (pybids generates it dynamically).
• Template Snakefile and docs pass participant_filter=config.get("participant_filter"). Existing apps need to add that line to get the CLI flag working.

Checklist

• Changes have been tested to ensure that fix is effective or that a feature works.
• Changes pass the unit tests
• I have included necessary documentation or comments (as necessary)
• Any dependent changes have been merged and published

New tests are in tests/test_participants.py; remote reading is tested with fsspec's in-memory filesystem. Locally, ruff and pyright are clean. The full suite passed except tests that also fail on main locally (template tests needing docker, intermittent hypothesis deadline timeouts). Opened as a draft to get CI results. User docs are in docs/running_snakebids/overview.md ("Selecting participants", including a Limitations section) and docs/bids_app/workflow.md ("Accessing participant metadata").

Notes

Known limitations, documented rather than fixed in this PR. Both come from the existing subject post-filter on main: the first also affects --participant-label, and the second can be triggered on main with generate_inputs(..., participant_label=[]), but the filter makes an empty selection much easier to reach:

• Components with a subject filter in pybids_inputs ignore the participant selection.
• A selection matching no subjects raises ValueError for components with a custom_path, instead of returning an empty component.

Open questions for review:

• Should BidsDataset.participants be restricted to the subjects in the dataset rather than the full table?
• pandas is now imported directly but is only listed in pyproject.toml under a Python ≥3.12 marker; it should probably become an unconditional direct dependency.

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 95.48%. Comparing base (1d97fee) to head (57c682e).

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #542      +/-   ##
==========================================
+ Coverage   95.35%   95.48%   +0.12%     
==========================================
  Files          56       57       +1     
  Lines        2543     2611      +68     
==========================================
+ Hits         2425     2493      +68     
  Misses        118      118              

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[Copilot]

🟡 Changes recommended

Existing subject filters can bypass participant-query selections, silently allowing unselected subjects to be processed.

3 open issues

• Apply participant selections despite subject prefilters · New
• Handle empty custom-path participant selections · New
• Convert participant decoding errors to ConfigError · New

What changed in this PR

Adds participant-table filtering to Snakebids input generation and exposes the full participants.tsv table through BidsDataset.participants.

Changes:

• Adds participant_filter and CLI support for selecting subjects with pandas queries.
• Introduces local and remote participant-table reading, with validation and warnings.
• Updates workflow examples, dependencies, type definitions, and tests.

File	Description
uv.lock	Records new runtime and typing dependencies.
typings/​bids/​layout/​layout.pyi	Adds the get_subjects type declaration.
tests/​test_plugins/​test_snakemake.py	Updates expected configuration with participant_filter.
tests/​test_participants.py	Tests table reading, querying, and filtering integration.
tests/​test_bidsapp.py	Updates plugin setup for the new argument.
src/​snakebids/​project_template/​{{name_slug}}/​workflow/​Snakefile	Passes participant filters into generated workflows.
src/​snakebids/​plugins/​bidsargs.py	Registers and documents the participant-filter CLI option.
src/​snakebids/​core/​participants.py	Implements participant-table reading and querying.
src/​snakebids/​core/​input_generation.py	Integrates participant selection and attaches table metadata.
src/​snakebids/​core/​datasets.py	Adds the unfiltered participants table to BidsDataset.
src/​snakebids/​bidsapp/​args.py	Adds the participant-filter configuration type.
pyproject.toml	Declares universal-pathlib and pandas typing dependencies.
docs/​bids_app/​workflow.md	Updates the workflow example to pass participant filters.

_{Review effort: Balanced}