📄 / / profiles / r-and-d / raw_evidence / scientific-agent-skills / skills / bids / references / metadata_fields.md

BIDS Metadata Fields Reference

This reference lists the required and recommended JSON sidecar fields for each BIDS modality.

Legend: - R = Required - REC = Recommended - OPT = Optional

Common MRI Fields (All MRI Modalities)

Field	Status	Type	Description
`MagneticFieldStrength`	REC	number	Field strength in Tesla
`Manufacturer`	REC	string	Scanner manufacturer
`ManufacturersModelName`	REC	string	Scanner model
`DeviceSerialNumber`	REC	string	Scanner serial number
`StationName`	REC	string	Scanner station name
`SoftwareVersions`	REC	string	Scanner software version
`InstitutionName`	REC	string	Name of institution
`InstitutionAddress`	REC	string	Address of institution
`InstitutionalDepartmentName`	REC	string	Department name

Anatomical MRI (anat/)

T1w, T2w, FLAIR, T2star, PDw

Field	Status	Type	Description
`RepetitionTime`	REC	number	TR in seconds
`EchoTime`	REC	number	TE in seconds
`InversionTime`	REC	number	TI in seconds (if applicable)
`FlipAngle`	REC	number	Flip angle in degrees
`SequenceName`	REC	string	Pulse sequence name
`SequenceVariant`	REC	string	Variant of the sequence
`ScanningSequence`	REC	string	General description
`PulseSequenceType`	REC	string	Type of pulse sequence
`NonlinearGradientCorrection`	REC	boolean	Whether applied
`ParallelReductionFactorInPlane`	REC	number	iPAT/GRAPPA factor
`ContrastBolusIngredient`	REC	string	Active contrast ingredient

Quantitative MRI (T1map, T2map, etc.)

Field	Status	Type	Description
`RepetitionTimeExcitation`	R	number	Excitation TR in seconds
`RepetitionTimePrepration`	R	number	Preparation TR in seconds
`FlipAngle`	R	number/array	Flip angle(s) in degrees
`MTState`	R	boolean	Magnetization transfer on/off
`SpoilingState`	REC	boolean	Whether RF spoiling applied
`SpoilingType`	REC	string	`RF`, `GRADIENT`, or `COMBINED`
`SpoilingRFPhaseIncrement`	REC	number	Phase increment in degrees

Functional MRI (func/)

BOLD

Field	Status	Type	Description
`RepetitionTime`	R	number	TR in seconds (volume acquisition time)
`TaskName`	R	string	Name of the task (must match `task-<label>`)
`SliceTiming`	REC	array	Time each slice was acquired, in seconds
`EchoTime`	REC	number	TE in seconds
`FlipAngle`	REC	number	Flip angle in degrees
`PhaseEncodingDirection`	REC	string	`i`, `i-`, `j`, `j-`, `k`, `k-`
`EffectiveEchoSpacing`	REC	number	Effective echo spacing in seconds
`TotalReadoutTime`	REC	number	Total readout time in seconds
`MultibandAccelerationFactor`	REC	number	Multiband/SMS factor
`NumberOfVolumesDiscardedByScanner`	REC	integer	Dummy scans removed
`NumberOfVolumesDiscardedByUser`	REC	integer	Volumes removed post-hoc
`TaskDescription`	REC	string	Longer description of the task
`CogAtlasID`	REC	string	Cognitive Atlas ID for the task
`CogPOID`	REC	string	Cognitive Paradigm Ontology ID
`Instructions`	REC	string	Instructions given to participants

Multi-echo BOLD

Field	Status	Type	Description
`EchoTime`	R	number	TE for this echo (each echo in separate file)
`EchoTime1`, `EchoTime2`	-	-	NOT used; use `echo-<index>` entity

BOLD Timing Details

SliceTiming - Array of times (in seconds) at which each slice was acquired relative to the start of volume acquisition. Length must equal the number of slices.

Example for ascending sequential (3 slices, TR=2s):

{"SliceTiming": [0.0, 0.667, 1.333]}

Example for interleaved (odd-first, 6 slices, TR=2s):

{"SliceTiming": [0.0, 0.667, 1.333, 0.333, 1.0, 1.667]}

PhaseEncodingDirection values: - i / i- : along first image axis (typically left-right) - j / j- : along second image axis (typically anterior-posterior) - k / k- : along third image axis (typically inferior-superior) - The - suffix indicates the negative direction along that axis

Diffusion-Weighted Imaging (dwi/)

Field	Status	Type	Description
`PhaseEncodingDirection`	R	string	Phase encoding direction
`TotalReadoutTime`	R	number	Total readout time in seconds
`EchoTime`	REC	number	TE in seconds
`RepetitionTime`	REC	number	TR in seconds
`FlipAngle`	REC	number	Flip angle in degrees
`EffectiveEchoSpacing`	REC	number	Effective echo spacing in seconds
`MultibandAccelerationFactor`	REC	number	SMS/multiband factor
`SliceTiming`	REC	array	Slice timing

