Example datasets for bep036 #465

Arshitha · 2024-08-29T21:20:12Z

Added pheno001 and pheno002 example dataset inspired by ds004215 on OpenNeuro but significantly modified to keep it simple and easy to convey the various use cases proposed in BEP036.

Use cases covered (and to be added to this PR):

pheno001 - Single session with both phenotype and imaging data
pheno002 - Two sessions with one imaging data only session
pheno003 - Two sessions with one phenotype data only session
pheno004 - Two sets of sessions. One set of sessions (e.g. screening, baseline, followup, etc) for phenotype data and another set of sessions (e.g. 01, 02, etc) for imaging data.

Still in draft state but would appreciate any and all feedback.

Pinging co-contributors: @ericearl @SamGuay @surchs

ericearl

This is great, thanks! I'm guessing you left it in draft state becausew of pheno001 and pheno002, right?

I think we should remove the age_at_visit column/field from all phenotype/ measurement tools and instead provide a root-level sessions file with that field. Should we maybe take that a step farther and RECOMMEND or say it's OPTIONAL to add age to the sessions file?

Arshitha · 2024-08-30T16:50:55Z

I like that idea. It's redundant information that can be aggregated to sessions level, and can be a recommendation in the BEP.

Arshitha · 2024-08-30T16:52:38Z

It's in Draft state because I haven't prepared pheno003 and pheno004 but yes, all four example datasets will violate the contribution guidelines.

pheno001/phenotype/ace.tsv

pheno001/participants.json

pheno001/participants.tsv

pheno002/sessions.json

pheno002/sessions.tsv

pheno003/sessions.json

pheno003/sessions.tsv

Co-authored-by: Eric Earl <eric.earl@nih.gov>

christinerogers · 2024-10-24T20:40:20Z

Got a question from @dominikwelke --

Could this PR include an example showing how to represent multiple runs from one participant-session?

@ericearl mentioned today this is easily done by adding a run column in the .tsv, would be nice to see illustrated and mentioned here.

- All participants.tsv files have been simplified. - pheno004 has become instead an example of some imaging-only, some phenotype-only, and some with both data

ericearl · 2025-02-06T20:34:06Z

I hijacked the not yet created pheno004 for use with some current bids-validator testing needs at bids-standard/bids-specification#2044. Can we make this a non-draft PR and get it merged hopefully? @effigies @Arshitha @SamGuay @surchs

Addressed in updates.

effigies · 2025-02-06T20:52:53Z

Please set the BIDS_SCHEMA environment variable to https://bids-specification--2044.org.readthedocs.build/en/2044/schema.json here:

bids-examples/.github/workflows/validate_datasets.yml

Line 114 in e52f77f

    
           run: echo BIDS_SCHEMA=https://bids-specification.readthedocs.io/en/latest/schema.json >> $GITHUB_ENV

Please also add pheno004 to be skipped on legacy and stable:

bids-examples/.github/workflows/validate_datasets.yml

Lines 98 to 101 in e52f77f

    
           - name: Skip legacy validation for post-legacy datasets 
        
             run: for DS in mrs_* dwi_deriv; do touch $DS/.SKIP_VALIDATION; done 
        
             if: matrix.bids-validator == 'legacy' 
        
             shell: bash

bids-examples/.github/workflows/validate_datasets.yml

Lines 103 to 106 in e52f77f

    
           - name: Skip stable validation for datasets with unreleased features 
        
             run: for DS in dwi_deriv; do touch $DS/.SKIP_VALIDATION; done 
        
             if: matrix.bids-validator != 'dev' 
        
             shell: bash

ericearl · 2025-02-06T21:15:19Z

@effigies Is that comment just above here a note for me? I'm confused by most of it and don't feel safe editing those files as-is. If you need me to take care of that, can I sit with you, Ross, or Nell to figure it out or have it explained to me enough to be able to do the work?

effigies · 2025-02-06T21:45:09Z

Okay, I did what I asked. It looks like there are issues in the schema that need to be addressed, but also there are unrelated issues in pheno001-003: https://github.com/bids-standard/bids-examples/actions/runs/13188395001/job/36815880378?pr=465

ericearl · 2025-02-07T21:31:26Z

This is super-helpful @effigies, thank you! I'm bringing the errors out of the logs here for us (@Arshitha @SamGuay @surchs):

# pheno001

	[ERROR] MISSING_DATASET_DESCRIPTION A dataset_description.json file is required in the root of the dataset
		

	Please visit https://neurostars.org/search?q=MISSING_DATASET_DESCRIPTION for existing conversations about this issue.

	[ERROR] JSON_INVALID Not a valid JSON file.
		/sub-01/anat/sub-01_T1w.json
		/sub-01/anat/sub-01_T1w.json

		2 more files with the same issue

	Please visit https://neurostars.org/search?q=JSON_INVALID for existing conversations about this issue.

# pheno002

	[ERROR] MISSING_DATASET_DESCRIPTION A dataset_description.json file is required in the root of the dataset
		

	Please visit https://neurostars.org/search?q=MISSING_DATASET_DESCRIPTION for existing conversations about this issue.

	[ERROR] TSV_COLUMN_ORDER_INCORRECT Some TSV columns are in the incorrect order
		session_id
		/sessions.tsv - Column 0 (starting from 0) found at index 1.

	Please visit https://neurostars.org/search?q=TSV_COLUMN_ORDER_INCORRECT for existing conversations about this issue.

	[ERROR] TSV_INDEX_VALUE_NOT_UNIQUE An index column(s) was specified for the tsv file and not all of the values for it are unique.
		/sessions.tsv - Row: 4, Value: 01
		/sessions.tsv - Row: 5, Value: 02

	Please visit https://neurostars.org/search?q=TSV_INDEX_VALUE_NOT_UNIQUE for existing conversations about this issue.

	[ERROR] JSON_INVALID Not a valid JSON file.
		/sub-01/ses-01/anat/sub-01_ses-01_T1w.json
		/sub-01/ses-01/anat/sub-01_ses-01_T1w.json

		6 more files with the same issue

	Please visit https://neurostars.org/search?q=JSON_INVALID for existing conversations about this issue.

# pheno003

	[ERROR] MISSING_DATASET_DESCRIPTION A dataset_description.json file is required in the root of the dataset
		

	Please visit https://neurostars.org/search?q=MISSING_DATASET_DESCRIPTION for existing conversations about this issue.

	[ERROR] TSV_COLUMN_ORDER_INCORRECT Some TSV columns are in the incorrect order
		session_id
		/sessions.tsv - Column 0 (starting from 0) found at index 1.

	Please visit https://neurostars.org/search?q=TSV_COLUMN_ORDER_INCORRECT for existing conversations about this issue.

	[ERROR] TSV_INDEX_VALUE_NOT_UNIQUE An index column(s) was specified for the tsv file and not all of the values for it are unique.
		/sessions.tsv - Row: 4, Value: baseline

	Please visit https://neurostars.org/search?q=TSV_INDEX_VALUE_NOT_UNIQUE for existing conversations about this issue.

	[ERROR] JSON_INVALID Not a valid JSON file.
		/sub-01/ses-baseline/anat/sub-01_ses-baseline_T1w.json
		/sub-01/ses-baseline/anat/sub-01_ses-baseline_T1w.json

		2 more files with the same issue

	Please visit https://neurostars.org/search?q=JSON_INVALID for existing conversations about this issue.

Arshitha · 2025-04-03T13:19:16Z

@ericearl I fixed some of the bids validation errors but I'm not sure how to fix the following:

~/Desktop/Projects/bep036/bids-examples -> master
(datasci) Thu Apr  3 18:44:02 2025 ❯ bids-validator-deno pheno002 --ignoreWarnings
	[ERROR] TSV_COLUMN_ORDER_INCORRECT Some TSV columns are in the incorrect order
		session_id
		/sessions.tsv - Column 0 (starting from 0) found at index 1.

	Please visit https://neurostars.org/search?q=TSV_COLUMN_ORDER_INCORRECT for existing conversations about this issue.

	[ERROR] TSV_INDEX_VALUE_NOT_UNIQUE An index column(s) was specified for the tsv file and not all of the values for it are unique.
		/sessions.tsv - Row: 4, Value: 01
		/sessions.tsv - Row: 5, Value: 02

	Please visit https://neurostars.org/search?q=TSV_INDEX_VALUE_NOT_UNIQUE for existing conversations about this issue.


          Summary:                         Available Tasks:        Available Modalities:
          18 Files, 41.2 MB                                        MRI
          2 - Subjects 2 - Sessions

	If you have any questions, please post on https://neurostars.org/tags/bids.

I checked the TSV files and they are valid TSV files with no apparent issues in the "column order" which is one of the errors. @effigies could this be related to the validator issues you mentioned earlier?

