LeoYeAI/agent-master-skills / skills/bids
bids
UnverifiedOrganizes, queries, validates, and converts Brain Imaging Data Structure (BIDS) datasets. Supports organizing neuroscience and biomedical data (MRI, EEG, MEG, iEEG, PET, microscopy, NIRS, motion capture, EMG, MR spectroscopy, behavioral), querying BIDS layouts, validating compliance, converting DICOM to BIDS, writing metadata sidecars, or creating BIDS derivatives.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 14.5 KB |
| references/beps.yml | config | 24.8 KB |
| references/bids_schema.json | config | 806.4 KB |
| references/bids_specification.md | markdown | 9.0 KB |
| references/conversion_tools.md | markdown | 20.0 KB |
| references/core_workflows.md | markdown | 20.0 KB |
| references/metadata_fields.md | markdown | 11.4 KB |
| scripts/update_schema.py | script | 4.0 KB |
references/metadata_fields.md
View on GitHub# BIDS Metadata Fields Reference
Reviewed against [BIDS 1.11.2](https://bids-specification.readthedocs.io/en/stable/)
on 2026-09-30. This is a practical selection, not a complete validator. The bundled
`bids_schema.json` contains field definitions under `objects.metadata`, conditional
requirements under `rules.sidecars`, and cross-file checks under `rules.checks`.
A field can be required only for a particular suffix, acquisition, or dataset context.
Read selectors before interpreting a rule; do not merge every modality's requirements.
Required metadata may be inherited from matching higher-level sidecars.
## MRI: units, timing and orientation
Use seconds for MRI timing fields, degrees for `FlipAngle`, and tesla for
`MagneticFieldStrength`. Convert DICOM millisecond values; do not copy units blindly.
`Manufacturer`, `ManufacturersModelName`, scanner/software identifiers and institution
fields are generally recommended. Check `rules.sidecars.mri` for exceptions, including
ASL and concurrent PET requirements.
- Anatomical MRI: `EchoTime` and `FlipAngle` are generally recommended;
`RepetitionTimeExcitation` and `RepetitionTimePreparation` are available where applicable.
Do not present one mandatory qMRI field set for all anatomical suffixes.
- BOLD: `TaskName` is required. It need not equal or be derived from the `task-` label.
Specify **either** `RepetitionTime` **or** `VolumeTiming`, never both.
With `VolumeTiming`, provide `SliceTiming` or `FrameAcquisitionDuration`;
`DelayTime` is not used with `VolumeTiming`. Sparse sequences need the additional
timing information described in the [MRI timing table](https://bids-specification.readthedocs.io/en/stable/modality-specific-files/magnetic-resonance-imaging-data.html#timing-parameters).
- `EchoTime` is required for multi-echo data, ASL, or where the stated fieldmap
conditions apply. With an `echo-` entity, record that echo's actual time, not its index.
- `PhaseEncodingDirection` uses NIfTI voxel axes `i`, `j`, `k` with optional `-`.
Anatomical AP/PA/LR labels do not determine the axis or sign without the affine and
converter orientation. Verify scanner metadata and image orientation together.
- `PhaseEncodingDirection` and `TotalReadoutTime` are recommended for DWI/BOLD and
become required under specified fieldmap/opposing-encoding conditions. For pepolar
`_epi` images, readout timing must be supplied or calculable through supported metadata.
`EffectiveEchoSpacing` alone is not numerically interchangeable with total readout time.
- `SliceTiming` contains acquisition offsets in seconds, indexed by slice (reversed
relative to slice index when `SliceEncodingDirection` is negative). It is not a list
of slice indices. The list length must match the slice dimension. Never infer offsets
from TR and slice order without accounting for multiband acquisition and dead time.
Illustrative odd-first order 1,3,5,2,4,6 with TR=2 s, equal spacing, no dead time and
positive slice encoding direction:
```json
{"SliceTiming": [0.0, 1.0, 0.333, 1.333, 0.667, 1.667]}
```
qMRI requirements are suffix-specific (`rules.sidecars.qmri`): VFA requires
`FlipAngle`, `PulseSequenceType`, and `RepetitionTimeExcitation`; MP2RAGE additionally
requires `InversionTime`, `RepetitionTimePreparation`, `NumberShots`, and field strength.
`MTState` is required for MT collections, not universally for every quantitative map.
The spelling is **`RepetitionTimePreparation`**.
## Diffusion gradients
Store `.bvec` as 3 rows × N columns and `.bval` as 1 row × N columns, with N equal to
stored image volumes. Use space-separated numbers. b=0 volumes have zero vectors;
diffusion-weighted vectors should be unit length. Preserve dcm2niix's FSL/BIDS image
coordinate convention and verify gradients after any image reorientation (including
the x-component handedness convention); scanner anatomical directions are insufficient.
See the [DWI specification](https://bids-specification.readthedocs.io/en/stable/modality-specific-files/magnetic-resonance-imaging-data.html#diffusion-imaging-data).
## Fieldmaps and association
| Acquisition | Required core fields | Additional checks |
|---|---|---|
| `_phasediff` | `EchoTime1`, `EchoTime2` | Shorter echo first; matching magnitude image |
| `_phase1` / `_phase2` | `EchoTime` per image | Verify echo pairs and magnitude association |
| `_fieldmap` | `Units` | `Hz`, `rad/s`, or `T`; retain actual physical units |
| `_epi` pepolar | `PhaseEncodingDirection` | Readout time or supported inputs to calculate it; complementary encoding scans |
`IntendedFor` is optional for fieldmaps, not universally required. Use meaningful
associations for processing: `B0FieldIdentifier` defines a field estimate and
`B0FieldSource` on a target selects it; `IntendedFor` remains supported. Check the
pipeline's support before choosing the association method.
Fieldmap JSON example for a target in the same raw dataset:
```json
{
"B0FieldIdentifier": "pepolar_fmap0",
"IntendedFor": ["bids::sub-01/func/sub-01_task-rest_bold.nii.gz"]
}
```
Target BOLD JSON addition:
```json
{"B0FieldSource": "pepolar_fmap0"}
```
`bids::` is relative to the nearest dataset root, including a derivative's own root.
For cross-dataset sources, use a named BIDS URI and `DatasetLinks`. Legacy subject-relative
`IntendedFor` paths are deprecated. See [BIDS URI resolution](https://bids-specification.readthedocs.io/en/stable/common-principles.html#resolution-of-bids-uris).
## ASL
For `_asl`, core requirements include `ArterialSpinLabelingType` (`CASL`, `PCASL`,
`PASL`), `PostLabelingDelay`, `BackgroundSuppression`, `M0Type`,
`RepetitionTimePreparation`, `TotalAcquiredPairs`, `MagneticFieldStrength`,
`MRAcquisitionType`, and `EchoTime`. Also provide `_aslcontext.tsv` with one volume
label per stored volume, and verify the M0 acquisition/estimate relation.
- CASL/PCASL requires `LabelingDuration`; it is not a universal PASL field.
- PASL requires `BolusCutOffFlag`; when true, also supply `BolusCutOffDelayTime`
and **`BolusCutOffTechnique`**.
- `M0Type: "Estimate"` requires `M0Estimate`; a separate `_m0scan` has an `IntendedFor` requirement.
- 2D ASL requires `SliceTiming`. Suppression pulse count/times are recommended when
background suppression is true.
Use the full [ASL specification](https://bids-specification.readthedocs.io/en/stable/modality-specific-files/magnetic-resonance-imaging-data.html#arterial-spin-labeling-perfusion-data)
for acquisition-specific conditions and per-volume arrays.
## Electrophysiology
| Datatype | Core required JSON fields for task recordings |
|---|---|
| EEG | `TaskName`, `SamplingFrequency`, `EEGReference`, `PowerLineFrequency`, `SoftwareFilters` |
| iEEG | `TaskName`, `SamplingFrequency`, `iEEGReference`, `PowerLineFrequency`, `SoftwareFilters` |
| MEG | `TaskName`, `SamplingFrequency`, `PowerLineFrequency`, `DewarPosition`, `SoftwareFilters`, `DigitizedLandmarks`, `DigitizedHeadPoints` |
| EMG | `TaskName`, `EMGPlacementScheme`, `EMGReference`, `SamplingFrequency`, `PowerLineFrequency`, `RecordingType`, `SoftwareFilters` |
`PowerLineFrequency` accepts a numeric frequency or `"n/a"`; `SoftwareFilters` accepts
a filter-description object or `"n/a"` under its field definition. EMG needs
`EMGPlacementSchemeDescription` when the scheme is `"Other"` and `EpochLength` for
epoched recordings. iEEG requires electrode/coordinate metadata; do not conflate
channels (recorded signals) with electrodes (physical contacts).
For EEG channels, `name`, `type`, and `units` are required columns. Coordinate units
and coordinate-system identifiers belong in matching `coordsystem.json`. Consult the
modality's rules for which companion files are required, recommended or conditional.
BrainVision datasets need the complete `.vhdr`, `.vmrk`, `.eeg` triplet with valid links.
Use `MiscChannelCount`; `MISCChannelCount` is a deprecated alias for EEG/motion.
Official modality pages: [EEG](https://bids-specification.readthedocs.io/en/stable/modality-specific-files/electroencephalography.html),
[iEEG](https://bids-specification.readthedocs.io/en/stable/modality-specific-files/intracranial-electroencephalography.html),
[MEG](https://bids-specification.readthedocs.io/en/stable/modality-specific-files/magnetoencephalography.html),
[EMG](https://bids-specification.readthedocs.io/en/stable/modality-specific-files/electromyography.html).
## PET
PET metadata is substantially richer than tracer name and frame timing. Required
raw `_pet` fields cover hardware (`Manufacturer`, `ManufacturersModelName`, `Units`),
radiochemistry (including `SpecificRadioactivity` and its units), timing, and
reconstruction (`AcquisitionMode`, decay correction fields, reconstruction method,
parameter labels, filter type, and attenuation correction). Conditional reconstruction
parameter values/units, filter sizes and infusion fields must also be satisfied.
Use `rules.sidecars.pet` and the [PET specification](https://bids-specification.readthedocs.io/en/stable/modality-specific-files/positron-emission-tomography.html)
for the full inventory; a small example is not a complete PET sidecar.
`TimeZero` defines the reference clock time and is not necessarily injection time.
`ScanStart`, `InjectionStart` and frame timing use the documented relation to that
reference. State measured activity and mass units explicitly; do not relabel numeric
values as MBq without conversion. `ReconFilterSize` accepts a number or an array under its definition.
Blood recordings have separate required columns and availability/correction fields.
## Microscopy, NIRS, motion and spectroscopy
| Datatype | Core metadata and caveats |
|---|---|
| Microscopy | `PixelSize` and `PixelSizeUnits` are required for non-photo microscopy images. `PixelSize` is a two- or three-number array; `PixelSizeUnits` is `"mm"`, `"um"`, or `"nm"`. Manufacturer/model and `SampleEnvironment` are recommended. Validate embedded OME metadata and image dimensions. |
| NIRS | `TaskName`, `SamplingFrequency`, `NIRSChannelCount`, `NIRSSourceOptodeCount`, `NIRSDetectorOptodeCount`; additional channel counts are conditional on channel type. Include channel/optode/coordinate companions according to the rules. |
| Motion | `TaskName` and `SamplingFrequency` are required; `TrackingSystemName` is optional. Spatial-axis/rotation descriptions belong to the coordinate-system rules, not an invented universal motion sidecar requirement. |
| MRS | `ResonantNucleus`, `SpectrometerFrequency`, `SpectralWidth`, and `EchoTime`; NIfTI-MRS also carries a header extension. A `voi-` entity requires body-part metadata. Verify nucleus/frequency arrays and acquisition-specific dimensions. |
Load `rules.sidecars.micr`, `.nirs`, `.motion`, or `.mrs` and corresponding
`objects.metadata` definitions rather than copying scalar types across modalities.
BIDS 1.11.2 adds OME-Zarr imaging support; confirm actual consumer support separately.
## Events and validation
`onset` and `duration` are the first two columns of `_events.tsv`. Times are seconds
relative to the first **stored** data point; negative onset values are allowed.
A zero duration denotes an impulse; `n/a` denotes an unavailable duration.
`trial_type` and `response_time` are optional. Sort rows by onset and describe custom
columns in JSON. Resting-state tasks do not necessarily have recorded events.
Run the full validator including image-header checks. Validation establishes structural
and metadata conformance, not the correctness of acquisition values, gradient orientation,
fieldmap selection, deidentification, or scientific preprocessing choices.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |