qsiparc 0.1.0

Extract parcellated diffusion features and connectivity matrices from QSIRecon outputs

QSIParc

Parcellated diffusion feature extraction from QSIRecon outputs.

QSIParc reads atlas parcellations and diffusion scalar maps produced by QSIRecon, computes per-region distribution statistics using direct numpy masking, and writes analysis-ready TSV files in a BIDS-derivative layout. It also repackages QSIRecon's structural connectivity matrices with standardized JSON sidecar metadata.

Part of the SNBB neuroimaging extraction stack, paired with fsatlas (FreeSurfer morphometrics).

Installation

pip install -e ".[dev]"

Quick start

# Extract all atlases, all subjects
qsiparc /data/qsirecon /data/qsiparc-out -v

# Single atlas, single subject
qsiparc /data/qsirecon /data/qsiparc-out \
    --atlas Schaefer2018N100Tian2020S2 \
    --participant-label sub-001 \
    -vv

# Only specific scalars
qsiparc /data/qsirecon /data/qsiparc-out --scalars FA MD ICVF

# Dry run
qsiparc /data/qsirecon /data/qsiparc-out --dry-run

Output layout

qsiparc-out/
├── dataset_description.json
└── sub-001/
    └── ses-01/
        └── dwi/
            └── atlas-Schaefer2018N100Tian2020S2/
                ├── sub-001_ses-01_atlas-Schaefer2018N100Tian2020S2_diffmap.tsv
                ├── sub-001_ses-01_atlas-Schaefer2018N100Tian2020S2_desc-streamline_count_connmatrix.csv
                └── sub-001_ses-01_atlas-Schaefer2018N100Tian2020S2_desc-streamline_count_connmatrix.json

Diffusion scalar TSV (long-format)

Each row is one region × one scalar:

| region_index | region_name | hemisphere | scalar | mean | median | std | iqr | skewness | kurtosis | n_voxels | coverage | |---|---|---|---|---|---|---|---|---|---|---|---|---| | 1 | LH_Vis_1 | L | cortex | FA | 0.42 | 0.41 | 0.08 | 0.11 | 0.15 | -0.32 | 847 | 0.98 |

Connectivity matrix

Square CSV (no headers) + JSON sidecar with region labels, edge weight type, and provenance.

Architecture

qsiparc/
├── discover.py    # BIDS file discovery (globs, entity parsing)
├── atlas.py       # Atlas LUT loading (TSV, JSON, FreeSurfer format)
├── extract.py     # Per-region scalar extraction (numpy masking)
├── connectome.py  # Connectivity matrix passthrough
├── output.py      # BIDS-derivative TSV/JSON writing
└── cli.py         # Click CLI

Key design decisions:

• Direct numpy masking (not nilearn) for full voxel distribution access
• No atlas warping — consumes QSIRecon's subject-space parcellations
• Long-format TSV with rich statistics (mean, median, std, IQR, skewness, kurtosis)
• Connectome passthrough (repackaging, not recomputation)

Testing

pytest
pytest --cov=qsiparc

All tests use synthetic 10×10×10 NIfTI volumes — no real data required.

Contributing

Bug reports, documentation fixes, and pull requests are welcome. See CONTRIBUTING for setup instructions, code style, and guidelines on what is in scope.

License

MIT