dralkh/seerai/bids

Claude Code and agent skill by dralkh/seerai

Trust tier 3
  • community
Source check pending

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/bids

SKILL.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.json for a new dataset
  • Working with BIDS entities (subject, session, task, acquisition, run, etc.)
  • Configuring .bidsignore to exclude files from validation
  • Preparing data for upload to OpenNeuro, DANDI, or other BIDS-aware repositories

Installation

bash
# Core BIDS querying library
uv pip install pybids
# BIDS validator (Deno-based, installed via PyPI wrapper)
uv pip install bids-validator-deno
# Alternative: install directly via Deno
# deno install -g -A npm:bids-validator
# DICOM-to-BIDS converters (install as needed)
uv pip install heudiconv # HeuDiConv - heuristic-based DICOM conversion
uv pip install dcm2bids # dcm2bids - config-file-based conversion
# BIDScoin: uv pip install bidscoin
# Useful companions
uv pip install nibabel # NIfTI/other neuroimaging file I/O
uv pip install pydicom # DICOM file reading (used by converters)

Core Workflows

1. BIDS Directory Structure

A minimal BIDS dataset follows this layout:

my_dataset/
dataset_description.json # Required: name, BIDSVersion, etc.
participants.tsv # Recommended: subject-level phenotypic data
participants.json # Recommended: column descriptions
README # Recommended: dataset documentation
CHANGES # Recommended: version history
.bidsignore # Optional: patterns to exclude from validation
sub-01/
anat/
sub-01_T1w.nii.gz
sub-01_T1w.json # Sidecar metadata
func/
sub-01_task-rest_bold.nii.gz
sub-01_task-rest_bold.json
sub-01_task-rest_events.tsv # Event timing for task fMRI
sub-01_task-rest_events.json
dwi/
sub-01_dwi.nii.gz
sub-01_dwi.json
sub-01_dwi.bvec
sub-01_dwi.bval
fmap/
sub-01_phasediff.nii.gz
sub-01_phasediff.json
sub-01_magnitude1.nii.gz
perf/
sub-01_asl.nii.gz
sub-01_asl.json
sub-01/
ses-pre/
anat/
sub-01_ses-pre_T1w.nii.gz
func/
sub-01_ses-pre_task-nback_bold.nii.gz
ses-post/
...

Key points:

  • Every NIfTI file should have a corresponding .json sidecar
  • 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.json is strictly required at the root level
2. Creating dataset_description.json
python
import json
dataset_description = {
"Name": "My Neuroimaging Study",
"BIDSVersion": "1.10.0",
"DatasetType": "raw",
"License": "CC0",
"Authors": ["First Author", "Second Author"],
"Acknowledgements": "Funded by NIH R01-MH123456",
"HowToAcknowledge": "Please cite: Author et al. (2025) Journal Name.",
"Funding": ["NIH R01-MH123456", "NSF BCS-7654321"],
"ReferencesAndLinks": ["https://doi.org/10.xxxx/xxxxx"],
"DatasetDOI": "10.18112/openneuro.ds000001.v1.0.0",
"GeneratedBy": [
{
"Name": "HeuDiConv",
"Version": "1.3.1",
"CodeURL": "https://github.com/nipy/heudiconv"
}
]
}
with open("dataset_description.json", "w") as f:
json.dump(dataset_description, f, indent=4)

For derivatives, set "DatasetType": "derivative" and add "GeneratedBy" listing the pipeline:

python
deriv_description = {
"Name": "fMRIPrep - fMRI PREProcessing",
"BIDSVersion": "1.10.0",
"DatasetType": "derivative",
"GeneratedBy": [
{
"Name": "fMRIPrep",
"Version": "24.1.0",
"CodeURL": "https://github.com/nipreps/fmriprep"
}
]
}
3. Querying BIDS Datasets with PyBIDS
python
from bids import BIDSLayout
# Index a BIDS dataset (validates structure on load)
layout = BIDSLayout("/path/to/bids_dataset")
# Basic queries
subjects = layout.get_subjects() # ['01', '02', '03', ...]
sessions = layout.get_sessions() # ['pre', 'post'] or []
tasks = layout.get_tasks() # ['rest', 'nback']
runs = layout.get_runs() # [1, 2] or []
# Find specific files
bold_files = layout.get(
suffix="bold",
extension=".nii.gz",
return_type="filename"
)
# Filter by subject, task, session
nback_sub01 = layout.get(
subject="01",
task="nback",
suffix="bold",
extension=".nii.gz",
return_type="filename"
)
# Get metadata from JSON sidecars (automatic inheritance)
metadata = layout.get_metadata("/path/to/sub-01/func/sub-01_task-rest_bold.nii.gz")
tr = metadata["RepetitionTime"]
# Get all entities for a file
entities = layout.get_entities()
# Build a path from entities using BIDSLayout
bids_file = layout.get(subject="01", suffix="T1w", extension=".nii.gz")[0]
print(bids_file.path)
print(bids_file.get_entities())

Key points:

  • BIDSLayout indexes the entire dataset on initialization; for large datasets use database_path to 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) for BIDSFile objects
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:

bash
# Install
uv pip install bids-validator-deno
# Validate a dataset
bids-validator /path/to/bids_dataset
# Ignore specific warnings/errors
bids-validator /path/to/bids_dataset --ignoreNiftiHeaders --ignoreSubjectConsistency
Using bids-validator via Deno directly

If Deno is already available, you can install or run the validator without PyPI:

bash
# Install globally via Deno
deno install -g -A npm:bids-validator
# Or run without installing
deno run -A npm:bids-validator /path/to/bids_dataset
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):

# Exclude sourcedata and extra files
sourcedata/
extra_data/
*.log
*_sbref.nii.gz
**/.DS_Store
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:

EntityKeyExampleRequired for
Subjectsub-sub-01All files
Sessionses-ses-preMulti-session studies
Tasktask-task-restfunc (bold, cbv, phase), eeg, meg
Acquisitionacq-acq-highresDistinguishing acquisition parameters
Contrast enhancing agentce-ce-gadoliniumContrast-enhanced images
Reconstructionrec-rec-magnitudeReconstruction variants
Directiondir-dir-APFieldmaps, DWI, phase-encoding
Runrun-run-01Multiple identical acquisitions
Echoecho-echo-1Multi-echo sequences
Partpart-part-magMagnitude/phase splits
Spacespace-space-MNI152NLin2009cAsymDerivatives in template space
Descriptiondesc-desc-preprocDerivatives 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:

DatatypeSuffixes
anatT1w, T2w, FLAIR, T2star, T1map, T2map, defacemask
funcbold, cbv, sbref, events, physio, stim
dwidwi, sbref
fmapphasediff, phase1, phase2, magnitude1, magnitude2, fieldmap, epi
perfasl, m0scan, aslcontext
eegeeg, channels, electrodes, events
megmeg, channels, coordsystem, events
ieegieeg, channels, electrodes, coordsystem, events
petpet, 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

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
vskill VERIFIED badge
[![vskill VERIFIED](https://verified-skill.com/api/v1/skills/dralkh/seerai/bids/badge)](https://verified-skill.com/skills/dralkh/seerai/bids)

Something wrong with this skill or its page? Tell us.