Arshitha · 2025-04-03T13:22:38Z

@ericearl - For pheno004, I added dataset_description.json and replaced empty nifti and json with non-empty ones from an openneuro dataset. Lmk if you'd like me to undo those changes.

pheno005/dataset_description.json

pheno005/phenotype/demographics.json

ericearl · 2025-04-08T13:01:23Z

pheno005/phenotype/demographics.json

+		"Description": "Age of the participant.",
+		"Units": "years"
+	},
+	"sex": {


I'm conflicted on whether sex at birth should go in the participants.tsv or the demographics.tsv. I know OpenNeuro crawls participants.tsv files better right now to improve its search functionality, which may be justification enough to move this. Anyway, this is a point of discussion and I am open to other ideas.

@ericearl Based on our slack discussion, I think we can leave the demographics info in the demographics file with participants.tsv being a list of unique participant IDs?

pheno005/sessions.json

pheno005/phenotype/ace.json

ericearl · 2025-04-08T13:04:33Z

pheno005/sub-01/ses-baseline/anat/sub-01_ses-baseline_T1w.nii.gz

The NIfTIs should be 0 Byte empty files.

@ericearl The validator was complaining about this so I replaced empty files with actual Niftis (from openneuro) in the other examples and this new example.

ericearl · 2025-04-08T13:04:41Z

pheno005/sub-02/ses-baseline/anat/sub-02_ses-baseline_T1w.nii.gz

The NIfTIs should be 0 Byte empty files.

See the above comment.

Arshitha · 2025-04-15T06:11:47Z

@christinerogers pheno005 is now available for review as the multi-run representative example!

adding 2 example datasets for bep036

b0d15b9

Arshitha marked this pull request as draft August 29, 2024 21:20

ericearl previously requested changes Aug 30, 2024

View reviewed changes

adding a dataset ; minor changes to existing datasets

0e60f77

ericearl reviewed Aug 30, 2024

View reviewed changes

pheno001/phenotype/ace.tsv Outdated Show resolved Hide resolved

ericearl reviewed Aug 30, 2024

View reviewed changes

pheno001/participants.json Show resolved Hide resolved

ericearl reviewed Aug 30, 2024

View reviewed changes

pheno001/participants.tsv Outdated Show resolved Hide resolved

ericearl reviewed Aug 30, 2024

View reviewed changes

pheno002/sessions.json Outdated Show resolved Hide resolved

ericearl reviewed Aug 30, 2024

View reviewed changes

pheno002/sessions.tsv Outdated Show resolved Hide resolved

ericearl reviewed Aug 30, 2024

View reviewed changes

pheno003/sessions.json Outdated Show resolved Hide resolved

ericearl reviewed Aug 30, 2024

View reviewed changes

pheno003/sessions.tsv Outdated Show resolved Hide resolved

Arshitha and others added 4 commits August 30, 2024 15:59

Update pheno002/sessions.tsv

588b644

Co-authored-by: Eric Earl <eric.earl@nih.gov>

Update pheno003/sessions.json

85dcd26

Co-authored-by: Eric Earl <eric.earl@nih.gov>

Update pheno002/sessions.json

b3efe27

Co-authored-by: Eric Earl <eric.earl@nih.gov>

Update pheno003/sessions.tsv

0792d1f

Co-authored-by: Eric Earl <eric.earl@nih.gov>

Update pheno 001-004 participants.tsv files and add pheno004

c23d88a

- All participants.tsv files have been simplified. - pheno004 has become instead an example of some imaging-only, some phenotype-only, and some with both data

ericearl marked this pull request as ready for review February 6, 2025 20:37

ericearl mentioned this pull request Feb 6, 2025

[ENH] Allow participants.tsv to contain a superset of subject directories and subjects listed in phenotype files bids-standard/bids-specification#2044

Merged

Merge branch 'master' into master

d8e8fc3

chore(ci): Use draft schema, shield pheno004 from older validators

a657cdf

effigies force-pushed the master branch from fdbbd88 to a657cdf Compare February 6, 2025 21:48

fixing some bids validation errors

8dc0c99

Arshitha requested a review from ericearl April 3, 2025 13:23

Arshitha added 3 commits April 8, 2025 15:25

adding pheno005 as multi-run example

0ff3eab

adding run info to sessions.tsv

fc52f3b

minor change

7cc9f4c