BIDS Validator Warnings for SIDECAR_KEY_RECOMMENDED

coopersharp · January 29, 2025, 9:13pm

Summary of what happened:

Hello, I am currently running the bids-validator on an updated version of this OpenNeuro dataset: OpenNeuro. Previously, this dataset only had two warnings, unrelated to the current issue. We are now receiving warnings for each echo files’ .json missing metadata. As this dataset is quite large, each missing metadata warning amounts to ~25,000 warnings, leading to a total of ~450,000 warnings.

The site MR technician does not think this metadata is collected at the DICOM level (Siemens 3T).

Is there a way to manually generate these fields if the metadata does in fact exist? If the metadata does not exist, how can I bypass the warnings on OpenNeuro upload. The current total of warnings causes a crash post-validation.

Command used (and if a helper script was used, a link to the helper script or the command generated):

bids-validator /root/ds005123/

Version:

Deno version: 2.1.4
bids version: 1.9.0
bids-validator version: 2.0.1
heudiconv version: 1.3.2
dcm2niix version: 1.0.20241211

Environment (Docker, Singularity / Apptainer, custom installation):

Apptainer for dcm2niix and heudiconv
Deno for bids-validator

Data formatted according to a validatable standard? Please provide the output of the validator:

[WARNING] SIDECAR_KEY_RECOMMENDED A data file's JSON sidecar is missing a key listed as recommended.
		GradientSetType
		/sub-10961/anat/sub-10961_FLAIR.nii.gz
		/sub-10961/anat/sub-10961_T1w.nii.gz

		24435 more files with the same issue

		MRTransmitCoilSequence
		/sub-10961/anat/sub-10961_FLAIR.nii.gz
		/sub-10961/anat/sub-10961_T1w.nii.gz

		24435 more files with the same issue

		PulseSequenceType
		/sub-10961/anat/sub-10961_FLAIR.nii.gz
		/sub-10961/anat/sub-10961_T1w.nii.gz

		24435 more files with the same issue

		MTState
		/sub-10961/anat/sub-10961_FLAIR.nii.gz
		/sub-10961/anat/sub-10961_T1w.nii.gz

		24435 more files with the same issue

		SpoilingType
		/sub-10961/anat/sub-10961_FLAIR.nii.gz
		/sub-10961/anat/sub-10961_T1w.nii.gz

		380 more files with the same issue

		NumberShots
		/sub-10961/anat/sub-10961_FLAIR.nii.gz
		/sub-10961/anat/sub-10961_T1w.nii.gz

		24435 more files with the same issue

		ParallelReductionFactorOutOfPlane
		/sub-10961/anat/sub-10961_FLAIR.nii.gz
		/sub-10961/anat/sub-10961_T1w.nii.gz

		24435 more files with the same issue

		ParallelAcquisitionTechnique
		/sub-10961/anat/sub-10961_FLAIR.nii.gz
		/sub-10961/anat/sub-10961_T1w.nii.gz

		24435 more files with the same issue

		PartialFourierDirection
		/sub-10961/anat/sub-10961_FLAIR.nii.gz
		/sub-10961/anat/sub-10961_T1w.nii.gz

		24435 more files with the same issue

		EffectiveEchoSpacing
		/sub-10961/anat/sub-10961_FLAIR.nii.gz
		/sub-10961/anat/sub-10961_T1w.nii.gz

		962 more files with the same issue

		MixingTime
		/sub-10961/anat/sub-10961_FLAIR.nii.gz
		/sub-10961/anat/sub-10961_T1w.nii.gz

		24435 more files with the same issue

		TotalReadoutTime
		/sub-10961/anat/sub-10961_FLAIR.nii.gz
		/sub-10961/anat/sub-10961_T1w.nii.gz

		962 more files with the same issue

		SliceEncodingDirection
		/sub-10961/anat/sub-10961_FLAIR.nii.gz
		/sub-10961/fmap/sub-10961_acq-dwi_dir-AP_epi.nii.gz

		24240 more files with the same issue

		MultibandAccelerationFactor
		/sub-10961/anat/sub-10961_FLAIR.nii.gz
		/sub-10961/anat/sub-10961_T1w.nii.gz

		12257 more files with the same issue

		PhaseEncodingDirection
		/sub-10961/anat/sub-10961_T1w.nii.gz
		/sub-10866/anat/sub-10866_T1w.nii.gz

		193 more files with the same issue

		SpoilingState
		/sub-10961/fmap/sub-10961_acq-dwi_dir-AP_epi.nii.gz
		/sub-10961/fmap/sub-10961_acq-dwi_dir-PA_epi.nii.gz

		24053 more files with the same issue

		InversionTime
		/sub-10961/fmap/sub-10961_acq-dwi_dir-AP_epi.nii.gz
		/sub-10961/fmap/sub-10961_acq-dwi_dir-PA_epi.nii.gz

		24053 more files with the same issue

		B0FieldIdentifier
		/sub-10961/fmap/sub-10961_acq-dwi_dir-AP_epi.nii.gz
		/sub-10961/fmap/sub-10961_acq-dwi_dir-PA_epi.nii.gz

		948 more files with the same issue

		ScanOptions
		/sub-10961/fmap/sub-10961_acq-bold_magnitude1.nii.gz
		/sub-10961/fmap/sub-10961_acq-bold_phasediff.nii.gz

		580 more files with the same issue

		ParallelReductionFactorInPlane
		/sub-10961/fmap/sub-10961_acq-bold_magnitude1.nii.gz
		/sub-10961/fmap/sub-10961_acq-bold_phasediff.nii.gz

		580 more files with the same issue

		NumberOfVolumesDiscardedByScanner
		/sub-10961/func/sub-10961_task-ugr_run-1_echo-4_part-mag_bold.nii.gz
		/sub-10961/func/sub-10961_task-sharedreward_run-1_echo-3_part-mag_bold.nii.gz

		11458 more files with the same issue

		NumberOfVolumesDiscardedByUser
		/sub-10961/func/sub-10961_task-ugr_run-1_echo-4_part-mag_bold.nii.gz
		/sub-10961/func/sub-10961_task-sharedreward_run-1_echo-3_part-mag_bold.nii.gz

		11458 more files with the same issue

		DelayTime
		/sub-10961/func/sub-10961_task-ugr_run-1_echo-4_part-mag_bold.nii.gz
		/sub-10961/func/sub-10961_task-sharedreward_run-1_echo-3_part-mag_bold.nii.gz

		11458 more files with the same issue

		AcquisitionDuration
		/sub-10961/func/sub-10961_task-ugr_run-1_echo-4_part-mag_bold.nii.gz
		/sub-10961/func/sub-10961_task-sharedreward_run-1_echo-3_part-mag_bold.nii.gz

		11458 more files with the same issue

		DelayAfterTrigger
		/sub-10961/func/sub-10961_task-ugr_run-1_echo-4_part-mag_bold.nii.gz
		/sub-10961/func/sub-10961_task-sharedreward_run-1_echo-3_part-mag_bold.nii.gz

		11458 more files with the same issue

		Instructions
		/sub-10961/func/sub-10961_task-ugr_run-1_echo-4_part-mag_bold.nii.gz
		/sub-10961/func/sub-10961_task-sharedreward_run-1_echo-3_part-mag_bold.nii.gz

		11458 more files with the same issue

		TaskDescription
		/sub-10961/func/sub-10961_task-ugr_run-1_echo-4_part-mag_bold.nii.gz
		/sub-10961/func/sub-10961_task-sharedreward_run-1_echo-3_part-mag_bold.nii.gz

		11458 more files with the same issue

		CogPOID
		/sub-10961/func/sub-10961_task-ugr_run-1_echo-4_part-mag_bold.nii.gz
		/sub-10961/func/sub-10961_task-sharedreward_run-1_echo-3_part-mag_bold.nii.gz

		11458 more files with the same issue

