fw-gear-freesurferator 0.2.0

No project description provided

freesurferator: create anatomical ROIs for DWI, fMRI, PET... in subject space

Overview

Summary

This gear takes either an existing FreeSurfer zipped run, or an anatomical NIfTI file and performs all of the FreeSurfer cortical reconstruction process. Outputs are provided in a zip file and include the entire output directory tree from recon-all. Configuration options exist for setting the subject ID and for converting outputs to NIfTI, and CSV. FreeSurfer is a software package for the analysis and visualization of structural and functional neuroimaging data from cross-sectional or longitudinal studies. It is developed by the Laboratory for Computational Neuroimaging at the Athinoula A. Martinos Center for Biomedical Imaging. Please see https://surfer.nmr.mgh.harvard.edu/fswiki/FreeSurferSoftwareLicense for license information. Additionally, this gear includes a bunch of atlases included (cerebellum, HCP, Neuropythy...) and user created ROIs in surface (fsaverage) or volumetric (MNI) space can be provided. Depending on the configuration options it will create ROIs in subject space that can later be incorporated to other neuroimaging tools (PETsurfer, RTP2 DWI pipeline...)

Cite

For citation information, please visit: https://www.biorxiv.org/content/10.1101/2022.03.17.484761v1 License: Other

Classification

Category: analysis

Gear Level:

• Project
• Subject
• Session
• Acquisition
• Analysis

---

[[TOC]]

---

Inputs

• anat

  • Name: anat
  • Type: nifti
  • Optional: false
  • Classification: **
  • Description: Anatomical NIfTI file.
  • Notes: **

• pre_fs

  • Name: pre_fs
  • Type: zip
  • Optional: true
  • Classification: **
  • Description: ZIP file with a full freesurfer run
  • Notes: **

• control_points

  • Name: control_points
  • Type: dat
  • Optional: true
  • Classification: **
  • Description: Text file with the control points created in Freeview. You can find them in the tmp/ folder once you create them in Freeview. If there is a control points file and it is correct, Freesurfer will use them. Be careful to add the proper recon-all call. The file name needs to be named control.dat, and you need to copy it from the tmp/ folder, if it is not the case, the gear will fail.
  • Notes: **

• mniroizip

  • Name: mniroizip
  • Type: zip
  • Optional: true
  • Classification: **
  • Description: ZIP file with ROIs in MNI space. If this zip exists (no folder names, all ROIs in base folder after unzipping), the ROIs will be converted to individual subject space. The ROIs need to be in FSL's 1mm isotropic MNI template space. Please check with mri_info (Freesurfer) or mrinfo (MRtrix) or an equivalent software that your ROI and the template are exactly in the same space. The ROIs should be composed of 0-s and 1-s. For downloading an example an several ROIs, please check https://osf.io/download/m6b7r
  • Notes: **

• annotfile

  • Name: annotfile
  • Type: zip
  • Optional: true
  • Classification: **
  • Description: zip with annot files in fsaverage space. Create surface ROIs in fsaverage and save them as annots and them zip them, the system will create cortical volumetric independent ROIs in subject space
  • Notes: **

• t1w_anatomical_2

  • Name: t1w_anatomical_2
  • Type: nifti
  • Optional: true
  • Classification: **
  • Description: Additional anatomical NIfTI file
  • Notes: **

• t1w_anatomical_3

  • Name: t1w_anatomical_3
  • Type: nifti
  • Optional: true
  • Classification: **
  • Description: Additional anatomical NIfTI file
  • Notes: **

• t1w_anatomical_4

  • Name: t1w_anatomical_4
  • Type: nifti
  • Optional: true
  • Classification: **
  • Description: Additional anatomical NIfTI file
  • Notes: **

• t1w_anatomical_5

  • Name: t1w_anatomical_5
  • Type: nifti
  • Optional: true
  • Classification: **
  • Description: Additional anatomical NIfTI file
  • Notes: **

