multiseed

multiseed runs unsupervised group-level resting-state fMRI network extraction using a many-seed-based approach combined with dimensionality reduction. It's available on PyPI.

In practice, it:

1. loads multiple rs-fMRI datasets grouped into cohorts,
2. builds one combined brain mask from all non-zero voxels,
3. samples random seed locations inside that mask,
4. turns each voxel into a vector of seed-correlation values,
5. reduces those vectors with factor analysis, absolute-value-based non-negative matrix factorization, principal component analysis or independent component analysis, and
6. writes one 3D map per extracted network/component for every dataset.

Because the mask, seed set, and reduction model are built jointly across all cohorts, the resulting feature maps are directly comparable across subjects/datasets.

Quick start

Install using pip:

pip install multiseed

Generate a template config (which contains several explanatory comments):

python -m multiseed --write-default-config analysis.cfg

Edit analysis.cfg, then run the analysis:

python -m multiseed analysis.cfg

If you installed a console entry point (default on most systems), the same command is:

multiseed analysis.cfg

The CLI uses a fixed random seed, so repeated runs with the same inputs/config are reproducible.

Programmatic use

The multiseed library exposes an extensive API encompassing almost all parts of its algorithm. See the documentation for more details.

Simple config example

N_SEEDS = 1000
SEED_RADIUS = 10
REDUCTION_ALGORITHM = FactorAnalysis
RESULTS_FOLDER = results

[Controls]
/data/controls/sub01
/data/controls/sub02

[Patients]
/data/patients/*

Available models are FactorAnalysis, AbsNMF, PCA, ICA

Each dataset is one folder containing the 3D volumes from a single scan. Supported image formats are:

• .img, .img.gz, .img.z
• .nii, .nii.gz

A cohort (e.g. Controls or Patients in this example) is a named list of dataset folders.

See the template config for more parameters and information.

What gets written

Resulting networks are written to the RESULTS_FOLDER, organized by cohort and dataset. The exact structure is:

results/
  mask.hdr.gz
  mask.img.gz
  seed_visualization.hdr.gz
  seed_visualization.img.gz
  network_001/
    average_visualization.hdr.gz
    average_visualization.img.gz
    <Cohort Name>/
      result_for_dataset_000001.hdr.gz
      result_for_dataset_000001.img.gz

Notes

• All datasets are assumed to have matching spatial dimensions.
• The combined mask is built from voxels that are nonzero in at least one dataset.
• The exported average visualizations are display-oriented summaries; for downstream numeric work, use the saved float results.