Multicompartment model for pathological connectomes

This tutorial introduces the basic steps required to dealing with lesions and reproduce the results presented in (Bosticardo et al., 2025).

Note

To use the model correctly, the scalar map must be additive.

This tutorial uses the same tractogram and the same white matter mask as the Getting Started tutorial. Then, you will need the following file:

• lesion_mask.nii.gz: binary mask that defines the position(s) of the lesion(s).
• scalar_map.nii.gz: intra-axonal density map computed using Spherical Mean Technique (Kaden et al., 2016) with simulated lesions.

Initialize COMMIT

import commit
commit.setup() # NB: this is required only the first time you run COMMIT

Import the tractogram and the lesion mask

In this step, we import the tractogram and the lesion mask. These inputs inform the model about which voxels should include the lesion compartment (based on the lesion mask) and the intra-axonal compartment (based on the tractogram) when fitting the signal.

# Load the tractogram and the lesion mask
from commit import trk2dictionary
trk2dictionary.run(
     filename_tractogram      = 'demo01_fibers.tck',
     filename_iso_mask        = 'lesion_mask.nii.gz',
     filename_mask            = 'WM.nii.gz',
     fiber_shift              = 0.5,
     ndirs                    = 1
)

Fit with COMMIT as usual

Now that the data are loaded, you are ready to run COMMIT while accounting for lesions. The fitting procedure remains the same as in the Getting Started tutorial, except for the model selection.

# Set parameters
mit = commit.Evaluation()

# Load the image to fit
mit.load_data( 'scalar_map.nii.gz' )

# Set model and generate the response functions
mit.set_model( 'ScalarMap' )
mit.generate_kernels()
mit.load_kernels()

# Load dictionary and buid the operator
mit.load_dictionary()
mit.set_threads()
mit.build_operator()

# Fit model to the data
mit.fit( tol_fun=1e-3, max_iter=1000 )
mit.save_results()

📄 Once the fitting has converged, the estimated contribution of each streamline—accounting for lesions—can be found in the file COMMIT/Results_ScalarMap/streamline_weights.txt. This text file contains one row per streamline, where the weights of streamlines passing through lesions have been scaled accordingly.

🔗 You can integrate this information into your standard analysis pipeline to evaluate, for example, connectivity while explicitly accounting for lesion effects.

🧠 In addition, the following voxel-wise output maps are provided:

• compartment_LESION.nii.gz: map of the estimated signal contribution from the lesion compartment, as fitted by the model.
• R_scaling_factor.nii.gz: map of the scaling coefficient R used to scale the weights of streamlines passing through lesions.