Squirrel Data Format — NiDB Neuroinformatics Database

A Single Archive File

Squirrel packages a research dataset — imaging data, behavioral assessments, pipelines, and metadata — into a single self-describing archive file. The receiving end needs no prior knowledge of the dataset structure to read it.

Squirrel is designed for moving multi-modal datasets between institutions, archives, and analysis environments while preserving the relationships between subjects, studies, and data types.

✓ Self-describing: metadata travels with the data
✓ Multi-modal imaging: store multiple types of imaging data in one package
✓ Non-imaging data: store demographics, assessments, observations, interventions, and clinical trial data
✓ Portable: open format readable without NiDB

Documentation ↗ Download ↗

🐿️

squirrel package

 dataset.sqrl

                ├─ squirrel.json

                ├─ data/

                │  ├─ subjects/

                │  │  ├─ 00001/

                │  │  │  ├─ 1/

                │  │  │  │  └─
                MRI series.../

                │  │  │  ├─ 2/

                │  │  │  │  └─
                EEG series.../

                │  │  │  └─ observations/

                │  │  └─ 00002/

                │  │     ├─ 1/

                │  │     │  └─
                MRI series.../

                │  │     ├─
                interventions/

                │  │     └─
                observations/

                │  └─ group-analysis/

                ├─ pipelines/

                ├─ data-dictionary/

                └─ experiments/

Format Features

What a squirrel package contains and how it handles multi-modal datasets.

📋

Self-Describing Metadata

Every squirrel package contains a manifest with complete metadata — subjects, studies, series, modalities, and acquisition parameters — so the data is interpretable without the source database.

🧠

Multi-Modal Support

MRI, EEG, eye-tracking, behavioral assessments, clinical data, and genetic data all live together in a single package, preserving the relationships between modalities.

⚙️

Pipeline Results Included

Analysis pipelines and their outputs travel alongside the raw data, so collaborators receive processed results in full context — not just raw files.

🔓

Open Format

Squirrel is an open specification. Packages can be read and created independently of NiDB, making it viable as a long-term archival and interchange format.

🔀

NiDB Native Export

Export any NiDB project directly to squirrel format. Import squirrel packages into any NiDB instance to restore the full dataset structure instantly.

🌐

Standards Compatible

Works alongside BIDS and NDA exports. Squirrel complements existing standards for cases where richer packaging is needed than those formats provide.

How Squirrel Works

A squirrel package is a portable archive combining data, metadata, and context in one place.

1

Select

Choose subjects, studies, or an entire project in NiDB to export.

2

Package

NiDB bundles data and metadata into a single .sqrl archive.

3

Transfer

Share the file via any means — email, cloud storage, physical media.

4

Import/Extract

Load the package into any NiDB instance, or extract specific objects.

📤

NiDB Integration

Squirrel is NiDB's native transfer format. Export and import are built into the NiDB web interface and do not require command-line use.

✓ Export any project, subject, or study to squirrel in a few clicks
✓ Import a squirrel package to rebuild the dataset in a new NiDB instance
✓ Transfer data between NiDB servers using squirrel as the interchange format
✓ Pipelines and results are preserved end-to-end

Squirrel Documentation ↗

Squirrel Command-Line Utilities

The squirrel CLI lets you create, inspect, modify, and validate packages without NiDB — useful for scripted workflows, HPC pipelines, and data-cleaning tasks.

Command	Description
`dicom2squirrel`	Convert a DICOM directory into a squirrel package
`bids2squirrel`	Convert a BIDS directory into a squirrel package
`info`	Display information about a package or its contents
`modify`	Add, remove, update, or transform objects within a package
`extract`	Extract objects from a package to disk
`validate`	Check whether a package is valid and readable

Import from DICOM or BIDS

Convert an existing dataset into a squirrel package in one command. Choose your output data format and whether subject directories use original IDs or sequential numbers.

# DICOM → squirrel (NIfTI 4D gzip, default)
squirrel dicom2squirrel /data/dicoms study.sqrl

# Anonymized DICOM output, quiet mode
squirrel dicom2squirrel /data/dicoms study.sqrl \
    --dataformat anon -q

# BIDS → squirrel
squirrel bids2squirrel /data/bids_study study.sqrl

Inspect & Validate

Query any level of the hierarchy — package, subject, study, series, pipeline, experiment, and more — in list or CSV format. Run validate before sharing a package.

# Package-level summary
squirrel info study.sqrl

# All subjects, full detail, CSV output
squirrel info study.sqrl --object subject \
    --dataset full --format csv

# Series for one subject's first study
squirrel info study.sqrl --object series \
    --subjectid S1234 --studynum 1

# Validate package integrity
squirrel validate study.sqrl

Modify Packages

Add or remove objects, update metadata, strip PHI, split by modality, and renumber subjects — all without unpacking the archive.

# Remove protected health information
squirrel modify study.sqrl --operation removephi

# Renumber subjects sequentially (sub0001…)
squirrel modify study.sqrl --operation renumber \
    --digits 4 --prefix sub

# Split into one package per imaging modality
squirrel modify study.sqrl --operation splitbymodality

# Update subject demographics
squirrel modify study.sqrl --operation update \
    --object subject --objectid S1234 \
    --objectdata 'Sex=M&DateOfBirth=1990-01-15'

Extract Data

Pull any object — a subject, a specific series, an experiment, or a pipeline — out of a package to a directory on disk.

# Extract a full subject
squirrel extract study.sqrl \
    --object subject --objectid S1234 \
    --outdir /tmp/out

# Extract one imaging series
squirrel extract study.sqrl \
    --object series --objectid 1 \
    --subjectid S1234 --studynum 1 \
    --outdir /tmp/out

# Extract an experiment
squirrel extract study.sqrl \
    --object experiment \
    --objectid MyExperiment --outdir /tmp/out

🐿️ Squirrel Data Format