BURNING ATLAS STRUCTURES INTO PATIENT SCANS
Requirements
Lead-DBS (v>=2.6) (https://netstim.gitbook.io/leaddbs)
Karawun (https://developmentalimagingmcri.github.io/karawun/)
Rosetta 2 if you use a Mac computer with Apple Silicon chip (³M1) (installation guide below)
FSL-FMRIB Software Library (https://fsl.fmrib.ox.ac.uk/fsl/docs/#/install/index)
BML_burn_script2.py (Lead-DBS v2.6)
BML_burn_script3.py (Lead-DBS >v3.1)
Setup:
The app Lead-DBS1 is the main application of the Lead suite. It allows the reconstruction of electrodes for one patient or a batch of patients. Lead-DBS constitutes the backbone of the burning pipeline and leverages the transformation matrix generated during normalization to convert imaging resources (e.g., atlas structures) generated in normative (MNI ICBM 152 2009b Nonlinear Asymmetric) space into patient-specific native space. Normalization entails the non-linear transformation of patient-specific scans into MNI space, which is inherently associated with errors, as we are trying to fit the individual anatomy of a patient to a normative template. The Lead-DBS algorithms are optimized to minimize these errors within the subcortex enabling an accurate mapping of basal ganglia and thalamus. Depending on the imaging quality, the extent of anatomical variability, and morphological changes, however, the degree of error may vary, and it is crucial to understand when the transformation can be trusted and when not! It is imperative to visually inspect the normalization results and evaluate deviations between the MNI template and the patient-specific scan that was warped into MNI space. Lead-DBS contains tools that allow the manual refinement of transformations based on visual inspection. Specifically, WarpDrive2 was developed for fine manual adjustments to better match, for example, an atlas delineating the subthalamic nucleus with the patient-specific nucleus. Anyone intending to use the pipeline presented here is advised to familiarize themselves with Lead-DBS, the limitations of normalizations, and Warpdrive prior to applying the burning pipeline!
This pipeline assumes the user’s familiarity with Lead-DBS. If the user is not familiar with the toolbox, they can refer to the Lead-DBS User Guide to get started (https://netstim.gitbook.io/leaddbs). The User Guide provides a step-by-step instruction to import, coregister, and normalize patient scans and gives an overview of quality control steps that can be used to verify accurate execution of each step. An overview of WarpDrive can be found here: https://github.com/netstim/SlicerNetstim/tree/master/WarpDrive.
How to install Karawun on any computer that is not Apple Silicon chip
If you are not using a Mac computer, Karawun can be installed using the following installation guide: https://github.com/DevelopmentalImagingMCRI/karawun.
How to install Karawun on a Mac computer with Apple Silicon chip
On a Mac computer with Apple Silicon, Rosetta 2 is necessary to install Karawun. To install Rosetta 2, use the following command in Terminal:
/usr/sbin/softwareupdate --install-rosetta
You will then need to create a Rosetta version of Terminal. This involves duplicating the Terminal application and changing the settings so it opens using Rosetta:
-
Go to the “Applications” folder on finder, then navigate to the “Utilities” subsection
-
Find the terminal application. Duplicate it by right clicking and selecting “Duplicate”
-
Rename the duplicated application as “Terminal_Rosetta”
-
Right click on the newly created “Terminal_Rosetta” and go to “get info”
-
Check the box that says “Open using Rosetta”
-
Close the “get info” and open the “Terminal_Rosetta” application
-
In this new terminal, create a new environment with Intel-based Python:
-
CONDA_SUBDIR=osx-64 conda create -n intel_env python=3.9
-
conda activate KarawunEnv
-
-
Install Karawun:
-
pip install karawun
-
-
Test the installation by running:
-
importTractography -h
-
In the future, you can enter the intel environment by running: conda activate KarawunEnv from any terminal, and test that Karawun is working by running importTractography -h
Lead-DBS
To perform burning of imaging resources from MNI space into native space, the transformation matrix indicating the mapping of each voxel from native to MNI space needs to be generated. To achieve this, follow the initial steps in the Lead-DBS User Guide (https://netstim.gitbook.io/leaddbs). Lead-DBS generally assumes that a postoperative CT or MRI scan is provided, however, the pipeline can also be run without defining this modality. Given that no postoperative image has been defined you will not be able to proceed with the pipeline after normalization. This means that steps such as brainshift correction will not be performed as they depend on a postoperative scan.
After finishing normalization, visual inspection, and adjustment of the transformation using WarpDrive, we need to perform the transformation of atlas resources in MNI space to native space. To achieve this, load the patient folder in the Lead-DBS GUI and then go to ‘Tools’ -> ‘Map file from template to anchor space’ -> ‘Run…’ (Figure 1).
​
Figure 1: Conversion of imaging resources from MNI space into native space using Lead-DBS v2.6 and v3.1.
This will open a new window that prompts you to select the imaging resources (e.g., atlases) that you would like to convert from MNI space into native space. Atlas files can be obtained from the Lead-DBS subfolder /leaddbs/templates/space/MNI_ICBM_2009b_NLIN_ASYM/atlases/. Click on the atlas of interest e.g., ‘Thomas Atlas (Saranathan 2019)/lh/’ and select the atlas structures in nii format that you would like to convert. You can select files individually by clicking on a single nii file or select multiple nii files to be converted into native space. Note that the current workflow supports the conversion of a maximum of six nii files. Following selection of nii files click ‘open’. This will prompt Lead-DBS to apply the generated transformation matrix to map the selected structures into native space. If transformation was performed correctly, you should find one or multiple files (if more than one nii file was selected) labeled w*.nii.gz in the patient folder in Lead-DBS v2.6 or one or multiple files (if more than one nii file was selected) labeled *Native.nii.gz in the current working directory as defined in Matlab in Lead-DBS >v3.1. In Lead-DBS >v3.1 you need to copy these files into the folder derivatives/sub-PatientID/coregistration/anat to proceed. Once you have confirmed that the files exist in the correct patient directory (Figure 2) Lead-DBS can be closed.
Figure 2: Content of patient folder after conversion of normative resources into native space. In the featured example, three atlas parcellations were converted from MNI space into native space. Left: Lead-DBS v2.6, Right: Lead-DBS >v3.1
Burning of Atlas Structures
The final step of the protocol entails the agregation of native atlas structures, burning of atlas structures into the native T1 scan, and conversion of the burned T1 scan from nii to dicom format. All these steps are handled by BML_burn_script.py.
If you used Lead-DBS v2.6 for preprocessing proceed here:
If you processed the patient using Lead-DBS v2.6, copy a single DICOM image from the PatientID/DICOM folder (Lead-DBS v2.6) into the PatientID folder (Figure 3) and rename the single DICOM image to ‘dummy00001.dcm’ (Figure 3 left). Open a terminal and access the environment, which contains the Karawun installation. Cd into the PatientID/ folder and execute BML_burn_script2.py as shown in Figure 4.
If you used Lead-DBS >v3.1 for preprocessing proceed here:
If you processed the patient using Lead-DBS >v3.1, copy a single DICOM image from /sourcedata/sub-PatientID/DICOM/ into the derivatives/sub-PatientID/coregistration/anat folder and rename the single DICOM image to ‘dummy00001.dcm’ (Figure 3 right). Open a terminal and access the environment, which contains the Karawun installation. Cd into the derivatives/sub-PatientID/coregistration/anat folder and execute BML_burn_script3.py as shown in Figure 4.
Figure 3: A single DICOM image was copied into the Lead-DBS folder. Left: Lead-DBS v2.6, Right: Lead-DBS >v3.1
Figure 4: Terminal prompts to execute BML_burn_script2.py in Lead-DBS v2.6 (left) and BML_burn_script3.py in Lead-DBS >v3.1 (right).
Final steps: After executing the script a new folder called burn_nuclei will been generated, which contains the DICOM files with the burned imaging resources. Running the script should take <5 minutes. These DICOM files can be exported.
Questions
If you are running into any issues with the installation of the required libraries or the execution of the scripts, please reach out to the Brain Modulation Lab: cneudorfer@mgh.harvard.edu. We are happy to help you sort out any issues!
References
1. Neudorfer C, Butenko K, Oxenford S, et al. Lead-DBS v3.0: Mapping deep brain stimulation effects to local anatomy and global networks. NeuroImage. 2023;268:119862. doi:10.1016/j.neuroimage.2023.119862
2. Oxenford S, Ríos AS, Hollunder B, et al. WarpDrive: Improving spatial normalization using manual refinements. Med Image Anal. 2024;91:103041. doi:10.1016/j.media.2023.103041