/doc/tutorials/simple_tutorial/step1_follows.rst

  1.. include:: ../../global.inc
  2.. _Simple_Tutorial_1st_step:
  3    
  4
  5###################################################################
  6Step 1: An introduction to Ruffus pipelines
  7###################################################################
  8
  9    * :ref:`Simple tutorial overview <Simple_Tutorial>` 
 10
 11
 12    Computational pipelines often become quite simple
 13    if we breakdown the process into simple stages.
 14    
 15    .. note::
 16        
 17        Ruffus refers to each stage of your pipeline as a :term:`task`.
 18
 19    | Let us start with the usual "Hello World". 
 20    | We have the following two python functions which
 21      we would like to turn into an automatic pipeline:
 22      
 23    
 24        .. image:: ../../images/simple_tutorial_hello_world.png
 25
 26    .. ::
 27    
 28        ::
 29        
 30            def first_task():
 31                print "Hello "
 32        
 33            def second_task():
 34                print "world"
 35
 36    
 37    The simplest **Ruffus** pipeline would look like this:
 38    
 39        .. image:: ../../images/simple_tutorial_intro_follows.png
 40    
 41    .. ::
 42    
 43        ::
 44        
 45            from ruffus import *
 46            
 47            def first_task():
 48                print "Hello "
 49        
 50            @follows(first_task)
 51            def second_task():
 52                print "world"
 53    
 54            pipeline_run([second_task])
 55
 56    
 57    The functions which do the actual work of each stage of the pipeline remain unchanged.
 58    The role of **Ruffus** is to make sure these functions are called in the right order, 
 59    with the right parameters, running in parallel using multiprocessing if desired.
 60        
 61    There are three simple parts to building a **ruffus** pipeline
 62
 63        #. importing ruffus
 64        #. "Decorating" functions which are part of the pipeline
 65        #. Running the pipeline!
 66    
 67.. index:: 
 68    pair: decorators; Tutorial
 69    
 70
 71****************************
 72"Decorating" functions
 73****************************
 74
 75    You need to tag or :term:`decorator` existing code to tell **Ruffus** that they are part
 76    of the pipeline.
 77    
 78    .. note::
 79        
 80        :term:`decorator`\ s are ways to tag or mark out functions. 
 81
 82        They start with a ``@`` prefix and take a number of parameters in parenthesis.
 83
 84        .. image:: ../../images/simple_tutorial_decorator_syntax.png
 85                
 86    The **ruffus** decorator :ref:`@follows <decorators.follows>` makes sure that
 87    ``second_task`` follows ``first_task``.
 88    
 89
 90    | Multiple :term:`decorator`\ s can be used for each :term:`task` function to add functionality
 91      to *Ruffus* pipeline functions. 
 92    | However, the decorated python functions can still be
 93      called normally, outside of *Ruffus*.
 94    | *Ruffus* :term:`decorator`\ s can be added to (stacked on top of) any function in any order.
 95
 96    * :ref:`More on @follows in the in the Ruffus `Manual <manual.follows>`
 97    * :ref:`@follows syntax in detail <decorators.follows>`
 98
 99
100.. index:: 
101    pair: pipeline_run; Tutorial
102
103****************************
104Running the pipeline
105****************************
106
107    We run the pipeline by specifying the **last** stage (:term:`task` function) of your pipeline.
108    Ruffus will know what other functions this depends on, following the appropriate chain of
109    dependencies automatically, making sure that the entire pipeline is up-to-date.
110
111    Because ``second_task`` depends on ``first_task``, both functions are executed in order.
112
113        ::
114            
115            >>> pipeline_run([second_task], verbose = 1)
116        
117    Ruffus by default prints out the ``verbose`` progress through the pipelined code, 
118    interleaved with the **Hello** printed by ``first_task`` and **World** printed
119    by ``second_task``.
120    
121        .. image:: ../../images/simple_tutorial_hello_world_output.png
122
123    .. ::
124    
125        ::
126            
127            >>> pipeline_run([second_task], verbose = 1)
128            Start Task = first_task
129            Hello
130                Job completed
131            Completed Task = first_task
132            Start Task = second_task
133            world
134                Job completed
135            Completed Task = second_task
136    
137    
138    
139