{"id":13676345,"url":"https://github.com/bids-apps/BrainSuite","last_synced_at":"2025-04-29T06:31:53.350Z","repository":{"id":65786888,"uuid":"102636805","full_name":"bids-apps/BrainSuite","owner":"bids-apps","description":"BrainSuite's structural, diffusion, and functional MRI processing pipelines with QC functionalities. ","archived":false,"fork":false,"pushed_at":"2024-11-04T08:29:55.000Z","size":16240,"stargazers_count":10,"open_issues_count":1,"forks_count":4,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-11-11T18:41:07.459Z","etag":null,"topics":["bids","bidsapp","mri","mri-analysis"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","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.txt","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}},"created_at":"2017-09-06T17:15:14.000Z","updated_at":"2024-11-04T08:29:59.000Z","dependencies_parsed_at":"2024-04-08T22:31:54.355Z","dependency_job_id":"41860ba3-fe32-4ab0-a70d-0e01b8f9c6c3","html_url":"https://github.com/bids-apps/BrainSuite","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bids-apps%2FBrainSuite","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bids-apps%2FBrainSuite/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bids-apps%2FBrainSuite/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bids-apps%2FBrainSuite/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bids-apps","download_url":"https://codeload.github.com/bids-apps/BrainSuite/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251450656,"owners_count":21591407,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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","mri","mri-analysis"],"created_at":"2024-08-02T13:00:23.418Z","updated_at":"2025-04-29T06:31:48.341Z","avatar_url":"https://github.com/bids-apps.png","language":"Python","funding_links":[],"categories":["BIDS Apps"],"sub_categories":["others"],"readme":"# BrainSuite BIDS App\nThis readme provides an outline of the functionality of the BrainSuite BIDS App.\nFor more detailed instructions on installation and use, please visit [our BrainSuite BIDS App documentation page](https://brainsuite.org/BIDS/).\nWe have made a small set of [sample data available](https://github.com/BrainSuite/BrainSuiteBIDSAppSampleData).\nA demo of the BrainSuite Dashboard interface, showing the processing of the sample data, is available [on our Github site](https://brainsuite.github.io/DashboardDemo/).\n\n## Overview\nThe BrainSuite BIDS App provides a portable, streamlined method for applying [BrainSuite](https://brainsuite.org) workflows to process and analyze anatomical, diffusion, and functional MRI data. This release of the BrainSuite BIDS-App is based on [version 23a of BrainSuite](https://brainsuite.org/brainsuite23a).\nThe BrainSuite BIDS-App implements three major BrainSuite pipelines for subject-level analysis, as well as corresponding group-level analysis functionality.\n\n### Participant-level processing\n\n\u003cp align=\"center\"\u003e\n \u003cimg src=\"./docs/pngs/3_brainsuite_bids_subject_level_comprehensive.low.whitebg.v19.png\" width=\"600\"/\u003e\n\u003c/p\u003e\n\nBrainSuite BIDS App's participant-level processing comprises three core pipelines:\n\n* `The BrainSuite Anatomical Pipeline (BAP)` processes T1-weighted (T1w) data by extracting cortical surface models ([CSE](https://brainsuite.org/processing/surfaceextraction/)) from a T1w MRI, computing cortical thickness, and performing surface-constrained volumetric registration ([SVReg](https://brainsuite.org/processing/svreg/)) to align the T1w MRI to a labeled anatomical atlas.\n* `The BrainSuite Diffusion Pipeline (BDP)` processes diffusion MRI (dMRI) data by correcting for eddy current and motion artifacts using [FSL's eddy](https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/eddy), co-registering the dMRI to the T1w data, correcting for geometric image distortion, and fitting diffusion models ([BDP](https://brainsuite.org/processing/diffusion/)).\n* `The BrainSuite Functional Pipeline (BFP)` processes functional MRI (fMRI) data by coregistering the fMRI data to the T1w data, correcting for motion, detecting outliers, and then transforming the data to the anatomical atlas space and to the grayordinate space using tools from [BrainSuite](https://brainsuite.org/bfp/), [FSL](fsl.fmrib.ox.ac.uk), and [AFNI](afni.nimh.nih.gov).\n\n### Group-level analysis\n\n\u003cp align=\"center\"\u003e\n \u003cimg src=\"./docs/pngs/group_analysis_VG.low.png\" width=\"900\"/\u003e\n\u003c/p\u003e\n\n* BrainSuite BIDS App's group-level analysis of structural data uses the BrainSuite Statistics Toolbox in R ([bstr](https://brainsuite.org/bssr/)), which supports:\n\n    * Tensor based morphometry (TBM) analysis.\n    * Cortical surface analysis of the vertex-wise thickness.\n    * Diffusion parameter maps analysis (e.g., FA, MD).\n    * ROI-based analysis of average measurements (e.g., gray matter thickness, surface area).\n\n  Additionally, bstr offers:\n\n    * Pearson correlation, general linear model, ANOVA, t-test, and permutation tests.\n    * Automated report generation to visualize statistical results.\n\n\n* BrainSuite BIDS App's group-level analysis of fMRI data (functional connectivity) is performed using [BrainSync](https://github.com/ajoshiusc/bfp/tree/master/src/BrainSync), which synchronizes time-series data temporally. Available analyses include:\n\n    * Atlas-based method: linear modeling using a reference dataset created from multiple input datasets.\n    * Atlas-free method: pairwise testing of all pairs of subjects, which is then used as test statistics for regression or group difference studies.\n\n### BrainSuite Dashboard and QC system\n\n\u003cp align=\"center\"\u003e\n \u003cimg src=\"./docs/pngs/4_BrainSuiteDashboard_23a_13July2023.png\" width=\"800\"/\u003e\n\u003c/p\u003e\n\nThe BrainSuite Dashboard is a browser-based system that provides interactive visualization of the intermediate participant-level workflow outputs as they are generated. This enables users to monitor the state of processing and identify errors as they occur. A quality control (QC) component in the BrainSuite BIDS App generates snapshots of key stages in the participant-level workflows, which are loaded in real time by the BrainSuite Dashboard for quick visualization and assessment.\n\n\n\n### Command line arguments\n```text\nusage: run.py [-h]\n              [--stages {CSE,SVREG,BDP,BFP,DASHBOARD,ALL} [{CSE,SVREG,BDP,BFP,DASHBOARD,ALL} ...]]\n              [--preprocspec PREPROCSPEC]\n              [--participant_label PARTICIPANT_LABEL [PARTICIPANT_LABEL ...]]\n              [--session SESSION [SESSION ...]] [--skipBSE]\n              [--atlas {BSA,BCI-DNI,USCBrain}] [--singleThread] [--TR TR]\n              [--fmri_task_name FMRI_TASK_NAME [FMRI_TASK_NAME ...]]\n              [--ignore_suffix IGNORE_SUFFIX] [--QCdir QCDIR]\n              [--QCsubjList QCSUBJLIST] [--localWebserver] [--port PORT]\n              [--bindLocalHostOnly] [--modelspec MODELSPEC]\n              [--analysistype {STRUCT,FUNC,ALL}] [--rmarkdown RMARKDOWN]\n              [--ignoreSubjectConsistency] [--bidsconfig [BIDSCONFIG]]\n              [--cache CACHE] [--ncpus NCPUS] [--maxmem MAXMEM] [-v]\n              bids_dir output_dir {participant,group}\n\nBrainSuite23a BIDS-App (T1w, dMRI, rs-fMRI). Copyright (C) 2022 The Regents of\nthe University of California Dept. of Neurology, David Geffen School of\nMedicine, UCLA.\n\npositional 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,group}   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. The group\n                        analysis performs group statistical analysis.\n\noptional arguments:\n  -h, --help            show this help message and exit\n  --stages {CSE,SVREG,BDP,BFP,DASHBOARD,ALL} [{CSE,SVREG,BDP,BFP,DASHBOARD,ALL} ...]\n                        Participant-level processing stage to be run. Space\n                        delimited list. Default is ALL which does not include\n                        DASHBOARD. CSE runs Cortical Surface Extractor and\n                        cortical thickness computation, which are the initial\n                        portions of the BrainSuite Anatomical Pipeline (BAP).\n                        SVREG runs Surface-constrained Volumetric\n                        registration, which is the latter portion of BAP. BDP\n                        runs BrainSuite Diffusion Pipeline. BFP runs\n                        BrainSuite Functional Pipeline. DASHBOARD runs the\n                        real-time monitoring that is required for BrainSuite\n                        Dashboard to update real-time. However, DASHBOARD can\n                        still be run after the participant-level processing\n                        has ended to generate the browser-based BrainSuite\n                        Dashboard.\n  --preprocspec PREPROCSPEC\n                        Optional. BrainSuite preprocessing parameters.Path to\n                        JSON file that contains preprocessing specifications.\n  --cache CACHE         Nipype cache output folder.\n  --ncpus NCPUS         Number of cpus allocated for running subject-level\n                        processing.\n  --maxmem MAXMEM       Maximum memory (in GB) that can be used at once.\n  -v, --version         show program's version number and exit\n\nOptions for selectively running specific datasets:\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 will be\n                        analyzed. Multiple participants can be specified with\n                        a space separated list.\n  --session SESSION [SESSION ...]\n                        The session label of the participant that should be\n                        analyzed. The label corresponds to ses-\u003csession label\u003e\n                        from the BIDS spec (so it does not include \"ses-\"). If\n                        this parameter is not provided, all sessions will be\n                        analyzed. Multiple sessions can be specified with a\n                        space separated list.\n\nCommand line arguments for BrainSuite Anatomical Pipeline (BAP). For more parameter options, please edit the preprocspecs.json file:\n  --skipBSE             Skips BSE stage when running CSE. Please make sure\n                        there are sub-ID_T1w.mask.nii.gz files in the subject\n                        folders.\n  --atlas {BSA,BCI-DNI,USCBrain}\n                        Atlas that is to be used for labeling in SVReg.\n                        Default atlas: BCI-DNI. Options: BSA, BCI-DNI,\n                        USCBrain.\n  --singleThread        Turns on single-thread mode for SVReg.This option can\n                        be useful when machines run into issues with the\n                        parallel processing tool from Matlab (Parpool).\n\nCommand line arguments for BrainSuite Functional Pipeline (BFP). For more parameter options, please edit the preprocspecs.json file:\n  --TR TR               Repetition time of MRI (in seconds).\n  --fmri_task_name FMRI_TASK_NAME [FMRI_TASK_NAME ...]\n                        fMRI task name to be processed during BFP. The name\n                        should only containthe contents after \"task-\". E.g.,\n                        restingstate.\n  --ignore_suffix IGNORE_SUFFIX\n                        Optional. Users can define which suffix to ignore in\n                        the output folder. E.g., if input T1w is sub-01_ses-\n                        A_acq-highres_run-01_T1w.nii.gz,and user would like to\n                        ignore the \"acq-highres\" suffix portion, then user can\n                        type \"--ignore_suffix acq\", which will render\n                        sub-01_ses-A_run-01 output folders.\n\nOptions for BrainSuite QC and Dashboard:\n  --QCdir QCDIR         Designate directory for QC Dashboard.\n  --QCsubjList QCSUBJLIST\n                        For QC purposes, optional subject list (txt format,\n                        individual subject ID separated by new lines; subject\n                        ID without \"sub-\" is required (i.e. 001). This is\n                        helpfulin displaying only the thumbnails of the queued\n                        subjects when running on clusters/compute nodes.\n  --localWebserver      Launch local webserver for QC.\n  --port PORT           Port number for QC local webserver. This defines the\n                        port number inside the BrainSuite BIDS App container.\n                        If using Singularity version of BrainSuite BIDS App,\n                        this argument also defines the port number of the\n                        local host.\n  --bindLocalHostOnly   When running local web server through this app, the\n                        server binds to all of the IPs on the machine. If you\n                        would like to only bind to the local host, please use\n                        this flag.\n\nArguments and options for group-level stage. --modelspec is required for groupmode:\n  --modelspec MODELSPEC\n                        Optional. Only for group analysis level.Path to JSON\n                        file that contains statistical model specifications.\n  --analysistype {STRUCT,FUNC,ALL}\n                        Group analysis type: structural (T1 or DWI)or\n                        functional (fMRI). Options: STRUCT, FUNC, ALL.\n  --rmarkdown RMARKDOWN\n                        Optional. Executable Rmarkdown file that uses bstr\n                        for group analysis stage. If this argument is\n                        specified, BrainSuite BIDS-App will run this Rmarkdown\n                        instead of using the content found in\n                        modelspec.json.Path to R Markdown file that contains\n                        bstr analysis commands.\n\nOptions for bids-validator:\n  --ignoreSubjectConsistency\n                        Reduces down the BIDS validator log and the associated\n                        memory needs. This is often helpful forlarge datasets.\n  --bidsconfig [BIDSCONFIG]\n                        Configuration of the severity of errors for BIDS\n                        validator. If this argument is used with no path\n                        specification, the bids-validator checks for a .bids-\n                        validator-config.json file at the top level of the\n                        input BIDS directory. However, if you would like to\n                        define the path of your .bids-validator-config.json\n                        file, then you can specify the path after this flag\n                        (i.e. --bidsconfig /path/to/file). For more\n                        information on how to create this JSON file, please\n                        visit https://github.com/bids-standard/bids-\n                        validator#configuration.\n```\n\n## Docker Implementation\n\nThe BrainSuite BIDS App build process uses a pre-compiled parent image [yeunkim/bidsapphead:2023](https://hub.docker.com/layers/yeunkim/bidsapphead/2023/images/sha256-b2a9d563efee636884e976b4667c7523e9675db960af5ffa95e86a6075e1c059?context=repo), which is available on Docker Hub. The dockerfile for this parent Docker image is available in this repository as ```Dockerfile_head```.\nThis enables us to have a faster build process and a more stable BIDS App.\nBrainSuite BIDS App relies on multiple source software from third-party repositories.\nFrequent rebuilding of all layers may introduce changes that impact the consistency of the software, possibly introducing instabilities or changes that affect the outcomes of the analysis software.\nBy developing our BrainSuite BIDS App using pre-compiled images, we are able to keep the parent images stable while changing only the top layers of the Docker image.\nOur pre-compiled parent images act as snapshots of version-controlled dependencies and file systems that our BrainSuite BIDS App needs.\n\n## Support\nQuestions about usage can be submitted to http://forums.brainsuite.org/.\nIssues or suggestions can be directly submitted as an issue to this Github Repository.\nFor full documentation on the BrainSuite BIDS App, please visit https://brainsuite.org/BIDS/.\n\n## Acknowledgments\nThis project is supported by National Institutes of Health grants R01-NS074980, R01-NS121761, and R01-EB026299.\n\n## Licenses\nThe primary BrainSuite BIDS App source code is licensed under the [GNU Public License v2.0 only\n(GPL-2.0-only)](https://spdx.org/licenses/GPL-2.0.html)\n\nThe BrainSuite BIDS App makes use of several freely available software packages. Details on the licenses for each of these are provide in the files within the LICENSES directory of this repository.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbids-apps%2FBrainSuite","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbids-apps%2FBrainSuite","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbids-apps%2FBrainSuite/lists"}