Metadata-Version: 2.4
Name: pydra-tasks-afni
Version: 0.5.0
Summary: Pydra tasks package for AFNI
Project-URL: Documentation, https://github.com/nipype/pydra-tasks-afni#readme
Project-URL: Issues, https://github.com/nipype/pydra-tasks-afni/issues
Project-URL: Source, https://github.com/nipype/pydra-tasks-afni
Author-email: Nipype developers <neuroimaging@python.org>
Maintainer-email: Nipype developers <neuroimaging@python.org>
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.
License-File: LICENSE
Keywords: MRI,bold,fMRI,neuroimaging,pydra
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.11
Requires-Dist: fileformats-datascience>=0.3.2
Requires-Dist: fileformats-medimage>=0.10.5
Requires-Dist: fileformats-vendor-afni
Requires-Dist: fileformats>=0.15.4
Requires-Dist: looseversion>=1.3.0
Requires-Dist: pydra>=1.0a2
Provides-Extra: dev
Requires-Dist: black; extra == 'dev'
Requires-Dist: pre-commit; extra == 'dev'
Provides-Extra: test
Requires-Dist: codecov; extra == 'test'
Requires-Dist: fileformats-datascience-extras; extra == 'test'
Requires-Dist: fileformats-extras; extra == 'test'
Requires-Dist: nipype2pydra>=0.5.0; extra == 'test'
Requires-Dist: pluggy>=1.2; extra == 'test'
Requires-Dist: pytest-cov>=4.1.0; extra == 'test'
Requires-Dist: pytest-env; extra == 'test'
Requires-Dist: pytest-rerunfailures; extra == 'test'
Requires-Dist: pytest-xdist>=3.5.0; extra == 'test'
Requires-Dist: pytest>=7.4; extra == 'test'
Description-Content-Type: text/markdown

# Pydra task package for afni

[![CI/CD](https://github.com/nipype/pydra-afni/actions/workflows/ci-cd.yaml/badge.svg)](https://github.com/nipype/pydra-afni/actions/workflows/ci-cd.yaml)
[![codecov](https://codecov.io/gh/nipype/pydra-afni/branch/main/graph/badge.svg?token=UIS0OGPST7)](https://codecov.io/gh/nipype/pydra-afni)
[![Python versions](https://img.shields.io/pypi/pyversions/pydra-afni.svg)](https://pypi.python.org/pypi/pydra-afni/)
[![Latest Version](https://img.shields.io/pypi/v/pydra-afni.svg)](https://pypi.python.org/pypi/pydra-afni/)

This package contains a collection of Pydra task interfaces for the afni 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.afni.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.afni.v*` packages, corresponding to the version of the afni 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

```bash
$ pip install -e .[test]
```

Then the tests, including [doctests](https://docs.python.org/3/library/doctest.html), can be launched using

```bash
$ 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

```bash
$ 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 repo in developer mode from the source directory and install pre-commit to
ensure consistent code-style and quality.

```bash
$ 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

```bash
$ pip install -r nipype-auto-conv/requirements.txt
```

The run the conversion script to convert Nipype interfaces to Pydra

```bash
$ 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.afni.auto` package should
be regenerated by running

```bash
$ nipype-auto-conv/generate
```

The tests should be run on the auto-generated tasks to see if they are valid

```bash
$ pytest --doctest-modules pydra/tasks/afni/auto/tests/test_<the-name-of-the-task-you-edited>.py
```

If the test passes you should then edit the `pydra/tasks/afni/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.

```python
from pydra.tasks.afni.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.