Getting started¶

In this tutorial, you will install Lacuna and walk through the full workflow from data preparation to group-level results. It provides the foundation for the analysis-specific tutorials.

What you'll learn:

• Install Lacuna and verify the installation
• Load the tutorial lesion dataset
• Convert lesion masks to BIDS format
• Explore available atlases and connectomes
• Run an analysis on single and multiple subjects
• Collect individual-level outputs into group-level tables

Setup¶

Note: Lacuna requires Python ≥ 3.10.

In [ ]:

remove_output

# Install Lacuna from GitHub
!pip install git+https://github.com/m-petersen/lacuna

# Install Lacuna from GitHub !pip install git+https://github.com/m-petersen/lacuna

In [ ]:

remove_output

# Verify installation
!lacuna --version

# Verify installation !lacuna --version

The Lacuna CLI¶

Lacuna offers the user two ways of using it via (1) the command line interface (CLI) and (2) via the Python API. Here we will focus on the CLI.

The CLI is hierarchically structured in subcommands following a typical lesion analysis workflow.

lacuna
└─tutorial  # Get the tutorial data
└─bidsify   # Transform your directory of masks into a BIDS-compliant dataset
└─fetch     # Download and fetch connectomes for network mapping analyses
└─run       # Run analyses
  └─rd      # Run regional damage analysis
  └─fnm     # Run functional network mapping
  └─snm     # Run structural network mapping
└─check     # Validate inputs and check output completeness
└─collect   # Collect individual-level outputs into analysis-ready group-level tables
└─info      # Get info on available resources (e.g., parcellation atlases, citations)

You can further explore the functionality via the help pages.

In [2]:

!lacuna --help

!lacuna --help

usage: lacuna [-h] [--version] <command> ...

Lacuna v0.0.1.dev454

options:
  -h, --help  show this help message and exit
  --version   show program's version number and exit

commands:
  Use 'lacuna <command> --help' for more information.

  <command>
    fetch     Download and setup connectomes
    run       Run lesion network mapping analyses
    collect   Aggregate parcelstats across subjects
    info      Display available resources (atlases, connectomes)
    bidsify   Convert NIfTI files to BIDS format
    tutorial  Setup tutorial data for learning Lacuna
    check     Validate inputs and check output completeness

Commands:
  bidsify   Convert NIfTI files to BIDS format
  fetch     Download and setup connectomes for analysis
  run       Run lesion analyses
  collect   Aggregate results across subjects
  info      Display available resources (atlases, connectomes)
  tutorial  Setup tutorial data for learning Lacuna
  check     Validate inputs and check output completeness

Examples:
  lacuna tutorial ./my_tutorial
  lacuna fetch gsp1000 --api-key \$DATAVERSE_API_KEY
  lacuna run rd /bids /output --parcel-atlases schaefer2018parcels100networks7
  lacuna run fnm /bids /output --connectome-path /path/to/gsp1000_batches
  lacuna collect /output
  lacuna info atlases

Get the tutorial data¶

We begin by loading the synthetic lesion dataset included in Lacuna. This dataset is designed for demonstration and testing and contains lesion masks already normalized to MNI152NLin6Asym space. Lacuna requires lesion masks to be in either MNI152NLin6Asym or MNI152NLin2009cAsym; see the explainer on coordinate spaces for details. If your data are not yet in MNI space, refer to the guide on spatial normalization.

Lacuna expects input data in BIDS format but provides utilities to convert (“bidsify”) non-compliant datasets. To illustrate this workflow, we will start from a non-BIDS version of the tutorial dataset. If you prefer to use the preformatted BIDS version, you can skip this step and omit the --raw flag referenced below.

In [3]:

!lacuna tutorial /tmp/tutorial_data --raw --force

!lacuna tutorial /tmp/tutorial_data --raw --force

Setting up tutorial data at: /tmp/tutorial_data
✓ Tutorial data copied to: /tmp/tutorial_data

The tutorial dataset includes:
  - 01.nii.gz, 02.nii.gz, 03.nii.gz

Convert to BIDS-style format¶

