Differences between revisions 71 and 72
Deletions are marked like this. Additions are marked like this.
Line 136: Line 136:
Careful: run_samseg_long can only handle MS lesions in the dev version, not in FS7!

'''''Preprocessing:'''''

This page is readable only by those in the LcnGroup and CmetGroup.

Samseg (cross-sectional, longitudinal, MS lesions)

This functionality is available in FreeSurfer 7, with gradual improvements appearing in the development version.

Author: Koen Van Leemput

E-mail: koen [at] nmr.mgh.harvard.edu

Rather than directly contacting the author, please post your questions on this module to the FreeSurfer mailing list at freesurfer [at] nmr.mgh.harvard.edu

If you use these tools in your analysis, please cite:

See also: ThalamicNuclei, HippocampalSubfieldsAndNucleiOfAmygdala, BrainstemSubstructures


1. General Description

Sequence Adaptive Multimodal SEGmentation (SAMSEG) is a tool to robustly segment dozens of brain structures from head MRI scans without preprocessing. The characteristic property of SAMSEG is that it accepts multi-contrast MRI data without prior assumptions on the specific type of scanner or pulse sequences used. Dedicated versions to handle longitudinal data, or to segment white matter lesions in multiple sclerosis (MS) patients are also available.

The figure below illustrates a typical SAMSEG segmentation result on a T1w-FLAIR scan of a MS patient:
3D_small.png

2. Basic SAMSEG (cross-sectional processing)

In its most basic form SAMSEG takes one or more co-registered MRI volumes as input, and produces an output segmentation in around 10 min on a good desktop computer (with multi-threading enabled). Preprocessing of the scan(s) with FreeSurfer is neither required nor recommended (e.g., no reformatting to 1mm isotropic resolution, no bias field correction and no skull stripping is needed nor recommended). The command line is:

run_samseg --input <file> [<file> ...] --output <dir> [--threads <threads>] [--pallidum-separate] 

where:

  • <file>: is the path to the input volume(s) in Nifti (.nii/.nii.gz) or FreeSurfer (.mgz) file format. If you have more than one contrast (e.g., both T1w and T2w) you can simply list all the input contrasts you want to use -- the only requirement is that all input volumes are co-registered with each other, and have the same image grid size and voxel dimensions (see below for instructions on how to do that with FreeSurfer).

  • <dir>: is the path to the output directory where the results will be saved. If this directory doesn't exist, it will be created automatically.

  • <threads> (optional): is the number of threads to be used by SAMSEG (default uses one thread). Set the number of threads to the number of CPU cores on your computer to get the fastest run time.

  • --pallidum-separate (optional): by default SAMSEG will treat the pallidum internally as a white matter structure, since it typically can't be discerned easily from white matter in T1w scans. However, if your combination of input volumes includes contrasts where the pallidum is clearly discernible (e.g., T2w or FLAIR) you should add this flag to your command line.

The output will consist of the following set of files, which can be found under the specified <dir> directory:

  • seg.mgz: is the output segmentation volume, where each voxel has been assigned to one anatomical structure. This file is similar to the "aseg.mgz" file produced by the standard volumetric stream in FreeSurfer: the correspondence between structure numbers and neuroanatomical labels is according to $FREESURFER_HOME/FreeSurferColorLUT.txt.

  • samseg.stats: contains the estimated volume (in cubic mm) for each segmented structure. These volumes will be very close (but not identical to) the number of voxels assigned to each structure in "seg.mgz" -- the reason for the discrepancy is that "seg.mgz" is computed in a winner-takes-all fashion, ignoring the uncertainty about the underlying voxel assignments (and therefore yielding slightly less accurate volume estimates).

  • mode0X_bias_corrected.mgz (with X=1,2,...): the bias field corrected MRI volume corresponding to each input contrast.

  • mode0X_bias_field.mgz (with X=1,2,...): the estimated bias field for each input contrast.

Running

run_samseg --help

will display instructions for using more advanced options, including the ability to save the full probabilistic ("soft") segmentations and skipping the initial subject-to-atlas affine registration step.

Examples:

Segment a single T1w scan using a single CPU core (e.g., for running on a cluster):

run_samseg --input /home/username/data/t1.nii --output /home/username/data/samsegOutput/ 

Segment a single T1w scan with 8 CPU cores:

run_samseg --input /home/username/data/t1.nii --output /home/username/data/samsegOutput/ --threads 8

Segment a subject with both T1w and a FLAIR scan (provided both scans are co-registered and have the same image grid size and voxel resolution -- see below) using 4 threads:

