{"id":13676442,"url":"https://github.com/bids-apps/tracula","last_synced_at":"2026-05-29T00:03:12.793Z","repository":{"id":41497629,"uuid":"77473131","full_name":"bids-apps/tracula","owner":"bids-apps","description":"implements Freesurfer's TRACULA (TRActs Constrained by UnderLying Anatomy) tool for cross-sectional as well as longitudinal (multi session) input data.","archived":false,"fork":false,"pushed_at":"2026-03-09T11:25:15.000Z","size":112,"stargazers_count":3,"open_issues_count":2,"forks_count":3,"subscribers_count":3,"default_branch":"master","last_synced_at":"2026-03-09T15:59:19.561Z","etag":null,"topics":["bids","bidsapp","diffusion-mri"],"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-12-27T17:51:59.000Z","updated_at":"2026-03-09T11:25:19.000Z","dependencies_parsed_at":"2023-11-14T11:28:18.856Z","dependency_job_id":"c4b14ecc-c66b-477f-a877-11d21aded57b","html_url":"https://github.com/bids-apps/tracula","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/bids-apps/tracula","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bids-apps%2Ftracula","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bids-apps%2Ftracula/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bids-apps%2Ftracula/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bids-apps%2Ftracula/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bids-apps","download_url":"https://codeload.github.com/bids-apps/tracula/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bids-apps%2Ftracula/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":["bids","bidsapp","diffusion-mri"],"created_at":"2024-08-02T13:00:27.144Z","updated_at":"2026-05-29T00:03:12.757Z","avatar_url":"https://github.com/bids-apps.png","language":"Python","funding_links":[],"categories":["BIDS Apps"],"sub_categories":["others"],"readme":"# TRACULA BIDS App\n\n[![CircleCI](https://circleci.com/gh/BIDS-Apps/tracula.svg?style=shield\u0026circle-token=:circle-token)](https://circleci.com/gh/BIDS-Apps/tracula)\n[![DOI](https://zenodo.org/badge/77473131.svg)](https://zenodo.org/badge/latestdoi/77473131)\n\n## Description\n\nThis [BIDS App](https://bids-apps.neuroimaging.io) implements\n[Freesurfer's](https://surfer.nmr.mgh.harvard.edu/)\n[TRACULA ](https://surfer.nmr.mgh.harvard.edu/fswiki/Tracula)\n(TRActs Constrained by UnderLying Anatomy) tool for\ncross-sectional as well as longitudinal (multi session) input data.\n\nThis tool is based on Freesurfer v6.0.0\n\n## Disclaimer\n\nThis BIDS-App was tested with [high-angular resolution\ndiffusion weighted imaging (DWI) data without\nfieldmaps](https://openfmri.org/dataset/ds000114/).\nIf you would like to see it working with more complex data,\n[get in touch](https://github.com/bids-apps/tracula/issues).\n\n\n## How to report errors\n\nFor Tracula-BIDS-Apps related problems, open an\n[issue](https://github.com/bids-apps/tracula/issues).\n\nFor Tracula-relade errors contact the\n[Freesurfer mailing list](https://surfer.nmr.mgh.harvard.edu/fswiki/FreeSurferSupport).\n\n## Acknowledgements\n\nIf you use this tool please cite the following sources:\n\n- *Franziskus Liem, \u0026 Krzysztof J. Gorgolewski. (2017).\nBIDS-Apps/tracula.* [![DOI](https://zenodo.org/badge/77473131.svg)](https://zenodo.org/badge/latestdoi/77473131)\n\n- The BIDS Apps\n[preprint](http://biorxiv.org/content/early/2016/10/20/079145):\n*Krzysztof J. Gorgolewski et al. (2017).\nBIDS Apps: Improving ease of use, accessibility and reproducibility\nof neuroimaging data analysis methods.\ndoi: https://doi.org/10.1101/079145*\n\n- The relevant Freesurfer\n[references](https://surfer.nmr.mgh.harvard.edu/fswiki/FreeSurferMethodsCitation).\n\n## Data\n\nTracula requires one DWI volume and a one T1w image\nper participant (or session if the data is longitudinal).\n\nIn a first step, the app will run the FreeSurfer reconstruction\n(`recon-all`). If the Freesurfer reconstruction is already available\nand is provided via the `{freesurfer_dir}` argument, this step is skipped.\nIn this case `recon-all` should have been performed with the\n[Freesurfer BIDS App](https://github.com/bids-apps/freesurfer)\n(or at least follow the BIDS naming scheme).\n\n## Analysis levels\n\n- **participant**: Tract reconstruction\n\n    Runs `recon-all` if not already available.\n    Subsequently, performs the three steps (prep, bedp, path) of Tracula's `trac-all`,\n    reconstructing major fiber tracts form Freesurfer outputs and\n    DWI raw data.\n    All data is written into `{output_dir}`.\n\n- **group1**: Motion statistics\n\n    Collects motion statistics for multiple subjects into one file.\n    Additionally, total motion index (TMI, according to\n    [Yendiki et al., 2013](http://doi.org/10.1016/j.neuroimage.2013.11.027)).\n    Output is written to\n    `{output_dir}/00_group1_motion_stats/group_motion.tsv`.\n\n    *Note*: In deviation to the original equation\n    (which includes rotation, translation, bad slices, dropout score),\n    this implementation of TMI only considers those measures\n    that show enought variance for normalization (i.e., don't\n    produce NaNs - often seen in 'PercentBadSlices' and\n    'AvgDropoutScore'). The measures that went into the\n    calculation can be found in the *TMI_info* column of the\n    output file.\n\n- **group2**: Tract statistics\n\n    Collects tract stats for multiple subjects.\n    Mean stats of a tract (average FA...) are written to\n    `{output_dir}/00_group2_tract_stats/overall_stats/`.\n    Along-tract stats are written to\n    `{output_dir}/00_group2_tract_stats/byvoxel_stats/`.\n\n\n## Usage\n\nThis App has the following command line arguments:\n\n    usage: run.py [-h] --license_key LICENSE_KEY\n                  [--participant_label PARTICIPANT_LABEL [PARTICIPANT_LABEL ...]]\n                  [--session_label SESSION_LABEL [SESSION_LABEL ...]]\n                  [--freesurfer_dir FREESURFER_DIR]\n                  [--stages {prep,bedp,path,all} [{prep,bedp,path,all} ...]]\n                  [--n_cpus N_CPUS] [--run-freesurfer-tests-only] [-v]\n                  bids_dir output_dir {participant,group1,group2}\n\n    BIDS App for Tracula processing stream.\n    https://surfer.nmr.mgh.harvard.edu/fswiki/Tracula\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.\n                            \"participant\": runs FreeSurfer and reconstructs paths\n                            (trac-all -prep, -bedp and -path), \"group1\": collects\n                            motion stats in one file, \"group2\": collects tract\n                            stats in one file.\n\n    optional arguments:\n      -h, --help            show this help message and exit\n      --license_key LICENSE_KEY\n                            FreeSurfer license key - letters and numbers after \"*\"\n                            in the email you received after registration. To\n                            register (for free) visit\n                            https://surfer.nmr.mgh.harvard.edu/registration.html\n                            (default: None)\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. (default: None)\n      --session_label SESSION_LABEL [SESSION_LABEL ...]\n                            The label of the sessions 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. (default: None)\n      --freesurfer_dir FREESURFER_DIR\n                            The directory with the FreeSurfer data. If not\n                            specified, FreeSurfer data is written into output_dir.\n                            If FreeSurfer data cannot be found for a subject, this\n                            app will run FreeSurfer as well. (default: None)\n      --stages {prep,bedp,path,all} [{prep,bedp,path,all} ...]\n                            Participant-level trac-all stages to run. Passing\"all\"\n                            will run \"prep\", \"bedp\" and \"path\". (default: ['all'])\n      --n_cpus N_CPUS       Number of CPUs/cores available to use. (default: 1)\n      --run-freesurfer-tests-only\n                            Dev option to enable freesurfer tests on circleci\n                            (default: False)\n      -v, --version         show program's version number and exit\n\n\n## Examples\n\nTo run it in participant level mode (for one participant):\n\n### Participant level\n\n        docker run -ti --rm \\\n         -v /data/ds114/sourcedata:/bids_dataset:ro \\\n         -v /data/ds114/derivates/tracula:/outputs \\\n         -v /data/ds114/derivates/freesurfer:/freesurfer \\\n         bids/tracula \\\n         /bids_dataset /outputs participant --participant_label 01 \\\n         --license_key \"XXXXXXXX\" \\\n         --freesurfer_dir /freesurfer\n\n**Note that** the path specified in --freesurfer_dir needs to be the\nmount point inside the docker container (e.g., `/freesurfer`, specified\nin the 4th line of the previous command, after the \":\"), not the\npath on your hard drive (e.g., `/data/ds114/derivates/freesurfer`)\n\n### Group level\n\nAfter doing this for all subjects (potentially in parallel) the group level analysis\ncan be run.\n\nTo aggregate motion statistics into one file (group1 stage), run:\n\n        docker run -ti --rm \\\n         -v /data/ds114/sourcedata:/bids_dataset:ro \\\n         -v /data/ds114/derivates/tracula:/outputs \\\n         -v /data/ds114/derivates/freesurfer:/freesurfer \\\n         bids/tracula \\\n         /bids_dataset /outputs group1 \\\n         --license_key \"XXXXXXXX\" \\\n         --freesurfer_dir /freesurfer\n\n\n\nTo aggregate tract statistics into one file  (group2 stage), run:\n\n        docker run -ti --rm \\\n         -v /data/ds114/sourcedata:/bids_dataset:ro \\\n         -v /data/ds114/derivates/tracula:/outputs \\\n         -v /data/ds114/derivates/freesurfer:/freesurfer \\\n         bids/tracula \\\n         /bids_dataset /outputs group2 \\\n         --license_key \"XXXXXXXX\" \\\n         --freesurfer_dir /freesurfer\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbids-apps%2Ftracula","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbids-apps%2Ftracula","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbids-apps%2Ftracula/lists"}