To bidsify the dataset, we provide lacuna bidsify with metadata about our masks:

1. Space: Type of MNI space. Lacuna supports MNI152NLin6Asym (used by FSL) or MNI152NLin2009cAsym (used by fMRIPrep).
2. Label: Refers to a specific lesion entity (e.g., acuteinfarct) if you have multiple lesion types.
3. Session: Specifies the timepoint or visit (e.g., 01, followup) if you have longitudinal data.

In [4]:

!lacuna bidsify /tmp/tutorial_data /tmp/tutorial_bids --space MNI152NLin6Asym --session 01 --label acuteinfarct

!lacuna bidsify /tmp/tutorial_data /tmp/tutorial_bids --space MNI152NLin6Asym --session 01 --label acuteinfarct

If your data is already in BIDS-style format, skip the bidsify step. You can also get the pre-formatted BIDS version of the tutorial dataset directly:

lacuna tutorial /tmp/tutorial_bids

For illustration purposes load one lesion mask and visualize it with nilearn.

In [5]:

import nibabel as nib
from nilearn import plotting

lesion_path = '/tmp/tutorial_bids/sub-01/ses-01/anat/sub-01_ses-01_space-MNI152NLin6Asym_label-acuteinfarct_mask.nii.gz'
lesion_img = nib.load(lesion_path)

plotting.plot_roi(lesion_img, 
                       radiological=True, 
                       title="Synthetic lesion mask 01", 
                       draw_cross=False, 
                       colorbar=False)

import nibabel as nib from nilearn import plotting lesion_path = '/tmp/tutorial_bids/sub-01/ses-01/anat/sub-01_ses-01_space-MNI152NLin6Asym_label-acuteinfarct_mask.nii.gz' lesion_img = nib.load(lesion_path) plotting.plot_roi(lesion_img, radiological=True, title="Synthetic lesion mask 01", draw_cross=False, colorbar=False)

Out[5]:

<nilearn.plotting.displays._slicers.OrthoSlicer at 0x7fcfb119f1c0>

Before running analyses on a new dataset, lacuna check input validates that all masks are well-formed — binary, non-empty, and in a detectable coordinate space. This catches common issues upfront rather than failing mid-batch.

In [6]:

!lacuna check input \
    /tmp/tutorial_bids \
    --mask-space MNI152NLin6Asym

!lacuna check input \ /tmp/tutorial_bids \ --mask-space MNI152NLin6Asym

Checking 3 input mask(s) in /tmp/tutorial_bids...

Checking masks: 100%|███████████████████████████| 3/3 [00:00<00:00,  8.82mask/s]
File                                                                    Status   Issues
----------------------------------------------------------------------------------------------------------------
.../sub-01_ses-01_space-MNI152NLin6Asym_label-acuteinfarct_mask.nii.gz  ok       
.../sub-02_ses-01_space-MNI152NLin6Asym_label-acuteinfarct_mask.nii.gz  ok       
.../sub-03_ses-01_space-MNI152NLin6Asym_label-acuteinfarct_mask.nii.gz  ok       

================================================================================================================
Summary: 3 ok, 0 warnings, 0 errors
================================================================================================================

Explore available resources¶

Lacuna ships with parcellation atlases and supports downloading normative connectomes. The lacuna info command shows what is available.

Parcellation atlases¶

Lacuna provides direct access to the Schaefer cortical and Tian (Melbourne) subcortical parcellations in different resolutions, as well as combined cortical + subcortical atlases. Beyond that, Lacuna provides functionality to load your own atlases which will be covered in a separate how-to.

If you use any of these atlases, please cite the corresponding papers.

In [7]:

!lacuna info atlases

!lacuna info atlases

Available Brain Parcellations (Atlases)
============================================================

