ENH: Add descriptions.tsv for BIDS derivatives

[yarikoptic]

Changes proposed in this pull request

This PR adds support for generating a descriptions.tsv file at the derivatives root level, following the BIDS common derivatives specification.

What it does

fMRIPrep produces outputs with _desc- entities (e.g., desc-preproc, desc-brain, desc-hmc) but previously lacked documentation of what these descriptions mean. This PR adds:

1. fmriprep/data/descriptions.json - Template definitions for all desc- entities with:

   • Procedure-focused descriptions explaining what processing was performed (not what the data represents - that's the role of _suffix)
   • Conditional parts that are only included when the corresponding processing was applied
   • Parameter placeholders for runtime substitution

2. fmriprep/utils/bids.py - New write_descriptions_tsv() function that:

   • Dynamically generates descriptions based on actual processing performed
   • Omits steps that weren't applied (e.g., SDC not mentioned if no fieldmaps)
   • Includes a JSON parameters column with thresholds and settings used

3. Integration in fmriprep/cli/run.py - Writes descriptions.tsv alongside dataset_description.json

Example output

With full preprocessing (SDC + STC):

desc_id	description	parameters
preproc	Preprocessing pipeline applied: head motion correction, susceptibility distortion correction (TOPUP), slice timing correction (reference: 0.5)	{"sdc_method": "TOPUP", "stc_applied": true, "slice_time_ref": 0.5}
brain	Brain extraction via FreeSurfer segmentation, projected and binarized	{"mask_source": "FreeSurfer"}

Without SDC/STC:

desc_id	description	parameters
preproc	Preprocessing pipeline applied: head motion correction	{"sdc_applied": false, "stc_applied": false}

Tests

• 10 new unit tests covering JSON structure, TSV generation, and dynamic description building
• All 152 existing tests pass
• Updated CircleCI expected output files

Documentation that should be reviewed

The descriptions.tsv output format follows BIDS conventions. No documentation changes are included in this PR, but the output files are self-documenting.

[yarikoptic]

FWIW, this is my convention to annotate AI produced unittests since often they are not "as good" as human curated and might require either consolidation or just more careful review to see if worthy

[codecov]

Codecov Report

❌ Patch coverage is 90.24390% with 16 lines in your changes missing coverage. Please review.
✅ Project coverage is 73.47%. Comparing base (55087d5) to head (6f854d2).

Files with missing lines	Patch %	Lines
fmriprep/tests/test_descriptions.py	92.56%	2 Missing and 7 partials ⚠️
fmriprep/utils/bids.py	87.80%	4 Missing and 1 partial ⚠️
fmriprep/cli/run.py	0.00%	2 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #3591      +/-   ##
==========================================
+ Coverage   72.88%   73.47%   +0.58%     
==========================================
  Files          60       61       +1     
  Lines        4821     4984     +163     
  Branches      626      655      +29     
==========================================
+ Hits         3514     3662     +148     
- Misses       1164     1171       +7     
- Partials      143      151       +8     

☔ View full report in Codecov by Sentry.
📢 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.