diff --git a/.zenodo.json b/.zenodo.json deleted file mode 100644 index 6961cdac..00000000 --- a/.zenodo.json +++ /dev/null @@ -1,90 +0,0 @@ -{ - "contributors": [ - { - "name": "Cieslak, Matthew", - "affiliation": "Department of Neuropsychiatry, University of Pennsylvania", - "orcid": "0000-0002-1931-4734" - }, - { - "name": "Camacho, Paul B.", - "affiliation": "Beckman Institute for Advanced Science & Technology, University of Illinois at Urbana-Champaign, IL, USA", - "orcid": "0000-0001-9048-7307" - }, - { - "name": "Covitz, Sydney", - "affiliation": "Perelman School of Medicine, University of Pennsylvania, PA, USA", - "orcid": "0000-0002-7430-4125" - }, - { - "name": "Foran, William", - "affiliation": "Department of Psychiatry, University of Pittsburgh Medical Center", - "orcid": "0000-0001-7491-9798" - }, - { - "name": "He, Xiaosong", - "affiliation": "Department of Bioengineering, University of Pennsylvania", - "orcid": "0000-0002-7941-2918" - }, - { - "name": "Humphries, Joseph", - "affiliation": "Turing Medical", - "orcid": "0000-0002-10257956" - }, - { - "name": "Legarreta Gorroรฑo, Jon Haitz", - "affiliation": "Brigham and Women's Hospital, Mass General Brigham/Harvard Medical School", - "orcid": "0000-0002-9661-1396" - }, - { - "name": "Magnussen, Fredrik", - "affiliation": "Department of Psychology, University of Oslo", - "orcid": "0000-0003-2574-1705" - }, - { - "name": "Meisler, Steven Lee", - "affiliation": "Harvard-MIT Program in Speech and Hearing Bioscience and Technology", - "orcid": "0000-0002-8888-1572" - }, - { - "name": "Krause, Michael", - "affiliation": "Max Planck Institute for Human Development, Berlin, Germany", - "orcid": "0000-0002-3878-6542" - }, - { - "name": "Sadil, Patrick", - "affiliation": "Johns Hopkins Bloomberg School of Public Health", - "orcid": "0000-0003-4141-1343" - }, - { - "name": "Salo, Taylor", - "affiliation": "Perelman School of Medicine, University of Pennsylvania", - "orcid": "0000-0001-9813-3167" - }, - { - "name": "Sydnor, Valerie Jill", - "affiliation": "Perelman School of Medicine, University of Pennsylvania", - "orcid": "0000-0002-8640-668X" - }, - { - "name": "Rauland, Amelie", - "affiliation": "Department of Psychology, University Hospital RWTH Aachen, Germany", - "orcid": "0000-0002-8095-2073" - }, - { - "name": "Satterthwaite, Theodore D.", - "affiliation": "Perelman School of Medicine, University of Pennsylvania, PA, USA", - "orcid": "0000-0001-7072-9399" - } - ], - "keywords": [ - "neuroimaging", - "workflow", - "pipeline", - "preprocessing", - "dMRI", - "BIDS" - ], - "title": "QSIRecon: An integrative platform for reconstructing diffusion MRI", - "license": "BSD-3-Clause", - "upload_type": "software" -} \ No newline at end of file diff --git a/CITATION.cff b/CITATION.cff new file mode 100644 index 00000000..5e7fc8a3 --- /dev/null +++ b/CITATION.cff @@ -0,0 +1,171 @@ +cff-version: 1.2.0 +title: "QSIRecon: Reconstruction of preprocessed q-space images (dMRI)" +message: If you use this software, please cite it using the following metadata. +type: software +authors: + - family-names: Cieslak + given-names: Matthew + affiliation: Department of Neuropsychiatry, University of Pennsylvania + orcid: https://orcid.org/0000-0002-1931-4734 + - family-names: Camacho + given-names: Paul B. + affiliation: Beckman Institute for Advanced Science & Technology, University of Illinois at Urbana-Champaign, IL, USA + orcid: https://orcid.org/0000-0001-9048-7307 + - family-names: Covitz + given-names: Sydney + affiliation: Perelman School of Medicine, University of Pennsylvania, PA, USA + orcid: https://orcid.org/0000-0002-7430-4125 + - family-names: Foran + given-names: William + affiliation: Department of Psychiatry, University of Pittsburgh Medical Center + orcid: https://orcid.org/0000-0001-7491-9798 + - family-names: He + given-names: Xiaosong + affiliation: Department of Bioengineering, University of Pennsylvania + orcid: https://orcid.org/0000-0002-7941-2918 + - family-names: Humphries + given-names: Joseph + affiliation: Turing Medical + orcid: https://orcid.org/0000-0002-1025-7956 + - family-names: Legarreta Gorroรฑo + given-names: Jon Haitz + affiliation: Brigham and Women's Hospital, Mass General Brigham/Harvard Medical School + orcid: https://orcid.org/0000-0002-9661-1396 + - family-names: Magnussen + given-names: Fredrik + affiliation: Department of Psychology, University of Oslo + orcid: https://orcid.org/0000-0003-2574-1705 + - family-names: Meisler + given-names: Steven Lee + affiliation: Harvard-MIT Program in Speech and Hearing Bioscience and Technology + orcid: https://orcid.org/0000-0002-8888-1572 + - family-names: Krause + given-names: Michael + affiliation: Max Planck Institute for Human Development, Berlin, Germany + orcid: https://orcid.org/0000-0002-3878-6542 + - family-names: Sadil + given-names: Patrick + affiliation: Johns Hopkins Bloomberg School of Public Health + orcid: https://orcid.org/0000-0003-4141-1343 + - family-names: Salo + given-names: Taylor + email: salot@pennmedicine.upenn.edu + affiliation: University of Pennsylvania + orcid: https://orcid.org/0000-0001-9813-3167 + - family-names: Sydnor + given-names: Valerie Jill + affiliation: Perelman School of Medicine, University of Pennsylvania + orcid: https://orcid.org/0000-0002-8640-668X + - family-names: Satterthwaite + given-names: Theodore D. + affiliation: Perelman School of Medicine, University of Pennsylvania, PA, USA + orcid: https://orcid.org/0000-0001-7072-9399 +preferred-citation: + type: article + authors: + - family-names: Cieslak + given-names: Matthew + - family-names: Cook + given-names: Philip A. + - family-names: He + given-names: Xiaosong + - family-names: Yeh + given-names: Fang-Cheng + - family-names: Dhollander + given-names: Thijs + - family-names: Adebimpe + given-names: Azeez + - family-names: Aguirre + given-names: Geoffrey K. + - family-names: Bassett + given-names: Danielle S. + - family-names: Betzel + given-names: Richard F. + - family-names: Bourque + given-names: Josiane + - family-names: Cabral + given-names: Laura M. + - family-names: Davatzikos + given-names: Christos + - family-names: Detre + given-names: John A. + - family-names: Earl + given-names: Eric + - family-names: Elliott + given-names: Mark A. + - family-names: Fadnavis + given-names: Shreyas + - family-names: Fair + given-names: Damien A. + - family-names: Foran + given-names: Will + - family-names: Fotiadis + given-names: Panagiotis + - family-names: Garyfallidis + given-names: Eleftherios + - family-names: Giesbrecht + given-names: Barry + - family-names: Gur + given-names: Ruben C. + - family-names: Gur + given-names: Raquel E. + - family-names: Kelz + given-names: Max B. + - family-names: Keshavan + given-names: Anisha + - family-names: Larsen + given-names: Bart S. + - family-names: Luna + given-names: Beatriz + - family-names: Mackey + given-names: Allyson P. + - family-names: Milham + given-names: Michael P. + - family-names: Oathes + given-names: Desmond J. + - family-names: Perrone + given-names: Anders + - family-names: Pines + given-names: Adam R. + - family-names: Roalf + given-names: David R. + - family-names: Richie-Halford + given-names: Adam + - family-names: Rokem + given-names: Ariel + - family-names: Sydnor + given-names: Valerie J. + - family-names: Tapera + given-names: Tinashe M. + - family-names: Tooley + given-names: Ursula A. + - family-names: Vettel + given-names: Jean M. + - family-names: Yeatman + given-names: Jason D. + - family-names: Grafton + given-names: Scott T. + - family-names: Satterthwaite + given-names: Theodore D. + doi: 10.1038/s41592-021-01185-5 + journal: Nature Methods + start: 775 + end: 778 + title: 'QSIPrep: an integrative platform for preprocessing and reconstructing diffusion MRI data' + issue: 7 + volume: 18 + year: 2021 +repository-code: 'https://github.com/PennLINC/qsirecon' +url: 'https://qsirecon.readthedocs.io' +keywords: + - neuroimaging + - workflow + - pipeline + - postprocessing + - reconstruction + - dMRI + - BIDS + - BIDS-App +license: BSD-3-Clause +version: 1.0.0rc1 +date-released: '2024-11-20' diff --git a/docs/building_workflows.rst b/docs/building_workflows.rst index c53f572f..ed8c562c 100644 --- a/docs/building_workflows.rst +++ b/docs/building_workflows.rst @@ -6,8 +6,8 @@ Custom Reconstruction Workflows ############################### -QSIRecon workflows are defined in ``YAML`` files. The :ref:`builtin_workflows` -can be found in the QSIRecon ``YAML`` format on +*QSIRecon* workflows are defined in ``YAML`` files. The :ref:`builtin_workflows` +can be found in the *QSIRecon* ``YAML`` format on `github `_, and are a great place to get started with customizing parts of these workflows. @@ -37,7 +37,7 @@ based on the T1w or T2w images in the input data. Currently accepted values are Pipeline nodes ************** -A *node* in the QSIRecon ``"nodes"`` list represents a unit of processing. +A *node* in the *QSIRecon* ``"nodes"`` list represents a unit of processing. Unlike NiPype nodes, which represent a single call to a commandline program or function, a node here represents a set of steps that accomplish a task. For example, if you want to perform CSD there are other steps that should @@ -62,7 +62,7 @@ The entry for this in the ``"nodes"`` list could look like: qsirecon_suffix: MRtrix3_act-FAST software: MRTrix3 -QSIRecon figures out which software to use based on the values specified +*QSIRecon* figures out which software to use based on the values specified for ``"software"`` and ``"action"``. The full list of recognized actions for each software package can be found in :meth:`qsirecon.workflows.build_workflow.workflow_from_spec`. @@ -75,7 +75,7 @@ as an id for this node and is used for :ref:`passing_downstream`. Connecting Nodes ================ -Mixing between software packages is something QSIRecon generally does well. +Mixing between software packages is something *QSIRecon* generally does well. There are a number of ways that nodes can exchange data with one another. .. _passing_downstream: diff --git a/docs/builtin_workflows.rst b/docs/builtin_workflows.rst index c213198f..5fcb4473 100644 --- a/docs/builtin_workflows.rst +++ b/docs/builtin_workflows.rst @@ -250,7 +250,7 @@ generated streamlines belong to the target tract based on the Hausdorff distance subject and atlas streamlines. Reconstructed subject-specific tracts are written out as .tck files that are aligned to the -qsirecon-generated _dwiref.nii.gz and preproc_T1w.nii.gz volumes; .tck files can be visualized +*QSIRecon*-generated _dwiref.nii.gz and preproc_T1w.nii.gz volumes; .tck files can be visualized overlaid on these volumes in mrview or MI-brain. Note, .tck files will not appear in alignment with the dwiref/T1w volumes in DSI Studio due to how the .tck files are read in. @@ -389,8 +389,8 @@ Scalar Maps ``reorient_fslstd`` =================== -Reorients the ``qsirecon`` preprocessed DWI and bval/bvec to the standard FSL orientation. -This can be useful if FSL tools will be applied outside of ``qsirecon``. +Reorients the *QSIRecon* preprocessed DWI and bval/bvec to the standard FSL orientation. +This can be useful if FSL tools will be applied outside of *QSIRecon*. .. _csdsi_3dshore: @@ -517,7 +517,7 @@ Connectivity matrices ********************* Instead of offering a bewildering number of options for constructing connectivity matrices, -``qsirecon`` will construct as many connectivity matrices as it can given the reconstruction +*QSIRecon* will construct as many connectivity matrices as it can given the reconstruction methods. It is **highly** recommended that you pick a weighting scheme before you run these pipelines and only look at those numbers. @@ -532,7 +532,7 @@ To skip this step in your workflow, you can modify an existing recon pipeline by Atlases ======= -The following atlases are included in ``qsirecon``. +The following atlases are included in *QSIRecon*. This means you do not need to add a ``--datasets`` argument to your command line, and can instead select them just with ``--atlases``. @@ -548,7 +548,7 @@ If you use one of them please be sure to cite the relevant publication. * ``Gordon333Ext``: :footcite:t:`gordon2016generation`, extended with subcortical parcels. * ``AAL116``: :footcite:t:`tzourio2002automated` -The ``qsirecon`` atlas set can be downloaded directly from +The *QSIRecon* atlas set can be downloaded directly from `box `_. The 4S atlas combines the Schaefer 2018 cortical atlas (version v0143) :footcite:p:`Schaefer_2017` @@ -559,7 +559,7 @@ the HCP thalamic atlas :footcite:p:`najdenovska2018vivo`, and the amygdala and hippocampus parcels from the HCP CIFTI subcortical parcellation :footcite:p:`glasser2013minimal`. The 4S atlas is used in the same manner across three PennLINC BIDS Apps: -QSIRecon, XCP-D, and ASLPrep, to produce synchronized outputs across modalities. +*QSIRecon*, *XCP-D*, and *ASLPrep*, to produce synchronized outputs across modalities. For more information about the 4S atlas, please see https://github.com/PennLINC/AtlasPack. Atlases are written out to the ``atlases`` subfolder, following @@ -601,7 +601,7 @@ Users can control which atlases are used with the ``--atlases`` and ``--datasets The nifti images should be registered to the `MNI152NLin2009cAsym `_ -included in ``qsirecon``. +included in *QSIRecon*. It is essential that your images are in the LPS+ orientation and have the sform zeroed-out in the header. **Be sure to check for alignment and orientation** in your outputs. diff --git a/docs/changes.md b/docs/changes.md new file mode 100644 index 00000000..7662c424 --- /dev/null +++ b/docs/changes.md @@ -0,0 +1,92 @@ +# What's New + +## 1.0.0rc1 + +This is a prerelease for the version that will be used by the HBCD project for their first data release. + +We plan to not introduce any backwards-incompatible changes for a while. + +### ๐Ÿ›  Breaking Changes + +* Rename QSIPrep to QSIRecon by @tsalo in https://github.com/PennLINC/qsirecon/pull/1 +* Start removing QSIPrep-specific code and documentation by @tsalo in https://github.com/PennLINC/qsirecon/pull/4 +* Remove QSIPrep-specific parameters and Config elements by @tsalo in https://github.com/PennLINC/qsirecon/pull/6 +* Drop Docker wrapper by @tsalo in https://github.com/PennLINC/qsirecon/pull/52 +* Restructure outputs into BIDS datasets by @tsalo in https://github.com/PennLINC/qsirecon/pull/66 +* Combine `mfp` and `mdp` entities into single `param` entity by @tsalo in https://github.com/PennLINC/qsirecon/pull/72 +* Replace `--recon-input-pipeline` with `--input-type` by @tsalo in https://github.com/PennLINC/qsirecon/pull/68 +* Remove unused `--longitudinal` argument by @tsalo in https://github.com/PennLINC/qsirecon/pull/88 +* Make all params and models lower-case by @tsalo in https://github.com/PennLINC/qsirecon/pull/90 +* Reorganize atlas management based on XCP-D and BIDS-Atlas by @tsalo in https://github.com/PennLINC/qsirecon/pull/123 +* Rename `--freesurfer-input` to `--fs-subjects-dir` by @tsalo in https://github.com/PennLINC/qsirecon/pull/152 +* [ENH] Read session-specific anat data by @mattcieslak in https://github.com/PennLINC/qsirecon/pull/151 +* Remove underscore versions of all parameters by @tsalo in https://github.com/PennLINC/qsirecon/pull/159 +* Make connectivity field names compatible with MATLAB by @tsalo in https://github.com/PennLINC/qsirecon/pull/166 + +### ๐ŸŽ‰ Exciting New Features + +* Add ng, perng, parng, and mapcoeffs to Dipy MAPMRI outputs by @tsalo in https://github.com/PennLINC/qsirecon/pull/55 +* Add DatasetLinks to dataset_description.json by @tsalo in https://github.com/PennLINC/qsirecon/pull/77 +* Pass DWI file metadata to reconstruction workflows by @tsalo in https://github.com/PennLINC/qsirecon/pull/154 +* Add HBCD Release1 recon workflow by @mattcieslak in https://github.com/PennLINC/qsirecon/pull/169 + +### ๐Ÿ› Bug Fixes + +* Write out QSIRecon pipeline-wise reports by @tsalo in https://github.com/PennLINC/qsirecon/pull/7 +* Write out reports to individual reconstruction derivative folders by @tsalo in https://github.com/PennLINC/qsirecon/pull/53 +* Add summary reportlets to HTML report by @tsalo in https://github.com/PennLINC/qsirecon/pull/61 +* Fix QSIRecon Entrypoint by @smeisler in https://github.com/PennLINC/qsirecon/pull/76 +* Use file lock to avoid concurrent edits to dataset_description.json by @cookpa in https://github.com/PennLINC/qsirecon/pull/91 +* Compress the tck files by @tsalo in https://github.com/PennLINC/qsirecon/pull/93 +* Add missing filename patterns by @tsalo in https://github.com/PennLINC/qsirecon/pull/131 +* Fix infant anatomical ingression by @tsalo in https://github.com/PennLINC/qsirecon/pull/126 +* Fix extension in ds_fs_5tt_hsvs by @tsalo in https://github.com/PennLINC/qsirecon/pull/165 +* Fix extension in ds_qsiprep_5tt_hsvs by @tsalo in https://github.com/PennLINC/qsirecon/pull/172 +* Fix space in ds_qsiprep_5tt_hsvs by @tsalo in https://github.com/PennLINC/qsirecon/pull/175 +* Make PlotPeaks robust enough that we don't need --writable-tempfs in singularity/apptainer by @mattcieslak in https://github.com/PennLINC/qsirecon/pull/174 + +### Other Changes + +* Remove internal version of LiterateWorkflow by @tsalo in https://github.com/PennLINC/qsirecon/pull/8 +* Drop and modify infrastructure files by @tsalo in https://github.com/PennLINC/qsirecon/pull/40 +* Remove QSIPrep-specific tests by @tsalo in https://github.com/PennLINC/qsirecon/pull/5 +* Drop unused modules, classes, and functions by @tsalo in https://github.com/PennLINC/qsirecon/pull/11 +* [CI] Speed up pyafq test by @mattcieslak in https://github.com/PennLINC/qsirecon/pull/57 +* [DOCS] Reorganize documentation by @mattcieslak in https://github.com/PennLINC/qsirecon/pull/56 +* Collect templates from TemplateFlow instead of package data by @tsalo in https://github.com/PennLINC/qsirecon/pull/49 +* Remove unused data files by @tsalo in https://github.com/PennLINC/qsirecon/pull/63 +* Replace hyperlinks with BibTeX references by @tsalo in https://github.com/PennLINC/qsirecon/pull/67 +* [DOCS] Add scalar tables by @mattcieslak in https://github.com/PennLINC/qsirecon/pull/80 +* Move scalar file configs to YAMLs and use a recon scalar workflow by @tsalo in https://github.com/PennLINC/qsirecon/pull/79 +* [WIP] Make a system for keeping docs and file names in sync by @mattcieslak in https://github.com/PennLINC/qsirecon/pull/86 +* Convert pipeline configs from JSON to YAML by @tsalo in https://github.com/PennLINC/qsirecon/pull/84 +* [DOCS] clean up by @mattcieslak in https://github.com/PennLINC/qsirecon/pull/101 +* Draft pre-init ingression by @tsalo in https://github.com/PennLINC/qsirecon/pull/102 +* [ENH] Update AMICO by @mattcieslak in https://github.com/PennLINC/qsirecon/pull/115 +* [FIX] mif2fib by @ameliecr in https://github.com/PennLINC/qsirecon/pull/116 +* Fix how bundles to be tracked are selected for DSIstudio autotrack by @ameliecr in https://github.com/PennLINC/qsirecon/pull/121 +* [FIX] workflow connection in dsi_studio_gqi by @mattcieslak in https://github.com/PennLINC/qsirecon/pull/142 +* [CI] add hsvs test by @mattcieslak in https://github.com/PennLINC/qsirecon/pull/136 +* [FIX] dsi_studio_gqi workflow connect by @mattcieslak in https://github.com/PennLINC/qsirecon/pull/146 +* [DOC] Minor addition for skipping connectivity matrices step by @chiuhoward in https://github.com/PennLINC/qsirecon/pull/150 +* Add page documenting output structure by @tsalo in https://github.com/PennLINC/qsirecon/pull/156 +* Add information about QSIPrep/QSIRecon releases by @tsalo in https://github.com/PennLINC/qsirecon/pull/158 +* [CI] Add tests for reading pre-1.0 outputs from qsiprep by @mattcieslak in https://github.com/PennLINC/qsirecon/pull/155 +* [ENH] Support outputs from qsiprep 1.0.0rc0 by @mattcieslak in https://github.com/PennLINC/qsirecon/pull/160 +* [FIX] get rid of logging error #145 by @mattcieslak in https://github.com/PennLINC/qsirecon/pull/161 +* Add UKB ingression by @smeisler in https://github.com/PennLINC/qsirecon/pull/147 +* [FIX] set TMPDIR before running plot_peaks by @mattcieslak in https://github.com/PennLINC/qsirecon/pull/163 +* [ENH] match to qsiprep nipype/nireports versions by @mattcieslak in https://github.com/PennLINC/qsirecon/pull/167 +* Add in Val's text for connectivity matrices by @mattcieslak in https://github.com/PennLINC/qsirecon/pull/173 +* Disable test_main in the CI integration tests by @mattcieslak in https://github.com/PennLINC/qsirecon/pull/177 + +### New Contributors + +* @tsalo made their first contribution in https://github.com/PennLINC/qsirecon/pull/1 +* @mattcieslak made their first contribution in https://github.com/PennLINC/qsirecon/pull/57 +* @cookpa made their first contribution in https://github.com/PennLINC/qsirecon/pull/91 +* @dependabot made their first contribution in https://github.com/PennLINC/qsirecon/pull/100 +* @ameliecr made their first contribution in https://github.com/PennLINC/qsirecon/pull/116 +* @chiuhoward made their first contribution in https://github.com/PennLINC/qsirecon/pull/150 + +**Full Changelog**: https://github.com/PennLINC/qsirecon/commits/1.0.0rc1 diff --git a/docs/comparisons.md b/docs/comparisons.md index 2aed6f82..6e1ecd36 100644 --- a/docs/comparisons.md +++ b/docs/comparisons.md @@ -1,14 +1,12 @@ # Comparisons to other pipelines -Other pipelines for preprocessing DWI data are currently being developed. Below are tables comparing -their current feature sets. These other +Other pipelines for preprocessing DWI data are currently being developed. +Below are tables comparing their current feature sets. +These other pipelines include: * [Tractoflow](https://doi.org/10.1016/j.neuroimage.2020.116889) * [PreQual](https://doi.org/10.1101/2020.09.14.260240) * [MRtrix3_connectome](https://github.com/BIDS-Apps/MRtrix3_connectome) - * [dMRIPrep](https://github.com/nipreps/dmriprep) - - dMRIPrep exclusively performs preprocessing and is therefore omitted from the [reconstruction](#reconstruction) and [tractography](#tractography) sections. ## Reconstruction @@ -39,5 +37,4 @@ their current feature sets. These other | | QSIRecon | Tractoflow | PreQual | MRtrix3_connectome | | ----------------------------- | :---------------: | :--------: | :-----: | :----------------: | | Automated methods boilerplate | โœ” | โœ˜ | โœ˜ | โœ˜ | -| HTML Preprocessing Report | [NiWorkflows-based](preprocessing.html#visual-reports) | โœ˜ | Custom | EddyQuad | -| HTML Reconstruction Report | NiWorkflows-based | โœ˜ | Custom | โœ˜ | \ No newline at end of file +| HTML Reconstruction Report | NiWorkflows-based | โœ˜ | Custom | โœ˜ | diff --git a/docs/contributors.rst b/docs/contributors.rst index 0c8f6ee2..96ac5e12 100644 --- a/docs/contributors.rst +++ b/docs/contributors.rst @@ -1,8 +1,8 @@ .. include:: links.rst ------------------------- -Contributing to qsirecon ------------------------- +########################## +Contributing to *QSIRecon* +########################## This document explains how to prepare a new development environment and update an existing environment, as necessary. @@ -14,8 +14,10 @@ By default, work should be built off of `pennlinc/qsirecon:latest installation_ guide for the basic procedure for running). +***************************** Patching working repositories -============================= +***************************** + In order to test new code without rebuilding the Docker image, it is possible to mount working repositories as source directories within the container. @@ -34,7 +36,7 @@ For example, :: -w /out/work/ In order to work directly in the container, use ``--entrypoint=bash`` and omit the qsirecon -arguments in a ``docker`` command:: +argument in a ``docker`` command:: $ docker run --rm -v $HOME/fullds005:/data:ro -v $HOME/dockerout:/out \ -v $HOME/projects/qsirecon/qsirecon:/usr/local/miniconda/lib/python3.10/site-packages/qsirecon:ro --entrypoint=bash \ @@ -54,8 +56,39 @@ Or you can patch Singularity containers using the PYTHONPATH variable: :: /scratch/dataset /scratch/out participant -w /out/work/ +Running tests locally +===================== + +To run the tests locally, *QSIRecon* includes a Python script to automatically mount the +local clone into ``pennlinc/qsirecon:unstable`` and run tests with ``pytest``. +The script will also download any required test data from Box. + +To run the tests, navigate to the tests folder and run ``run_local_tests.py``:: + + $ cd /path/to/qsirecon/qsirecon/tests + $ python run_local_tests.py + +You can select individual tests to run by using the ``-m`` (to select markers) or ``-k`` (the select tests by name) flags:: + + $ python run_local_tests.py -m "dsdti_fmap" + $ python run_local_tests.py -k "test_some_name" + +.. warning:: + + Please note that the integration tests in *QSIRecon* are computationally intensive + and may take a long time to run, so be prepared for that before running them on a laptop. + + +If the tests pass, that's a good sign that your changes are solid. +We also recommend opening the HTML reports produced by integration tests to check the results. +Evaluating whether the HTML reports look "good" requires some domain knowledge and +familiarity with *QSIRecon* outputs. + + +******************* Adding dependencies -=================== +******************* + New dependencies to be inserted into the Docker image will either be Python or non-Python dependencies. Python dependencies may be added in three places, depending on whether @@ -81,10 +114,13 @@ For example, installing an ``apt`` package may be done as follows: :: RUN apt-get update && \ apt-get install -y + +*********************** Rebuilding Docker image -======================= +*********************** + If it is necessary to rebuild the Docker image, a local image named -``qsirecon`` may be built from within the working qsirecon +``qsirecon`` may be built from within the working *QSIRecon* repository, located in ``~/projects/qsirecon``: :: ~/projects/qsirecon$ docker build -t qsirecon . @@ -93,12 +129,13 @@ To work in this image, replace ``pennlinc/qsirecon:latest`` with ``qsirecon`` in any of the above commands. +*********************************************** Adding new features to the citation boilerplate -=============================================== +*********************************************** The citation boilerplate is built by adding two dunder attributes of workflow objects: ``__desc__`` and ``__postdesc__``. -Once the full *qsirecon* workflow is built, starting from the +Once the full *QSIRecon* workflow is built, starting from the outer workflow and visiting all sub-workflows in topological order, all defined ``__desc__`` are appended to the citation boilerplate before descending into sub-workflows. diff --git a/docs/help.rst b/docs/help.rst index 8e29db30..b004baf4 100644 --- a/docs/help.rst +++ b/docs/help.rst @@ -1,13 +1,13 @@ Getting help ############ -If you have a problem, would like to ask a question about how to use QSIRecon, -or have a question about the features and behavior of QSIRecon, please submit +If you have a problem, would like to ask a question about how to use *QSIRecon*, +or have a question about the features and behavior of *QSIRecon*, please submit your question to `NeuroStars.org `_ using the ``qsirecon`` tag and the "Software Support" category. -Previous questions about QSIRecon are available at https://neurostars.org/tag/qsirecon/. +Previous questions about *QSIRecon* are available at https://neurostars.org/tag/qsirecon/. If you have a bug you're like to report, or a new feature you'd like to request, -please open an issue on the QSIRecon GitHub page at https://github.com/pennlinc/qsirecon/issues. +please open an issue on the *QSIRecon* GitHub page at https://github.com/pennlinc/qsirecon/issues. diff --git a/docs/index.rst b/docs/index.rst index 3f18136e..cff18828 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -8,12 +8,13 @@ Contents .. toctree:: :maxdepth: 2 - getting_started - input_data installation + quickstart builtin_workflows building_workflows outputs + contributors + changes comparisons help license diff --git a/docs/input_data.rst b/docs/input_data.rst index c4672f5a..0d58a233 100644 --- a/docs/input_data.rst +++ b/docs/input_data.rst @@ -3,31 +3,31 @@ .. _input_data: -####################### -Input Data for QSIRecon -####################### +######################### +Input Data for *QSIRecon* +######################### *Raw BIDS dMRI should not be used and will not work*. Instead, gather data processed by QSIPrep_ or UKBioBank_. The directory containing the ``sub-*`` directories (if from QSIPrep) or the directory with the numerals/underscores per subject if UKBB -will be the first argument to QSIRecon. +will be the first argument to *QSIRecon*. -*********************** -Using Data from QSIPrep -*********************** +************************* +Using Data from *QSIPrep* +************************* -QSIPrep outputs will work as inputs for QSIRecon as-is, aside from some +*QSIPrep* outputs will work as inputs for *QSIRecon* as-is, aside from some when some specific options were selected for preprocessing. .. important:: - QSIRecon endeavors to maintain compatibility with QSIPrep outputs from the same + *QSIRecon* endeavors to maintain compatibility with *QSIPrep* outputs from the same release series. - We cannot guarantee that QSIPrep outputs from different releases will work - with QSIRecon. + We cannot guarantee that *QSIPrep* outputs from different releases will work + with *QSIRecon*. - QSIPrep and QSIRecon follow a matched release schedule, + *QSIPrep* and *QSIRecon* follow a matched release schedule, with major (i.e., backwards-incompatible) releases made at the same time. Minor and patch releases may be made independently. @@ -36,7 +36,7 @@ If ``--anat-modality none`` was used ==================================== If ``--anat-modality none`` was used, there will be no preprocessed T1w data in -the ``qsirecon`` results. Instead the DWI images have been aligned to AC-PC as +the *QSIRecon* results. Instead the DWI images have been aligned to AC-PC as closely as possible (likely imperfectly). In this case, the FreeSurfer skull-stripped ``brain.mgz`` is rigidly registered to ``dwiref`` of each preprocessed DWI. The FreeSurfer brain mask is resampled to the grid of the DWI. @@ -55,7 +55,7 @@ Using Data Preprocessed by Other Pipelines Many open datasets are provided in minimally preprocessed form. Most of these have a bespoke processing pipeline and in many cases these pipelines are very similar to -QSIRecon. Instead of preprocessing these from scratch, you can run reconstruction +*QSIRecon*. Instead of preprocessing these from scratch, you can run reconstruction workflows on the minimally preprocessed data by specifying the pipeline that was used for preprocessing. @@ -74,7 +74,7 @@ HCP Young Adult Preprocessed Data To use minimally preprocessed dMRI data from HCP-YA specify ``--input-type hcpya``. Note that the transforms to/from MNI space are not able to be used at this time. Please note that if you have the HCPYA dataset from datalad (https://github.com/datalad-datasets/human-connectome-project-openaccess) -then you should ``datalad get`` relevant subject data before running QSIRecon, +then you should ``datalad get`` relevant subject data before running *QSIRecon*, and be mindful about how you mount the directory in Docker/Apptainer. .. _anat_reqs: @@ -160,7 +160,7 @@ You can run: --fs-subjects-dir "${PWD}/derivatives/freesurfer" \ -v -v -This will read the FreeSurfer data, align it to the ``qsiprep`` results and use it +This will read the FreeSurfer data, align it to the *QSIPrep* results and use it for subsequent reconstruction steps. diff --git a/docs/installation.rst b/docs/installation.rst index fa952e0a..93e76ae0 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -6,13 +6,13 @@ Installation ############ -The official source of QSIRecon is the +The official source of *QSIRecon* is the `Docker repository `_. -******************************* -Running QSIRecon via containers -******************************* +********************************* +Running *QSIRecon* via containers +********************************* .. _install_docker`: @@ -20,7 +20,7 @@ Running QSIRecon via containers Docker ====== -In order to run qsirecon in a Docker container, Docker must be `installed +In order to run *QSIRecon* in a Docker container, Docker must be `installed `_. .. note:: If running Docker Desktop on MacOS (or via Docker Desktop), be sure to set @@ -45,13 +45,13 @@ A Docker command line may look like: Singularity/Apptainer ===================== -The easiest way to get a Sigularity image is to run: +The easiest way to get a Singularity image is to run: .. code-block:: bash apptainer build qsirecon-.sif docker://pennlinc/qsirecon: -Where ```` should be replaced with the desired version of qsirecon that you want to download. +Where ```` should be replaced with the desired version of *QSIRecon* that you want to download. Do not use ``latest`` or ``unstable`` unless you are performing limited testing. As with Docker, you will need to bind the Freesurfer license.txt when running Singularity : @@ -75,7 +75,7 @@ As with Docker, you will need to bind the Freesurfer license.txt when running Si External Dependencies --------------------- -QSIRecon is written using Python 3.10, and is based on nipype_. +*QSIRecon* is written using Python 3.10, and is based on nipype_. The external dependencies are built in the `qsirecon_build `_ repository. There you can find the URLs used to download the dependency source code diff --git a/docs/license.rst b/docs/license.rst index 7bdc3712..e5392b44 100644 --- a/docs/license.rst +++ b/docs/license.rst @@ -3,7 +3,7 @@ License information We use the 3-clause BSD license; the full license may be found in the `LICENSE `_ file -in the ``qsirecon`` distribution. +in the *QSIRecon* distribution. All trademarks referenced herein are property of their respective holders. diff --git a/docs/getting_started.rst b/docs/quickstart.rst similarity index 82% rename from docs/getting_started.rst rename to docs/quickstart.rst index 08a19c96..04724da7 100644 --- a/docs/getting_started.rst +++ b/docs/quickstart.rst @@ -1,14 +1,14 @@ .. include:: links.rst -############### -Getting Started -############### +########### +Quick Start +########### -Before you can use QSIRecon, you must have some preprocessed dMRI. +Before you can use *QSIRecon*, you must have some preprocessed dMRI data. See :ref:`input_data` -The next step is to get a containerized version of QSIRecon. This can be -done with Singularity_, Apptainer_ or Docker_. Most users run QSIRecon on +The next step is to get a containerized version of *QSIRecon*. This can be +done with Singularity_, Apptainer_ or Docker_. Most users run *QSIRecon* on a high performance computing cluster, so we will assume Apptainer is being used throughout this documentation. See :ref:`install_qsirecon` on how to create a `sif` file or pull the image with Docker. @@ -17,9 +17,9 @@ Next, you need to decide which workflow you'd like to run. You can pick from any of the :ref:`builtin_workflows` or :ref:`building_workflows`. Here we'll pick the ``dsi_studio_autotrack`` workflow. -Finally, you'll need to craft a command to set up your QSIRecon run. +Finally, you'll need to craft a command to set up your *QSIRecon* run. Suppose you're in a directory where there are some qsiprep results in -``inputs/qsiprep``. You'd like to save QSIRecon outputs in ``results``. You +``inputs/qsiprep``. You'd like to save *QSIRecon* outputs in ``results``. You have access to 8 cpus. To run the from ``qsirecon-latest.sif`` you could use: .. code-block:: bash