BIDSapp NIDM Standards

Standardize BIDSapp repositories with NIDM integration for consistent structure, output formats, and BABS compatibility.

Overview

This skill defines standards for BIDSapp repositories that:

1. Process neuroimaging data (FreeSurfer, MRIQC, ANTs, etc.)
2. Integrate NIDM (Neuroimaging Data Model) outputs
3. Run through BABS (BIDS App Bootstrap) on HPC clusters
4. Maintain consistent structure across multiple analysis tools

Core Standards

Repository Structure

All BIDSapp repos follow this structure:

<bidsapp_name>/
├── src/
│   ├── <analysis_name>/          # Main analysis code
│   │   ├── __init__.py
│   │   ├── run.py               # Entry point
│   │   └── <analysis>_runner.py
│   └── nidm/                     # NIDM conversion (analysis-specific)
│       ├── __init__.py
│       ├── nidm_converter.py
│       └── data/
├── tests/
│   ├── test_<analysis>.py
│   └── test_nidm.py
├── examples/
├── Dockerfile
├── Singularity
├── setup.py
├── requirements.txt
├── VERSION
└── README.md

CLI Arguments

Standard BIDS arguments (required):

• bids_dir

  - Input BIDS dataset path

• output_dir

  - Output directory path

• analysis_level

  - Must be "participant"

• --participant-label

  - Subject ID(s) without "sub-" prefix

• --session-label

  - Session ID(s) without "ses-" prefix (optional)

Standard NIDM arguments (required):

• --nidm-input-dir

  - Path to existing NIDM files directory

• --skip-nidm

  - Skip NIDM conversion

• --skip-<analysis>

  - Skip analysis if already run (e.g.,

  --skip-freesurfer

  ,

  --skip-mriqc

  ,

  --skip-ants

  )

Analysis-specific arguments (optional):

• Add as needed for specific analysis tools (e.g.,

  --fs-license

  for FreeSurfer,

  --nprocs

  for MRIQC)

See

references/cli_arguments.md

for complete specifications.

Output Structure

BIDS-compliant derivatives structure:

<output_dir>/
└── <bidsapp_name>/              # e.g., freesurfer_nidm, mriqc_nidm, ants_nidm
    ├── dataset_description.json
    ├── <analysis>/              # e.g., freesurfer, mriqc, ants
    │   ├── dataset_description.json
    │   └── sub-{id}/
    │       └── ses-{session}/   # Optional
    │           └── [analysis outputs]
    └── nidm/
        ├── dataset_description.json
        └── sub-{id}/
            └── ses-{session}/   # Optional
                └── sub-{id}_ses-{session}.ttl

NIDM Integration Workflow

The standard NIDM workflow:

1. Copy existing NIDM file from

   --nidm-input-dir

   to output NIDM folder
2. Run analysis (unless

   --skip-<analysis>

   )
3. Extract metrics from analysis outputs
4. Integrate into NIDM file (overwrite the copied file)

The NIDM input directory should contain:

• Single

  nidm.ttl

  file at root, OR
• Per-subject files:

  sub-{id}/ses-{session}/sub-{id}_ses-{session}.ttl

For complete NIDM integration specifications, see

references/nidm_integration.md

.

Common Workflows

Check Repository Compliance

Verify a repo follows standards:

1. Directory structure: Compare against

   references/repo_structure.md

2. CLI arguments: Check

   src/<analysis>/run.py

   for standard args
3. Output structure: Verify code creates

   <bidsapp_name>/{<analysis>, nidm}/

   pattern
4. NIDM integration: Ensure copy→run→integrate workflow exists
5. Containers: Check Dockerfile/Singularity follow

   references/container_patterns.md

Refactor Existing Repository

To update a repo to match standards:

1. Review: Compare current structure against

   references/repo_structure.md

2. Reorganize: Move files to match standard layout
3. Update CLI: Add missing standard arguments
   • Ensure

     --participant-label

     ,

     --session-label

   • Add

     --nidm-input-dir

     ,

     --skip-nidm

     ,

     --skip-<analysis>

4. Fix output structure: Update code to create proper BIDS derivatives
5. Update NIDM workflow: Implement copy→run→integrate pattern
6. Align containers: Update Dockerfile/Singularity
7. Standardize setup.py: Match template configuration
8. Update tests: Ensure test coverage for all components

Create New BIDSapp

To create a new NIDM-integrated BIDSapp from scratch:

1. Initialize structure: Copy

   assets/template/

   directory
2. Rename components: Replace

   <analysis>

   placeholders throughout
3. Implement analysis: Code

   src/<analysis>/<analysis>_runner.py

4. Implement NIDM: Code

   src/nidm/nidm_converter.py

   for this analysis
5. Build containers:
   • Create Dockerfile following

     references/container_patterns.md

   • Create Singularity file for HPC deployment
6. Add tests: Follow standard test patterns
7. Generate BABS config: Use

   references/babs_config.md

   template
8. Document: Update README with usage examples

Update Standards Across All Repos

When changing standards that affect all BIDSapps:

1. Update this skill: Modify reference documentation first
2. Identify affected repos: List all BIDSapps needing updates
3. Update each repo:
   • NIDM converter pattern changes →

     src/nidm/nidm_converter.py

   • CLI changes →

     src/<analysis>/run.py

   • Output structure changes → Runner and output code
   • Container changes → Dockerfile, Singularity
4. Test with BABS: Ensure all repos work with BABS workflow
5. Update BABS configs: Regenerate YAML files if needed

Reference Documentation

All reference files provide detailed specifications:

• references/repo_structure.md

  - Complete repository structure template with explanations

• references/nidm_integration.md

  - Full NIDM workflow, file formats, integration patterns

• references/babs_config.md

  - BABS YAML configuration template with examples

• references/cli_arguments.md

  - Complete CLI argument specifications and validation

• references/container_patterns.md

  - Docker and Singularity build patterns

• references/testing_patterns.md

  - Test structure and coverage requirements

Container Standards

Both Dockerfile and Singularity should:

• Use analysis tool base images where available (e.g.,

  vnmd/freesurfer_8.0.0

  )
• Install Python package via setup.py
• Set appropriate entry points
• Support both Docker and Apptainer/Singularity execution
• Follow BIDS App containerization best practices

See

references/container_patterns.md

for complete specifications.

Testing Standards

Standard test coverage:

• CLI argument parsing and validation
• BIDS input dataset validation
• Analysis execution (with mock or example data)
• NIDM conversion correctness
• Output structure validation
• Container build and execution

Use pytest with fixtures for test data. See

references/testing_patterns.md

.

BABS Integration

All BIDSapps must work with BABS for HPC deployment. Key requirements:

• Accept standard BIDS App CLI arguments
• Output to BIDS derivatives structure
• Support DataLad input datasets
• Work with Singularity/Apptainer containers
• Include proper resource requirements

Generate BABS YAML configs using

references/babs_config.md

template.