run_samseg --input /home/username/data/t1.nii /home/username/data/flair.nii --pallidum-separate --output /home/username/data/samsegOutput/ --threads 4

Co-registering multi-contrast data:

When giving multi-contrast data as input, SAMSEG expects that all contrasts have already been co-registered and reformatted to the same image grid. To avoid loss of information, it is recommended to select the contrast with the highest spatial resolution (smallest voxel size) and reformat all other contrasts to that.

FreeSurfer comes with a set of tools to perform accurate inter-modality co-registration and reformatting. For instance, given a 1x1x1mm3 T1w scan "t1.nii" and a 1x1x3mm3 FLAIR "flair.nii", coregistering and reformatting the FLAIR to the T1w can be accomplished using:

mri_coreg --mov flair.nii --ref t1.nii --reg flairToT1.lta
mri_vol2vol --mov  flair.nii  --reg flairToT1.lta  --o flair_reg.nii --targ t1.nii

SAMSEG can then be called using e.g.,

run_samseg --input t1.nii flair_reg.nii --pallidum-separate --output samsegOutput/ 


3. SAMSEG for MS patients (cross-sectional processing)

SAMSEG comes with a dedicated extension to explicitly segment white matter lesions in multiple sclerosis patients. To use it, you need to invoke SAMSEG with the following additional flags:

  • --lesion: is the flag to tell SAMSEG to segment white matter lesions.

  • --lesion-mask-pattern <pattern> (optional but strongly recommended): only considers voxels as candidate lesions if their (possibly multi-contrast) intensity satisfies certain constraints compared to the intensity of cortical gray matter. The pattern is a sequence of numbers, one number for each input contrast, with the following meaning: a value of "-1" or "1" indicates the voxels should be darker or brighter than cortical gray matter, respectively, whereas a value of "0" means that no intensity constraint is applied to the corresponding input contrast. Typically "0" would be used for T1w scans, and "1" for T2w/FLAIR scans.

  • --threshold <threshold> (optional): is the threshold applied to the probability of a voxel being lesion in order to assign it to lesion (or some other structure) in "seg.mgz". The default value (0.3 in the current implementation) will typically give reasonable results, but you can tweak this value (between 0.0 and 1.0) to obtain a more fine-grained balance between false positive (low threshold value) and false negative (high threshold value) lesion detections.

When doing a study comparing MS patients with controls, you should use the same SAMSEG command to process both patient groups -- SAMSEG with the lesion flag enabled should work robustly even in subjects with no white matter lesions.

The first time you run this module, you may be prompted to install Tensorflow. Simply follow the instructions on the screen to install the CPU or GPU version. If you have a compatible GPU, you can install the GPU version for faster processing, but this requires installing additional libraries (GPU driver, Cuda, CuDNN). These libraries are generally required for a GPU, and are not specific for this tool.

Examples:

Segment an MS subject with both a T1w and a FLAIR scan (provided both scans are co-registered and have the same image grid size and voxel resolution -- see above) using a single core:

run_samseg --input /home/username/data/t1.nii /home/username/data/flair.nii --pallidum-separate --lesion --lesion-mask-pattern 0 1 --output /home/username/data/samsegOutput/ 

Segment an MS subject with a T1w, a FLAIR and a PDw scan (provided all scans are co-registered and have the same image grid size and voxel resolution -- see above) using 8 CPU cores and a lesion threshold of 0.7:

run_samseg --input /home/username/data/t1.nii /home/username/data/flair.nii /home/username/data/pd.nii --pallidum-separate --lesion --lesion-mask-pattern 0 1 0 --threshold 0.7 --output /home/username/data/samsegOutput/ --threads 8


4. Longitudinal processing with SAMSEG

Careful: run_samseg_long can only handle MS lesions in the dev version, not in FS7!

Preprocessing:

# First register all the t1 scans in a unbiased common space (original data tp1_t1.nii ...tpn_t1.nii)
mri_robust_template --mov tp1_t1.nii ... tpn_t1.nii --template mean.mgz   --satit --mapmov tp1_t1_reg.mgz 

# Then coregister the other contrast to the new register t1 scans
# Example for a flair scan for tp1 
mri_coreg --mov origFLAIR.nii --ref tp1_t1_reg.mgz --reg tp1.lta
mri_vol2vol --mov origFLAIR.nii  --reg tp1.lta  --o tp1_flair_reg.mgz --targ tp1_t1_reg.mgz

Samseg (last edited 2023-03-20 17:46:12 by AvnishKumar)