Skip to content

Add information on BIDS curation to Usage page - #1001

Merged
tsalo merged 6 commits into
masterfrom
doc-bids
Dec 4, 2025
Merged

Add information on BIDS curation to Usage page#1001
tsalo merged 6 commits into
masterfrom
doc-bids

Conversation

@tsalo

@tsalo tsalo commented Nov 14, 2025

Copy link
Copy Markdown
Member

Closes #975 and closes #342.

Changes proposed in this pull request

Document the following gotchas with BIDS datasets and QSIPrep:

Documentation that should be reviewed

https://qsiprep--1001.org.readthedocs.build/en/1001/usage.html#preparing-data-for-qsiprep

Comment thread docs/usage.rst
Comment thread docs/usage.rst
===================

If you acquire complex-valued data, you should (1) split the data into magnitude and phase files (NOT real and imaginary!)
and (2) retain a copy of the bval and bvec files with the part-mag entity included (i.e., do not use the inheritance principle on these files).

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Doesn't this conflict with below where you need to have files with both the part-mag and the part-phase

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You need them for each file for BIDS (e.g., with both part-mag and part-phase or without part at all), but you need it with part-mag for QSIPrep.

So this is BIDS-valid:

sub-01_dwi.bval
sub-01_dwi.bvec
sub-01_part-mag_dwi.nii.gz
sub-01_part-phase_dwi.nii.gz

But on the other hand you need this for QSIPrep:

sub-01_part-mag_dwi.bval
sub-01_part-mag_dwi.bvec
sub-01_part-mag_dwi.nii.gz
sub-01_part-phase_dwi.nii.gz

Note that the part-phase bval and bvec are not needed for QSIPrep.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'll make changes to make this clearer

@codecov-commenter

codecov-commenter commented Nov 14, 2025

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 46.16%. Comparing base (69be226) to head (06e7973).
⚠️ Report is 3 commits behind head on master.

Additional details and impacted files
@@           Coverage Diff           @@
##           master    #1001   +/-   ##
=======================================
  Coverage   46.15%   46.16%           
=======================================
  Files          65       65           
  Lines        9793     9796    +3     
  Branches     1083     1084    +1     
=======================================
+ Hits         4520     4522    +2     
- Misses       5045     5046    +1     
  Partials      228      228           

☔ 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.

@tsalo

tsalo commented Nov 17, 2025

Copy link
Copy Markdown
Member Author

@arokem I'd love to get your thoughts on my changes before I merge.

@tsalo
tsalo requested a review from mattcieslak December 4, 2025 17:20

@mattcieslak mattcieslak left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Excellent!

Comment thread docs/usage.rst
The inheritance principle ensures that the bvals and bvecs without the ``part`` entity
apply to both the magnitude and phase files.

Unfortunately, if you do this, QSIPrep will not be able to find the bvec and bval files.

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Definitely worth documenting until we have a patch for this

@tsalo
tsalo merged commit c9b93cf into master Dec 4, 2025
24 checks passed
@tsalo
tsalo deleted the doc-bids branch December 4, 2025 18:00
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Documentation for field map file layout and IntendedFor field. Documentation sentence ends abruptly

4 participants