N/A?

Screenshots / relevant information:

I have tried the following troubleshooting steps, condensed for the sake of brevity:

Attempted to manually extract DICOM metadeta using pydicom. Was able to retrieve non-problematic fields, but none of the metadata described in the validator warnings.
Deleted .heudiconv folder in bids/ and regenerated
Ran dcm2niix without heudiconv conversion
Confirmed with site MR technician that this metadata is not collected (to the best of their knowledge)

effigies · January 29, 2025, 9:42pm

Originally, the BIDS specification was written in plain text, and the validator was written by hand, which meant that you would have a lot of mismatches. The original validator did not cover all of BIDS, and also included some warnings that, although helpful, not written anywhere in the specification.

For various reasons, this was unsustainable, and so a schema was written to be the ground truth for both the specification and the validator, and BIDS Validator 2.0 depends on the schema. See this blog post for more history.

One thing that had to be decided was what to do with metadata recommendations. Some were warnings, while others were silently ignored, but now we wanted to make decisions based on the schema and not based on historical choices. If RECOMMENDED is to mean anything, we decided, it has to mean warn on absence. That we had not always been doing this meant that the spread of RECOMMENDED fields that cannot reasonably be expected of most users went unnoticed, and now it is an absolute flood.

My personal preference is that we go through the spec and demote many RECOMMENDED fields to OPTIONAL. They may be genuinely nice to have, but too many warnings is the same as none, as they all get ignored. Would you be up for opening an issue with a specific proposal to demote the fields that you’re seeing and unable to provide?

