================================
Pydra task package for nireports
================================
.. image:: https://github.com/nipype/pydra-nireports/actions/workflows/ci-cd.yaml/badge.svg
:target: https://github.com/nipype/pydra-nireports/actions/workflows/ci-cd.yaml
.. image:: https://codecov.io/gh/nipype/pydra-nireports/branch/main/graph/badge.svg?token=UIS0OGPST7
:target: https://codecov.io/gh/nipype/pydra-nireports
.. image:: https://img.shields.io/pypi/pyversions/pydra-nireports.svg
:target: https://pypi.python.org/pypi/pydra-nireports/
:alt: Supported Python versions
.. image:: https://img.shields.io/pypi/v/pydra-nireports.svg
:target: https://pypi.python.org/pypi/pydra-nireports/
:alt: Latest Version
This package contains a collection of Pydra task interfaces for the nireports toolkit.
The basis of this collection has been formed by the semi-automatic conversion of
existing `Nipype <https://github.com/nipy/nipype>`__ interfaces to Pydra using the
`Nipype2Pydra <https://github.com/nipype/nipype2pydra>`__ tool
Automatically-generated vs manually-curated tasks
-------------------------------------------------
Automatically generated tasks can be found in the `pydra.tasks.nireports.auto` package.
These packages should be treated with extreme caution as they likely do not pass testing.
Generated tasks that have been edited and pass testing are imported into one or more of the
`pydra.tasks.nireports.v*` packages, corresponding to the version of the nireports toolkit
they are designed for.
Tests
-----
This package comes with a battery of automatically generated test modules. To install
the necessary dependencies to run the tests
.. code-block::
$ pip install -e .[test]
Then the tests, including `doctests` <https://docs.python.org/3/library/doctest.html>`__, can be launched using
.. code-block::
$ pytest --doctest-modules pydra/tasks/*
By default, the tests are set to time-out after 10s, after which the underlying tool is
assumed to have passed the validation/initialisation phase and we assume that it will
run to completion. To disable this and run the test(s) through to completion run
.. code-block::
$ pytest --doctest-modules --timeout-pass 0 pydra/tasks/*
Continuous integration
----------------------
This template uses `GitHub Actions <https://docs.github.com/en/actions/>`__` to run tests and
deploy packages to PYPI. New packages are built and uploaded when releases are created on
GitHub, or new releases of Nipype or the Nipype2Pydra conversion tool are released.
Releases triggered by updates to Nipype or Nipype2Pydra are signified by the `postN`
suffix where `N = <nipype-version><nipype2pydra-version>` with the '.'s stripped, e.g.
`v0.2.3post185010` corresponds to the v0.2.3 tag of this repository with auto-generated
packages from Nipype 1.8.5 using Nipype2Pydra 0.1.0.
Contributing to this package
----------------------------
Developer installation
~~~~~~~~~~~~~~~~~~~~~~
Install the `fileformats <https://arcanaframework.github.io/fileformats/>`__ packages
corresponding to AFNI specific file formats
.. code-block::
$ pip install -e ./related-packages/fileformats[dev]
$ pip install -e ./related-packages/fileformats-extras[dev]
Install repo in developer mode from the source directory and install pre-commit to
ensure consistent code-style and quality.
.. code-block::
$ pip install -e .[test,dev]
$ pre-commit install
Next install the requirements for running the auto-conversion script and generate the
Pydra task interfaces from their Nipype counterparts
.. code-block::
$ pip install -r nipype-auto-conv/requirements.txt
The run the conversion script to convert Nipype interfaces to Pydra
.. code-block::
$ nipype-auto-conv/generate
Methodology
~~~~~~~~~~~
The development of this package is expected to have two phases
1. Where the corresponding Nipype interfaces are considered to be the ground truth, and
the Pydra tasks are generated from them
2. When the Pydra tasks are considered be mature and they are edited by hand
Different tasks will probably mature at different times so there will probably be an
intermediate phase between 1 and 2.
Auto-conversion phase
~~~~~~~~~~~~~~~~~~~~~
The auto-converted Pydra tasks are generated from their corresponding Nipype interface
in combination with "conversion hints" contained in YAML specs
located in `nipype-auto-conv/specs/`. The self-documented conversion specs are
to be edited by hand in order to assist the auto-converter produce valid pydra tasks.
After editing one or more conversion specs the `pydra.tasks.nireports.auto` package should
be regenerated by running
.. code-block::
$ nipype-auto-conv/generate
The tests should be run on the auto-generated tasks to see if they are valid
.. code-block::
$ pytest --doctest-modules pydra/tasks/nireports/auto/tests/test_<the-name-of-the-task-you-edited>.py
If the test passes you should then edit the `pydra/tasks/nireports/v<tool-version>/__init__.py` file
to import the now valid task interface to signify that it has been validated and is ready
for use, e.g.
.. code-block::python
from pydra.tasks.nireports.auto import <the-task-you-have-validated>
Typing and sample test data
~~~~~~~~~~~~~~~~~~~~~~~~~~~
The automatically generated tests will attempt to provided the task instance to be tested
with sensible default values based on the type of the field and any constraints it has
on it. However, these will often need to be manually overridden after consulting the
underlying tool's documentation.
For file-based data, automatically generated file-system objects will be created for
selected format types, e.g. Nifti, Dicom. Therefore, it is important to specify the
format of the file using the "mime-like" string corresponding to a
`fileformats <https://github.com/ArcanaFramework/fileformats>`__ class
in the ``inputs > types`` and ``outputs > types`` dicts of the YAML spec.
If the required file-type is not found implemented within fileformats, please see the `fileformats
docs <https://arcanaframework.github.io/fileformats/developer.html>`__ for instructions on how to define
new fileformat types, and see
`fileformats-medimage-extras <https://github.com/ArcanaFramework/fileformats-medimage-extras/blob/6c2dabe91e95687eebc2639bb6f034cf9595ecfc/fileformats/extras/medimage/nifti.py#L30-L48>`__
for an example on how to implement methods to generate sample data for them.
Raw data
{
"_id": null,
"home_page": null,
"name": "pydra-nireports",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "Nipype developers <neuroimaging@python.org>",
"keywords": "pydra",
"author": null,
"author_email": "Nipype developers <neuroimaging@python.org>",
"download_url": "https://files.pythonhosted.org/packages/23/22/c22757702cbb8f9e88c1e0c3a7e17c8c42c28d4e9b7c193ab833ad69c552/pydra_nireports-0.1.1.tar.gz",
"platform": null,
"description": "================================\nPydra task package for nireports\n================================\n\n.. image:: https://github.com/nipype/pydra-nireports/actions/workflows/ci-cd.yaml/badge.svg\n :target: https://github.com/nipype/pydra-nireports/actions/workflows/ci-cd.yaml\n.. image:: https://codecov.io/gh/nipype/pydra-nireports/branch/main/graph/badge.svg?token=UIS0OGPST7\n :target: https://codecov.io/gh/nipype/pydra-nireports\n.. image:: https://img.shields.io/pypi/pyversions/pydra-nireports.svg\n :target: https://pypi.python.org/pypi/pydra-nireports/\n :alt: Supported Python versions\n.. image:: https://img.shields.io/pypi/v/pydra-nireports.svg\n :target: https://pypi.python.org/pypi/pydra-nireports/\n :alt: Latest Version\n\n\nThis package contains a collection of Pydra task interfaces for the nireports toolkit.\nThe basis of this collection has been formed by the semi-automatic conversion of\nexisting `Nipype <https://github.com/nipy/nipype>`__ interfaces to Pydra using the\n`Nipype2Pydra <https://github.com/nipype/nipype2pydra>`__ tool\n\n\nAutomatically-generated vs manually-curated tasks\n-------------------------------------------------\n\nAutomatically generated tasks can be found in the `pydra.tasks.nireports.auto` package.\nThese packages should be treated with extreme caution as they likely do not pass testing.\nGenerated tasks that have been edited and pass testing are imported into one or more of the\n`pydra.tasks.nireports.v*` packages, corresponding to the version of the nireports toolkit\nthey are designed for. \n\nTests\n-----\n\nThis package comes with a battery of automatically generated test modules. To install\nthe necessary dependencies to run the tests\n\n.. code-block::\n\n $ pip install -e .[test]\n\nThen the tests, including `doctests` <https://docs.python.org/3/library/doctest.html>`__, can be launched using\n\n.. code-block::\n\n $ pytest --doctest-modules pydra/tasks/*\n\nBy default, the tests are set to time-out after 10s, after which the underlying tool is\nassumed to have passed the validation/initialisation phase and we assume that it will\nrun to completion. To disable this and run the test(s) through to completion run\n\n.. code-block::\n\n $ pytest --doctest-modules --timeout-pass 0 pydra/tasks/*\n\nContinuous integration\n----------------------\n\nThis template uses `GitHub Actions <https://docs.github.com/en/actions/>`__` to run tests and\ndeploy packages to PYPI. New packages are built and uploaded when releases are created on\nGitHub, or new releases of Nipype or the Nipype2Pydra conversion tool are released.\nReleases triggered by updates to Nipype or Nipype2Pydra are signified by the `postN`\nsuffix where `N = <nipype-version><nipype2pydra-version>` with the '.'s stripped, e.g.\n`v0.2.3post185010` corresponds to the v0.2.3 tag of this repository with auto-generated\npackages from Nipype 1.8.5 using Nipype2Pydra 0.1.0.\n\n\nContributing to this package\n----------------------------\n\nDeveloper installation\n~~~~~~~~~~~~~~~~~~~~~~\n\nInstall the `fileformats <https://arcanaframework.github.io/fileformats/>`__ packages\ncorresponding to AFNI specific file formats\n\n\n.. code-block::\n\n $ pip install -e ./related-packages/fileformats[dev]\n $ pip install -e ./related-packages/fileformats-extras[dev]\n\nInstall repo in developer mode from the source directory and install pre-commit to\nensure consistent code-style and quality.\n\n.. code-block::\n\n $ pip install -e .[test,dev]\n $ pre-commit install\n\nNext install the requirements for running the auto-conversion script and generate the\nPydra task interfaces from their Nipype counterparts\n\n.. code-block::\n\n $ pip install -r nipype-auto-conv/requirements.txt\n\nThe run the conversion script to convert Nipype interfaces to Pydra\n\n.. code-block::\n\n $ nipype-auto-conv/generate\n\nMethodology\n~~~~~~~~~~~\n\nThe development of this package is expected to have two phases\n\n1. Where the corresponding Nipype interfaces are considered to be the ground truth, and\n the Pydra tasks are generated from them\n2. When the Pydra tasks are considered be mature and they are edited by hand\n\nDifferent tasks will probably mature at different times so there will probably be an\nintermediate phase between 1 and 2.\n\nAuto-conversion phase\n~~~~~~~~~~~~~~~~~~~~~\n\nThe auto-converted Pydra tasks are generated from their corresponding Nipype interface\nin combination with \"conversion hints\" contained in YAML specs\nlocated in `nipype-auto-conv/specs/`. The self-documented conversion specs are\nto be edited by hand in order to assist the auto-converter produce valid pydra tasks.\nAfter editing one or more conversion specs the `pydra.tasks.nireports.auto` package should\nbe regenerated by running\n\n.. code-block::\n\n $ nipype-auto-conv/generate\n\nThe tests should be run on the auto-generated tasks to see if they are valid\n\n.. code-block::\n\n $ pytest --doctest-modules pydra/tasks/nireports/auto/tests/test_<the-name-of-the-task-you-edited>.py\n\nIf the test passes you should then edit the `pydra/tasks/nireports/v<tool-version>/__init__.py` file\nto import the now valid task interface to signify that it has been validated and is ready\nfor use, e.g.\n\n.. code-block::python\n\n from pydra.tasks.nireports.auto import <the-task-you-have-validated>\n\n\nTyping and sample test data\n~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nThe automatically generated tests will attempt to provided the task instance to be tested\nwith sensible default values based on the type of the field and any constraints it has\non it. However, these will often need to be manually overridden after consulting the\nunderlying tool's documentation.\n\nFor file-based data, automatically generated file-system objects will be created for\nselected format types, e.g. Nifti, Dicom. Therefore, it is important to specify the\nformat of the file using the \"mime-like\" string corresponding to a\n`fileformats <https://github.com/ArcanaFramework/fileformats>`__ class\nin the ``inputs > types`` and ``outputs > types`` dicts of the YAML spec.\n\nIf the required file-type is not found implemented within fileformats, please see the `fileformats\ndocs <https://arcanaframework.github.io/fileformats/developer.html>`__ for instructions on how to define\nnew fileformat types, and see \n`fileformats-medimage-extras <https://github.com/ArcanaFramework/fileformats-medimage-extras/blob/6c2dabe91e95687eebc2639bb6f034cf9595ecfc/fileformats/extras/medimage/nifti.py#L30-L48>`__\nfor an example on how to implement methods to generate sample data for them.\n",
"bugtrack_url": null,
"license": "Copyright 2021 Nipype developers Licensed under the Apache License, Version 2.0 (the \"License\"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an \"AS IS\" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.",
"summary": "Pydra tasks package for nireports",
"version": "0.1.1",
"project_urls": null,
"split_keywords": [
"pydra"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "f507ff085883553e60b698ff5929b72c8eb5e7f9a2e2242e2f583d3df52373ef",
"md5": "2d932cd0bcbba1cc146649757d2e71df",
"sha256": "03b0e2bd52d2cf332c09c73e74d0178c739609c32d8225ad8875ee19035081bc"
},
"downloads": -1,
"filename": "pydra_nireports-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "2d932cd0bcbba1cc146649757d2e71df",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 44646,
"upload_time": "2024-05-20T23:31:44",
"upload_time_iso_8601": "2024-05-20T23:31:44.636209Z",
"url": "https://files.pythonhosted.org/packages/f5/07/ff085883553e60b698ff5929b72c8eb5e7f9a2e2242e2f583d3df52373ef/pydra_nireports-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "2322c22757702cbb8f9e88c1e0c3a7e17c8c42c28d4e9b7c193ab833ad69c552",
"md5": "7bed555d56b3e96364af5175c878b40d",
"sha256": "ba4da1ecfc9f714dd23083dcf33acec03647f2acce6a7ffd69eeaebe7267dfe2"
},
"downloads": -1,
"filename": "pydra_nireports-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "7bed555d56b3e96364af5175c878b40d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 37824,
"upload_time": "2024-05-20T23:31:46",
"upload_time_iso_8601": "2024-05-20T23:31:46.364457Z",
"url": "https://files.pythonhosted.org/packages/23/22/c22757702cbb8f9e88c1e0c3a7e17c8c42c28d4e9b7c193ab833ad69c552/pydra_nireports-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-05-20 23:31:46",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "pydra-nireports"
}
JSON