Schaefer Cortical Parcellations:
  schaefer2018parcels1000networks17             (MNI152NLin6Asym, 1mm)
  schaefer2018parcels1000networks7              (MNI152NLin6Asym, 1mm)
  schaefer2018parcels100networks17              (MNI152NLin6Asym, 1mm)
  schaefer2018parcels100networks7               (MNI152NLin6Asym, 1mm)
  schaefer2018parcels200networks17              (MNI152NLin6Asym, 1mm)
  schaefer2018parcels200networks7               (MNI152NLin6Asym, 1mm)
  schaefer2018parcels400networks17              (MNI152NLin6Asym, 1mm)
  schaefer2018parcels400networks7               (MNI152NLin6Asym, 1mm)

  Citation:
    Schaefer et al, 2018. https://doi.org/10.1093/cercor/bhx179

Tian Subcortical Parcellations:
  tian2020parcels16                             (MNI152NLin6Asym, 1mm)
  tian2020parcels32                             (MNI152NLin6Asym, 1mm)
  tian2020parcels50                             (MNI152NLin6Asym, 1mm)
  tian2020parcels54                             (MNI152NLin6Asym, 1mm)

  Citation:
    Tian et al, 2020. https://doi.org/10.1038/s41593-020-00711-6

Combined Cortical + Subcortical:
  schaefer2018tian2020parcels1016networks17     (MNI152NLin6Asym, 1mm)
  schaefer2018tian2020parcels1016networks7      (MNI152NLin6Asym, 1mm)
  schaefer2018tian2020parcels1032networks17     (MNI152NLin6Asym, 1mm)
  schaefer2018tian2020parcels1032networks7      (MNI152NLin6Asym, 1mm)
  schaefer2018tian2020parcels1050networks17     (MNI152NLin6Asym, 1mm)
  schaefer2018tian2020parcels1050networks7      (MNI152NLin6Asym, 1mm)
  schaefer2018tian2020parcels1054networks17     (MNI152NLin6Asym, 1mm)
  schaefer2018tian2020parcels1054networks7      (MNI152NLin6Asym, 1mm)
  schaefer2018tian2020parcels416networks17      (MNI152NLin6Asym, 1mm)
  schaefer2018tian2020parcels416networks7       (MNI152NLin6Asym, 1mm)
  schaefer2018tian2020parcels432networks17      (MNI152NLin6Asym, 1mm)
  schaefer2018tian2020parcels432networks7       (MNI152NLin6Asym, 1mm)
  schaefer2018tian2020parcels450networks17      (MNI152NLin6Asym, 1mm)
  schaefer2018tian2020parcels450networks7       (MNI152NLin6Asym, 1mm)
  schaefer2018tian2020parcels454networks17      (MNI152NLin6Asym, 1mm)
  schaefer2018tian2020parcels454networks7       (MNI152NLin6Asym, 1mm)

============================================================
Total: 28 atlas(es) available

Connectomes¶

Network mapping analyses (FNM, SNM) require a normative connectome. Lacuna supports three connectomes that differ in modality and size:

In [8]:

!lacuna info connectomes

!lacuna info connectomes

Registered Connectomes
============================================================

Functional Connectomes:
  None registered. Use 'lacuna fetch gsp1000' to download GSP1000.

Structural Connectomes:
  None registered. Use 'lacuna fetch dtor985' or 'lacuna fetch hcp1065'.

============================================================

Fetchable Connectomes (use 'lacuna fetch <name>'):

  gsp1000  - GSP1000 Functional Connectome (~200GB)
             1000 subjects, MNI152NLin6Asym space
             Citation:
               Cohen et al, 2020. https://doi.org/10.7910/DVN/ILXIKS

  dtor985  - dTOR985 Structural Connectome (~11GB)
             985 subjects, MNI152NLin2009bAsym space
             Citation:
               Elias et al, 2024. https://doi.org/10.1038/s41597-024-03197-0

  hcp1065  - HCP1065 Structural Connectome (~2GB)
             1065 subjects, MNI152NLin2009cAsym (native: MNI152NLin2009aAsym) space
             Citation:
               Yeh et al, 2022. https://doi.org/10.1038/s41467-022-32595-4

Fetch connectomes¶

Connectomes are large datasets that need to be downloaded once before running network mapping analyses. The lacuna fetch command handles downloading and format conversion.

