1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
|
.. include:: ../../global.inc
.. include:: manual_chapter_numbers.inc
.. index::
pair: pipeline_printout_graph; Tutorial
.. _new_manual.pipeline_printout_graph:
############################################################################################################################################################################################################
|new_manual.pipeline_printout_graph.chapter_num|: Displaying the pipeline visually with :ref:`pipeline_printout_graph(...) <pipeline_functions.pipeline_printout_graph>`
############################################################################################################################################################################################################
.. seealso::
* :ref:`Manual Table of Contents <new_manual.table_of_contents>`
* :ref:`pipeline_printout_graph(...) <pipeline_functions.pipeline_printout_graph>` syntax
* :ref:`@graphviz(...) <decorators.graphviz>` syntax
.. note::
Remember to look at the example code:
* :ref:`new_manual.pipeline_printout_graph.code`
=============================================
Printing out a flowchart of our pipeline
=============================================
It is all very well being able to trace the data flow through the pipeline as text.
Sometimes, however, we need a bit of eye-candy!
We can see a flowchart for our fledgling pipeline by executing:
::
pipeline_printout_graph ( 'flowchart.svg',
'svg',
[second_task],
no_key_legend = False)
.. image:: ../../images/simple_tutorial_stage5_flowchart.png
:scale: 70
Flowcharts can be printed in a large number of formats including ``jpg``, ``svg``, ``png`` and ``pdf``.
.. note::
Flowcharts rely on the ``dot`` programme from `Graphviz <http://www.graphviz.org/>`__.
Please make sure this is installed.
There are 8 standard colour schemes, but you can further customise all the colours to your satisfaction:
.. image:: ../../images/flowchart_colour_schemes.png
See :ref:`here <new_manual.flowchart_colours>` for example code.
================================================================
Command line options made easier with ``ruffus.cmdline``
================================================================
If you are using ``ruffus.cmdline``, then you can easily ask for a flowchart from the command line:
.. code-block:: bash
your_script.py --flowchart pipeline_flow_chart.png
The output format is deduced from the extension but can be specified manually:
.. code-block:: bash
# specify format. Otherwise, deduced from the extension
your_script.py --flowchart pipeline_flow_chart.png --flowchart_format png
Print the flow chart horizontally or vertically...
.. code-block:: bash
# flowchart proceeds from left to right , rather than from top to bottom
your_script.py --flowchart pipeline_flow_chart.png --draw_graph_horizontally
...with or without a key legend
.. code-block:: bash
# Draw key legend
your_script.py --flowchart pipeline_flow_chart.png --key_legend_in_graph
=============================================
Horribly complicated pipelines!
=============================================
Flowcharts are especially useful if you have really complicated pipelines, such as
.. image:: ../../images/simple_tutorial_complex_flowchart.png
:scale: 70
=============================================
Circular dependency errors in pipelines!
=============================================
Especially, if the pipeline is not set up properly, and vicious circular dependencies
are present:
.. image:: ../../images/simple_tutorial_complex_flowchart_error.png
:scale: 70
.. _new_manual.graphviz:
==========================================================================================
``@graphviz``: Customising the appearance of each task
==========================================================================================
The graphic for each task can be further customised as you please by adding
`graphviz attributes <http://www.graphviz.org/doc/info/attrs.html>`__ such as the URL, shape, colour
directly to that node using the decorator ```@graphviz``.
For example, we can customise the graphic for ``myTask()`` to look like:
.. image:: ../../images/history_html_flowchart.png
:scale: 30
by adding the requisite attributes as follows:
.. code-block:: python
@graphviz(URL='"http://cnn.com"', fillcolor = '"#FFCCCC"',
color = '"#FF0000"', pencolor='"#FF0000"', fontcolor='"#4B6000"',
label_suffix = "???", label_prefix = "What is this?<BR/> ",
label = "<What <FONT COLOR=\"red\">is</FONT>this>",
shape= "component", height = 1.5, peripheries = 5,
style="dashed")
def Up_to_date_task2(infile, outfile):
pass
# Can use dictionary if you wish...
graphviz_params = {"URL":"http://cnn.com", "fontcolor": '"#FF00FF"'}
@graphviz(**graphviz_params)
def myTask(input,output):
pass
.. **
You can even using HTML formatting in task names, including specifying line wraps (as in the above example),
using the ``label`` parameter. However, HTML labels **must** be enclosed in ``<`` and ``>``.
.. code-block:: python
label = "<Line <BR/> wrapped task_name()>"
Otherwise, you can also opt to keep the task name and wrap it with a prefix and suffix:
.. code-block:: python
label_suffix = "??? ", label_prefix = ": What is this?"
The ``URL`` attribute allows the generation of clickable svg, and also client / server
side image maps usable in web pages.
See `Graphviz documentation <http://www.graphviz.org/content/output-formats#dimap>`__
|