• freesurfer_license_file

  • Name: freesurfer_license_file
  • Type: file
  • Optional: true
  • Classification: {Based on "inputs.Input-File.base"}
  • Description: FreeSurfer license file, provided during registration with FreeSurfer. This file will be copied to the $FSHOME directory and used during execution of the Gear.
  • Notes: **

• t2w_anatomical

  • Name: t2w_anatomical
  • Type: nifti
  • Optional: true
  • Classification: **
  • Description: T2w Anatomical NIfTI file
  • Notes: **

Config

• subject_id

  • Name: subject_id
  • Type: string
  • Description: Desired subject ID. Any spaces in the subject_id will be replaced with underscores and will be used to name the resulting FreeSurfer output directory. NOTE: If using a previous Gear output as input the subject code will be parsed from the input archive, however it should still be provided here for good measure.
  • Default: Sxxx

• reconall_options

  • Name: reconall_options
  • Type: string
  • Description: Command line options to the recon-all algorithm. (Default=-all -qcache. -all runs the entire pipeline and -qcache will resample data onto the average subject (called fsaverage) and smooth it at various full-width/half-max (FWHM) values, usually 0, 5, 10, 15, 20, and 25mm, which can speed later processing.) Note that modification of these options may result in failure if the options are not recognized. Note: if the optional file control_points are included, then it will write it in the tmp/ folder and it will re-reun it with the options set up in this field. For example, if control points are added for intensity correction, then -autorecon2-cp and -autorecon3 will be expected here instead of -all.
  • Default: -all -qcache

• hippocampal_subfields

  • Name: hippocampal_subfields
  • Type: boolean
  • Description: Generates an automated segmentation of the hippocampal subfields based on a statistical atlas built primarily upon ultra-high resolution (~0.1 mm isotropic) ex vivo MRI data. Choosing this option will write <subject_id>_HippocampalSubfields.csv to the final results. See: https://surfer.nmr.mgh.harvard.edu/fswiki/HippocampalSubfields for more info. (Default=false)
  • Default: false

• brainstem_structures

  • Name: brainstem_structures
  • Type: boolean
  • Description: Generate automated segmentation of four different brainstem structures from the input T1 scan: medulla oblongata, pons, midbrain and superior cerebellar peduncle (SCP). We use a Bayesian segmentation algorithm that relies on a probabilistic atlas of the brainstem (and neighboring brain structures) built upon manual delineations of the structures on interest in 49 scans (10 for the brainstem structures, 39 for the surrounding structures). The delineation protocol for the brainstem was designed by Dr. Adam Boxer and his team at the UCSF Memory and Aging Center, and is described in the paper. Choosing this option will write <subject_id>_BrainstemStructures.csv to the final results. See: https://surfer.nmr.mgh.harvard.edu/fswiki/BrainstemSubstructures for more info. (Default=false)
  • Default: false

• thalamic_nuclei

  • Name: thalamic_nuclei
  • Type: boolean
  • Description: Generate parcellation of the thalamus into 25 different nuclei, using a probabilistic atlas built with histological data. The parcellation is based on structural MRI, either the main T1 scan processed through recon-all, or an additional scan of a different modality, which potentially shows better contrast between the nuclei. Choosing this option will write <subject_id>_thalamic-nuclei.lh.v10.T1.csv and <subject_id>_thalamic-nuclei.rh.v10.T1.stats.csv to the final results. See: https://surfer.nmr.mgh.harvard.edu/fswiki/ThalamicNuclei for more info. (Default=false)
  • Default: false

• cerebellum

  • Name: cerebellum
  • Type: boolean
  • Description: bring CerebellumParcellation-Bucker2011 (17Networks LooseMask) into native space, and generate separate image files for each volume
  • Default: false

• hcp

  • Name: hcp
  • Type: boolean
  • Description: bring MNI_Glasser_HCP into native space, and generate separate image files for each volume.
  • Default: false

• mni_rois

  • Name: mni_rois
  • Type: boolean
  • Description: Bring MNI ROIs such as MNI_JHU_tracts_ROIs, custom created and other ROIs into native space. If no mniroizip input is passed and this is set to True, it will use the default Mori ROIs, CC ROIs and some other (such as eyes or the mOTS and pOTS VWFAs). Download the zip from the Freesurferator repo or check the README for more information. If this is set to True and a mniroizip input is passed, then both will be added and converted to subject's space. If it is set to False and mniroizip is passed only those MNI ROIs will be converted.
  • Default: false

