dralkh/seerai/bids
Claude Code and agent skill by dralkh/seerai
- community
Checking that the SKILL.md file is still in the repository.
Use this skill when working with Brain Imaging Data Structure (BIDS) datasets: 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.
Install
npx vskill@latest install dralkh/seerai/bidsSKILL.md
The same SKILL.md was published earlier as dralkh/seerai/bids.
Brain Imaging Data Structure (BIDS)
Overview
The Brain Imaging Data Structure (BIDS) is a community standard for organizing and describing neuroscience and biomedical research datasets. It defines a consistent file naming convention, directory hierarchy, and metadata schema so that datasets are immediately understandable by humans and software tools alike. BIDS is governed by the BIDS Specification (currently v1.11.x) and is maintained by the community via the BIDS-Standard GitHub organization.
While BIDS originated for MRI, it has grown well beyond neuroimaging. The specification now covers 11 modalities spanning imaging, electrophysiology, and behavioral data:
- Imaging: MRI (structural, functional, diffusion, fieldmaps, perfusion/ASL), PET, microscopy
- Electrophysiology: EEG, MEG, iEEG (intracranial EEG), EMG
- Other: NIRS (near-infrared spectroscopy), motion capture, behavioral data (without imaging), MR spectroscopy
Active BEPs are extending BIDS further — notably BEP032 (microelectrode electrophysiology) will add support for extracellular recordings including Neuropixels probes, bringing BIDS to a prevalent methodology in animal neuroscience research (see also the neuropixels-analysis skill).
Adoption is required or strongly encouraged by major data repositories (OpenNeuro, DANDI), leading journals (NeuroImage, Human Brain Mapping, Scientific Data), and funding agencies (NIH, ERC).
The Python ecosystem for BIDS centers on PyBIDS (pybids) for querying and indexing BIDS datasets, and the bids-validator (Deno-based, available as PyPI package bids-validator-deno or via Deno directly) for compliance checking. Conversion from DICOM is typically done with HeuDiConv, dcm2bids, or BIDScoin.
When to Use This Skill
Apply this skill when:
- Organizing raw neuroscience data (imaging, electrophysiology, behavioral) into BIDS-compliant directory structures
- Querying an existing BIDS dataset to find specific files by subject, session, task, run, or modality
- Validating a dataset against the BIDS specification before sharing or submission
- Converting DICOM data from scanners into BIDS format
- Writing or editing JSON sidecar metadata files
- Creating BIDS-compliant derivatives (preprocessed data, analysis outputs)
- Setting up a
dataset_description.jsonfor a new dataset - Working with BIDS entities (subject, session, task, acquisition, run, etc.)
- Configuring
.bidsignoreto exclude files from validation - Preparing data for upload to OpenNeuro, DANDI, or other BIDS-aware repositories
Installation
Core Workflows
1. BIDS Directory Structure
A minimal BIDS dataset follows this layout:
Key points:
- Every NIfTI file should have a corresponding
.jsonsidecar - File names encode entities:
sub-<label>[_ses-<label>][_task-<label>][_acq-<label>][_run-<index>]_<suffix>.<extension> - Entity order in filenames is fixed by the specification
- Only
dataset_description.jsonis strictly required at the root level
2. Creating dataset_description.json
For derivatives, set "DatasetType": "derivative" and add "GeneratedBy" listing the pipeline:
3. Querying BIDS Datasets with PyBIDS
Key points:
BIDSLayoutindexes the entire dataset on initialization; for large datasets usedatabase_pathto cache the index- Metadata inheritance: a JSON sidecar at a higher level (e.g., root or subject) is inherited by all files below unless overridden
- Use
return_type="filename"for paths,return_type="object"(default) forBIDSFileobjects
4. Validating BIDS Datasets
Using bids-validator via PyPI (recommended)
The bids-validator-deno PyPI package bundles the Deno-based validator as a standalone CLI:
Using bids-validator via Deno directly
If Deno is already available, you can install or run the validator without PyPI:
Legacy Node.js validator
The older Node.js-based validator (npm install -g bids-validator) is deprecated in favor of the Deno-based version. The Deno version is the reference implementation for BIDS Specification v1.9+.
Using .bidsignore
Create .bidsignore at the dataset root to exclude files from validation (gitignore syntax):
5. BIDS Entities and File Naming
The authoritative, machine-readable source of truth for entities, their ordering, allowed suffixes, and all filename rules is the BIDS Schema — a structured YAML/JSON representation of the specification. A JSON export is shipped with this skill at references/bids_schema.json. The schema is defined in the bids-specification `src/schema/` directory and published at https://bids-specification.readthedocs.io/en/stable/schema.json. BEP-specific schema previews are available at https://github.com/bids-standard/bids-schema/tree/main/BEPs.
Run scripts/update_schema.py to refresh the schema and BEPs list from upstream (no dependencies beyond stdlib).
The tables below are a convenient summary; when in doubt, consult the schema.
BIDS filenames are built from ordered key-value entity pairs:
| Entity | Key | Example | Required for | |
|---|---|---|---|---|
| Subject | sub- | sub-01 | All files | |
| Session | ses- | ses-pre | Multi-session studies | |
| Task | task- | task-rest | func (bold, cbv, phase), eeg, meg | |
| Acquisition | acq- | acq-highres | Distinguishing acquisition parameters | |
| Contrast enhancing agent | ce- | ce-gadolinium | Contrast-enhanced images | |
| Reconstruction | rec- | rec-magnitude | Reconstruction variants | |
| Direction | dir- | dir-AP | Fieldmaps, DWI, phase-encoding | |
| Run | run- | run-01 | Multiple identical acquisitions | |
| Echo | echo- | echo-1 | Multi-echo sequences | |
| Part | part- | part-mag | Magnitude/phase splits | |
| Space | space- | space-MNI152NLin2009cAsym | Derivatives in template space | |
| Description | desc- | desc-preproc | Derivatives only |
Entity ordering in filenames is fixed by the spec (defined in rules.entities in bids_schema.json). See references/bids_specification.md for the complete numbered ordering table. A common subset: sub-<label>[_ses-<label>][_task-<label>][_acq-<label>][_ce-<label>][_rec-<label>][_dir-<label>][_run-<index>][_echo-<index>][_part-<label>][_space-<label>][_desc-<label>]_<suffix>.<extension>
Common suffixes by datatype:
| Datatype | Suffixes | |
|---|---|---|
| anat | T1w, T2w, FLAIR, T2star, T1map, T2map, defacemask | |
| func | bold, cbv, sbref, events, physio, stim | |
| dwi | dwi, sbref | |
| fmap | phasediff, phase1, phase2, magnitude1, magnitude2, fieldmap, epi | |
| perf | asl, m0scan, aslcontext | |
| eeg | eeg, channels, electrodes, events | |
| meg | meg, channels, coordsystem, events | |
| ieeg | ieeg, channels, electrodes, coordsystem, events | |
| pet | pet, blood |
6. DICOM to BIDS Conversion
HeuDiConv
HeuDiConv is the most flexible DICOM-to-BIDS converter. It supports three usage modes — from fully automatic to fully custom — and handles duplicates, provenance tracking, and sourcedata archiving out of the box.
Mode 1: ReproIn (turnkey, recommended for new studies)
If scanner protocol names follow the ReproIn naming convention, conversion is fully automatic — no heuristic file to write:
This is the start of the file. Read the full SKILL.md on GitHub.
Security
- Security scanPassed, 95 of 100Pattern checks on the skill's files.
- Model reviewPassed
Quality evaluation
- Task evaluationNot runNo evaluation yet. Run one in Skill Studio.
Source
- SKILL.md in the repositoryCheckingskills/bids/SKILL.md
Popularity
- Repository stars
- 81
- Repository forks
- 5
- 7-day trend score
- 22
Stars and forks are for the whole GitHub repository, not this skill alone. Not refreshed yet.
Works with
Any agent vskill installs to: 56 targets in all. These 39 have a page on this site.
- Claude Code
- Cursor
- GitHub Copilot
- Windsurf
- Codex
- Gemini CLI
- Cline
- Amp
- Roo Code
- Goose
- Continue
- Kilo Code
- Junie
- Trae
- OpenHands
- Qwen Code
- AI Agent
- Tabnine Chat
- Sourcegraph Cody
- Amazon Q
- Firebase Genkit
- Sweep
- Devin
- Phind
- Mentat
- Claude Desktop
- Aider
- GPT Pilot
- Plandex
- bolt.new
- v0
- Replit Agent
- Anse
- TypingMind
- BetterChatGPT
- LibreChat
- Warp AI
- Pieces
- Fig AI
Embed badge
[](https://verified-skill.com/skills/dralkh/seerai/bids)