DWI Gradient Files

.bvec file (3 rows x N columns, N = number of volumes):

0 0.707 -0.707 0 0.577
0 0.707 0.707 0 0.577
0 0 0 1 0.577

.bval file (1 row x N columns):

0 1000 1000 1000 2000

b=0 volumes have zero-vectors in .bvec
Gradient directions are in the image coordinate system
Values are space-separated (not tab-separated)
Number of columns must match number of volumes in the NIfTI

Fieldmaps (fmap/)

Case 1: Phase-difference map (`_phasediff`)

Field	Status	Type	Description
`EchoTime1`	R	number	TE of the first echo (shorter)
`EchoTime2`	R	number	TE of the second echo (longer)
`IntendedFor`	R	string/array	BIDS URI(s) of files to correct
`B0FieldIdentifier`	REC	string	Identifier for this B0 field

Case 2: Two phase maps (`_phase1`, `_phase2`)

Field	Status	Type	Description
`EchoTime`	R	number	TE for this phase image
`IntendedFor`	R	string/array	Files to correct

Case 3: Direct fieldmap (`_fieldmap`)

Field	Status	Type	Description
`Units`	R	string	Must be `Hz` or `rad/s`
`IntendedFor`	R	string/array	Files to correct

Case 4: "Pepolar" fieldmaps (`_epi`)

Field	Status	Type	Description
`PhaseEncodingDirection`	R	string	PE direction for this image
`TotalReadoutTime`	R	number	Total readout time
`IntendedFor`	R	string/array	Files to correct
`B0FieldIdentifier`	REC	string	Identifier for this B0 field
`B0FieldSource`	REC	string	Which B0 field to use

IntendedFor Syntax

BIDS URI format (recommended, v1.7+):

{
    "IntendedFor": [
        "bids::sub-01/func/sub-01_task-rest_bold.nii.gz",
        "bids::sub-01/dwi/sub-01_dwi.nii.gz"
    ]
}

Relative path format (legacy):

{
    "IntendedFor": [
        "func/sub-01_task-rest_bold.nii.gz",
        "dwi/sub-01_dwi.nii.gz"
    ]
}

B0FieldIdentifier/B0FieldSource (preferred in v1.9+):

// In the fieldmap sidecar
{"B0FieldIdentifier": "pepolar_fmap0"}

// In the BOLD sidecar
{"B0FieldSource": "pepolar_fmap0"}

Perfusion Imaging (perf/)

ASL

Field	Status	Type	Description
`ArterialSpinLabelingType`	R	string	`CASL`, `PCASL`, or `PASL`
`PostLabelingDelay`	R	number/array	PLD in seconds
`BackgroundSuppression`	R	boolean	Whether applied
`MagneticFieldStrength`	R	number	In Tesla
`M0Type`	R	string	`Separate`, `Included`, `Estimate`, `Absent`
`RepetitionTimePreparation`	R	number	Time between ASL pulses
`LabelingDuration`	R	number	Duration of labeling pulse
`BackgroundSuppressionNumberPulses`	REC	integer	Number of suppression pulses
`BackgroundSuppressionPulseTime`	REC	array	Timing of suppression pulses
`VascularCrushing`	REC	boolean	Whether applied
`LabelingOrientation`	REC	string	Orientation of labeling plane
`LabelingDistance`	REC	number	Distance from isocenter (mm)
`BolusCutOffFlag`	R (PASL)	boolean	Whether QUIPSS applied
`BolusCutOffTimingSequence`	R (PASL)	string	QUIPSS sequence type
`BolusCutOffDelayTime`	R (PASL)	number	QUIPSS delay time

aslcontext.tsv

Required file listing the order of volumes (label/control/m0scan):

volume_type
control
label
control
label
m0scan

EEG (eeg/)

Field	Status	Type	Description
`TaskName`	R	string	Name of the task
`SamplingFrequency`	R	number	In Hz
`EEGReference`	R	string	Reference electrode(s)
`PowerLineFrequency`	R	number	50 or 60 Hz (or `n/a`)
`SoftwareFilters`	R	object	Online filters applied
`EEGPlacementScheme`	REC	string	e.g., `10-20`, `10-10`
`CapManufacturer`	REC	string	Cap manufacturer
`CapManufacturersModelName`	REC	string	Cap model
`EEGChannelCount`	REC	integer	Number of EEG channels
`EOGChannelCount`	REC	integer	Number of EOG channels
`ECGChannelCount`	REC	integer	Number of ECG channels
`EMGChannelCount`	REC	integer	Number of EMG channels
`MiscChannelCount`	REC	integer	Number of misc channels
`TriggerChannelCount`	REC	integer	Number of trigger channels
`RecordingDuration`	REC	number	In seconds
`RecordingType`	REC	string	`continuous`, `epoched`, `discontinuous`

channels.tsv (EEG)

Column	Status	Description
`name`	R	Channel name
`type`	R	`EEG`, `EOG`, `ECG`, `EMG`, `MISC`, `TRIG`, etc.
`units`	R	`V`, `mV`, `uV`
`sampling_frequency`	OPT	Per-channel if different
`low_cutoff`	REC	High-pass filter frequency (Hz)
`high_cutoff`	REC	Low-pass filter frequency (Hz)
`notch`	REC	Notch filter frequency (Hz)
`reference`	REC	Reference electrode name
`status`	REC	`good` or `bad`
`status_description`	OPT	Reason for bad status

electrodes.tsv (EEG)

Column	Status	Description
`name`	R	Electrode name
`x`	R	X coordinate
`y`	R	Y coordinate
`z`	R	Z coordinate
`type`	OPT	Electrode type
`material`	OPT	Electrode material
`impedance`	OPT	Impedance in kOhm

MEG (meg/)

Field	Status	Type	Description
`TaskName`	R	string	Name of the task
`SamplingFrequency`	R	number	In Hz
`PowerLineFrequency`	R	number	50 or 60 Hz
`DewarPosition`	R	string	Position of the dewar
`SoftwareFilters`	R	object	Online filters
`DigitizedLandmarks`	R	boolean	Fiducials digitized
`DigitizedHeadPoints`	R	boolean	Head shape digitized
`MEGChannelCount`	REC	integer	Number of MEG channels
`MEGREFChannelCount`	REC	integer	Reference channels
`ContinuousHeadLocalization`	REC	boolean	HPI on
`HeadCoilFrequency`	REC	array	HPI coil frequencies
`InstitutionName`	REC	string	Institution name

PET (pet/)

Field	Status	Type	Description
`TracerName`	R	string	Name of the radiotracer
`TracerRadionuclide`	R	string	e.g., `C11`, `F18`, `O15`
`InjectedRadioactivity`	R	number	In MBq
`InjectedRadioactivityUnits`	R	string	Must be `MBq`
`InjectedMass`	R	number	Mass of tracer injected
`InjectedMassUnits`	R	string	e.g., `ug`
`ModeOfAdministration`	R	string	`bolus`, `infusion`, `bolus-infusion`
`TimeZero`	R	string	Time of injection (HH:MM:SS)
`ScanStart`	R	number	Start time relative to TimeZero
`InjectionStart`	R	number	Injection time relative to TimeZero
`FrameTimesStart`	R	array	Frame start times in seconds
`FrameDuration`	R	array	Frame durations in seconds
`Units`	R	string	Unit of voxel values (e.g., `Bq/mL`)
`TracerRadLex`	REC	string	RadLex ID for tracer
`BodyWeight`	REC	number	In kg
`BodyPart`	REC	string	Imaged body part
`AttenuationCorrection`	REC	string	Method description
`ReconMethodName`	REC	string	Reconstruction method
`ReconMethodParameterLabels`	REC	array	Parameter names
`ReconMethodParameterValues`	REC	array	Parameter values
`ReconFilterType`	REC	string	Post-recon filter type
`ReconFilterSize`	REC	number	Filter FWHM in mm

Microscopy (micr/)

Field	Status	Type	Description
`Manufacturer`	R	string	Microscope manufacturer
`ManufacturersModelName`	R	string	Microscope model
`PixelSize`	R	array	[X, Y] or [X, Y, Z] in micrometers
`PixelSizeUnits`	R	string	`um` (micrometers)
`Magnification`	REC	number	Objective magnification
`SampleEnvironment`	R	string	`in vivo`, `ex vivo`, `in vitro`
`SampleFixation`	REC	string	Fixation method
`SampleStaining`	REC	string	Staining protocol
`SliceThickness`	REC	number	In micrometers
`TissueDeformationScaling`	REC	number	Scaling factor

NIRS (nirs/)

Field	Status	Type	Description
`TaskName`	R	string	Name of the task
`SamplingFrequency`	R	number	In Hz
`NIRSSourceOptodeCount`	R	integer	Number of sources
`NIRSDetectorOptodeCount`	R	integer	Number of detectors
`ACCELChannelCount`	REC	integer	Accelerometer channels
`NIRSPlacementScheme`	REC	string	e.g., `10-20`

Motion (motion/)

Field	Status	Type	Description
`TaskName`	R	string	Name of the task
`SamplingFrequency`	R	number	In Hz
`TrackingSystemName`	R	string	Name of tracking system
`ACCELChannelCount`	REC	integer	Accelerometer channels
`GYROChannelCount`	REC	integer	Gyroscope channels
`MAGNChannelCount`	REC	integer	Magnetometer channels
`RotationOrder`	REC	string	e.g., `XYZ`
`RotationRule`	REC	string	`left-hand` or `right-hand`
`SpatialAxes`	REC	string	e.g., `ALS`