coopersharp · January 29, 2025, 9:51pm

Absolutely, and thanks so much for the quick response. I will do a double-check to make sure there aren’t any we’re just missing. The issue should be posted sometime tonight or tomorrow. Thanks again!

effigies · January 29, 2025, 10:03pm

Looking specifically at the warnings you have now…

A number of these probably just need to be made more focused, e.g., EffectiveEchoSpacing is important for EPI, but not T1w.

Some I think are probably logic errors, either in the schema or the validator. I don’t think DelayTime or AcquisitionDuration were ever intended to be RECOMMENDED, since they only apply in sparse acquisition sequences.

I think Instructions, TaskDescription and CogPOID were originally intentionally warnings, and the idea there was that they would need to be manually provided, since they wouldn’t be in DICOM. I think you’re likely to get some pushback on abolishing these warnings entirely, as the idea is to make the dataset more understandable to someone receiving the dataset, but it might be feasible to propose a single warning if all are absent.

coopersharp · January 29, 2025, 10:24pm

Would it make sense to propose combining warning messages across files? For example, we have the same number (24,435) of warnings for 9 different metadata fields. Instead of creating 219,915 errors, what if you combined the metadata keys into one warning. For example:

```[WARNING] SIDECAR_KEY_RECOMMENDED A data file's JSON sidecar is missing a key listed as recommended.
	GradientSetType
	/sub-10961/anat/sub-10961_FLAIR.nii.gz
	/sub-10961/anat/sub-10961_T1w.nii.gz

	24435 more files with the same issue

	MRTransmitCoilSequence
	/sub-10961/anat/sub-10961_FLAIR.nii.gz
	/sub-10961/anat/sub-10961_T1w.nii.gz

	24435 more files with the same issue

Could become:

	[WARNING] SIDECAR_KEY_RECOMMENDED A data file's JSON sidecar is missing a key listed as recommended.
		GradientSetType, MRTransmitCoilSequence, PulseSequenceType, etc. 
		/sub-10961/anat/sub-10961_FLAIR.nii.gz
		/sub-10961/anat/sub-10961_T1w.nii.gz

		24435 more files with the same issue

This solution may be a little surface-level, as I am self-admittedly a BIDS novice. However, I do think it provides a happy-medium between not fully disregarding the nature of the issue and dealing with the fact that you’re likely unable to provide it. Even something like the --verbose could just expand on the warnings for those that want to see them/address them. Now that I am reading back your response, is this essentially what you were proposing as the “one warning if all were missing”?

coopersharp · February 4, 2025, 2:53pm

GitHub issue posted here: Reduce Cumbersome BIDS Validator Warnings for SIDECAR_KEY_RECOMMENDED Missing Metadata · Issue #2040 · bids-standard/bids-specification · GitHub