{"id":13689127,"url":"https://github.com/HALFpipe/HALFpipe","last_synced_at":"2025-05-01T23:32:21.374Z","repository":{"id":37098019,"uuid":"276106570","full_name":"HALFpipe/HALFpipe","owner":"HALFpipe","description":"ENIGMA HALFpipe is a user-friendly software that facilitates reproducible analysis of fMRI data","archived":false,"fork":false,"pushed_at":"2024-11-11T15:58:49.000Z","size":7389,"stargazers_count":74,"open_issues_count":97,"forks_count":13,"subscribers_count":4,"default_branch":"main","last_synced_at":"2024-11-11T16:41:12.926Z","etag":null,"topics":["bids","fmri","meta-analysis","neuroimaging","pipeline","reproducibility"],"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/HALFpipe.png","metadata":{"files":{"readme":"README.rst","changelog":"CHANGELOG.rst","contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-06-30T13:27:55.000Z","updated_at":"2024-10-29T06:47:18.000Z","dependencies_parsed_at":"2023-10-25T06:46:08.843Z","dependency_job_id":"fed8f9ec-67dc-4bdc-ab13-fb092c0734bc","html_url":"https://github.com/HALFpipe/HALFpipe","commit_stats":null,"previous_names":[],"tags_count":16,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HALFpipe%2FHALFpipe","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HALFpipe%2FHALFpipe/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HALFpipe%2FHALFpipe/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HALFpipe%2FHALFpipe/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/HALFpipe","download_url":"https://codeload.github.com/HALFpipe/HALFpipe/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224282131,"owners_count":17285776,"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","fmri","meta-analysis","neuroimaging","pipeline","reproducibility"],"created_at":"2024-08-02T15:01:34.584Z","updated_at":"2024-11-12T13:30:49.362Z","avatar_url":"https://github.com/HALFpipe.png","language":"Python","funding_links":[],"categories":["Python","Pipelines"],"sub_categories":["BOLD"],"readme":"################################\n Welcome to ENIGMA ``HALFpipe``\n################################\n\n.. image:: https://github.com/HALFpipe/HALFpipe/actions/workflows/continuous_integration.yml/badge.svg\n   :target: https://github.com/HALFpipe/HALFpipe/actions/workflows/continuous_integration.yml\n\n.. image:: https://codecov.io/gh/HALFpipe/HALFpipe/branch/main/graph/badge.svg\n   :target: https://codecov.io/gh/HALFpipe/HALFpipe\n\n.. image:: https://zenodo.org/badge/DOI/10.5281/zenodo.5657185.svg\n   :target: https://doi.org/10.5281/zenodo.5657185\n\n``HALFpipe`` is a user-friendly software that facilitates reproducible\nanalysis of fMRI data, including preprocessing, single-subject, and\ngroup analysis. It provides state-of-the-art preprocessing using\n`fmriprep \u003chttps://fmriprep.readthedocs.io/\u003e`__, but removes the\nnecessity to convert data to the `BIDS\n\u003chttps://bids-specification.readthedocs.io/en/stable/\u003e`__ format. Common\nresting-state and task-based fMRI features can then be calculated on the\nfly.\n\n`HALFpipe` relies on tools from well-established neuroimaging software\npackages, either directly or through our dependencies, including `ANTs\n\u003chttps://antspy.readthedocs.io/\u003e`__, `FreeSurfer\n\u003chttps://surfer.nmr.mgh.harvard.edu/\u003e`__,  `FSL \u003chttp://fsl.fmrib.ox.ac.uk/\u003e`__,\n`AFNI \u003chttps://afni.nimh.nih.gov/\u003e`__ and `nipype \u003chttps://nipype.readthedocs.io/\u003e`__.\nWe strongly urge users to acknowledge these tools when publishing results obtained\nwith HALFpipe.\n\n   Subscribe to our `mailing list \u003chttps://mailman.charite.de/mailman/listinfo/halfpipe-announcements\u003e`_ to stay up to date with new developments and releases.\n\n..\n\n   If you encounter issues, please see the `troubleshooting\n   \u003c#troubleshooting\u003e`__ section of this document.\n\n..\n\n   Some sections of this document are marked as outdated. While we are\n   working on updating them, the `paper \u003chttps://doi.org/hmts\u003e`__\n   and the `analysis manual\n   \u003chttps://docs.google.com/document/d/108-XBIuwtJziRVVdOQv73MRgtK78wfc-NnVu-jSc9oI/edit#heading=h.3y6rt7h7o483\u003e`__\n   should be able to answer most questions.\n\n*******************\n Table of Contents\n*******************\n\n.. raw:: html\n\n   \u003c!-- toc --\u003e\n\n-  `Getting started \u003c#getting-started\u003e`__\n\n   -  `Container platform \u003c#container-platform\u003e`__\n   -  `Download \u003c#download\u003e`__\n   -  `Running \u003c#running\u003e`__\n\n-  `User interface \u003c#user-interface\u003e`__\n\n   -  `Files \u003c#files\u003e`__\n   -  `Features \u003c#features\u003e`__\n   -  `Models \u003c#models\u003e`__\n\n-  `Running on a high-performance computing cluster\n   \u003c#running-on-a-high-performance-computing-cluster\u003e`__\n\n-  `Quality checks \u003c#quality-checks\u003e`__\n\n-  `Outputs \u003c#outputs\u003e`__\n\n   -  `Subject-level features \u003c#subject-level-features\u003e`__\n   -  `Preprocessed images \u003c#preprocessed-images\u003e`__\n   -  `Group-level \u003c#group-level\u003e`__\n\n-  `Troubleshooting \u003c#troubleshooting\u003e`__\n\n-  `Command line flags \u003c#command-line-flags\u003e`__\n\n   -  `Control command line logging \u003c#control-command-line-logging\u003e`__\n   -  `Automatically remove unneeded files\n      \u003c#automatically-remove-unneeded-files\u003e`__\n   -  `Adjust nipype \u003c#adjust-nipype\u003e`__\n   -  `Choose which parts to run or to skip\n      \u003c#choose-which-parts-to-run-or-to-skip\u003e`__\n   -  `Working directory \u003c#working-directory\u003e`__\n   -  `Data file system root \u003c#data-file-system-root\u003e`__\n\n-  `Contact \u003c#contact\u003e`__\n\n.. raw:: html\n\n   \u003c!-- tocstop --\u003e\n\n*****************\n Getting started\n*****************\n\n``HALFpipe`` is distributed as a container, meaning that all required\nsoftware comes bundled in a monolithic file, the container. This allows\nfor easy installation on new systems, and makes data analysis more\nreproducible, because software versions are guaranteed to be the same\nfor all users.\n\nContainer platform\n==================\n\nThe first step is to install one of the supported container platforms.\nIf you’re using a high-performance computing cluster, more often than\nnot `Singularity \u003chttps://sylabs.io\u003e`__ will already be available.\n\nIf not, we recommend using the latest version of\\ `Singularity\n\u003chttps://sylabs.io\u003e`__. However, it can be somewhat cumbersome to\ninstall, as it needs to be built from source.\n\nThe `NeuroDebian \u003chttps://neuro.debian.net/\u003e`__ package repository\nprovides an older version of `Singularity\n\u003chttps://sylabs.io/guides/2.6/user-guide/\u003e`__ for `some\n\u003chttps://neuro.debian.net/pkgs/singularity-container.html\u003e`__ Linux\ndistributions.\n\nIf you are running ``mac OS``, then you should be able to run the\ncontainer with ``Docker Desktop``.\n\nIf you are running Windows, you can also try running with ``Docker\nDesktop``, but we have not done any compatibility testing yet, so issues\nmay occur, for example with respect to file systems.\n\n.. list-table::\n   :header-rows: 1\n\n   -  -  Container platform\n      -  Version\n      -  Installation\n\n   -  -  Singularity\n      -  3.x\n      -  https://sylabs.io/guides/3.8/user-guide/quick_start.html\n\n   -  -  Singularity\n      -  2.x\n      -  ``sudo apt install singularity-container``\n\n   -  -  Docker\n      -  ..\n      -  See https://docs.docker.com/engine/install/\n\nDownload\n========\n\nThe second step is to download the ``HALFpipe`` to your computer. This\nrequires approximately 5 gigabytes of storage.\n\n.. list-table::\n   :header-rows: 1\n\n   -  -  Container platform\n      -  Version\n      -  Installation\n\n   -  -  Singularity\n      -  3.x\n      -  https://download.fmri.science/singularity/halfpipe-latest.sif\n\n   -  -  Singularity\n      -  2.x\n      -  https://download.fmri.science/singularity/halfpipe-latest.simg\n\n   -  -  Docker\n      -  ..\n      -  ``docker pull halfpipe/halfpipe:latest``\n\n``Singularity`` version ``3.x`` creates a container image file called\n``HALFpipe_{version}.sif`` in the directory where you run the ``pull``\ncommand. For ``Singularity`` version ``2.x`` the file is named\n``halfpipe-halfpipe-master-latest.simg``. Whenever you want to use the\ncontainer, you need pass ``Singularity`` the path to this file.\n\n   **NOTE:** ``Singularity`` may store a copy of the container in its\n   cache directory. The cache directory is located by default in your\n   home directory at ``~/.singularity``. If you need to save disk space\n   in your home directory, you can safely delete the cache directory\n   after downloading, i.e. by running ``rm -rf ~/.singularity``.\n   Alternatively, you could move the cache directory somewhere with more\n   free disk space using a symlink. This way, files will automatically\n   be stored there in the future. For example, if you have a lot of free\n   disk space in ``/mnt/storage``, then you could first run ``mv\n   ~/.singularity /mnt/storage`` to move the cache directory, and then\n   ``ln -s /mnt/storage/.singularity ~/.singularity`` to create the\n   symlink.\n\n``Docker`` will store the container in its storage base directory, so it\ndoes not matter from which directory you run the ``pull`` command.\n\nRunning\n=======\n\nThe third step is to run the downloaded container. You may need to\nreplace ``halfpipe-halfpipe-latest.simg`` with the actual path and\nfilename where ``Singularity`` downloaded your container.\n\n.. list-table::\n   :header-rows: 1\n\n   -  -  Container platform\n      -  Command\n\n   -  -  Singularity\n      -  ``singularity run --containall --bind /:/ext\n         halfpipe-halfpipe-latest.simg``\n\n   -  -  Docker\n      -  ``docker run --interactive --tty --volume /:/ext\n         halfpipe/halfpipe``\n\nYou should now see the user interface.\n\nBackground\n----------\n\nContainers are by default isolated from the host computer. This adds\nsecurity, but also means that the container cannot access the data it\nneeds for analysis. ``HALFpipe`` expects all inputs (e.g., image files\nand spreadsheets) and outputs (the working directory) to be places in\nthe path\\ ``/ext`` (see also ```--fs-root``\n\u003c#data-file-system-root---fs-root\u003e`__). Using the option ``--bind\n/:/ext``, we instruct ``Singularity`` to map all of the host file system\n(``/``) to that path (``/ext``). You can also run ``HALFpipe`` and only\nmap only part of the host file system, but keep in mind that any\ndirectories that are not mapped will not be visible later.\n\n``Singularity`` passes the host shell environment to the container by\ndefault. This means that in some cases, the host computer’s\nconfiguration can interfere with the software. To avoid this, we need to\npass the option ``--containall``. ``Docker`` does not pass the host\nshell environment by default, so we don’t need to pass an option.\n\n****************\n User interface\n****************\n\n   Outdated\n\nThe user interface asks a series of questions about your data and the\nanalyses you want to run. In each question, you can press ``Control+C``\nto cancel the current question and go back to the previous one.\n``Control+D`` exits the program without saving. Note that these keyboard\nshortcuts are the same on Mac.\n\nFiles\n=====\n\nTo run preprocessing, at least a T1-weighted structural image and a BOLD\nimage file is required. Preprocessing and data analysis proceeds\nautomatically. However, to be able to run automatically, data files need\nto be input in a way suitable for automation.\n\nFor this kind of automation, ``HALFpipe`` needs to know the\nrelationships between files, such as which files belong to the same\nsubject. However, even though it would be obvious for a human, a program\ncannot easily assign a file name to a subject, and this will be true as\nlong as there are differences in naming between different researchers or\nlabs. One researcher may name the same file ``subject_01_rest.nii.gz``\nand another ``subject_01/scan_rest.nii.gz``.\n\nIn ``HALFpipe``, we solve this issue by inputting file names in a\nspecific way. For example, instead of ``subject_01/scan_rest.nii.gz``,\n``HALFpipe`` expects you to input ``{subject}/scan_rest.nii.gz``.\n``HALFpipe`` can then match all files on disk that match this naming\nschema, and extract the subject ID ``subject_01``. Using the extracted\nsubject ID, other files can now be matched to this image. If all input\nfiles are available in BIDS format, then this step can be skipped.\n\n#. ``Specify working directory`` All intermediate and outputs of\n   ``HALFpipe`` will be placed in the working directory. Keep in mind to\n   choose a location with sufficient free disk space, as intermediates\n   can be multiple gigabytes in size for each subject.\n\n#. ``Is the data available in BIDS format?``\n\n   -  ``Yes``\n\n      #. ``Specify the path of the BIDS directory``\n\n   -  ``No``\n\n      #. ``Specify anatomical/structural data`` ``Specify the path of\n         the T1-weighted image files``\n\n      #. ``Specify functional data`` ``Specify the path of the BOLD\n         image files``\n\n      #. ``Check repetition time values`` / ``Specify repetition time in\n         seconds``\n\n      #. ``Add more BOLD image files?``\n\n         -  ``Yes`` Loop back to 2\n         -  ``No`` Continue\n\n#. ``Do slice timing?``\n\n   -  ``Yes``\n\n      #. ``Check slice acquisition direction values``\n      #. ``Check slice timing values``\n\n   -  ``No`` Skip this step\n\n#. ``Specify field maps?`` If the data was imported from a BIDS\n   directory, this step will be omitted.\n\n   -  ``Yes``\n\n      #. ``Specify the type of the field maps``\n\n         -  EPI (blip-up blip-down)\n\n            #. ``Specify the path of the blip-up blip-down EPI image\n               files``\n\n         -  Phase difference and magnitude (used by Siemens scanners)\n\n            #. ``Specify the path of the magnitude image files``\n            #. ``Specify the path of the phase/phase difference image\n               files``\n            #. ``Specify echo time difference in seconds``\n\n         -  Scanner-computed field map and magnitude (used by GE /\n            Philips scanners)\n\n            #. ``Specify the path of the magnitude image files``\n            #. ``Specify the path of the field map image files``\n\n      #. ``Add more field maps?`` Loop back to 1\n\n      #. ``Specify effective echo spacing for the functional data in\n         seconds``\n\n      #. ``Specify phase encoding direction for the functional data``\n\n   -  ``No`` Skip this step\n\nFeatures\n========\n\nFeatures are analyses that are carried out on the preprocessed data, in\nother words, first-level analyses.\n\n#. ``Specify first-level features?``\n\n   -  ``Yes``\n\n      #. ``Specify the feature type``\n\n         -  ``Task-based``\n\n            #. ``Specify feature name``\n            #. ``Specify images to use``\n            #. ``Specify the event file type``\n\n            -  ``SPM multiple conditions`` A MATLAB .mat file containing\n               three arrays: ``names`` (condition), ``onsets`` and\n               ``durations``\n\n            -  ``FSL 3-column`` One text file for each condition. Each\n               file has its corresponding condition in the filename. The\n               first column specifies the event onset, the second the\n               duration. The third column of the files is ignored, so\n               parametric modulation is not supported\n\n            -  ``BIDS TSV`` A tab-separated table with named columns\n               ``trial_type`` (condition), ``onset`` and ``duration``.\n               While BIDS supports defining additional columns,\n               ``HALFpipe`` will currently ignore these\n\n            #. ``Specify the path of the event files``\n\n            #. ``Select conditions to add to the model``\n\n            #. ``Specify contrasts``\n\n               #. ``Specify contrast name``\n\n               #. ``Specify contrast values``\n\n               #. ``Add another contrast?``\n\n                  -  ``Yes`` Loop back to 1\n                  -  ``No`` Continue\n\n            #. ``Apply a temporal filter to the design matrix?`` A\n               separate temporal filter can be specified for the design\n               matrix. In contrast, the temporal filtering of the input\n               image and any confound regressors added to the design\n               matrix is specified in 10. In general, the two settings\n               should match\n\n            #. ``Apply smoothing?``\n\n               -  ``Yes``\n\n                  #. ``Specify smoothing FWHM in mm``\n\n               -  ``No`` Continue\n\n            #. ``Grand mean scaling will be applied with a mean of\n               10000.000000``\n\n            #. ``Temporal filtering will be applied using a\n               gaussian-weighted filter`` ``Specify the filter width in\n               seconds``\n\n            #. ``Remove confounds?``\n\n         -  ``Seed-based connectivity``\n\n            #. ``Specify feature name``\n\n            #. ``Specify images to use``\n\n            #. ``Specify binary seed mask file(s)``\n\n               #. ``Specify the path of the binary seed mask image\n                  files``\n               #. ``Check space values``\n               #. ``Add binary seed mask image file``\n\n         -  ``Dual regression``\n\n            #. ``Specify feature name``\n            #. ``Specify images to use``\n            #. TODO\n\n         -  ``Atlas-based connectivity matrix``\n\n            #. ``Specify feature name``\n            #. ``Specify images to use``\n            #. TODO\n\n         -  ``ReHo``\n\n            #. ``Specify feature name``\n            #. ``Specify images to use``\n            #. TODO\n\n         -  ``fALFF``\n\n            #. ``Specify feature name``\n            #. ``Specify images to use``\n            #. TODO\n\n   -  ``No`` Skip this step\n\n#. ``Add another first-level feature?``\n\n   -  ``Yes`` Loop back to 1\n   -  ``No`` Continue\n\n#. ``Output a preprocessed image?``\n\n   -  ``Yes``\n\n      #. ``Specify setting name``\n\n      #. ``Specify images to use``\n\n      #. ``Apply smoothing?``\n\n         -  ``Yes``\n\n            #. ``Specify smoothing FWHM in mm``\n\n         -  ``No`` Continue\n\n      #. ``Do grand mean scaling?``\n\n         -  ``Yes``\n\n            #. ``Specify grand mean``\n\n         -  ``No`` Continue\n\n      #. ``Apply a temporal filter?``\n\n         -  ``Yes``\n\n            #. ``Specify the type of temporal filter``\n\n               -  ``Gaussian-weighted``\n               -  ``Frequency-based``\n\n         -  ``No`` Continue\n\n      #. ``Remove confounds?``\n\n   -  ``No`` Continue\n\nModels\n======\n\nModels are statistical analyses that are carried out on the features.\n\n   TODO\n\n*************************************************\n Running on a high-performance computing cluster\n*************************************************\n\n#. Log in to your cluster’s head node\n\n#. Request an interactive job. Refer to your cluster’s documentation for\n   how to do this\n\n#. |  In the interactive job, run the ``HALFpipe`` user interface, but\n      add the flag ``--use-cluster`` to the end of the command.\n   |  For example, ``singularity run --containall --bind /:/ext\n      halfpipe-halfpipe-latest.sif --use-cluster``\n\n#. As soon as you finish specifying all your data, features and models\n   in the user interface, ``HALFpipe`` will now generate everything\n   needed to run on the cluster. For hundreds of subjects, this can take\n   up to a few hours.\n\n#. When ``HALFpipe`` exits, edit the generated submit script\n   ``submit.slurm.sh`` according to your cluster’s documentation and\n   then run it. This submit script will calculate everything except\n   group statistics.\n\n#. As soon as all processing has been completed, you can run group\n   statistics. This is usually very fast, so you can do this in an\n   interactive session. Run ``singularity run --containall --bind /:/ext\n   halfpipe-halfpipe-latest.sif --only-model-chunk`` and then select\n   ``Run without modification`` in the user interface.\n\n..\n\n   A common issue with remote work via secure shell is that the\n   connection may break after a few hours. For batch jobs this is not an\n   issue, but for interactive jobs this can be quite frustrating. When\n   the connection is lost, the node you were connected to will\n   automatically quit all programs you were running. To prevent this,\n   you can run interactive jobs within ``screen`` or ``tmux`` (whichever\n   is available). These commands allow you to open sessions in the\n   terminal that will continue running in the background even when you\n   close or disconnect. Here’s a quick overview of how to use the\n   commands (more in-depth documentation is available for example at\n   http://www.dayid.org/comp/tm.html).\n\n   #. Open a new screen/tmux session on the head node by running either\n      ``screen`` or ``tmux``\n\n   #. Request an interactive job from within the session, for example\n      with ``srun --pty bash -i``\n\n   #. Run the command that you want to run\n\n   #. Detach from the screen/tmux session, meaning disconnecting with\n      the ability to re-connect later For screen, this is done by first\n      pressing ``Control+a``, then letting go, and then pressing ``d``\n      on the keyboard. For tmux, it’s ``Control+b`` instead of\n      ``Control+a``. Note that this is always ``Control``, even if\n      you’re on a mac.\n\n   #. Close your connection to the head node with ``Control+d``.\n      ``screen``/``tmux`` will remain running in the background\n\n   #. Later, connect again to the head node. Run ``screen -r`` or ``tmux\n      attach`` to check back on the interactive job. If everything went\n      well and the command you wanted to run finished, close the\n      interactive job with ``Control+d`` and then the\n      ``screen``/``tmux`` session with ``Control+d`` again. If the\n      command hasn’t finished yet, detach as before and come back later\n\n..\n\n    Are you getting a \"missing dependencies\" error? Some clusters configure singularity with an option called `mount hostfs \u003chttps://sylabs.io/guides/3.9/user-guide/bind_paths_and_mounts.html#disabling-system-binds\u003e`_ that will bind all cluster file systems into the container. These file systems may in some cases have paths that conflict with where software is installed in the ``HALFpipe`` container, effectively overwriting that software. You can disable this by adding the option ``--no-mount hostfs`` right after ``singularity run``.\n\n****************\n Quality checks\n****************\n\nPlease see the `manual \u003chttps://drive.google.com/file/d/1TMg9MRvBwZO8HB1UJmH0gm4tYaBVnvcQ/view\u003e`_\n\n*********\n Outputs\n*********\n\n   Outdated\n\n-  A visual report page ``reports/index.html``\n\n-  A table with image quality metrics ``reports/reportvals.txt``\n\n-  A table containing the preprocessing status\n   ``reports/reportpreproc.txt``\n\n-  The untouched ``fmriprep`` derivatives. Some files have been omitted\n   to save disk space ``fmriprep`` is very strict about only processing\n   data that is compliant with the BIDS standard. As such, we may need\n   to format subjects names for compliance. For example, an input\n   subject named ``subject_01`` will appear as ``subject01`` in the\n   ``fmriprep`` derivatives. ``derivatives/fmriprep``\n\nSubject-level features\n======================\n\n-  |  For task-based, seed-based connectivity and dual regression\n      features, ``HALFpipe`` outputs the statistical maps for the\n      effect, the variance, the degrees of freedom of the variance and\n      the z-statistic. In FSL, the effect and variance are also called\n      ``cope`` and ``varcope``\n   |  ``derivatives/halfpipe/sub-.../func/..._stat-effect_statmap.nii.gz``\n   |  ``derivatives/halfpipe/sub-.../func/..._stat-variance_statmap.nii.gz``\n   |  ``derivatives/halfpipe/sub-.../func/..._stat-dof_statmap.nii.gz``\n   |  ``derivatives/halfpipe/sub-.../func/..._stat-z_statmap.nii.gz``\n   |  The design and contrast matrix used for the final model will be\n      outputted alongside the statistical maps\n   |  ``derivatives/halfpipe/sub-.../func/sub-..._task-..._feature-..._desc-design_matrix.tsv``\n   |  ``derivatives/halfpipe/sub-.../func/sub-..._task-..._feature-..._desc-contrast_matrix.tsv``\n\n-  |  ReHo and fALFF are not calculated based on a linear model. As\n      such, only one statistical map of the z-scaled values will be\n      output\n   |  ``derivatives/halfpipe/sub-.../func/..._alff.nii.gz``\n   |  ``derivatives/halfpipe/sub-.../func/..._falff.nii.gz``\n   |  ``derivatives/halfpipe/sub-.../func/..._reho.nii.gz``\n\n-  For every feature, a ``.json`` file containing a summary of the\n   preprocessing\n\n-  |  settings, and a list of the raw data files that were used for the\n      analysis (``RawSources``)\n   |  ``derivatives/halfpipe/sub-.../func/....json``\n\n-  |  For every feature, the corresponding brain mask is output beside\n      the statistical maps. Masks do not differ between different\n      features calculated, they are only copied out repeatedly for\n      convenience\n   |  ``derivatives/halfpipe/sub-.../func/...desc-brain_mask.nii.gz``\n\n-  |  Atlas-based connectivity outputs the time series and the full\n      covariance and correlation matrices as text files\n   |  ``derivatives/halfpipe/sub-.../func/..._timeseries.txt``\n   |  ``derivatives/halfpipe/sub-.../func/..._desc-covariance_matrix.txt``\n   |  ``derivatives/halfpipe/sub-.../func/..._desc-correlation_matrix.txt``\n\nPreprocessed images\n===================\n\n-  |  Masked, preprocessed BOLD image\n   |  ``derivatives/halfpipe/sub-.../func/..._bold.nii.gz``\n\n-  |  Just like for features\n   |  ``derivatives/halfpipe/sub-.../func/..._bold.json``\n\n-  |  Just like for features\n   |  ``derivatives/halfpipe/sub-.../func/sub-..._task-..._setting-..._desc-brain_mask.nii.gz``\n\n-  |  Filtered confounds time series, where all filters that are applied\n      to the BOLD image are applied to the regressors as well. Note that\n      this means that when grand mean scaling is active, confounds time\n      series are also scaled, meaning that values such as ``framewise\n      displacement`` can not be interpreted in terms of their original\n      units anymore.\n   |  ``derivatives/halfpipe/sub-.../func/sub-..._task-..._setting-..._desc-confounds_regressors.tsv``\n\nGroup-level\n===========\n\n-  ``grouplevel/...``\n\n*****************\n Troubleshooting\n*****************\n\n-  If an error occurs, this will be output to the command line and\n   simultaneously to the ``err.txt`` file in the working directory\n\n-  If the error occurs while running, usually a text file detailing the\n   error will be placed in the working directory. These are text files\n   and their file names start with ``crash``\n\n   -  Usually, the last line of these text files contains the error\n      message. Please read this carefully, as may allow you to\n      understand the error\n\n   -  For example, consider the following error message: ``ValueError:\n      shape (64, 64, 33) for image 1 not compatible with first image\n      shape (64, 64, 34) with axis == None`` This error message may seem\n      cryptic at first. However, looking at the message more closely, it\n      suggests that two input images have different, incompatible\n      dimensions. In this case, ``HALFpipe`` correctly recognized this\n      issue, and there is no need for concern. The images in question\n      will simply be excluded from preprocessing and/or analysis\n\n   -  In some cases, the cause of the error can be a bug in the\n      ``HALFpipe`` code. Please check that no similar issue has been\n      reported `here on GitHub\n      \u003chttps://github.com/HALFpipe/HALFpipe/issues\u003e`__. In this case,\n      please submit an `issue\n      \u003chttps://github.com/HALFpipe/HALFpipe/issues/new/choose\u003e`__.\n\n********************\n Command line flags\n********************\n\nControl command line logging\n============================\n\n.. code:: bash\n\n   --verbose\n\nBy default, only errors and warnings will be output to the command line.\nThis makes it easier to see when something goes wrong, because there is\nless output. However, if you want to be able to inspect what is being\nrun, you can add the ``--verbose`` flag to the end of the command used\nto call ``HALFpipe``.\n\nVerbose logs are always written to the ``log.txt`` file in the working\ndirectory, so going back and inspecting this log is always possible,\neven if the ``--verbose`` flag was not specified.\n\nSpecifying the flag ``--debug`` will print additional, fine-grained\nmessages. It will also automatically start the `Python Debugger\n\u003chttps://docs.python.org/3/library/pdb.html\u003e`__ when an error occurs.\nYou should only use ``--debug`` if you know what you’re doing.\n\nAutomatically remove unneeded files\n===================================\n\n.. code:: bash\n\n   --keep\n\n``HALFpipe`` saves intermediate files for each pipeline step. This\nspeeds up re-running with different settings, or resuming after a job\nafter it was cancelled. The intermediate file are saved by the `nipype\n\u003chttps://nipype.readthedocs.io/\u003e`__ workflow engine, which is what\n``HALFpipe`` uses internally. ``nipype`` saves the intermediate files in\nthe ``nipype`` folder in the working directory.\n\nIn environments with limited disk capacity, this can be problematic. To\nlimit disk usage, ``HALFpipe`` can delete intermediate files as soon as\nthey are not needed anymore. This behavior is controlled with the\n``--keep`` flag.\n\nThe default option ``--keep some`` keeps all intermediate files from\nfMRIPrep and MELODIC, which would take the longest to re-run. We believe\nthis is a good tradeoff between disk space and computer time. ``--keep\nall`` turns of all deletion of intermediate files. ``--keep none``\ndeletes as much as possible, meaning that the smallest amount possible\nof disk space will be used.\n\nConfigure nipype\n================\n\n.. code:: bash\n\n   --nipype-\u003comp-nthreads|memory-gb|n-procs|run-plugin\u003e\n\n``HALFpipe`` chooses sensible defaults for all of these values.\n\nChoose which parts to run or to skip\n====================================\n\n   Outdated\n\n.. code:: bash\n\n   --\u003conly|skip\u003e-\u003cspec-ui|workflow|run|model-chunk\u003e\n\nA ``HALFpipe`` run is divided internally into three stages, spec-ui,\nworkflow, and run.\n\n#. The ``spec-ui`` stage is where you specify things in the user\n   interface. It creates the ``spec.json`` file that contains all the\n   information needed to run ``HALFpipe``. To only run this stage, use\n   the option ``--only-spec-ui``. To skip this stage, use the option\n   ``--skip-spec-ui``\n\n#. The ``workflow`` stage is where ``HALFpipe`` uses the ``spec.json``\n   data to search for all the files that match what was input in the\n   user interface. It then generates a ``nipype`` workflow for\n   preprocessing, feature extraction and group models. ``nipype`` then\n   validates the workflow and prepares it for execution. This usually\n   takes a couple of minutes and cannot be parallelized. For hundreds of\n   subjects, this may even take a few hours. This stage has the\n   corresponding option ``--only-workflow`` and ``--skip-workflow``.\n\n-  This stage saves several intermediate files. These are named\n   ``workflow.{uuid}.pickle.xz``, ``execgraph.{uuid}.pickle.xz`` and\n   ``execgraph.{n_chunks}_chunks.{uuid}.pickle.xz``. The ``uuid`` in the\n   file name is a unique identifier generated from the ``spec.json``\n   file and the input files. It is re-calculated every time we run this\n   stage. The uuid algorithm produces a different output if there are\n   any changes (such as when new input files for new subjects become\n   available, or the ``spec.json`` is changed, for example to add a new\n   feature or group model). Otherwise, the ``uuid`` stays the same.\n   Therefore, if a workflow file with the calculated ``uuid`` already\n   exists, then we do not need to run this stage. We can simple reuse\n   the workflow from the existing file, and save some time.\n\n-  In this stage, we can also decide to split the execution into chunks.\n   The flag ``--subject-chunks`` creates one chunk per subject. The flag\n   ``--use-cluster`` automatically activates ``--subject-chunks``. The\n   flag ``--n-chunks`` allows the user to specify a specific number of\n   chunks. This is useful if the execution should be spread over a set\n   number of computers. In addition to these, a model chunk is\n   generated.\n\n#. The ``run`` stage loads the\n   ``execgraph.{n_chunks}_chunks.{uuid}.pickle.xz`` file generated in\n   the previous step and runs it. This file usually contains two chunks,\n   one for the subject level preprocessing and feature extraction\n   (“subject level chunk”), and one for group statistics (“model\n   chunk”). To run a specific chunk, you can use the flags\n   ``--only-chunk-index ...`` and ``--only-model-chunk``.\n\nWorking directory\n=================\n\n.. code:: bash\n\n   --workdir\n\n..\n\n   TODO\n\nData file system root\n=====================\n\n.. code:: bash\n\n   --fs-root\n\nThe ``HALFpipe`` container, or really most containers, contain the\nentire base system needed to run\n\n*********\n Contact\n*********\n\nFor questions or support, please submit an `issue\n\u003chttps://github.com/HALFpipe/HALFpipe/issues/new/choose\u003e`__ or contact\nus via e-mail at enigma@charite.de.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FHALFpipe%2FHALFpipe","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FHALFpipe%2FHALFpipe","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FHALFpipe%2FHALFpipe/lists"}