Connectome	Type	Size	API key required
GSP1000	Functional (resting-state fMRI)	~200 GB	Dataverse
dTOR985	Structural (tractogram)	~11 GB	Figshare
HCP1065	Structural (tractogram)	~1.5 GB	None

We will not download any connectomes in this getting-started tutorial. The analysis-specific tutorials cover fetching the relevant connectome.

Run an analysis¶

All analyses follow the same CLI pattern:

lacuna run <analysis> <bids_dir> <output_dir> [options]

Lacuna currently provides three analysis types:

• rd (regional damage) — Lesion overlap with parcellation atlases. No connectome needed.
• fnm (functional network mapping) — Lesion-derived functional connectivity maps. Requires a functional connectome (GSP1000).
• snm (structural network mapping) — White matter disconnection maps. Requires a structural connectome (dTOR985 or HCP1065) and MRtrix3.

To demonstrate the general workflow, we use regional damage as it requires no external connectome and runs quickly. The analysis-specific tutorials cover each analysis type in detail.

In [9]:

!lacuna run rd --help

!lacuna run rd --help

usage: lacuna run rd [-h] [--participant-label LABEL [LABEL ...]]
                     [--session-id SESSION [SESSION ...]] [--pattern GLOB]
                     [--mask-space SPACE] [--overwrite]
                     [--on-empty {warn,skip,error}] [--keep-intermediate] [-v]
                     [--nprocs N] [--batch-size N]
                     [--parcel-atlases ATLAS [ATLAS ...]]
                     [--custom-parcellation NAME NIFTI LABELS SPACE]
                     bids_dir output_dir

RegionalDamage Analysis

Computes lesion overlap with brain parcellations (atlases).
For each parcel, calculates the percentage of voxels overlapping
with the lesion mask.

Use 'lacuna info atlases' to see available atlases.

Examples:
  lacuna run rd /bids /output
  lacuna run rd /bids /output --parcel-atlases schaefer2018parcels100networks7
  lacuna run rd /bids /output --parcel-atlases schaefer2018parcels400networks17 tian2020parcels32

positional arguments:
  bids_dir              Root folder of BIDS dataset (sub-XXXXX folders at top
                        level), OR path to a single NIfTI mask file for quick
                        analysis
  output_dir            Output directory for derivatives

options:
  -h, --help            show this help message and exit

