Creating a new workflow.

A workflow is a series of DIPY operations with fixed inputs and outputs that is callable via command line or another interface.

For example, after installing DIPY, you can call anywhere from your command line:

dipy_nlmeans t1.nii.gz t1_denoised.nii.gz

First create your workflow (let’s name this workflow file as my_workflow.py). Usually this is a python file in the <../dipy/workflows> directory.

import shutil

shutil Will be used for sample file manipulation.

from dipy.workflows.workflow import Workflow

Workflow is the base class that will be extended to create our workflow.

class AppendTextFlow(Workflow):
    def run(
        self, input_files, text_to_append="dipy", out_dir="", out_file="append.txt"
    ):
        """
        Parameters
        ----------
        input_files : string
            Path to the input files. This path may contain wildcards to
            process multiple inputs at once.

        text_to_append : string, optional
            Text that will be appended to the file. (default 'dipy')

        out_dir : string, optional
            Where the resulting file will be saved. (default '')

        out_file : string, optional
            Name of the result file to be saved. (default 'append.txt')
        """

        """
        ``AppendTextFlow`` is the name of our workflow. Note that it needs
        to extend Workflow for everything to work properly. It will append
        text to a file.

        It is mandatory to have out_dir as a parameter. It is also mandatory
        to put `out_` in front of every parameter that is going to be an
        output. Lastly, all `out_` params needs to be at the end of the params
        list.

        The ``run`` docstring is very important, you need to document every
        parameter as they will be used with inspection to build the command line
        argument parser.
        """

        io_it = self.get_io_iterator()

        for in_file, out_file in io_it:
            shutil.copy(in_file, out_file)

            with open(out_file, "a") as myfile:
                myfile.write(text_to_append)

Use self.get_io_iterator() in every workflow you create. This creates an IOIterator object that create output file names and directory structure based on the inputs and some other advanced output strategy parameters.

By iterating on the IOIterator object you created previously you conveniently get all input and output paths for every input file found when globbing the input parameters.

The code in the loop is the actual workflow processing code. It can be anything. For example, it just appends text to an input file.

This is it for the workflow! Now to be able to call it easily via command line, you need to add this workflow in 2 different files:

• <dipy_root>/pyproject.toml: open this file and add the following line to the [project.scripts] section: dipy_append_text = "dipy.workflows.cli:run"

• <dipy_root>/dipy/workflows/cli.py: open this file and add the workflow information to the cli_flows dictionary. The key is the name of the command line command and the value is a tuple with the module name and the workflow class name. In this case it would be: "dipy_append_text": ("dipy.workflows.my_workflow", "AppendTextFlow")

That`s it! Now you can call your workflow from anywhere with the command line. Let’s just call the script you just made with -h to see the argparser help text:

dipy_append_text --help

You should see all your parameters available along with some extra common ones like logging file and force overwrite. Also all the documentation you wrote about each parameter is there.