= recon-all-clinical =


'''''[WARNING: the script in FreeSurfer 7.4 has a small bug when computing the surface label files at the end of the script. Please replace $FREESURFER_HOME/bin/recon-all-clinical.sh with the latest version [[https://github.com/freesurfer/freesurfer/blob/dev/recon_all_clinical/recon-all-clinical.sh|HERE]]. Development versions newer than June 15th 2023 do not have this problem.]'''''


'''''This functionality is available since FreeSurfer 7.4.'''''

''Author: Karthik Gopinath''

''E-mail: kgopinath[at]mgh[dot]harvard[dot]edu''

''Please post your questions on this module to the FreeSurfer mailing list at freesurfer[at]nmr.mgh.harvard.edu rather than directly contacting the author. ''

''If you use this package in your analysis, please cite:''

 * [[https://arxiv.org/abs/2305.01827|Cortical analysis of heterogeneous clinical brain MRI scans for large-scale neuroimaging studies]]. K Gopinath, DN Greeve, S Das, S Arnold, C Magdamo, JE Iglesias
 * [[https://www.sciencedirect.com/science/article/pii/S1361841523000506|SynthSeg: Segmentation of brain MRI scans of any contrast and resolution without retraining]]. B Billot, DN Greve, O Puonti, A Thielscher, K Van Leemput, B Fischl, AV Dalca, JE Iglesias. Medical Image Analysis, 83, 102789 (2023).
 * [[https://www.pnas.org/doi/10.1073/pnas.2216399120|Robust machine learning segmentation for large-scale analysis of heterogeneous clinical brain MRI datasets]]. B Billot, C Magdamo, SE Arnold, S Das, JE Iglesias. PNAS, 120(9), e2216399120 (2023).
 * [[https://www.science.org/doi/10.1126/sciadv.add3607|SynthSR: a public AI tool to turn heterogeneous clinical brain scans into high-resolution T1-weighted images for 3D morphometry]]. JE Iglesias, B Billot, Y Balbastre, C Magdamo, S Arnold, S Das, B Edlow, D Alexander, P Golland, B Fischl. Science Advances, 9(5), eadd3607 (2023).

=== General description: ===
This tool performs recon-all-clinical, the first out-of-the-box cortical surface reconstruction and analysis of brain MRI scans of any modality, contrast and resolution without retraining and fine-tuning.

This "Recon-all-like" stream for clinical scans of arbitrary orientation/resolution/contrast is essentially a combination of:

 * SynthSeg: to obtain a volumetric segmentation and linear registration to Talairach space
 * [[SynthSR]]: to have a higher resolution 1mm MPRAGE for visualization
 * SynthDist: to fit surfaces by predicting the distance maps and reconstructing topologically accurate cortical surfaces

{{attachment:sample_output_recon_all_clinical.png||width="720",height="405"}} <<BR>>''Out of the box cortical surface reconstruction and analysis of heterogenous scans. (a)Sagittal T1 scan with .4×.4×6mm resolution. (b)Axial FLAIR scan with 1.7×1.7×6mm resolution. (c)Axial T2-weighted scan with .9×.9×6mm resolution. The WM surface with cortical parcellation overlaid and pial surfaces are also shown.''<<BR>>

=== Usage: ===
Once'''''[[https://surfer.nmr.mgh.harvard.edu/fswiki/FreeSurfer|FreeSurfer]] '''''has been sourced, you can simply run {{{recon-all-clinical}}} on your own data with

{{{
recon-all-clinical.sh INPUT_SCAN SUBJECT_ID THREADS [SUBJECT_DIR]
}}}
where:

- INPUT_SCAN: path to an image that will be processed.

- SUBJECT_ID: specifies the name or ID of the subject you would like to use. A directory with that name will be created for all the subject's FreeSurfer output.

- THREADS (optional): number of CPU threads to use. The default is just 1, so crank it up for faster processing if you have multiple cores!

- SUBJECT_DIR: only necessary if the environment variable SUBJECTS_DIR has not been set when sourcing FreeSurfer or if you want to override it.

''This stream runs a bit faster than the original {{{recon-all}}}, since the volumetric segmentation is much faster than the iterative Bayesian method in the standard stream''

=== Outputs: ===
''This stream will create a directory structure that is almost the same as {{{recon-all}}}, but with some minor changes in the {{{SUBJECT_DIR/mri}}}:''

 * {{{native.mgz}}}: input (reconstructed) volume.
 * {{{synthseg.mgz}}}: initial volumetric segmentation given by SynthSeg.
 * {{{aseg.auto_noCCseg.mgz}}}: same as synthseg.mgz that is required for a number of subsequent processing steps of FreeSurfer.
 * {{{aseg.presurf.mgz}}}: same as synthseg.mgz that is required for a number of subsequent processing steps of FreeSurfer.
 * {{{synthSR.raw.mgz}}}: raw output of SynthSR.
 * {{{synthSR.norm.mgz}}}: cleaned up version of synthSR.raw.mgz, scaled such that the white matter has intensity of 110.
 * {{{synthsurf.mgz}}}: file with distance maps predicted by SynthDist.
 * {{{norm.mgz}}}: generated intensity image with super-resolved cortex estimated from the distance maps in synthsurf.mgz. The subcortex of the brain is ignored here for placing surfaces.
 * {{{brain.mgz}}}: same as norm.mgz that is required for a number of subsequent processing steps of FreeSurfer.
 * {{{brainmask.mgz}}}: same as norm.mgz that is required for a number of subsequent processing steps of FreeSurfer.
 * {{{wm.mgz}}} and {{{wm.seg.mgz}}}: these are volumetric white matter masks used to initialize the surface placement.

''Post completion of the cortical surface stream, some of the results from the cortical stream are used to refine the results in the directory {{{SUBJECT_DIR/mri}}}:''

 * {{{aseg.mgz}}}: this is the aseg with the refined cortex label from the placed surfaces.
 * {{{aparc*+aseg.mgz}}}: same as aseg, but with parcellated cortical labels (according to 3 different atlases).
 * {{{*ribbon.mgz}}}: the ribbon, given by the surfaces.
 * {{{synthSR.mgz}}}: this is essentially synthSR.norm.mgz updated with the information from the cortical surfaces.
 * {{{wmparc.mgz}}}: white matter parcellation.

=== Cortical thickness and future work ===
''The current {{{recon-all-clinical}}} stream is accurate for parcellation at nearly any resolution / slice spacing (see paper). However, the quality of cortical thickness estimation does degrade relatively quickly with increasing slice spacing; we plan to improve this in future versions of the tool.''