BIDS filtering options:
  --participant-label LABEL [LABEL ...], --participant_label LABEL [LABEL ...]
                        Subject IDs to process (without sub- prefix)
  --session-id SESSION [SESSION ...], --session_id SESSION [SESSION ...]
                        Session IDs to process (without ses- prefix)
  --pattern GLOB        Glob pattern to filter mask files (e.g., '*label-
                        WMH*')

Mask space options:
  --mask-space SPACE    Coordinate space of input masks (MNI152NLin6Asym or
                        MNI152NLin2009cAsym). Required if not detectable from
                        filename or sidecar JSON.

Other options:
  --overwrite           Overwrite existing output files
  --on-empty {warn,skip,error}
                        Behavior when a subject has an empty mask (no non-zero
                        voxels) or no overlap with the analysis network/atlas:
                        warn (default, process with zero-valued outputs), skip
                        (exclude from processing), or error (raise error and
                        halt processing).
  --keep-intermediate   Keep intermediate results in output
  -v, --verbose         Increase verbosity (-v=INFO, -vv=DEBUG)

Performance options:
  --nprocs N            Number of parallel processes for subject processing
                        (-1 for all CPUs)
  --batch-size N        Number of subjects to process before writing outputs
                        (-1 for all). Lower values produce incremental output
                        and reduce peak memory.

RegionalDamage options:
  --parcel-atlases ATLAS [ATLAS ...]
                        Atlas names to use. Use 'lacuna info atlases' to list
                        available atlases.
  --custom-parcellation NAME NIFTI LABELS SPACE
                        Custom parcellation: a short name for output
                        labelling, NIfTI file path, labels file path, and
                        coordinate space (e.g., MNI152NLin6Asym). Can be
                        specified multiple times.

Shared arguments across all analysis types include:

• bids_dir — Path to a BIDS dataset (or a single NIfTI file for quick analysis)
• output_dir — Where to write results (BIDS derivatives format)
• --participant-label — Process only specific subjects (omit to process all)
• --session-id — Session IDs to process
• --pattern — Filter to select specific masks within subject directory
• --mask-space — MNI space of the input masks (if not detectable from filenames)
• --on-empty — How to handle subjects with empty or no-overlap masks: warn (default, produce zero-valued outputs), skip, or error
• --verbose / -v — Show detailed processing logs

Each analysis type adds its own specific options (e.g., --connectome-path for FNM/SNM).

Run the regional damage analysis on a single subject.

In [10]:

!lacuna run rd \
    /tmp/tutorial_bids/ \
    /tmp/outputs_rd/ \
    --parcel-atlases schaefer2018parcels100networks7 schaefer2018tian2020parcels416networks17 \
    --participant-label 01 \
    --mask-space MNI152NLin6Asym

!lacuna run rd \ /tmp/tutorial_bids/ \ /tmp/outputs_rd/ \ --parcel-atlases schaefer2018parcels100networks7 schaefer2018tian2020parcels416networks17 \ --participant-label 01 \ --mask-space MNI152NLin6Asym

Results are saved in BIDS derivatives format, mirroring the input directory structure.

In [11]:

!ls /tmp/outputs_rd/sub-01/ses-01/anat/

!ls /tmp/outputs_rd/sub-01/ses-01/anat/

sub-01_ses-01_desc-provenance.json
sub-01_ses-01_label-acuteinfarct_method-rd_atlas-schaefer2018parcels100networks7_desc-damagebin_parcelstats.json
sub-01_ses-01_label-acuteinfarct_method-rd_atlas-schaefer2018parcels100networks7_desc-damagebin_parcelstats.tsv
sub-01_ses-01_label-acuteinfarct_method-rd_atlas-schaefer2018parcels100networks7_desc-damagepct_parcelstats.json
sub-01_ses-01_label-acuteinfarct_method-rd_atlas-schaefer2018parcels100networks7_desc-damagepct_parcelstats.tsv
sub-01_ses-01_label-acuteinfarct_method-rd_atlas-schaefer2018tian2020parcels416networks17_desc-damagebin_parcelstats.json
sub-01_ses-01_label-acuteinfarct_method-rd_atlas-schaefer2018tian2020parcels416networks17_desc-damagebin_parcelstats.tsv
sub-01_ses-01_label-acuteinfarct_method-rd_atlas-schaefer2018tian2020parcels416networks17_desc-damagepct_parcelstats.json
sub-01_ses-01_label-acuteinfarct_method-rd_atlas-schaefer2018tian2020parcels416networks17_desc-damagepct_parcelstats.tsv
sub-01_ses-01_label-acuteinfarct_space-MNI152NLin6Asym_mask.nii.gz

Run on multiple subjects¶

Omitting --participant-label processes all subjects in the dataset. With --verbose we can inspect which masks are detected.

In [12]:

!lacuna run rd \
    /tmp/tutorial_bids/ \
    /tmp/outputs_rd_all/ \
    --parcel-atlases schaefer2018parcels100networks7 \
    --mask-space MNI152NLin6Asym \
    --verbose

!lacuna run rd \ /tmp/tutorial_bids/ \ /tmp/outputs_rd_all/ \ --parcel-atlases schaefer2018parcels100networks7 \ --mask-space MNI152NLin6Asym \ --verbose

2026-04-01 09:28:58 - lacuna.cli.main - INFO - Lacuna CLI starting
2026-04-01 09:28:58 - lacuna.cli.main - INFO - Input: /tmp/tutorial_bids
2026-04-01 09:28:58 - lacuna.cli.main - INFO - Output directory: /tmp/outputs_rd_all
2026-04-01 09:28:58 - lacuna.cli.main - INFO - Analysis: rd
2026-04-01 09:28:58 - lacuna.cli.main - INFO - Running analysis: RegionalDamage
2026-04-01 09:28:58 - lacuna.cli.main - INFO - 
2026-04-01 09:28:58 - lacuna.cli.main - INFO - ============================================================
2026-04-01 09:28:58 - lacuna.cli.main - INFO - DISCOVERY SUMMARY
2026-04-01 09:28:58 - lacuna.cli.main - INFO - ============================================================
2026-04-01 09:28:58 - lacuna.cli.main - INFO -   Total mask images: 3
2026-04-01 09:28:58 - lacuna.cli.main - INFO -   Unique subjects:   3
2026-04-01 09:28:58 - lacuna.cli.main - INFO -   Unique sessions:   1
2026-04-01 09:28:58 - lacuna.cli.main - INFO -   Labels:            acuteinfarct
2026-04-01 09:28:58 - lacuna.cli.main - INFO - ============================================================
2026-04-01 09:28:58 - lacuna.cli.main - INFO - 
2026-04-01 09:28:58 - lacuna.cli.main - INFO - Masks to process:
2026-04-01 09:28:58 - lacuna.cli.main - INFO -     1. sub-01/ses-01/acuteinfarct
2026-04-01 09:28:58 - lacuna.cli.main - INFO -     2. sub-02/ses-01/acuteinfarct
2026-04-01 09:28:58 - lacuna.cli.main - INFO -     3. sub-03/ses-01/acuteinfarct
2026-04-01 09:28:58 - lacuna.cli.main - INFO - 
2026-04-01 09:28:58 - lacuna.cli.main - INFO - Batch processing: 3 masks in batches of 3
2026-04-01 09:28:58 - lacuna.cli.main - INFO - 
─── RegionalDamage ───
RegionalDamage:   0%|                                   | 0/3 [00:00<?, ?mask/s]2026-04-01 09:28:58 - lacuna.analysis - INFO - Aggregating 1 source(s) across 1 atlas(es): schaefer2018parcels100networks7
2026-04-01 09:29:00 - lacuna.analysis - INFO - Aggregation complete (1 results)
RegionalDamage:  33%|█████████                  | 1/3 [00:01<00:03,  1.73s/mask]2026-04-01 09:29:00 - lacuna.analysis - INFO - Aggregating 1 source(s) across 1 atlas(es): schaefer2018parcels100networks7
2026-04-01 09:29:01 - lacuna.analysis - INFO - Aggregation complete (1 results)
RegionalDamage:  67%|██████████████████         | 2/3 [00:03<00:01,  1.67s/mask]2026-04-01 09:29:02 - lacuna.analysis - INFO - Aggregating 1 source(s) across 1 atlas(es): schaefer2018parcels100networks7
2026-04-01 09:29:03 - lacuna.analysis - INFO - Aggregation complete (1 results)
RegionalDamage: 100%|███████████████████████████| 3/3 [00:05<00:00,  1.68s/mask]
2026-04-01 09:29:03 - lacuna.cli.main - INFO - Successfully processed 3 subject(s)
2026-04-01 09:29:03 - lacuna.cli.main - INFO - Results saved to: /tmp/outputs_rd_all
2026-04-01 09:29:03 - lacuna.cli.main - INFO - Lacuna CLI completed successfully

In [13]:

!ls /tmp/outputs_rd_all/

!ls /tmp/outputs_rd_all/

dataset_description.json  sub-01  sub-02  sub-03

Check outputs¶

After processing, lacuna check identifies which subjects have complete outputs — useful when a batch job fails partway through and you need to rerun only the missing subjects.

Since we only ran the single-subject analysis on sub-01, lacuna check will report sub-02 and sub-03 as missing and print the exact rerun command needed.

In [14]:

!lacuna check rd \
    /tmp/tutorial_bids/ \
    /tmp/outputs_rd/ \
    --mask-space MNI152NLin6Asym

!lacuna check rd \ /tmp/tutorial_bids/ \ /tmp/outputs_rd/ \ --mask-space MNI152NLin6Asym

Checking rd outputs in /tmp/outputs_rd for 3 subject(s)...

Subject  Session     Status
-------------------------------------------
sub-01   ses-01      complete
sub-02   ses-01      MISSING  (*method-rd*parcelstats.tsv)
sub-03   ses-01      MISSING  (*method-rd*parcelstats.tsv)

===========================================
Summary: 1 / 3 complete, 2 missing
===========================================

Rerun missing subjects:
  lacuna run rd /tmp/tutorial_bids /tmp/outputs_rd --participant-label 02 03

After running on all subjects, check reports everything as complete. Use --output-file to save missing subject IDs to a file for scripting, or --quiet for machine-readable output.

In [17]:

!lacuna check rd \
    /tmp/tutorial_bids/ \
    /tmp/outputs_rd_all/ \
    --mask-space MNI152NLin6Asym

!lacuna check rd \ /tmp/tutorial_bids/ \ /tmp/outputs_rd_all/ \ --mask-space MNI152NLin6Asym

Checking rd outputs in /tmp/outputs_rd_all for 3 subject(s)...

Subject  Session     Status
-------------------------------------------
sub-01   ses-01      complete
sub-02   ses-01      complete
sub-03   ses-01      complete

===========================================
Summary: 3 / 3 complete
===========================================

All subjects are complete.

Zero-valued outputs¶

Some subjects may produce all-zero outputs. There are two distinct reasons for this:

• No spatial overlap — the mask is valid but does not intersect the analysis atlas or connectome. For example, sub-02 in the tutorial dataset has a cerebellar lesion — since the Schaefer atlas only covers cortex, all regional damage values are zero. This is expected behaviour and not an error.
• Empty mask — the mask image contains no non-zero voxels at all (e.g., a failed segmentation). Use --on-empty to control how Lacuna handles these at run time:

--on-empty	Behaviour
warn (default)	Process and produce zero-valued outputs
skip	Exclude from processing
error	Halt processing immediately

To detect which subjects produced all-zero outputs after a run (regardless of cause), pass --check-content to lacuna check. This inspects file contents rather than just checking existence, and reports affected subjects as EMPTY.

In [18]:

# --check-content flags subjects with all-zero outputs as EMPTY
!lacuna check rd \
    /tmp/tutorial_bids/ \
    /tmp/outputs_rd_all/ \
    --mask-space MNI152NLin6Asym \
    --check-content

# --check-content flags subjects with all-zero outputs as EMPTY !lacuna check rd \ /tmp/tutorial_bids/ \ /tmp/outputs_rd_all/ \ --mask-space MNI152NLin6Asym \ --check-content

Checking rd outputs in /tmp/outputs_rd_all for 3 subject(s)...

Subject  Session     Status
-------------------------------------------
sub-01   ses-01      complete
sub-02   ses-01      EMPTY  (all-zero output)
sub-03   ses-01      complete

===========================================
Summary: 2 / 3 complete, 1 empty
===========================================

Note: 1 subject(s) produced empty (all-zero) outputs.
This typically means the input mask had no overlap with the analysis atlas/network.

Collect group-level tables¶

Individual outputs live in per-subject directories. lacuna collect merges them into analysis-ready group-level tables. The --pattern flag allows selective collection by filename pattern.

In [19]:

!lacuna collect \
    /tmp/outputs_rd_all/ \
    --output-dir /tmp/group_outputs/ \
    --pattern "*schaefer2018*" \
    --verbose

!lacuna collect \ /tmp/outputs_rd_all/ \ --output-dir /tmp/group_outputs/ \ --pattern "*schaefer2018*" \ --verbose

2026-04-01 09:29:53 - lacuna.cli.main - INFO - Running collect (group-level aggregation)
2026-04-01 09:29:53 - lacuna.cli.main - INFO - Scanning derivatives directory: /tmp/outputs_rd_all
2026-04-01 09:29:53 - lacuna.cli.main - INFO - Output directory: /tmp/group_outputs
2026-04-01 09:29:53 - lacuna.cli.main - INFO - Pattern: *schaefer2018*_parcelstats.tsv
2026-04-01 09:29:53 - lacuna.cli.main - INFO - Found 6 file(s) across 3 subject(s) and 2 output type(s)
Collecting output types:   0%|                          | 0/2 [00:00<?, ?type/s]
  Reading ses-01_label-acuteinfarct_method-rd_atlas-schaefer2018parcels100networ
                                                                                
  Reading ses-01_label-acuteinfarct_method-rd_atlas-schaefer2018parcels100networ
Collecting output types: 100%|██████████████████| 2/2 [00:00<00:00, 63.45type/s]
2026-04-01 09:29:53 - lacuna.cli.main - INFO - Created 2 group-level TSV file(s):
2026-04-01 09:29:53 - lacuna.cli.main - INFO -   - group_ses-01_label-acuteinfarct_method-rd_atlas-schaefer2018parcels100networks7_desc-damagepct_parcelstats.tsv
2026-04-01 09:29:53 - lacuna.cli.main - INFO -   - group_ses-01_label-acuteinfarct_method-rd_atlas-schaefer2018parcels100networks7_desc-damagebin_parcelstats.tsv

In [23]:

!ls /tmp/group_outputs/

!ls /tmp/group_outputs/

group_ses-01_label-acuteinfarct_method-rd_atlas-schaefer2018parcels100networks7_desc-damagebin_parcelstats.json
group_ses-01_label-acuteinfarct_method-rd_atlas-schaefer2018parcels100networks7_desc-damagebin_parcelstats.tsv
group_ses-01_label-acuteinfarct_method-rd_atlas-schaefer2018parcels100networks7_desc-damagepct_parcelstats.json
group_ses-01_label-acuteinfarct_method-rd_atlas-schaefer2018parcels100networks7_desc-damagepct_parcelstats.tsv

In [25]:

import pandas as pd

parcel_df = pd.read_csv("/tmp/group_outputs/group_ses-01_label-acuteinfarct_method-rd_atlas-schaefer2018parcels100networks7_desc-damagepct_parcelstats.tsv", sep="\t", index_col=0)
parcel_df

import pandas as pd parcel_df = pd.read_csv("/tmp/group_outputs/group_ses-01_label-acuteinfarct_method-rd_atlas-schaefer2018parcels100networks7_desc-damagepct_parcelstats.tsv", sep="\t", index_col=0) parcel_df

Out[25]:

	session_id	label	7Networks_LH_Vis_1	7Networks_LH_Vis_2	7Networks_LH_Vis_3	7Networks_LH_Vis_4	7Networks_LH_Vis_5	7Networks_LH_Vis_6	7Networks_LH_Vis_7	7Networks_LH_Vis_8	...	7Networks_RH_Default_Temp_1	7Networks_RH_Default_Temp_2	7Networks_RH_Default_Temp_3	7Networks_RH_Default_PFCv_1	7Networks_RH_Default_PFCv_2	7Networks_RH_Default_PFCdPFCm_1	7Networks_RH_Default_PFCdPFCm_2	7Networks_RH_Default_PFCdPFCm_3	7Networks_RH_Default_pCunPCC_1	7Networks_RH_Default_pCunPCC_2
participant_id
1	1	acuteinfarct	0.0	0.0	0.577883	0.0	0.118796	11.231361	0.0	0.0	...	0.000000	0.00000	0.000000	0.0	0.0	0.0	0.0	0.0	15.208071	0.892061
2	1	acuteinfarct	0.0	0.0	0.000000	0.0	0.000000	0.000000	0.0	0.0	...	0.000000	0.00000	0.000000	0.0	0.0	0.0	0.0	0.0	0.000000	0.000000
3	1	acuteinfarct	0.0	0.0	0.000000	0.0	0.000000	0.000000	0.0	0.0	...	13.600105	5.60675	29.534862	0.0	0.0	0.0	0.0	0.0	0.000000	0.000000

3 rows × 102 columns

Next steps¶

The workflow shown here — tutorial data, bidsify, run, collect — is the same for all analysis types. For analysis-specific tutorials that cover fetching connectomes, interpreting outputs, and visualization see:

• Functional network mapping
• Structural network mapping
• Regional damage analysis