See Decorators for more decorators
There are only three functions for Ruffus pipelines:
- pipeline_run executes a pipeline
- pipeline_printout prints a list of tasks and jobs which will be run in a pipeline
- pipeline_printout_graph prints a schematic flowchart of pipeline tasks in various graphical formats
pipeline_run ( target_tasks, [ forcedtorun_tasks = [], multiprocess = 1, logger = stderr_logger, gnu_make_maximal_rebuild_mode = True, verbose =1], runtime_data = None, one_second_per_job = True, touch_files_only = False)
Purpose:
Runs all specified pipelined functions if they or any antecedent tasks are incomplete or out-of-date.
- Example:
# # Run task2 whatever its state, and also task1 and antecedents if they are incomplete # Do not log pipeline progress messages to stderr # pipeline_run([task1, task2], forcedtorun_tasks = [task2], logger = blackhole_logger)Parameters:
- target_tasks
Pipeline functions and any necessary antecedents (specified implicitly or with @follows) which should be invoked with the appropriate parameters if they are incomplete or out-of-date.
- forcedtorun_tasks
Optional. These pipeline functions will be invoked regardless of their state. Any antecedents tasks will also be executed if they are out-of-date or incomplete.
- multiprocess
Optional. The number of processes which should be dedicated to running in parallel independent tasks and jobs within each task. If multiprocess is set to 1, the pipeline will execute in the main process.
- logger
For logging messages indicating the progress of the pipeline in terms of tasks and jobs. Defaults to outputting to sys.stderr. Setting logger=blackhole_logger will prevent any logging output.
- gnu_make_maximal_rebuild_mode
Warning
This is a dangerous option. Use rarely and with caution
Optional parameter governing how Ruffus determines which part of the pipeline is out of date and needs to be re-run. If set to False, ruffus will work back from the target_tasks and only execute the pipeline after the first up-to-date tasks that it encounters. For example, if there are four tasks:
# # task1 -> task2 -> task3 -> task4 -> task5 # target_tasks = [task5]If task3() is up-to-date, then only task4() and task5() will be run. This will be the case even if task2() and task1() are incomplete.
This allows you to remove all intermediate results produced by task1 -> task3.
- verbose
Optional parameter indicating the verbosity of the messages sent to logger:
verbose = 0 : prints nothing verbose = 1 : logs warnings and tasks which are not up-to-date and which will be run verbose = 2 : logs doc strings for task functions as well verbose = 3 : logs job parameters for jobs which are out-of-date verbose = 4 : logs list of up-to-date tasks but parameters for out-of-date jobs verbose = 5 : logs parameters for all jobs whether up-to-date or not verbose = 10: logs messages useful only for debugging ruffus pipeline codeverbose >= 10 are intended for debugging Ruffus by the developers and the details are liable to change from release to release
- runtime_data
Experimental feature for passing data to tasks at run time
- one_second_per_job
By default, Ruffus ensures jobs take a minimum of 1 second to complete, to get around coarse grained timestamps in some file systems. This is rarely an issue when many jobs run in parallel. If your file system has sub-second time stamps, you can turn off this delay by setting one_second_per_job to False
- touch_files_only
Create or update output files only to simulate the running of the pipeline. Does not invoke real task functions to run jobs. This is most useful to force a pipeline to acknowledge that a particular part is now up-to-date.
This will not work properly if the identities of some files are not known before hand, and depend on run time. In other words, not recommended if @split or custom parameter generators are being used.
pipeline_printout (output_stream, target_tasks, forcedtorun_tasks = [], verbose = 1, indent = 4, gnu_make_maximal_rebuild_mode = True, wrap_width = 100, runtime_data = None)
Purpose:
Prints out all the pipelined functions which will be invoked given specified target_tasks without actually running the pipeline. Because this is a simulation, some of the job parameters may be incorrect. For example, the results of a @split operation is not predetermined and will only be known after the pipelined function splits up the original data. Parameters of all downstream pipelined functions will be changed depending on this initial operation.
- Example:
# # Simulate running task2 whatever its state, and also task1 and antecedents # if they are incomplete # Print out results to STDOUT # pipeline_printout(sys.stdout, [task1, task2], forcedtorun_tasks = [task2], verbose = 1)Parameters:
- output_stream
Where to printout the results of simulating the running of the pipeline.
- target_tasks
As in pipeline_run: Pipeline functions and any necessary antecedents (specified implicitly or with @follows) which should be invoked with the appropriate parameters if they are incomplete or out-of-date.
- forcedtorun_tasks
As in pipeline_run:These pipeline functions will be invoked regardless of their state. Any antecedents tasks will also be executed if they are out-of-date or incomplete.
- verbose
Optional parameter indicating the verbosity of the printout. Please do not expect messages to stay constant between release
verbose = 0 : prints nothing verbose = 1 : logs warnings and tasks which are not up-to-date and which will be run verbose = 2 : logs doc strings for task functions as well verbose = 3 : logs job parameters for jobs which are out-of-date verbose = 4 : logs list of up-to-date tasks but parameters for out-of-date jobs verbose = 5 : logs parameters for all jobs whether up-to-date or not verbose = 10: logs messages useful only for debugging ruffus pipeline code
- indent
Optional parameter governing the indentation when printing out the component job parameters of each task function.
- gnu_make_maximal_rebuild_mode
Warning
This is a dangerous option. Use rarely and with caution
See explanation in pipeline_run.
- wrap_width
Optional parameter governing the length of each line before it starts wrapping around.
- runtime_data
Experimental feature for passing data to tasks at run time
pipeline_printout_graph (stream, output_format, target_tasks, forcedtorun_tasks = [], ignore_upstream_of_target = False, skip_uptodate_tasks = False, gnu_make_maximal_rebuild_mode = True, test_all_task_for_update = True, no_key_legend = False, minimal_key_legend = True, user_colour_scheme = None, pipeline_name = “Pipeline”, size = (11,8), dpi = 120, runtime_data = None)
Purpose:
Prints out flowchart of all the pipelined functions which will be invoked given specified target_tasks without actually running the pipeline.
- Example:
pipeline_printout_graph("flowchart.jpg", "jpg", [task1, task16], forcedtorun_tasks = [task2], no_key_legend = True)Customising appearance:
The user_colour_scheme parameter can be used to change flowchart colours. This allows the default Colour Schemes to be set. An example of customising flowchart appearance is available (see code) .Parameters:
- stream
The file or file-like object to which the flowchart should be printed. If a string is provided, it is assumed that this is the name of the output file which will be opened automatically.
- output_format
- target_tasks
As in pipeline_run: Pipeline functions and any necessary antecedents (specified implicitly or with @follows) which should be invoked with the appropriate parameters if they are incomplete or out-of-date.
- forcedtorun_tasks
As in pipeline_run:These pipeline functions will be invoked regardless of their state. Any antecedents tasks will also be executed if they are out-of-date or incomplete.
- draw_vertically
Draw flowchart in vertical orientation
- ignore_upstream_of_target
Start drawing flowchart from specified target tasks. Do not draw tasks which are downstream (subsequent) to the targets.
- ignore_upstream_of_target
Do not draw up-to-date / completed tasks in the flowchart unless they are lie on the execution path of the pipeline.
- gnu_make_maximal_rebuild_mode
Warning
This is a dangerous option. Use rarely and with caution
See explanation in pipeline_run.
- test_all_task_for_update
Indicates whether intermediate tasks are out of date or not. Normally Ruffus will stop checking dependent tasks for completion or whether they are out-of-date once it has discovered the maximal extent of the pipeline which has to be run.For displaying the flow of the pipeline, this is hardly very informative.
- no_key_legend
Do not include key legend explaining the colour scheme of the flowchart.
- minimal_key_legend
Do not include unused task types in key legend.
- user_colour_scheme
Dictionary specifying colour scheme for flowchart
See complete list of Colour Schemes.
Colours can be names e.g. "black" or quoted hex e.g. '"#F6F4F4"' (note extra quotes)Default values will be used unless specified
key
Subkey
- 'colour_scheme_index'
index of default colour scheme,0-7, defaults to 0 unless specified
- 'Final target'
- 'Explicitly specified task'
- 'Task to run'
- 'Down stream'
- 'Up-to-date Final target'
- 'Up-to-date task forced to rerun'
- 'Up-to-date task'
- 'Vicious cycle'
- 'fillcolor'
- 'fontcolor'
- 'color'
- 'dashed' = 0/1
Colours / attributes for each task type
- 'Vicious cycle'
- 'Task to run'
- 'Up-to-date'
- 'linecolor'
Colours for arrows between tasks
- 'Pipeline'
- 'fontcolor'
Flowchart title colour
- 'Key'
- 'fontcolor'
- 'fillcolor'
Legend colours
Example:
Use colour scheme index = 1
pipeline_printout_graph ("flowchart.svg", "svg", [final_task], user_colour_scheme = { "colour_scheme_index" :1, "Pipeline" :{"fontcolor" : '"#FF3232"' }, "Key" :{"fontcolor" : "Red", "fillcolor" : '"#F6F4F4"' }, "Task to run" :{"linecolor" : '"#0044A0"' }, "Final target" :{"fillcolor" : '"#EFA03B"', "fontcolor" : "black", "dashed" : 0 } })
- pipeline_name
Specify title for flowchart
- size
Size in inches for flowchart
- dpi
Resolution in dots per inch. Ignored for svg output
- runtime_data
Experimental feature for passing data to tasks at run time