ensemble

Getting Started

Configuration

Git

Install Git version 2.2 or later:

# example
 (main) chovey@mac/Users/chovey/autotwin/ensemble> git --version
git version 2.39.3 (Apple Git-146)

For Windows, we recommend Git Bash. For macOS and Linux, use the Bash shell or similar. The Fish shell is also nice.

Configure Git:

git config --global user.name "your full name here"
git config --global user.email "your email here"

# example
git config --global user.name "Jeannette Rankin"
git config --global user.email "[email protected]"

To write to the repository, set up ssh keys between your local computer and the repository.

Ensemble Repo

cd ~
mkdir autotwin # create a directory called `autotwin`
cd autotwin

# clone the ensemble repo
git clone [email protected]:autotwin/ensemble.git

Python

Install Python version 3.10. All references to python will be this version.

Virtual Environment

We use a virtual environment to support encapsulation and reproducibility.

With in the autotwin/ensemble directory, create a virtual environment:

python3.10 -m venv .venv # with python and the venv module, create a virtual environment called .venv

# activate the virtual environment with one of the following:
source .venv/bin/activate       # for bash shell
source .venv/bin/activate.csh   # for c shell
source .venv/bin/activate.fish  # for fish shell
.\.venv\Scripts/activate        # for powershell

Note: If .venv already exists from previous installs, then remove it:

(.venv) $ deactivate            # deactivate if the virtual environment is currently active
$ pip uninstall .venv           # uninstall
$ rm -rf ~/autotwin/ensemble/.venv  # remove the virtual environment folder with `rm -rf .venv/`.

Update pip and setuptools:

pip install --upgrade pip setuptools

Ensemble Module

We currently support the module in a developer configuration. Production and client configurations will be forthcoming.

• Reference: https://packaging.python.org/en/latest/tutorials/packaging-projects/

ensemble/
├── LICENSE
├── pyproject.toml
├── README.md
├── src/
│   └── ensemble/
│       ├── __init__.py
│       └── example.py
└── tests/

Install the module as a developer:

pip install -e .  # install in dev mode, with the editable flag

Freesurfer

Install Freesurfer. We use Freesurfer version 7.4.1, released June 2023.

• Downloads for installation. For example, the macOS installation with the GUI Package install option, freesurfer-macOS-darwin_x86_64-7.4.1.pkg 6.6 GB, MD5: e050d9a939cb1c969ff0f0d12c5d2749.
• Introduction to Freesurfer Output

recon-all

• Get aseg.mgz(has the segmentation data we care about), is the last step in recon-all (command that runs 31 sequential analyses).
• https://surfer.nmr.mgh.harvard.edu/fswiki/SubcorticalSegmentation
  • "In automatic subcortical segmentation, each voxel in the normalized brain volume is assigned one of about 40 labels, including: Cerebral White Matter, Cerebral Cortex, Lateral Ventricle, Inferior Lateral Ventricle, Cerebellum White Matter, Cerebellum Cortex, Thalamus, Caudate, Putamen, Pallidum, Hippocampus, Amygdala, Lesion, Accumbens area, Vessel, Third Ventricle, Fourth Ventricle, Brain Stem, Cerebrospinal Fluid."
• https://surfer.nmr.mgh.harvard.edu/fswiki/recon-all
• to date, SynthSeg is used in favor of recon-all.

SynthStrip

Use the SynthStrip functionality within Freesurfer.

• Use SynthStrip, the command to remove the skull from the input scan.
• on the synthstrip website, e.g., mri_synthstrip --i input.nii.gz --o stripped.nii.gz --no-csf
• Processed 122 examples from the IXI dataset.

SynthSeg

Use the SynthSeg functionality within Freesurfer.

• Use SynthSeg, the command to recapitulate recon-all directly from the input scan with a neural network.
• on the synthseg website, e.g., mri_synthseg --i input.nii.gz --o segmented.nii.gz
• note that we cound indicies [2, 3, 7, 8, 10, 11, 12, 13, 16, 17, 18, 26, 28, 41, 42, 46, 47, 49, 50, 51, 52, 53, 54, 58, 60] as brain
• Processed 122 examples from the IXI dataset.

FSL

Install FSL.

Use the Brain Extraction Tool (Bet).

# RMU workflow
FSL: /usr/local/fsl/bin/bet  [input file] [output file] -f 0.3 -m -B -A

Use the FMRIB's Automated Segmentation Tool (FAST).

• Run FAST after performing skull stripping with either SynthStrip or FSL BET, e.g., fast -t 1 -n 3 -H 0.1 -I 4 -l 20.0 -o input_name output_name
• Processed 122 examples from the IXI dataset.

Segment Anything Model (SAM) and MedSAM

Reference: https://segment-anything.com/

• Assessment 2024-04-16

BU SCC - running segmentation software

Modules:

module load freesurfer/7.4.1
module load fsl/6.0.7.8

Input file: input_MRI.nii

Output files:

• SynthStrip without CSF:

mri_synthstrip -i input_MRI.nii -m input_MRI_synthsrip_mask.nii --no-csf

relevant output file: input_MRI_synthsrip_mask.nii

• SynthStrip + FAST:

mri_synthstrip -i input_MRI.nii -o input_MRI_synthstrip_brain.nii

fast -t 1 -n 3 -H 0.1 -I 4 -l 20.0 -o input_MRI_synthstrip_brain input_MRI_synthstrip_brain

relevant output file: input_MRI_synthsrip_brain_seg.nii.gz

• BET + FAST:

bet input_MRI input_MRI_bet_brain -f 0.5 -g 0

fast -t 1 -n 3 -H 0.1 -I 4 -l 20.0 -o input_MRI_bet_brain input_MRI_bet_brain

relevant output file: input_MRI_bet_brain_seg.nii.gz

• SynthSeg:

mri_synthseg --i input_MRI.nii --o input_MRI_mri_synthseg.nii

relevant output file: input_MRI_mri_synthseg.nii

122 examples from the IXI dataset have been run with this workflow.

Workflow

Run the test suite to assure the virtual environment and module work:

(.venv)  (main) chovey@mac/Users/chovey/autotwin/ensemble> pytest -v
================================================== test session starts ==================================================
platform darwin -- Python 3.10.11, pytest-8.1.1, pluggy-1.4.0 -- /Users/chovey/autotwin/ensemble/.venv/bin/python3.10
cachedir: .pytest_cache
rootdir: /Users/chovey/autotwin/ensemble
configfile: pyproject.toml
plugins: cov-5.0.0
collected 2 items                                                                                                       

tests/test_hello.py::test_hello PASSED                                  [ 50%]
tests/test_hello.py::test_adios PASSED                                  [100%]

Review the command line interface (CLI):

-----------------
autotwin.ensemble
-----------------

ensemble
    (this command)

process <pathfile>.yml
    Process the .yml input file.
    Example:
        process tests/files/getting_started.yml # TODO

pytest
    Runs the test suite (non-verbose option).

pytest -v
    Runs the test suite (verbose option).

validate <pathfile>.yml # TODO
    Validate the .yml input file against the module's schema.

version
    Prints the semantic version of the current installation.

Preliminary Results - IXI dataset

In the analysis folder we have one script for performaing the ensemble of results from the IXI dataset IXI_brain_ensemble.py and one script for plotting these results IXI_brain_ensemble_plot.py.

References

Slicer

• The RMU manual workflow user Slicer.
• RMU workflow