{
  "cells": [
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "%matplotlib inline"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "\n# Creating a new workflow.\n\nA workflow is a series of DIPY_ operations with fixed inputs and outputs\nthat is callable via command line or another interface.\n\nFor example, after installing DIPY_, you can call anywhere from your command\nline::\n\n    dipy_nlmeans t1.nii.gz t1_denoised.nii.gz\n\nFirst create your workflow (let's name this workflow file as my_workflow.py). Usually this is a python file in\nthe ``<../dipy/workflows>`` directory.\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "import shutil"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "``shutil`` Will be used for sample file manipulation.\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "from dipy.workflows.workflow import Workflow"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "``Workflow`` is the base class that will be extended to create our workflow.\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "class AppendTextFlow(Workflow):\n\n    def run(self, input_files, text_to_append='dipy', out_dir='',\n            out_file='append.txt'):\n        \"\"\"\n        Parameters\n        ----------\n        input_files : string\n            Path to the input files. This path may contain wildcards to\n            process multiple inputs at once.\n\n        text_to_append : string, optional\n            Text that will be appended to the file. (default 'dipy')\n\n        out_dir : string, optional\n            Where the resulting file will be saved. (default '')\n\n        out_file : string, optional\n            Name of the result file to be saved. (default 'append.txt')\n        \"\"\"\n\n        \"\"\"\n        ``AppendTextFlow`` is the name of our workflow. Note that it needs\n        to extend Workflow for everything to work properly. It will append\n        text to a file.\n\n        It is mandatory to have out_dir as a parameter. It is also mandatory\n        to put `out_` in front of every parameter that is going to be an\n        output. Lastly, all `out_` params needs to be at the end of the params\n        list.\n\n        The ``run`` docstring is very important, you need to document every\n        parameter as they will be used with inspection to build the command line\n        argument parser.\n        \"\"\"\n\n        io_it = self.get_io_iterator()\n\n        for in_file, out_file in io_it:\n\n            shutil.copy(in_file, out_file)\n\n            with open(out_file, 'a') as myfile:\n\n                myfile.write(text_to_append)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "Use self.get_io_iterator() in every workflow you create. This creates\nan ``IOIterator`` object that create output file names and directory structure\nbased on the inputs and some other advanced output strategy parameters.\n\nBy iterating on the ``IOIterator`` object you created previously you\nconveniently get all input and output paths for every input file\nfound when globbing the input parameters.\n\nThe code in the loop is the actual workflow processing code. It can be\nanything. For example, it just appends text to an input file.\n\nThis is it for the workflow! Now to be able to call it easily via command\nline, you need to add this bit of code. Usually this is in a separate\nexecutable file located in ``bin``.\n\nThe first line imports the run_flow method from the flow_runner class.\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "from dipy.workflows.flow_runner import run_flow"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "The second line imports the ``AppendTextFlow`` class from the newly created\n``my_workflow.py`` file. In this specific case, we comment on this import\nsince the ``AppendTextFlow`` class is not in an external file but in the\ncurrent file.\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "# from dipy.workflows.my_workflow import AppendTextFlow"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "This is the method that will wrap everything that is needed to make a flow\ncommand line ready then run it.\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "# if __name__ == \"__main__\":\n#     run_flow(AppendTextFlow())"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "This is the only thing needed to make your workflow available through the\ncommand line.\n\nNow just call the script you just made with ``-h`` to see the argparser help\ntext::\n\n   python workflow_creation.py --help\n\nYou should see all your parameters available along with some extra common ones\nlike logging file and force overwrite. Also all the documentation you wrote\nabout each parameter is there.\n\nNow call it for real with a text file::\n\n   python workflow_creation.py ./text_file.txt\n\n\n.. include:: ../links_names.inc\n\n\n"
      ]
    }
  ],
  "metadata": {
    "kernelspec": {
      "display_name": "Python 3",
      "language": "python",
      "name": "python3"
    },
    "language_info": {
      "codemirror_mode": {
        "name": "ipython",
        "version": 3
      },
      "file_extension": ".py",
      "mimetype": "text/x-python",
      "name": "python",
      "nbconvert_exporter": "python",
      "pygments_lexer": "ipython3",
      "version": "3.9.13"
    }
  },
  "nbformat": 4,
  "nbformat_minor": 0
}