{"id":13676373,"url":"https://github.com/bids-apps/freesurfer","last_synced_at":"2026-05-29T00:03:17.905Z","repository":{"id":56505585,"uuid":"64512144","full_name":"bids-apps/freesurfer","owner":"bids-apps","description":"BIDS app wrapping recon-all from FreeSurfer","archived":false,"fork":false,"pushed_at":"2026-03-16T10:00:44.000Z","size":237,"stargazers_count":44,"open_issues_count":16,"forks_count":35,"subscribers_count":4,"default_branch":"master","last_synced_at":"2026-03-16T20:52:01.379Z","etag":null,"topics":["anatomical-mri","bids","bidsapp","mri","preprocessing"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bids-apps.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2016-07-29T21:43:31.000Z","updated_at":"2026-03-16T10:00:40.000Z","dependencies_parsed_at":"2024-04-08T22:32:12.898Z","dependency_job_id":"d9a2c7f2-09e0-4069-84a6-ed7c70c0dc7d","html_url":"https://github.com/bids-apps/freesurfer","commit_stats":{"total_commits":237,"total_committers":16,"mean_commits":14.8125,"dds":0.6877637130801688,"last_synced_commit":"e36a470e04f371cc84cd9406f6963a9b4ac1c299"},"previous_names":[],"tags_count":27,"template":false,"template_full_name":null,"purl":"pkg:github/bids-apps/freesurfer","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bids-apps%2Ffreesurfer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bids-apps%2Ffreesurfer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bids-apps%2Ffreesurfer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bids-apps%2Ffreesurfer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bids-apps","download_url":"https://codeload.github.com/bids-apps/freesurfer/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bids-apps%2Ffreesurfer/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33631002,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-28T02:00:06.440Z","response_time":99,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["anatomical-mri","bids","bidsapp","mri","preprocessing"],"created_at":"2024-08-02T13:00:24.128Z","updated_at":"2026-05-29T00:03:17.889Z","avatar_url":"https://github.com/bids-apps.png","language":"Python","funding_links":[],"categories":["BIDS Apps"],"sub_categories":["others"],"readme":"\n[![Docker version](https://img.shields.io/docker/pulls/bids/freesurfer.svg?style=plastic)](https://hub.docker.com/r/bids/freesurfer)\n## Freesurfer recon-all BIDS App\n\n### Description\nThis app implements surface reconstruction using Freesurfer.\nIt reconstructs the surface for each subject individually\nand then creates a study specific template.\nIn case there are multiple sessions the Freesurfer longitudinal pipeline is used\n(creating subject specific templates) unless instructed to combine data across sessions.\nThis app is available for both Freesurfer 6 and 7.\n\nThe current Freesurfer version for Freesurfer 6 is based on:\n\n- `freesurfer-Linux-centos6_x86_64-stable-pub-v6.0.1.tar.gz`\n\nThe current Freesurfer version for Freesurfer 7 is based on:\n\n- `freesurfer-linux-centos7_x86_64-7.4.1.tar.gz`\n\nWe only plan to support only one version of Freesurfer 6 and Freesurfer 7 at a time.\n\nThe output of the pipeline consist of the `SUBJECTS_DIR` created during the analysis.\n\n### How to get it\nFreesurfer 6 will remain the default image till 2024, at which point Freesurfer 7 will become the default.\n\nYou can get the default version with `docker pull bids/freesurfer`.\n\nFreesurfer 7 is available at `docker pull bids/freesurfer:7`.\n\nFreesurfer 6 is available at `docker pull bids/freesurfer:6`.\n\n### Documentation\n - [Surface reconstruction](https://surfer.nmr.mgh.harvard.edu/fswiki/recon-all)\n - [Study specific template creation](https://surfer.nmr.mgh.harvard.edu/fswiki/SurfaceRegAndTemplates#CreatingaregistrationtemplateinitializedwithFreeSurfertemplate.28DG.29)\n - [Longitudinal pipeline](https://surfer.nmr.mgh.harvard.edu/fswiki/LongitudinalProcessing)\n\n### How to report errors\nhttps://surfer.nmr.mgh.harvard.edu/fswiki/FreeSurferSupport\n\n### Acknowledgements\nhttps://surfer.nmr.mgh.harvard.edu/fswiki/FreeSurferMethodsCitation\n\n### Usage\nThis App has the following command line arguments:\n\n\n        $ docker run -ti --rm bids/freesurfer --help\n        usage: run.py [-h]\n                      [--participant_label PARTICIPANT_LABEL [PARTICIPANT_LABEL ...]]\n                      [--session_label SESSION_LABEL [SESSION_LABEL ...]]\n                      [--n_cpus N_CPUS]\n                      [--stages {autorecon1,autorecon2,autorecon2-cp,autorecon2-wm,autorecon-pial,autorecon3,autorecon-all,all}\n                                [{autorecon1,autorecon2,autorecon2-cp,autorecon2-wm,autorecon-pial,autorecon3,autorecon-all,all} ...]]\n                      [--steps {cross-sectional,template,longitudinal}\n                               [{cross-sectional,template,longitudinal} ...]]\n                      [--template_name TEMPLATE_NAME] --license_file LICENSE_FILE\n                      [--acquisition_label ACQUISITION_LABEL]\n                      [--refine_pial_acquisition_label REFINE_PIAL_ACQUISITION_LABEL]\n                      [--multiple_sessions {longitudinal,multiday}]\n                      [--refine_pial {T2,FLAIR,None,T1only}]\n                      [--hires_mode {auto,enable,disable}]\n                      [--parcellations {aparc,aparc.a2009s} [{aparc,aparc.a2009s} ...]]\n                      [--measurements {area,volume,thickness,thicknessstd,meancurv,gauscurv,foldind,curvind}\n                                      [{area,volume,thickness,thicknessstd,meancurv,gauscurv,foldind,curvind} ...]]\n                      [-v] [--bids_validator_config BIDS_VALIDATOR_CONFIG]\n                      [--skip_bids_validator] [--3T {true,false}]\n                      bids_dir output_dir {participant,group1,group2}\n\n        FreeSurfer recon-all + custom template generation.\n\n        positional arguments:\n          bids_dir              The directory with the input dataset formatted\n                                according to the BIDS standard.\n          output_dir            The directory where the output files should be stored.\n                                If you are running group level analysis this folder\n                                should be prepopulated with the results of\n                                theparticipant level analysis.\n          {participant,group1,group2}\n                                Level of the analysis that will be performed. Multiple\n                                participant level analyses can be run independently\n                                (in parallel) using the same output_dir. \"group1\"\n                                creates study specific group template. \"group2\"\n                                exports group stats tables for cortical parcellation,\n                                subcortical segmentation a table with euler numbers.\n\n        optional arguments:\n          -h, --help            show this help message and exit\n          --participant_label PARTICIPANT_LABEL [PARTICIPANT_LABEL ...]\n                                The label of the participant that should be analyzed.\n                                The label corresponds to sub-\u003cparticipant_label\u003e from\n                                the BIDS spec (so it does not include \"sub-\"). If this\n                                parameter is not provided all subjects should be\n                                analyzed. Multiple participants can be specified with\n                                a space separated list.\n          --session_label SESSION_LABEL [SESSION_LABEL ...]\n                                The label of the session that should be analyzed. The\n                                label corresponds to ses-\u003csession_label\u003e from the BIDS\n                                spec (so it does not include \"ses-\"). If this\n                                parameter is not provided all sessions should be\n                                analyzed. Multiple sessions can be specified with a\n                                space separated list.\n          --n_cpus N_CPUS       Number of CPUs/cores available to use.\n          --stages {autorecon1,autorecon2,autorecon2-cp,autorecon2-wm,autorecon-pial,autorecon3,autorecon-all,all}\n                                [{autorecon1,autorecon2,autorecon2-cp,autorecon2-wm,autorecon-pial,autorecon3,autorecon-all,all} ...]\n                                Autorecon stages to run.\n          --steps {cross-sectional,template,longitudinal} [{cross-sectional,template,longitudinal} ...]\n                                Longitudinal pipeline steps to run.\n          --template_name TEMPLATE_NAME\n                                Name for the custom group level template generated for\n                                this dataset\n          --license_file LICENSE_FILE\n                                Path to FreeSurfer license key file. To obtain it you\n                                need to register (for free) at\n                                https://surfer.nmr.mgh.harvard.edu/registration.html\n          --acquisition_label ACQUISITION_LABEL\n                                If the dataset contains multiple T1 weighted images\n                                from different acquisitions which one should be used?\n                                Corresponds to \"acq-\u003cacquisition_label\u003e\"\n          --refine_pial_acquisition_label REFINE_PIAL_ACQUISITION_LABEL\n                                If the dataset contains multiple T2 or FLAIR weighted\n                                images from different acquisitions which one should be\n                                used? Corresponds to \"acq-\u003cacquisition_label\u003e\"\n          --multiple_sessions {longitudinal,multiday}\n                                For datasets with multiday sessions where you do not\n                                want to use the longitudinal pipeline, i.e., sessions\n                                were back-to-back, set this to multiday, otherwise\n                                sessions with T1w data will be considered independent\n                                sessions for longitudinal analysis.\n          --refine_pial {T2,FLAIR,None,T1only}\n                                If the dataset contains 3D T2 or T2 FLAIR weighted\n                                images (~1x1x1), these can be used to refine the pial\n                                surface. If you want to ignore these, specify None or\n                                T1only to base surfaces on the T1 alone.\n          --hires_mode {auto,enable,disable}\n                                Submilimiter (high resolution) processing. 'auto' -\n                                use only if \u003c1.0mm data detected, 'enable' - force on,\n                                'disable' - force off\n          --parcellations {aparc,aparc.a2009s} [{aparc,aparc.a2009s} ...]\n                                Group2 option: cortical parcellation(s) to extract\n                                stats from.\n          --measurements {area,volume,thickness,thicknessstd,meancurv,gauscurv,foldind,curvind}\n                                [{area,volume,thickness,thicknessstd,meancurv,gauscurv,foldind,curvind} ...]\n                                Group2 option: cortical measurements to extract stats\n                                for.\n          -v, --version         show program's version number and exit\n          --bids_validator_config BIDS_VALIDATOR_CONFIG\n                                JSON file specifying configuration of bids-validator:\n                                See https://github.com/INCF/bids-validator for more\n                                info\n          --skip_bids_validator\n                                skips bids validation\n\t  --3T {true,false}     enables the two 3T specific options that recon-all\n\t  \t\t\tsupports: nu intensity correction params, and the\n\t\t\t\tspecial schwartz atlas\n\n#### Participant level\nTo run it in participant level mode (for one participant):\n\n\t\tdocker run -ti --rm \\\n      -v /Users/filo/data/ds005:/bids_dataset:ro \\\n      -v /Users/filo/outputs:/outputs \\\n      -v /Users/filo/freesurfer_license.txt:/license.txt \\\n      bids/freesurfer \\\n        /bids_dataset /outputs participant --participant_label 01 \\\n        --license_file \"/license.txt\"\n\n\n#### Group level\nAfter doing this for all subjects (potentially in parallel) the\ngroup level analyses can be run.\n\n##### Template creation\nTo create a study specific template run:\n\n\t\tdocker run -ti --rm \\\n      -v /Users/filo/data/ds005:/bids_dataset:ro \\\n      -v /Users/filo/outputs:/outputs \\\n      -v /Users/filo/freesurfer_license.txt:/license.txt \\\n      bids/freesurfer \\\n        /bids_dataset /outputs group1 \\\n        --license_file \"/license.txt\"\n\n##### Stats and quality tables export\nTo export tables with aggregated measurements within regions of\ncortical parcellation and subcortical segementation, and a table with\n euler numbers (a quality metric, see\n [Rosen et. al, 2017](https://www.biorxiv.org/content/early/2017/10/01/125161))\n run:\n\n\t\tdocker run -ti --rm \\\n\t\t-v /Users/filo/data/ds005:/bids_dataset:ro \\\n\t\t-v /Users/filo/outputs:/outputs \\\n\t\t-v /Users/filo/freesurfer_license.txt:/license.txt \\\n\t\tbids/freesurfer \\\n\t\t/bids_dataset /outputs group2 \\\n\t\t--license_file \"/license.txt\"\nAlso see the *--parcellations* and *--measurements* arguments.\n\nThis step writes ouput into `\u003coutput_dir\u003e/00_group2_stats_tables/`.\nE.g.:\n\n* `lh.aparc.thickness.tsv` contains cortical thickness values for the\nleft hemisphere extracted via the aparac parcellation.\n* `aseg.tsv` contains subcortical information from the aseg segmentation.\n* `euler.tsv` contains the euler numbers\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbids-apps%2Ffreesurfer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbids-apps%2Ffreesurfer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbids-apps%2Ffreesurfer/lists"}