statCraft

Generalistic neuroimaging Second-level/Group-level analysis tool

Features | Installation | Quick Start | Configuration | Outputs

StatCraft is a second-level (group-level) analysis tool that you run after your first-level / participant-level pipeline has finished. You point StatCraft to the folder where your first-level pipeline (e.g., fmridenoiser, SPM, FSL, cvrmap, pet data, custom scripts) has written its derivatives — such as statistical brain maps, connectivity matrices, or other subject-level measures — and StatCraft builds and fits group-level models on top of those outputs.

In this workflow, the first positional argument to statcraft is typically the derivatives directory. The second positional argument is the output directory where StatCraft will write group-level results (maps, tables, and reports).

The general principle for file discovery is based on pattern-matching (see below), making it very flexible and versatile.

Features

• Multiple Analysis Types

  • One-sample t-tests
  • Two-sample t-tests (group comparisons)
  • Paired t-tests (within-subject comparisons)
  • General Linear Model (GLM) with custom design matrices, e.g. for regression analysis with the possibility of adding confounds

• BIDS-Compliant

  • Reads data following BIDS structure
  • Supports filtering by BIDS entities (subject, session, task)
  • BIDS-like output structure

• Statistical Inference

  • Uncorrected thresholding (default p < 0.001)
  • FDR (False Discovery Rate) correction
  • Bonferroni FWER (Family-Wise Error Rate) correction
  • Permutation-based FWER correction

• Comprehensive Reporting

  • HTML reports with visualizations
  • Design matrix plots
  • Activation maps (thresholded and unthresholded)
  • Cluster tables with anatomical labels (several atlases supported)

Installation

git clone https://github.com/ln2t/statCraft.git
cd statCraft
pip install -e .

Quick Start

Command Line Interface

# One-sample t-test on first-level maps
statcraft /path/to/derivatives /path/to/output \
  --analysis-type one-sample \
  --task nback

# Two-sample t-test (group comparison)
statcraft /path/to/derivatives /path/to/output \
  --analysis-type two-sample \
  --group-column group

# Paired t-test
statcraft /path/to/derivatives /path/to/output \
  --analysis-type paired \
  --pair-by session \
  --condition1 pre \
  --condition2 post

# Using a configuration file
statcraft /path/to/derivatives /path/to/output \
  --config config.yaml

# Skip BIDS validation (when BIDS metadata are available)
statcraft /path/to/derivatives /path/to/output \
  --analysis-type one-sample \
  --skip-bids-validator

Generate Default Configuration

statcraft --init-config config.yaml

Configuration

StatCraft can be configured via command-line arguments, configuration files (YAML/JSON), or Python dictionaries.

Example Configuration (YAML)

# Analysis type
analysis_type: glm

# BIDS filters
bids_filters:
  task: nback
  session: baseline
  space: MNI152NLin2009cAsym

# Design matrix columns (from participants.tsv)
design_matrix:
  columns:
    - age
    - group
  add_intercept: true

# Contrasts to compute
contrasts:
  - age                    # Effect of age
  - patients - controls    # Group difference

# Paired test settings (for paired analysis)
paired_test:
  pair_by: session
  condition1: pre
  condition2: post

# Statistical inference
inference:
  alpha: 0.05
  height_threshold: 0.001
  cluster_threshold: 10
  corrections:
    - uncorrected
    - fdr
    - bonferroni
    - permutations

# Atlas for cluster annotation
atlas: harvard_oxford

# Output settings
output:
  generate_report: true
  report_filename: report.html

Outputs

StatCraft generates:

1. Statistical Maps (*.nii.gz)

   • T-statistic maps
   • P-value maps
   • Effect size maps
   • Thresholded maps (uncorrected, FDR, Bonferroni)

2. Cluster Tables (*.tsv)

   • Peak coordinates (MNI)
   • Cluster sizes
   • Peak statistics
   • Anatomical labels

3. HTML Report (report.html)

   • Methodology description
   • Design matrix visualization
   • Activation maps
   • Glass brain views
   • Cluster tables

4. Configuration (config.yaml)

   • Complete configuration for reproducibility

Advanced Features

Intersection Mask for GLM

When z-scoring is performed during preprocessing, StatCraft automatically:

• Tracks individual brain masks used during z-scoring
• Computes the intersection (overlap) of all masks for consistency
• Uses this intersection mask for the second-level GLM analysis
• Ensures all subjects contribute to the same brain regions

Benefits:

• Ensures voxel-wise comparability across subjects
• Reduces noise from mask boundaries
• Uses masks from actual preprocessing, not automatic computation
• Improves statistical validity of group analysis

Supplementary Data Feature

Overview

The supplementary data feature allows users to control whether intermediate and auxiliary data files are saved during analysis. By default, supplementary data is NOT saved to minimize output size. Users can enable it with the --save-supplementary-data flag.

What is Supplementary Data?

Supplementary data includes intermediate processing files useful for quality control, debugging, and reproducibility:

• Original images: Images before normalization (z-scoring or scaling)
• Normalized images: Z-scored or scaled images before GLM
• Difference images: Paired test difference images (in dedicated diff/ folder)
• Masks: Brain masks used for z-scoring
• Manifest files: Mapping of which masks were used for which images

Intersection Mask Feature

Overview

When z-scoring is performed during preprocessing, each image is normalized using its corresponding brain mask. These masks may differ across subjects if they're subject-specific (e.g., from fMRIPrep).

The intersection mask feature automatically computes the intersection (overlap) of all individual masks used during z-scoring and uses this intersection as the explicit mask for the second-level GLM analysis.

What is an Intersection Mask?

An intersection mask contains only voxels that are valid (non-zero) in ALL individual masks.

Example:

• Subject 1 mask: voxels A, B, C, D, E
• Subject 2 mask: voxels B, C, D, E, F
• Intersection: voxels B, C, D, E (common to both)

How It Works

1. During Z-Scoring: Each image's mask path is recorded
2. During GLM Fitting: All unique masks are loaded and their intersection is computed
3. For Analysis: The intersection mask is passed to the GLM model
4. Fallback: If no masks available, uses automatic mask computation

Automatic behavior:

• Multiple masks → computes intersection
• Single mask → uses it directly
• No masks → falls back to automatic computation
• Errors → gracefully continues with fallback

Citation

If you use StatCraft in your research, please cite:

@software{statcraft,
  title = {StatCraft: Second-Level Neuroimaging Analysis Tool},
  author = {StatCraft Contributors},
  year = {2024},
  url = {https://github.com/ln2t/statCraft}
}

License

This project is licensed under the GNU Affero General Public License v3.0 (AGPLv3) - see the LICENSE file for details.

Acknowledgments

• Nilearn - Core neuroimaging functionality
• PyBIDS - BIDS data handling
• NiBabel - NIfTI file handling