├── .codespellignore ├── .github ├── ISSUE_TEMPLATE │ ├── bug-report.md │ ├── documentation.md │ ├── feature-request.md │ └── questions-help-support.md ├── dependabot.yml └── workflows │ ├── build.yml │ ├── code-style.yml │ ├── doc.yml │ └── publish.yml ├── .gitignore ├── CHANGES.md ├── CODE_OF_CONDUCT.md ├── CONTRIBUTING.md ├── DESCRIPTION.md ├── LICENSE ├── README.md ├── SECURITY.md ├── VERSION ├── doc ├── Authors.rst ├── Changelog.rst ├── Citations.rst ├── Development.rst ├── Functionality.rst ├── Installation.rst ├── License.rst ├── Makefile ├── Requirements.rst ├── Usage.rst ├── _static │ └── .gitkeep ├── _templates │ └── autosummary │ │ ├── class.rst │ │ ├── function.rst │ │ └── module.rst ├── api │ └── index.rst ├── conf.py ├── index.rst ├── links.inc ├── make.bat └── references.bib ├── docker ├── Docker.md └── Dockerfile ├── fsqc ├── __init__.py ├── checkCCSize.py ├── checkContrast.py ├── checkRotation.py ├── checkSNR.py ├── checkTopology.py ├── cli │ └── __init__.py ├── commands │ ├── __init__.py │ └── sys_info.py ├── createScreenshots.py ├── createSurfacePlots.py ├── evaluateFornixSegmentation.py ├── evaluateHippocampalSegmentation.py ├── evaluateHypothalamicSegmentation.py ├── fsqcMain.py ├── fsqcUtils.py ├── outlierDetection.py └── utils │ ├── __init__.py │ ├── _config.py │ ├── _imports.py │ └── tests │ ├── __init__.py │ ├── test_config.py │ └── test_imports.py ├── pyproject.toml ├── requirements.txt ├── run_fsqc ├── setup.py └── singularity └── Singularity.md /.codespellignore: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Deep-MI/fsqc/923d71733008656ee34dbf522bf3d2323ca996e6/.codespellignore -------------------------------------------------------------------------------- /.github/ISSUE_TEMPLATE/bug-report.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: Bug Report 3 | about: Create a bug report to help us improve qatools-python 4 | title: '' 5 | labels: bug 6 | assignees: '' 7 | 8 | --- 9 | 10 | ## Description 11 | 12 | .... 13 | 14 | ## Steps to Reproduce 15 | 22 | 23 | 24 | ... 25 | 26 | ## Expected Behavior 27 | 28 | ... 29 | 30 | ## Screenshots 31 | 32 | ... 33 | 34 | ## Environment 35 | - qatools-python Version: ... 36 | - OS: ... 37 | - CPU: ... 38 | 39 | 40 | 41 | 42 | 43 | ### Execution 44 | 45 | 46 | 47 | Run Command: 48 | 49 | ## Additional Context 50 | 51 | ... 52 | -------------------------------------------------------------------------------- /.github/ISSUE_TEMPLATE/documentation.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: Documentation 3 | about: Report an issue or make a suggestion related to qatools-python documentation 4 | title: '' 5 | labels: documentation 6 | assignees: '' 7 | 8 | --- 9 | 10 | ## Documentation 11 | 12 | ... 13 | -------------------------------------------------------------------------------- /.github/ISSUE_TEMPLATE/feature-request.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: Feature Request 3 | about: Submit a proposal/request for a new qatools-python feature 4 | title: '' 5 | labels: enhancement 6 | assignees: '' 7 | 8 | --- 9 | 10 | ## Feature Description 11 | 12 | ... 13 | 14 | ## Motivation 15 | 16 | ... 17 | 18 | ## Alternatives 19 | 20 | ... 21 | 22 | ## Additional Context 23 | 24 | ... 25 | -------------------------------------------------------------------------------- /.github/ISSUE_TEMPLATE/questions-help-support.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: Questions/Help/Support 3 | about: Submit a request for support or a question 4 | title: '' 5 | labels: question 6 | assignees: '' 7 | 8 | --- 9 | 10 | ## Question/Support Request 11 | 12 | ... 13 | 14 | ## Screenshots 15 | 16 | ... 17 | 18 | 19 | 20 | ## Environment 21 | - qatools-python Version: ... 22 | - OS: ... 23 | - CPU: ... 24 | 25 | 26 | 27 | 28 | 29 | ### Execution 30 | 31 | 32 | 33 | Run Command: 34 | -------------------------------------------------------------------------------- /.github/dependabot.yml: -------------------------------------------------------------------------------- 1 | # To get started with Dependabot version updates, you'll need to specify which 2 | # package ecosystems to update and where the package manifests are located. 3 | # Please see the documentation for all configuration options: 4 | # https://docs.github.com/github/administering-a-repository/configuration-options-for-dependency-updates 5 | 6 | version: 2 7 | updates: 8 | - package-ecosystem: "" # See documentation for possible values 9 | directory: "/" # Location of package manifests 10 | schedule: 11 | interval: "weekly" 12 | -------------------------------------------------------------------------------- /.github/workflows/build.yml: -------------------------------------------------------------------------------- 1 | name: build 2 | concurrency: 3 | group: ${{ github.workflow }}-${{ github.event.number }}-${{ github.event.ref }} 4 | cancel-in-progress: true 5 | on: 6 | pull_request: 7 | push: 8 | branches: [stable] 9 | workflow_dispatch: 10 | 11 | jobs: 12 | build: 13 | timeout-minutes: 10 14 | strategy: 15 | fail-fast: false 16 | matrix: 17 | os: [ubuntu, macos, windows] 18 | python-version: ["3.9", "3.10", "3.11", "3.12"] 19 | name: ${{ matrix.os }} - py${{ matrix.python-version }} 20 | runs-on: ${{ matrix.os }}-latest 21 | defaults: 22 | run: 23 | shell: bash 24 | steps: 25 | - name: Checkout repository 26 | uses: actions/checkout@v4 27 | - name: Setup Python ${{ matrix.python-version }} 28 | uses: actions/setup-python@v5 29 | with: 30 | python-version: ${{ matrix.python-version }} 31 | - name: Install dependencies 32 | run: | 33 | python -m pip install --progress-bar off --upgrade pip setuptools wheel 34 | python -m pip install --progress-bar off .[build] 35 | - name: Test package install 36 | run: run_fsqc 37 | - name: Remove package install 38 | run: python -m pip uninstall -yq fsqc 39 | - name: Build package 40 | run: python -m build 41 | - name: Install sdist 42 | run: pip install ./dist/*.tar.gz 43 | - name: Test sdist install 44 | run: run_fsqc 45 | - name: Remove sdist install 46 | run: python -m pip uninstall -yq fsqc 47 | - name: Install wheel 48 | run: pip install ./dist/*.whl 49 | - name: Test wheel install 50 | run: run_fsqc 51 | - name: Remove wheel install 52 | run: python -m pip uninstall -yq fsqc 53 | -------------------------------------------------------------------------------- /.github/workflows/code-style.yml: -------------------------------------------------------------------------------- 1 | name: code-style 2 | concurrency: 3 | group: ${{ github.workflow }}-${{ github.event.number }}-${{ github.event.ref }} 4 | cancel-in-progress: true 5 | on: 6 | pull_request: 7 | push: 8 | branches: [stable] 9 | workflow_dispatch: 10 | 11 | jobs: 12 | style: 13 | timeout-minutes: 10 14 | runs-on: ubuntu-latest 15 | steps: 16 | - name: Checkout repository 17 | uses: actions/checkout@v4 18 | - name: Setup Python 3.10 19 | uses: actions/setup-python@v5 20 | with: 21 | python-version: '3.10' 22 | architecture: 'x64' 23 | - name: Install dependencies 24 | run: | 25 | python -m pip install --progress-bar off --upgrade pip setuptools wheel 26 | python -m pip install --progress-bar off .[style] 27 | - name: Run Ruff 28 | run: ruff check . 29 | - name: Run codespell 30 | uses: codespell-project/actions-codespell@master 31 | with: 32 | check_filenames: true 33 | check_hidden: true 34 | skip: './.git,./build,./.mypy_cache,./.pytest_cache' 35 | ignore_words_file: ./.codespellignore 36 | -------------------------------------------------------------------------------- /.github/workflows/doc.yml: -------------------------------------------------------------------------------- 1 | name: doc 2 | concurrency: 3 | group: ${{ github.workflow }}-${{ github.event.number }}-${{ github.event.ref }} 4 | cancel-in-progress: true 5 | on: 6 | pull_request: 7 | push: 8 | branches: [stable] 9 | workflow_dispatch: 10 | 11 | jobs: 12 | build: 13 | timeout-minutes: 10 14 | runs-on: ubuntu-latest 15 | defaults: 16 | run: 17 | shell: bash 18 | steps: 19 | - name: Checkout repository 20 | uses: actions/checkout@v4 21 | with: 22 | path: ./main 23 | - name: Setup Python 3.10 24 | uses: actions/setup-python@v5 25 | with: 26 | python-version: '3.10' 27 | architecture: 'x64' 28 | - name: Install package 29 | run: | 30 | python -m pip install --progress-bar off --upgrade pip setuptools wheel 31 | python -m pip install --progress-bar off main/.[doc] 32 | - name: Display system information 33 | run: fsqc-sys_info --developer 34 | - name: Build doc 35 | run: TZ=UTC sphinx-build ./main/doc ./doc-build/dev -W --keep-going 36 | - name: Upload documentation 37 | uses: actions/upload-artifact@v4 38 | with: 39 | name: doc-dev 40 | path: ./doc-build/dev 41 | 42 | deploy: 43 | if: github.event_name == 'push' 44 | needs: build 45 | timeout-minutes: 10 46 | runs-on: ubuntu-latest 47 | permissions: 48 | contents: write 49 | defaults: 50 | run: 51 | shell: bash 52 | steps: 53 | - name: Download documentation 54 | uses: actions/download-artifact@v4 55 | with: 56 | name: doc-dev 57 | path: ./doc-dev 58 | - name: Deploy dev documentation 59 | uses: peaceiris/actions-gh-pages@v4 60 | with: 61 | github_token: ${{ secrets.GITHUB_TOKEN }} 62 | publish_dir: ./doc-dev 63 | destination_dir: ./dev 64 | user_name: 'github-actions[bot]' 65 | user_email: 'github-actions[bot]@users.noreply.github.com' 66 | -------------------------------------------------------------------------------- /.github/workflows/publish.yml: -------------------------------------------------------------------------------- 1 | name: publish 2 | on: 3 | workflow_dispatch: 4 | release: 5 | types: [published] 6 | 7 | jobs: 8 | pypi: 9 | timeout-minutes: 10 10 | runs-on: ubuntu-latest 11 | steps: 12 | - name: Checkout repository 13 | uses: actions/checkout@v4 14 | - name: Setup Python 3.10 15 | uses: actions/setup-python@v5 16 | with: 17 | python-version: '3.10' 18 | architecture: 'x64' 19 | - name: Install dependencies 20 | run: | 21 | python -m pip install --progress-bar off --upgrade pip setuptools wheel 22 | python -m pip install --progress-bar off .[build] 23 | - name: Build and publish 24 | env: 25 | TWINE_USERNAME: __token__ 26 | TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }} 27 | run: | 28 | python -m build 29 | twine upload dist/* 30 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | # 2 | misc 3 | deprecated 4 | testing 5 | 6 | # macOS 7 | .DS_Store 8 | 9 | # 10 | .flake8 11 | 12 | # 13 | .ipynb_checkpoints 14 | 15 | # Byte-compiled / optimized / DLL files 16 | __pycache__/ 17 | *.py[cod] 18 | *$py.class 19 | 20 | # C extensions 21 | *.so 22 | 23 | # Distribution / packaging 24 | .Python 25 | build/ 26 | develop-eggs/ 27 | dist/ 28 | downloads/ 29 | eggs/ 30 | .eggs/ 31 | lib/ 32 | lib64/ 33 | parts/ 34 | sdist/ 35 | var/ 36 | wheels/ 37 | *.egg-info/ 38 | .installed.cfg 39 | *.egg 40 | MANIFEST 41 | -------------------------------------------------------------------------------- /CHANGES.md: -------------------------------------------------------------------------------- 1 | # Changelog 2 | =========== 3 | 4 | This is a document summarizing the changes that are associated with (major) updates and releases. Priority is given to changes that are relevant to the user, and those that introduce new features or break compatibility with prior versions. 5 | 6 | ## Version 2.1.0 7 | 8 | - Added group-only, no-group options to allow for running the scripts at the individual or group level only. Default is to run at both levels. 9 | - Added status file and skip-existing option to allow for incremental updates of a given output directory; additional cases or additional modules will be added. Existing ones will not be recomputed. 10 | 11 | ## Version 2.0.2 12 | 13 | - This fixes an issue with the outlier module, which did not run for FastSurfer output due to incorrect expectations for names of stats files. 14 | 15 | ## Version 2.0.1 16 | 17 | - This fix addresses two minor issues where output was omitted for the SNR computation and the fornix evaluation whenever hires inputs were used. 18 | 19 | ## Version 2.0.0 20 | 21 | - Name changes for the toolbox, repository, package, and scripts: the toolbox has been renamed to "fsqc tools", the python package name "qatoolspython" has been changed to "fsqc", and the "qatools.py" script has been renamed to "run_fsqc". The github repository is now located at "https://github.com/Deep-MI/fsqc", but requests to the old "https://github.com/Deep-MI/qatools-python" repository will be redirected. 22 | - Name changes for output files (replacing 'qatools' with 'fsqc'). 23 | - Interface changes: importing and running the scripts has changed. In particular, `run_fsqc` is now an executable file and replaces the `qatools` or `qatools.py` command. `run_fsqc()` is now also function that can be used in a Python environment. See [here](https://github.com/Deep-MI/fsqc#usage) for details. 24 | - New names for main and dev branches: the main (default) branch is now called `stable` (was: `freesurfer-module-releases`), and the dev branch is now called `dev` (was: `freesurfer-module-dev`). The old branches will still be kept for a while in a deprecation state, but will not receive further updates or support. 25 | - Screenshots are now in radiological orientation (left is right). Before version 2.0, screenshots were in neurological orientation (left is left). 26 | - Addition of skullstrip, surfaces, hippocampus and hypothalamus modules. 27 | - Improved logging, error handling, and testing frameworks. 28 | - Enhanced containerization support (docker, singularity, dockerhub). 29 | - Updated requirements, easier installation of the package and its dependencies, availability of the package on [pypi.org](https://pypi.org). 30 | - FreeSurfer is no longer required as a dependency (except for the optional 'shape analysis' module, which relies on the brainprint package). 31 | - We do not preserve compatibility with earlier versions. 32 | -------------------------------------------------------------------------------- /CODE_OF_CONDUCT.md: -------------------------------------------------------------------------------- 1 | # Contributor Covenant Code of Conduct 2 | 3 | ## Our Pledge 4 | 5 | In the interest of fostering an open and welcoming environment, we as 6 | contributors and maintainers pledge to making participation in our project and 7 | our community a harassment-free experience for everyone, regardless of age, body 8 | size, disability, ethnicity, sex characteristics, gender identity and expression, 9 | level of experience, education, socioeconomic status, nationality, personal 10 | appearance, race, religion, or sexual identity and orientation. 11 | 12 | ## Our Standards 13 | 14 | Examples of behavior that contributes to creating a positive environment 15 | include: 16 | 17 | * Using welcoming and inclusive language 18 | * Being respectful of differing viewpoints and experiences 19 | * Gracefully accepting constructive criticism 20 | * Focusing on what is best for the community 21 | * Showing empathy towards other community members 22 | 23 | Examples of unacceptable behavior by participants include: 24 | 25 | * The use of sexualized language or imagery and unwelcome sexual attention or 26 | advances 27 | * Trolling, insulting/derogatory comments, and personal or political attacks 28 | * Public or private harassment 29 | * Publishing others' private information, such as a physical or electronic 30 | address, without explicit permission 31 | * Other conduct which could reasonably be considered inappropriate in a 32 | professional setting 33 | 34 | ## Our Responsibilities 35 | 36 | Project maintainers are responsible for clarifying the standards of acceptable 37 | behavior and are expected to take appropriate and fair corrective action in 38 | response to any instances of unacceptable behavior. 39 | 40 | Project maintainers have the right and responsibility to remove, edit, or 41 | reject comments, commits, code, wiki edits, issues, and other contributions 42 | that are not aligned to this Code of Conduct, or to ban temporarily or 43 | permanently any contributor for other behaviors that they deem inappropriate, 44 | threatening, offensive, or harmful. 45 | 46 | ## Scope 47 | 48 | This Code of Conduct applies both within project spaces and in public spaces 49 | when an individual is representing the project or its community. Examples of 50 | representing a project or community include using an official project e-mail 51 | address, posting via an official social media account, or acting as an appointed 52 | representative at an online or offline event. Representation of a project may be 53 | further defined and clarified by project maintainers. 54 | 55 | ## Enforcement 56 | 57 | Instances of abusive, harassing, or otherwise unacceptable behavior may be 58 | reported by contacting the project team at any of the mail addresses listed 59 | here: https://deep-mi.org/members/ (e.g. kersten.diers (at) dzne.de and 60 | martin.reuter (at) dzne.de). All complaints will be reviewed and 61 | investigated and will result in a response that is deemed necessary and 62 | appropriate to the circumstances. The project team is obligated to maintain 63 | confidentiality with regard to the reporter of an incident. Further details 64 | of specific enforcement policies may be posted separately. 65 | 66 | Project maintainers who do not follow or enforce the Code of Conduct in good 67 | faith may face temporary or permanent repercussions as determined by other 68 | members of the project's leadership. 69 | 70 | ## Attribution 71 | 72 | This Code of Conduct was adapted from the [Contributor Covenant][homepage], version 1.4, 73 | available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html 74 | 75 | [homepage]: https://www.contributor-covenant.org 76 | 77 | For answers to common questions about this code of conduct, see 78 | https://www.contributor-covenant.org/faq 79 | -------------------------------------------------------------------------------- /CONTRIBUTING.md: -------------------------------------------------------------------------------- 1 | # Contributing to the fsqc tools 2 | 3 | All types of contributions are encouraged and valued. The community looks forward to your contributions. 4 | 5 | ## Reporting Bugs 6 | 7 | ### Before Submitting a Bug Report 8 | 9 | Please complete the following steps in advance to help us fix any potential bug as fast as possible. 10 | 11 | - Make sure that you are using the latest version. 12 | - Determine if your bug is really a bug and not an error on your side e.g. using incompatible environment components/versions. 13 | - To see if other users have experienced (and potentially already solved) the same issue you are having, check if there is not already a bug report existing for your bug or error in the [bug tracker](issues?q=label%3Abug). 14 | - Collect information about the bug: 15 | - OS and package version 16 | - Possibly your input and the output 17 | - Can you reliably reproduce the issue? 18 | 19 | ### How Do I Submit a Good Bug Report? 20 | 21 | We use GitHub issues to track bugs and errors. If you run into an issue with the project: 22 | 23 | - Open an [Issue](issues/new). (Since we can't be sure at this point whether it is a bug or not, we ask you not to talk about a bug yet and not to label the issue.) 24 | - Explain the behavior you would expect and the actual behavior. 25 | - Please provide as much context as possible and describe the *reproduction steps* that someone else can follow to recreate the issue on their own. 26 | - Provide the information you collected in the previous section. 27 | 28 | Once it's filed: 29 | 30 | - The project team will label the issue accordingly. 31 | - A team member will try to reproduce the issue with your provided steps. If there are no reproduction steps or no obvious way to reproduce the issue, the team will ask you for those steps and mark the issue as `needs-repro`. Bugs with the `needs-repro` tag will not be addressed until they are reproduced. 32 | - If the team is able to reproduce the issue, it will be marked `needs-fix`, as well as possibly other tags (such as `critical`). 33 | 34 | ## Suggesting Enhancements 35 | 36 | Please follow these guidelines to help maintainers and the community to understand your suggestion for enhancements. 37 | 38 | ### Before Submitting an Enhancement 39 | 40 | - Make sure that you are using the latest version. 41 | - Read the documentation carefully and find out if the functionality is already covered, maybe by an individual configuration. 42 | - Perform a [search](issues) to see if the enhancement has already been suggested. If it has, add a comment to the existing issue instead of opening a new one. 43 | - Find out whether your idea fits with the scope and aims of the project. 44 | 45 | ### How Do I Submit a Good Enhancement Suggestion? 46 | 47 | Enhancement suggestions are tracked as [GitHub issues](issues). 48 | 49 | - Use a **clear and descriptive title** for the issue to identify the suggestion. 50 | - Provide a **step-by-step description of the suggested enhancement** in as many details as possible. 51 | - **Describe the current behavior** and **explain which behavior you expected to see instead** and why. 52 | - **Explain why this enhancement would be useful** to most users. 53 | 54 | ## Attribution 55 | 56 | This guide is based on the **contributing-gen**. [Make your own](https://github.com/bttger/contributing-gen)! 57 | -------------------------------------------------------------------------------- /DESCRIPTION.md: -------------------------------------------------------------------------------- 1 | # fsqc toolbox 2 | 3 | ## Description 4 | 5 | This package provides quality assurance / quality control scripts for FastSurfer- or 6 | FreeSurfer-processed structural MRI data. 7 | 8 | It is a revision, extension, and translation to the Python language of the 9 | [Freesurfer QA Tools](https://surfer.nmr.mgh.harvard.edu/fswiki/QATools). It has 10 | been augmented by additional functions from the [MRIQC toolbox](https://github.com/poldracklab/mriqc), 11 | and with code derived from the [LaPy](https://github.com/Deep-MI/lapy) and 12 | [BrainPrint](https://github.com/Deep-MI/brainprint) toolboxes. 13 | 14 | The core functionality of this toolbox is to compute the following features: 15 | 16 | variable | description 17 | ---------------|---------------------------------------------------------------- 18 | subject | subject ID 19 | wm_snr_orig | signal-to-noise ratio for white matter in orig.mgz 20 | gm_snr_orig | signal-to-noise ratio for gray matter in orig.mgz 21 | wm_snr_norm | signal-to-noise ratio for white matter in norm.mgz 22 | gm_snr_norm | signal-to-noise ratio for gray matter in norm.mgz 23 | cc_size | relative size of the corpus callosum 24 | lh_holes | number of holes in the left hemisphere 25 | rh_holes | number of holes in the right hemisphere 26 | lh_defects | number of defects in the left hemisphere 27 | rh_defects | number of defects in the right hemisphere 28 | topo_lh | topological fixing time for the left hemisphere 29 | topo_rh | topological fixing time for the right hemisphere 30 | con_lh_snr | wm/gm contrast signal-to-noise ratio in the left hemisphere 31 | con_rh_snr | wm/gm contrast signal-to-noise ratio in the right hemisphere 32 | rot_tal_x | rotation component of the Talairach transform around the x axis 33 | rot_tal_y | rotation component of the Talairach transform around the y axis 34 | rot_tal_z | rotation component of the Talairach transform around the z axis 35 | 36 | The program will use an existing output directory (or try to create it) and 37 | write a csv table into that location. The csv table will contain the above 38 | metrics plus a subject identifier. 39 | 40 | The program can also be run on images that were processed with [FastSurfer](https://github.com/Deep-MI/FastSurfer) 41 | (v1.1 or later) instead of FreeSurfer. In that case, simply add a `--fastsurfer` 42 | switch to your shell command. Note that FastSurfer's full processing stream must 43 | have been run, including surface reconstruction (i.e. brain segmentation alone 44 | is not sufficient). 45 | 46 | In addition to the core functionality of the toolbox there are several optional 47 | modules that can be run according to need: 48 | 49 | - screenshots module 50 | 51 | This module allows for the automated generation of cross-sections of the brain 52 | that are overlaid with the anatomical segmentations (asegs) and the white and 53 | pial surfaces. These images will be saved to the 'screenshots' subdirectory 54 | that will be created within the output directory. These images can be used for 55 | quickly glimpsing through the processing results. Note that no display manager 56 | is required for this module, i.e. it can be run on a remote server, for example. 57 | 58 | - surfaces module 59 | 60 | This module allows for the automated generation of surface renderings of the 61 | left and right pial and inflated surfaces, overlaid with the aparc annotation. 62 | These images will be saved to the 'surfaces' subdirectory that will be created 63 | within the output directory. These images can be used for quickly glimpsing 64 | through the processing results. Note that no display manager is required for 65 | this module, i.e. it can be run on a remote server, for example. 66 | 67 | - skullstrip module 68 | 69 | This module allows for the automated generation cross-sections of the brain 70 | that are overlaid with the colored and semi-transparent brainmask. This allows 71 | to check the quality of the skullstripping in FreeSurfer. The resulting images 72 | will be saved to the 'skullstrip' subdirectory that will be created within the 73 | output directory. 74 | 75 | - fornix module 76 | 77 | This is a module to assess potential issues with the segmentation of the 78 | corpus callosum, which may incorrectly include parts of the fornix. To assess 79 | segmentation quality, a screenshot of the contours of the corpus callosum 80 | segmentation overlaid on the norm.mgz will be saved as 'cc.png' for each 81 | subject within the 'fornix' subdirectory of the output directory. 82 | 83 | - modules for the amygdala, hippocampus, and hypothalamus 84 | 85 | These modules evaluate potential missegmentations of the amygdala, hippocampus, 86 | and hypothalamus. To assess segmentation quality, screenshots will be created 87 | These modules require prior processing of the MR images with FreeSurfer's 88 | dedicated toolboxes for the segmentation of the amygdala and hippocampus, and 89 | the hypothalamus, respectively. 90 | 91 | - shape module 92 | 93 | The shape module will run a shapeDNA / brainprint analysis to compute distances 94 | of shape descriptors between lateralized brain structures. This can be used 95 | to identify discrepancies and irregularities between pairs of corresponding 96 | structures. The results will be included in the main csv table, and the output 97 | directory will also contain a 'brainprint' subdirectory. 98 | 99 | - outlier module 100 | 101 | This is a module to detect extreme values among the subcortical ('aseg') 102 | segmentations as well as the cortical parcellations. If present, hypothalamic 103 | and hippocampal subsegmentations will also be included. 104 | 105 | The outlier detection is based on comparisons with the 106 | distributions of the sample as well as normative values taken from the 107 | literature (see References). 108 | 109 | For comparisons with the sample distributions, extreme values are defined in 110 | two ways: nonparametrically, i.e. values that are 1.5 times the interquartile 111 | range below or above the 25th or 75th percentile of the sample, respectively, 112 | and parametrically, i.e. values that are more than 2 standard deviations above 113 | or below the sample mean. Note that a minimum of 10 supplied subjects is 114 | required for running these analyses, otherwise `NaNs` will be returned. 115 | 116 | For comparisons with the normative values, lower and upper bounds are computed 117 | from the 95% prediction intervals of the regression models given in Potvin et 118 | al., 1996, and values exceeding these bounds will be flagged. As an 119 | alternative, users may specify their own normative values by using the 120 | '--outlier-table' argument. This requires a custom csv table with headers 121 | `label`, `upper`, and `lower`, where `label` indicates a column of anatomical 122 | names. It can be a subset and the order is arbitrary, but naming must exactly 123 | match the nomenclature of the 'aseg.stats' and/or '[lr]h.aparc.stats' file. 124 | If cortical parcellations are included in the outlier table for a comparison 125 | with aparc.stats values, the labels must have a 'lh.' or 'rh.' prefix. file. 126 | `upper` and `lower` are user-specified upper and lower bounds. 127 | 128 | The main csv table will be appended with the following summary variables, and 129 | more detailed output about will be saved as csv tables in the 'outliers' 130 | subdirectory of the main output directory. 131 | 132 | variable | description 133 | -------------------------|--------------------------------------------------- 134 | n_outliers_sample_nonpar | number of structures that are 1.5 times the IQR above/below the 75th/25th percentile 135 | n_outliers_sample_param | number of structures that are 2 SD above/below the mean 136 | n_outliers_norms | number of structures exceeding the upper and lower bounds of the normative values 137 | 138 | ___ 139 | 140 | ## Usage 141 | 142 | ### As a command line tool 143 | 144 | ``` 145 | run_fsqc --subjects_dir --output_dir 146 | [--subjects SubjectID [SubjectID ...]] 147 | [--subjects-file ] [--screenshots] 148 | [--screenshots-html] [--surfaces] [--surfaces-html] 149 | [--skullstrip] [--skullstrip-html] 150 | [--fornix] [--fornix-html] [--hippocampus] 151 | [--hippocampus-html] [--hippocampus-label ... ] 152 | [--hypothalamus] [--hypothalamus-html] [--shape] 153 | [--outlier] [--fastsurfer] [--exit-on-error] 154 | [--skip-existing] [-h] [--more-help] 155 | [...] 156 | 157 | 158 | required arguments: 159 | --subjects_dir 160 | subjects directory with a set of Freesurfer- or 161 | Fastsurfer-processed individual datasets. 162 | --output_dir 163 | output directory 164 | 165 | optional arguments: 166 | --subjects SubjectID [SubjectID ...] 167 | list of subject IDs 168 | --subjects-file filename of a file with subject IDs (one per line) 169 | --screenshots create screenshots of individual brains 170 | --screenshots-html create screenshots of individual brains incl. 171 | html summary page 172 | --surfaces create screenshots of individual brain surfaces 173 | --surfaces-html create screenshots of individual brain surfaces 174 | and html summary page 175 | --skullstrip create screenshots of individual brainmasks 176 | --skullstrip-html create screenshots of individual brainmasks and 177 | html summary page 178 | --fornix check fornix segmentation 179 | --fornix-html check fornix segmentation and create html summary 180 | page of fornix evaluation 181 | --hypothalamus check hypothalamic segmentation 182 | --hypothalamus-html check hypothalamic segmentation and create html 183 | summary page 184 | --hippocampus check segmentation of hippocampus and amygdala 185 | --hippocampus-html check segmentation of hippocampus and amygdala 186 | and create html summary page 187 | --hippocampus-label specify label for hippocampus segmentation files 188 | (default: T1.v21). The full filename is then 189 | [lr]h.hippoAmygLabels-