• aparc2009

  • Name: aparc2009
  • Type: boolean
  • Description: separate the aparc.a2009 from freesurfer to individual images for each segment
  • Default: false

• rois_in_output

  • Name: rois_in_output
  • Type: boolean
  • Description: Depending on the selection there can be hundreds of ROIs, therefore they will be all zipped in the fs.zip archive in the /ROIs folder. In some cases (few ROIs, debugging) it might be of interest having the ROIs in the output. Default is false.
  • Default: false

• neuropythy_analysis

  • Name: neuropythy_analysis
  • Type: boolean
  • Description: Perform a neuropythy analysis. See: https://github.com/noahbenson/neuropythy for more info. (Default=false)
  • Default: false

• run_gtmseg

  • Name: run_gtmseg
  • Type: boolean
  • Description: Run gtmseg, it is a step required for PETsurfer. By default, is false.
  • Default: false

• force_ants

  • Name: force_ants
  • Type: boolean
  • Description: Ants will be automatically done depending on what segmentations are asked. If this options is set to true, ANTs will be run regardless of those options. Default=false
  • Default: false

• freesurfer_license_key

  • Name: freesurfer_license_key
  • Type: string
  • Description: Text from license file generated during FreeSurfer registration. Entries should be space separated. Usually this should be added at the project level and it will be read from there.
  • Default: **

Outputs

Files

• freesurferator_<subject_id>_.zip

  • Name: freesurferator_<subject_id>_.zip
  • Type: zip
  • Optional: false
  • Classification: zip
  • Description: Freesurfer's complete output, zipped
  • Notes: **

• fs.zip

  • Name: fs.zip
  • Type: zip
  • Optional: false
  • Classification: zip
  • Description: All ROIs in subject space, that can be used in other analyses. On top of that, it contains T1w file, the MNI template and other files.
  • Notes: **

• T1.nii.gz

  • Name: T1.nii.gz
  • Type: nifti
  • Optional: false
  • Classification: nifti
  • Description: T1w image, from Freesurfer's output
  • Notes: **

There are other files in the output, but most of them depend on the config options. They should be auto-explicative.

Metadata

This gear does not generate metadata

Pre-requisites

It has no prerequisites, more than having a nifti file

Prerequisite Gear Runs

A list of gears, in the order they need to be run:

1. __dcm2niix
   • Level: Acquisition

Prerequisite Files

A list of any files (OTHER than those specified by the input) that the gear will need. If possible, list as many specific files as you can:

None

Prerequisite Metadata

A description of any metadata that is needed for the gear to run. If possible, list as many specific metadata objects that are required:

None

Usage

This gear is used directly or as a Gear Rule. It has only one required file, the T1w. This is actually not always necessary. If a T1w and a previously run freesurfer zip is passed, it will ignore the T1w and unzip the fs_zip and go from there.

Description

In the most basic form it just runs freesurfer. If a fs_zip is passed, not even that. On top of those options, it is possible to select many other segmentations and atlases to obtain innumerable ROIs. It is possible to pass a zip with MNI ROIs that the gear will convert to subject space ROIs. It is possible to pass a zip with fsaverage annotfiles, and the gear will generate cortical volumetric ROIs as well.

Workflow

There is no workflow, it runs recon_all or unzips de zipped freesurfer output, and then the rest of the analyses are optional and it depends on what the researcher wants.

Description of workflow

1. Upload file to container
2. Select file as input to gear
3. Geat places output in Analysis

Logging

There are several logs, depending on what has been run. If recon_all is being run, there will be a huge fresurfer log. Then, depending on the selected options, there will be sections per every groups of ROIs that have been asked to calculate.

FAQ

FAQ.md

Contributing

[For more information about how to get started contributing to that gear, checkout CONTRIBUTING.md.]