Last Update: "2024-07-10 10:57:26 ban"
- Introduction – what is FS2BV ?
- System requirements
- How to use FS2BV
- Importing FreeSurfer volume, surface, ROIs
- The other VOIs (the original ROI files are required to be downloaded separately)
- Importing FreeSurfer segmentation into BrainVoyager
- The other tools in the toolbox
- Acknowledgments
- License
- Citation of the FS2BV toolbox
- TODOs
The FS2BV toolbox is a collection of MATLAB functions for importing FreeSurfer anatomy volumes, cortical surfaces, and ROIs to BrainVoyager (BrainInnovation, Inc) as VMR, SRF, VOI, POI files (this toolbox is a part of our in-house BrainVoyager extensions. if some files are missing, I will add them to the repository asap). Some SPM/FSL ROI files can be also imported to BrainVoyager using the toolbox. Furthermore, BrainVoyager POIs can be exported as FreeSurfer Annotation files.For more details, please see the comments in each of the functions. Please also see VOI snapshots in ~/FS2BV/images.
The package is made publicly available in the hope of keeping our research group being transparent and open. Furthermore, the package is made open also for people who want to know our group's research activities, who want to join our group in the near future, and who want to learn how to create visual stimuli for vision science. Please feel free to contact us if you are interested in our research projects.
Links
Matlab The Mathworks
FreeSurfer FreeSurfer Wiki
BrainVoyager BrainInnovation
OS: Windows, Mac OSX, and Linux
- FS2BV works on all three OSs listed above, while it depends on some external utilities or toolboxes below.
Dependency
- UNIX command line tools: some utilitiess like gzip are required to extract *.nii.gz files etc. If you want to use the FS2BV toolbox functions on Windows, please additionally install UNIX command emulator, Cygwin or MSYS2, or a standalone gzip executable etc, and set the envitonmental path to the tools in advance.
- BrainVoyager's MATLAB tools, BVQX_tools: BVQX_tools_08d is recommended. NeuroElf may be compatible but not tested.
ref: neuroelf - freesurfer_matlab_tools: Matlab tools to read/write FreeSurfer files. In this toolbox, a bit modified version of the functions are included so that they are compatible with Windows OS.
ref: FreeSurfer matlab_tools
Please also read LICENSE_on_freesurfer_matlab_tools.txt. - geom3d: a library to handle and visualize 3D geometric primitives such as points, lines, planes, polyhedra... It provides low-level functions for manipulating 3D geometric primitives, making easier the development of more complex geometric algorithms.
ref: geom3d
Please set the MATLAB paths to ~/FS2BV/fs2bv and ~/FS2BV/freesurfer_matlab_tools.
In importing some ROIs (e.g. FSL ROIs to BrainVoyager), please work in each of the directory in ~/FS2BV/VOIs. A simple script for automatic importing is already prepared in each of the directory.
To import the ROIs defined outside BrainVoyager, the FS2BV toolbox provides several functions below.
ConvertNiftiRoi2BVvoi_ProbThres : Converts NII-format ROI probability map to BrainVoayer VOIs
with thresholding the map values
ConvertNiftiRoi2BVvoi_Labels : Converts NII-format ROI probability map to BrainVoayer VOIs
using the label lookuptable corresponding to the map ID
ExtractFSLroi : Extracts specific value(s) from NII based on XML database
ExtractFSLroiDirect : Extracts specific value(s) from NII directly for ROI generations
ConvertFSLroi2BVvoi : Converts FSL NII ROIs to BrainVoyager VOIs
ConvertSPMroi2BVvoi : Converts SPM NII ROIs to BrainVoyager VOIs
ConvertsAALroi2BVvoi : Converts SPM AAL antomical tempolate (NII) ROIs to BrainVoyager VOIs
ConvertFreeSurferAnnotation2BVpoi : Converts FreeSurfer surface annotations to BrainVoyager POIs
ConvertFreeSurferParcellation2BVvoi : Converts FreeSurfer MGZ parcellations to BrainVoyager VOIs
ConvertFreeSurferMGZ2VMR : Converts FreeSurer MGZ T1/ROI files to BrainVoayer VMRs
ConvertFreeSurferRibbon2BL2VMR : Converts FreeSurfer ribbon.mgz to BrainVoyager *_{LH|RH}_BL2.vmr
ConvertFreeSurferSurf2SRF : Converts FreeSurer surface files to BrainVoayer SRFs
ImportFreeSurfer2BrainVoyager : Imports FreeSurfer-processed files into BrainVoyager
MaskVMRbyFreeSurferSegmentation : for general masking purposes. Any *.mgz segmentation result can be used as a
mask (by default, the parameters are tuned to process wm.seg.mgz as a mask)
MaskVMRbyFreeSurferSegmentation_ribbon: Specific for applying a mask using the white (and gray) matter segmentation
result in ribbon.mgz.
Generally, for surface reconstructions, MaskVMRbyFreeSurferSegmentation_ribbon
gives the better results.
ConvertBVpoi2FreeSurferAnnotation : Converts BrainVoyager POIs to FreeSurfer Annotation files. We can further
generate label or volume ROI files from the generated annotation files using
FreeSurfer commands.
To find the VOIs in specific XYZs of TAL/MNI coords, please use the function below,
GetAreaNameFromAtlasVOI : Returns area candidates, in which the input XYZ coordinate(s)
is(are) belonging to, based on the pre-defined VOI atlases.
In these functions, for importing the FreeSurfer-preprocessed files into BrainVoyager, the wrapper function, ImportFreeSurfer2BrainVoyager, is prepared which makes all the file imports fully automatic.
The ImportFreeSurfer2BrainVoyager function especially uses
- ConvertFreeSurferMGZ2VMR for importing anatomy and auto segmentation files as VMRs
- ConvertFreeSurferSurf2SRF for importing surface files as SRFs
- ConvertFreeSurferParcellation2BVvoi for importing volume ROI files as VOIs
- ConvertFreeSurferAnnotation2BVpoi for importing surface ROI files as POIs
So please just call ImportFreeSurfer2BrainVoyager on MATLAB shell.
usage
function ImportFreeSurfer2BrainVoyager(fs_subj_dir,:do_flg)
(: is optinal)Example
>> fs_subj_dir='./freesurfer/subjects/DC';
>> do_flg=ones(1,5); % run all the importing procedures
>> ImportFreeSurfer2BrainVoyager(fs_subj_dir,do_flg);input
fs_subj_dir : FreeSurfer subject directory with a relative path format, in which
the origin of the path is the location where this function is called.
e.g. ../subjects/DC
do_flg : (optional) a [1 x 5] matrix. flags to decide whether running the
importing step listed below.
step 01: importing FreeSurfer anatomy files
step 02: importing FreeSurfer volume ROI files
step 03: importing FreeSurfer surface files
step 04: importing FreeSurfer surface ROI files
step 05: adding subject name prefix (e.g. HB_) at the head of each of files.
if each flag is set to 1, the importing procedure correspond to that step
is run. If some of the flags are set to 0, the corresponding procure(s)
will be skipped.
do_flg=[1,1,1,1,1]; by default.
output
no output variable
generated BrainVoyager-format files are stored in fs_subj_dir as
fs_subj_dir/BrainVoyager/(subj_name)/{vmr|srf|voi|poi}/*.{vmr|srf|voi|poi}
The FS2BV toolbox can also import the other ROI files defined for SPM and FSL into BrainVoyager. For importing, you can use one of
- ConvertNiftiRoi2BVvoi_ProbThres - ConvertNiftiRoi2BVvoi_Labels - ExtractFSLroi - ExtractFSLroiDirect - ConvertFSLroi2BVvoi - ConvertSPMroi2BVvoi - ConvertsAALroi2BVvoi
ROIs that can be imported to BrainVoyager and auto-conversion scripts Importing the ROI files listed below were already tested. For details, please see the contents ~/FS2BV/VOIs directory. In each of the subdirectories, simple script for the conversion is already stored. The original ROI files (e.g. *.nii) have to be downloaded by yourself from the links below.
about : SPM AAL/AAL2/AAL3 templates
ref : https://www.gin.cnrs.fr/en/tools/aal/
script: ~/FS2BV/VOIs/automated_anatomical_labeling_VOIs/aal/script_convert_AALnii2VOI.m
~/FS2BV/VOIs/automated_anatomical_labeling_VOIs/aal2/script_convert_AALnii2VOI.m
~/FS2BV/VOIs/automated_anatomical_labeling_VOIs/aal3/script_convert_AAL3nii2VOI.m
about : Activity atlas for object recognition ref : http://www.brainactivityatlas.org/atlas/atlas-download/ script: ~/FS2BV/VOIs/BAA_OR_VOIs/script_convert_BAAOAnii2VOI.m
about : Brainnetome Atlas ref : http://atlas.brainnetome.org/index.html script: ~/FS2BV/VOIs/Brainnetome_Atlas_VOIs/script_convert_nii2voi
about : Brodmann 48 Area Atlas, extracted from MRIcron
ref : http://people.cas.sc.edu/rorden/mricron/index.html
http://www.cabiatl.com/mricro/mricro/template.html
script: ~/FS2BV/VOIs/brodmann_VOIs/script_convert_BrodmannNII2VOIs.m
about : Cerebellum parcellation estimated by intrinsic functional connectivity ref : https://surfer.nmr.mgh.harvard.edu/fswiki/CerebellumParcellation_Buckner2011 script: ~/FS2BV/VOIs/Buckner_JNeurophysiol11_MNI152_VOIs/script_convert_nii2voi.m
about : Striatum parcellation estimated by intrinsic functional connectivity ref : http://surfer.nmr.mgh.harvard.edu/fswiki/StriatumParcellation_Choi2012 script: ~/FS2BV/VOIs/Choi_JNeurophysiol12_MNI152_VOIs/script_convert_nii2voi.m
about : Atlas for cortical network/connectivity analysis
ref : https://web.conn-toolbox.org/
script: ~/FS2BV/VOIs/CONN/script_convert_atlas_NII2VOIs.m
~/FS2BV/VOIs/CONN/script_convert_Brodmann_NII2VOIs.m
~/FS2BV/VOIs/CONN/script_convert_networks_NII2VOIs.m
about : FreeSurfer individual cortex parcellation ref : https://surfer.nmr.mgh.harvard.edu/ script: please use **ImportFreeSurfer2BrainVoyager** (please see the description above)
about : Templates and atlases included with FSL
ref : https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/Atlases
script: ~/FS2BV/VOIs/FSL_atlases_VOIs/script_FSL_ROI_conversion.m
please also see README.txt
about : The Human Connectome Project MMP1 atlas ref : https://osf.io/azup8 script: ~/FS2BV/VOIs/HCP_MMP1_VOIs/script_convert_HCP_MMP1_to_VOI.m
about : Probabilistic hMT+ atlas ref : http://www.brainactivityatlas.org/atlas/atlas-download/ script: ~/FS2BV/VOIs/MT_atlases_VOIs/script_convert_MTnii2VOI.m
about : Probabilistic Maps of Visual Topography in Human Cortex
ref : http://scholar.princeton.edu/napl/resources
script: ~/FS2BV/VOIs/ProbAtlas_v4_VOIs/script_convert_Wang_maxprob_ROIs2VOIs.m
~/FS2BV/VOIs/ProbAtlas_v4_VOIs/script_convert_Wang_probability_ROIs2VOIs.m
about : Functional Brain Atlas from Finn/Shen et al Nature Neuro 2015, from NeuroElf package.
ref : https://www.nitrc.org/frs/?group_id=51
http://neuroelf.net/
script: ~/FS2BV/VOIs/shenparcel_VOIs/script_convert_TAL2MNI_VOI.m
about : Examples on how to make spherical VOIs whose centers are located on specific TAL/MNI coords
ref : no reference
script: ~/FS2BV/VOIs/Spheric_VOIs/script_generate_MNI_VOIs.m
~/FS2BV/VOIs/Spheric_VOIs/script_generate_TAL_VOIs.m
about : Official Talairach segmentation. Talairach.nii is a NIfTI image that contains the Talairach label data ref : http://www.talairach.org/ script: ~/FS2BV/VOIs/Talairach.org_VOIs/script_convert_NII2VOI.m
about : Cortical Parcellation Estimated by Intrinsic Functional Connectivity ref : http://surfer.nmr.mgh.harvard.edu/fswiki/CorticalParcellation_Yeo2011 script: ~/FS2BV/VOIs/Yeo_JNeurophysiol11_MNI152_VOIs/script_convert_nii2voi.m
You can also import the FreeSurfer recon_all's segmentation output (ribbon.mgz, wm.seg.mgz etc) into BrainVoygaer for masking VMR anatomy files.
Please use one of these functions.
MaskVMRbyFreeSurferSegmentation : for general masking purposes. Any *.mgz segmentation result can be used as a
mask (by default, the parameters are tuned to process wm.seg.mgz as a mask)
MaskVMRbyFreeSurferSegmentation_ribbon: Specific for applying a mask using the white (and gray) matter segmentation
result in ribbon.mgz.
Generally, for surface reconstructions, MaskVMRbyFreeSurferSegmentation_ribbon
gives the better results.
Procedures of masking a VMR using FreeSurfer files
The steps required to mask the BrainVoyager VMR anatomy file with the FreeSurfer output, such as ribbon.mgz are as below.
- Adjusting contrast and brightness of the ribbon.mgz so that the mean grayscale value of the white matter region is around 180.
- Transforming from the default FreeSurfer coordinate into the BrainVoyager SAG coordinate, and generating ribbon.vmr.
- Coregistration of FreeSurfer segmentation VMR to the input BrainVoyager VMR.
Note: Even when you are using exactly the same anatomy volume datasets, this coregistration step is required since FreeSurfer seems to adjut the orgin (center) of the volume in segmentation procedure. Therefore, the imported FreeSurfer VMR and the corresponding BrainVoyager VMR are displaced. - (Finally) Masking the white (and gray) matter region of the target VMR with the FreeSurfer segmentation file.
Step 00: preparation
Firstly, before running the function, please organize data structgure: Please copy FreeSurfer wm.seg.mgz and ribbon.mgz to the same directory where the target VMR anatomy file you are going to mask is placed. Here, as an example, let's assume that we are having
In the directory, ~/fMRI_data/HB/3d/ (a relative-path format)
- hb21_001.3d_ACPC.vmr -- BrainVoyager anatomy file, ACPC file is recommended while the native-space VMR is also accepted.
- wm.seg.mgz -- segmented white matter, used for the coregistration, originally stored as $FREESURFER_SUBJECT_DIR/(subj)/mri/wm.seg.mgz
- ribbon.mgz -- segmented gray/white matters, used for the masking, originally stored as $FREESURFER_SUBJECT_DIR/(subj)/mri/ribbon.mgz
Step 01: run the function, MaskVMRbyFreeSurferSegmentation_ribbon
Then, on the MATLAB shell, please run the command below.
>> % please specify all the input variables in the relative path format
>> % usage: MaskVMRbyFreeSurferSegmentation_ribbon(vmr_file,:freesurfer_ribbon_file,...
>> % :freesurfer_wm_seg_file,:include_gray_flg,:flip_flg,:vmr_framingcube)
>> % (: is optional)
>> % note: if empty value is set to ribbon_file and wm_seg_file, the function tries to find
>> % them in the target vmr_file directory.
>>
>> MaskVMRbyFreeSurferSegmentation_ribbon('/fMRI_data/HB/3d/hb21_001.3d_ACPC.vmr',[],[],1,1,256);
>> % then, please follow the instructions of the functionStep 02: coregistration of FreeSurfer wm.seg.vmr to the target BrainVoyager VMR file
In the middle of the MaskVMRbyFreeSurferSegmentation_ribbon processing, the function asks to coregist the wm.seg.vmr (wm.seg.mgz is converted to wm.seg.vmr and stored in the same directory with wm.seg.mgz by the function) to the target BrainVoyager VMR (e.g. hb21_001.3d_ACPC.vmr). At this stage, the MATLAB shell turns to the "waiting" mode. Then, please just leave the MATLAB shell as it is, follow the procedures below,
- Please launch BrainVoyager.
- Please load wm.seg.vmr (not wm.seg.), which is to be coregistered.
- Please select "Volumes" --> "3D volume tools" --> "Coregitration" tab --> "VMR-VMR coregistration" --> "Select VMR." Then, please select the target hb21_001.3d_ACPC.vmr as the destination anatomy.
- Please run the coregistration by selecting "Volumes" --> "3D volume tools" --> "Coregitration" tab --> "VMR-VMR coregistration" --> "Align."
- You will get the transformation file, like "wm.seg-TO-hb21_001.3d_ACPC.trf"
After these steps, please go back to the MATLAB shell and please press "F5" or please type
>> dbcontto proceed. Then, the rest of the procedures will be automatically carried on and you will get the final output, hb21_001.3d_ACPC_masked.vmr.
Step 03: Segmentation in BrainVoyager
For the masked VMR, hb21_001.3d_ACPC_masked.vmr, you can apply the BrainVoyager's standard segmentation and cortical reconstruction processing. The segmentation performance may be improved in some cases. If you need to apply TAL/MNI transformation, please apply it before the cortical reconstruction (in transformation, any interpolation (nearest-neighbor, trilinear interpolation, etc) would work finely).
Finally, if you want to simply import the FreeSurfer segmentation results, including the cortical surface reconstructed in FreeSurfer, without changing any vertex IDs etc (this matching is sometimes required, for instance, in exporting BrainVoyager-defined POI to FreeSurfer Annotation etc.), please use ImportFreeSurfer2BrainVoyager, rather than importing only the wm.seg.mgz and ribbon.mgz files. For details, please see the Importing FreeSurfer volume, surface, ROIs section.
COMING SOON...
The FS2BV toolbox has been developed to import ROIs defined for FreeSurfer/SPM/FSL on BrainVoyager to compare our fMRI results with the other studies.
We would like to express our deepest gratitude to all the researchers who made their own findings as the ROIs available to the public free of charge.
Also, the core of the tool were built on the great MATLAB tool to handle BrainVoyager data, BVQX_tools. For details, please see the links below. We also express our gratitude to the developers of the tool.
BVQX_tools (now NeuroElf) : MATLAB tools for handling BrainVoyager files and datasets
NeurElf website: https://neuroelf.net/
BVQX_tools release note: https://support.brainvoyager.com/brainvoyager/available-tools/88-matlab-tools-bvxqtools/361-release-notes-neuroelf-bvqxtools
BVQX_tools history: https://support.brainvoyager.com/brainvoyager/available-tools/88-matlab-tools-bvxqtools/362-history-of-neuroelf-bvqxtools
The toolbox is distributed under the BSD license described below.
FS2BV --- MATLAB tools for importing FreeSurfer anatomy volumes and cortical surfaces, and FreeSurfer/SPM/FSL ROIs into BrainVoyager. Copyright (c) 2021, Hiroshi Ban, All rights reserved.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
* Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
* Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in
the documentation and/or other materials provided with the distribution
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
The views and conclusions contained in the software and documentation are those of the authors and should not be interpreted as representing official policies, either expressed or implied, of the FreeBSD Project.
Please also read the license terms on
- freesurfer_matlab_tools: LICENSE_on_freesurfer_matlab_tools.txt.
- geom3d tool: license.txt
IMPORTANT: If you use some of the imported VOIs in your studies, please put the first priority to cite the original authors' papers and the software packages rather than citing the FS2BV tool.
Even after that, if you still have some space in your reference section, please cite this GitHub repository like,
FS2BV toolbox: https://github.com/hiroshiban/FS2BV
by Hiroshi Ban
If you have no space, please cite it somewhere someday next time. Thank you so much.
- Adding some more VOI conversion scripts.
- Compiling *.m files using the MATLAB compiler so that we can provide a standalone verion of the FS2BV package.
- Make the tool be compatible with NeuroElf as well as BVQX_tools.