BARSTOOLRV Brain Extraction and Segmentation - dwong263/MAGIQ GitHub Wiki
Note: Document unfinished. Currently being written!
This tab allows you to skull-strip your reference anatomical images, produce a three-dimensional mask image representing the spectroscopy voxel, and produce a binary segmentation of CSF versus tissue. Different skull-stripping tools are used for acquisitions from the Varian small animal scanners and acquisitions from the Bruker small animal scanners. This is why there are two sub-tabs, one named "Varian" and another named "Bruker" ().
For Varian datasets, BARSTOOL-RV uses the Robust Automatic Rodent Brain Extraction method, which uses 3-D pulse-coupled neural networks.
The code for this method that is provided by the authors is written in MATLAB. This code used to be available on their website, but that URL appears to be broken now. As a result, this code is now provided as part of MAGIQ in the barstoolrv/tools/PCNN3D_matlab/
folder. The authors of MAGIQ cannot guarantee that this included code is entirely bug-free or is the latest version of the code available.
Because this is MATLAB code, it is called by BARSTOOL-RV using the MATLAB Engine API for Python. You will need to make sure you have correctly installed the MATLAB Engine API for Python first. The PCNN3D code also relies on NIfTI Tools, which is available on MATLAB File Exchange. Make sure both PCNN3D_matlab and NIfTI Tools are on your MATLAB path.
To use this method, BARSTOOL-RV calls a helper MATLAB function called runPCNN3D.m
located in the barstoolrv/
folder, passing the file path of the image to be skull-stripped to this function. Within this helper function are a couple parameters that you may want to alter. The lines of code that define these parameters are shown below:
BrSize=[350,550]; % brain size range for mouse (mm3). If you use 10x data, this should be 10x too
%BrSize=[1200,4400]; % brain size range for RAT (mm3)
StrucRadius=5; % use =3 for low resolution
-
BrSize
is a parameter that describes the expected range the volume of the brain being skull-stripped should fall into. If your image is of a mouse, setBrSize=[350,550]
. If your image is of a rat brain, setBrSize=[1200, 4400]
. The number of iterations that the PCNN3D algorithm requires to determine the final brain mask is determined in part by this volume range. - This method makes use of a weighting matrix, which is a normalized 3-D Gaussian function with FWHM = 0.5, with the peak at the center of the brain volume and radius r.
StrucRadius
is equal to this r. Read the paper for more details. SetStrucRadius=5
for high resolution images, andStrucRadius=3
for low resolution images.
Edit the helper function code directly to change these parameters.
For Bruker datasets, BARSTOOL-RV uses the RATS skull-stripping method from The Iowa Institute for Biomedical Imaging. This method is provided by the authors as a binary that may be called from the command line. As such, no additional software prerequisites are needed. BARSTOOL-RV provides a GUI for this command line tool.
First select the directories that contain your image acquisition by clicking the Select Mouse Directories button. You may select multiple directories.
Currently, BARSTOOL-RV expects an anatomical image acquired using the 2D fast-spin echo sequence called fse2D.img
to be present within the selected directories. Note that fse2D.img
is not a file, but rather a folder as Varian stores image acquisitions in a .img
folder that contains .fdf
files. The .fdf
files themselves contain the image data. For example, if a fast spin-echo sequence was used to acquire an anatomical brain image from a mouse called a2_9m
, then the directory may look something like this:
data/
├── results/
│ ├── a2_9m/
│ │ ├── fse2D.img/
│ │ │ ├── procpar
│ │ │ ├── slice001image001echo001.fdf
│ │ │ ├── slice002image001echo001.fdf
│ │ │ ├── ...
Next specify the matrix size of your images. These are the x, y, z dimensions of your images. BARSTOOL-RV assumes that all images you selected are acquired using the same matrix size.
Then, specify your image type. Currently, BARSTOOL-RV only supports anatomical images acquired using the 2D fast-spin echo sequence.
Finally, convert all selected FDF images to NIfTI images by clicking the Convert FDF Images to NIFTI button. BARSTOOL-RV will produce a fse2d.nii.gz
within each selected directory. This image may be opened and visualized in fsleyes
.
Click the Run Voxel Alignment button to generate a three-dimensional mask image representing the spectroscopy voxel for each selected dataset. This will produce a file called mrsvoxel.nii.gz
within each selected directory. mrsvoxel.nii.gz
is spatially aligned with fse2D.nii.gz
and may be overlaid together in fsleyes
to visualize the placement of the spectroscopy voxel.
Note that for this step, BARSTOOL-RV expects the full (metabolite + macromolecule) acquisition (metab.fid
) or the water-unsuppressed acquisition (water.fid
) to be present in the selected directories. Also note that metab.fid
and water.fid
are not files, but are rather folders as Varian stores spectroscopy acquisitions in a .fid
folder that contains a fid
file and a procpar
file. The fid
file contain the spectroscopy data, while the procpar
file contains information about the acquisition.
For example, if a full (metabolite + macromolecule) spectroscopy acquisition was performed on a mouse called a2_9m
, then the directory may look something like this:
data/
├── results/
│ ├── a2_9m/
│ │ ├── metab.fid/
│ │ │ ├── procpar
│ │ │ ├── fid
│ │ │ ├── text
Click the Run Brain Extraction button to skull-strip the anatomical image. Ensure you have edited the helper function to have the appropriate parameters.
Click the Run Tissue / CSF Extraction button to isolate the
First, select the directories that contain your image acquisition by clicking the Select Mouse Directories button. You may only select one directory.
For Bruker datasets, BARSTOOL-RV expects an anatomical image in *.nii.gz
format, with the name of the file identical to the folder name. For example, if a Bruker dataset is called "BrownRat2_20190627_1", then the anatomical image should be located within the "BrownRat2_20190627_1" folder should be called "BrownRat2_20190627_1.nii.gz".
data/
├── results/
│ ├── BrownRat2_20190627_1/
│ │ ├── sup/
│ │ ├── uns/
│ │ ├── BrownRat2_20190627_1.nii.gz
For Bruker data, BARSTOOL-RV uses the RATS skull-stripping method from The Iowa Institute for Biomedical Imaging. Please refer to the associated paper for a more in depth description of the parameters. In brief, the parameters are as follows:
Parameter | Description | Default |
---|---|---|
k | Approximate number of voxels that separate brain and skull. | 2 |
t | Intensity threshold. Usually set to the mean intensity of the image. Note that this parameter is not yet changeable. |
10 |
v | Volume threshold. Usually set to 1650 mm3 for rats and 380 mm3 for mice. | 1650 |
Hit the Run Brain Extraction button to run the brain extraction. BARSTOOL-RV will produce a *_brain.nii.gz
containing the brain extracted image within the Bruker data directory. BARSTOOL-RV will also produce a *_mask.nii.gz
containing the corresponding brain mask image. Using the example above ("BrownRat2_20190627_1"), a completed brain extraction will result in:
data/
├── results/
│ ├── BrownRat2_20190627_1/
│ │ ├── sup/
│ │ ├── uns/
│ │ ├── BrownRat2_20190627_1.nii.gz
│ │ ├── BrownRat2_20190627_1_brain.nii.gz
│ │ ├── BrownRat2_20190627_1_mask.nii.gz
Next, hit the Run Voxel Alignment button to generate a three-dimensional mask image representing the spectroscopy voxel for the selected dataset. This will produce a *_voxel_overlay.nii.gz
file containing this image. *_voxel_overlay.nii.gz
is spatially aligned with *_brain.nii.gz
and may be overlaid together in fsleyes to visualize the placement of the spectroscopy voxel.
Using the example above ("BrownRat2_20190627_1"), a completed voxel alignment extraction will result in:
data/
├── results/
│ ├── BrownRat2_20190627_1/
│ │ ├── sup/
│ │ ├── uns/
│ │ ├── BrownRat2_20190627_1.nii.gz
│ │ ├── BrownRat2_20190627_1_brain.nii.gz
│ │ ├── BrownRat2_20190627_1_mask.nii.gz
│ │ ├── BrownRat2_20190627_1_voxel_overlay.nii.gz