|
| 1 | +# Writing a workflow |
| 2 | + |
| 3 | +## Our workflow philosophy |
| 4 | + |
| 5 | +The explicit aim of CGAT-core is to allow users to quickly and easily build their own computational pipelines, speeding up their analysis workflow. |
| 6 | + |
| 7 | +When building pipelines, it is often useful to keep in mind the following guiding principles: |
| 8 | + |
| 9 | +### Flexibility |
| 10 | + |
| 11 | +There are always new tools and insights that could be incorporated into a pipeline. Ultimately, a pipeline should be flexible, and the code should not constrain you when implementing new features. |
| 12 | + |
| 13 | +### Scriptability |
| 14 | + |
| 15 | +The pipeline should be scriptable, i.e., the entire pipeline can be run within another pipeline. Similarly, parts of a pipeline should be easily duplicated to process several data streams in parallel. This is crucial in genome studies, as a single analysis will not always permit making inferences by itself. When writing a pipeline, we typically create a command line script (included in the CGAT-apps repository) and then run this script as a command line statement in the pipeline. |
| 16 | + |
| 17 | +### Reproducibility |
| 18 | + |
| 19 | +The pipeline should be fully automated so that the same inputs and configuration produce the same outputs. |
| 20 | + |
| 21 | +### Reusability |
| 22 | + |
| 23 | +The pipeline should be reusable on similar data, preferably requiring only changes to a configuration file (such as `pipeline.yml`). |
| 24 | + |
| 25 | +### Archivability |
| 26 | + |
| 27 | +Once finished, the whole project should be archivable without relying heavily on external data. This process should be simple; all project data should be self-contained, without needing to go through various directories or databases to determine dependencies. |
| 28 | + |
| 29 | +## Building a pipeline |
| 30 | + |
| 31 | +The best way to build a pipeline is to start from an example. The [CGAT Showcase](https://cgat-showcase.readthedocs.io/en/latest/index.html) contains a toy example of an RNA-seq analysis pipeline, demonstrating how simple workflows can be generated with minimal code. For more complex workflows, you can refer to [CGAT-Flow](https://github.com/cgat-developers/cgat-flow). |
| 32 | + |
| 33 | +For a step-by-step tutorial on running pipelines, refer to our [Getting Started Tutorial](#). |
| 34 | + |
| 35 | +To construct a pipeline from scratch, continue reading below. |
| 36 | + |
| 37 | +In an empty directory, create a new directory and then a Python file with the same name. For example: |
| 38 | + |
| 39 | +```bash |
| 40 | +mkdir test && touch pipeline_test.py |
| 41 | +``` |
| 42 | + |
| 43 | +All pipelines require a `.yml` configuration file that allows you to modify the behaviour of your code. This file is placed in the `test/` directory and should have the same name as the pipeline Python file: |
| 44 | + |
| 45 | +```bash |
| 46 | +touch test/pipeline.yml |
| 47 | +``` |
| 48 | + |
| 49 | +To facilitate debugging and reading, our pipelines are designed so that the pipeline task file contains Ruffus tasks, while the code to transform and analyse data is in an associated module file. |
| 50 | + |
| 51 | +If you wish to create a module file, it is conventionally named using the format `ModuleTest.py`. You can import it into the main pipeline task file (`pipeline_test.py`) as follows: |
| 52 | + |
| 53 | +```python |
| 54 | +import ModuleTest |
| 55 | +``` |
| 56 | + |
| 57 | +The [pipeline module](https://github.com/cgat-developers/cgat-core/tree/master/cgatcore/pipeline) in CGAT-core provides many useful functions for pipeline construction. |
| 58 | + |
| 59 | +## Pipeline input |
| 60 | + |
| 61 | +Pipelines are executed within a dedicated working directory, which usually contains: |
| 62 | + |
| 63 | +- A pipeline configuration file: `pipeline.yml` |
| 64 | +- Input data files, typically specified in the pipeline documentation |
| 65 | + |
| 66 | +Other files that might be used include external data files, such as genomes, referred to by their full path. |
| 67 | + |
| 68 | +Pipelines work with input files in the working directory, usually identified by their suffix. For instance, a mapping pipeline might look for any `.fastq.gz` files in the directory, perform QC on them, and map the reads to a genome sequence. |
| 69 | + |
| 70 | +## Pipeline output |
| 71 | + |
| 72 | +The pipeline will generate files and database tables in the working directory. You can structure your files/directories in any way that fits your needs—some prefer a flat structure with many files, while others use deeper hierarchies. |
| 73 | + |
| 74 | +To save disk space, compressed files should be used wherever possible. Most data files compress well; for example, `fastq` files often compress by up to 80%. Working with compressed files is straightforward using Unix pipes (`gzip`, `gunzip`, `zcat`). |
| 75 | + |
| 76 | +If you need random access to a file, load it into a database and index it appropriately. Genomic interval files can be indexed with `tabix` to allow random access. |
| 77 | + |
| 78 | +## Import statements |
| 79 | + |
| 80 | +To run our pipelines, you need to import the CGAT-core Python modules into your pipeline. We recommend importing the following modules for every CGAT pipeline: |
| 81 | + |
| 82 | +```python |
| 83 | +from ruffus import * |
| 84 | +import cgatcore.experiment as E |
| 85 | +from cgatcore import pipeline as P |
| 86 | +import cgatcore.iotools as iotools |
| 87 | +``` |
| 88 | + |
| 89 | +Additional modules can be imported as needed. |
| 90 | + |
| 91 | +## Selecting the appropriate Ruffus decorator |
| 92 | + |
| 93 | +Before starting a pipeline, it is helpful to map out the steps and flow of your potential pipeline on a whiteboard. This helps identify the inputs and outputs of each task. Once you have a clear picture, determine which Ruffus decorator to use for each task. For more information on each decorator, refer to the [Ruffus documentation](http://www.ruffus.org.uk/decorators/decorators.html). |
| 94 | + |
| 95 | +## Running commands within tasks |
| 96 | + |
| 97 | +To run a command line program within a pipeline task, build a statement and call the `P.run()` method: |
| 98 | + |
| 99 | +```python |
| 100 | +@transform('*.unsorted', suffix('.unsorted'), '.sorted') |
| 101 | +def sortFile(infile, outfile): |
| 102 | + statement = '''sort %(infile)s > %(outfile)s''' |
| 103 | + P.run(statement) |
| 104 | +``` |
| 105 | + |
| 106 | +In the `P.run()` method, the environment of the caller is examined for a variable called `statement`, which is then subjected to string substitution from other variables in the local namespace. In the example above, `%(infile)s` and `%(outfile)s` are replaced with the values of `infile` and `outfile`, respectively. |
| 107 | + |
| 108 | +The same mechanism also allows configuration parameters to be set, as shown here: |
| 109 | + |
| 110 | +```python |
| 111 | +@transform('*.unsorted', suffix('.unsorted'), '.sorted') |
| 112 | +def sortFile(infile, outfile): |
| 113 | + statement = '''sort -t %(tmpdir)s %(infile)s > %(outfile)s''' |
| 114 | + P.run(statement) |
| 115 | +``` |
| 116 | + |
| 117 | +In this case, the configuration parameter `tmpdir` is substituted into the command. |
| 118 | + |
| 119 | +### Chaining commands with error checking |
| 120 | + |
| 121 | +If you need to chain multiple commands, you can use `&&` to ensure that errors in upstream commands are detected: |
| 122 | + |
| 123 | +```python |
| 124 | +@transform('*.unsorted.gz', suffix('.unsorted.gz'), '.sorted') |
| 125 | +def sortFile(infile, outfile): |
| 126 | + statement = '''gunzip %(infile)s %(infile)s.tmp && |
| 127 | + sort -t %(tmpdir)s %(infile)s.tmp > %(outfile)s && |
| 128 | + rm -f %(infile)s.tmp''' |
| 129 | + P.run(statement) |
| 130 | +``` |
| 131 | + |
| 132 | +Alternatively, you can achieve this more efficiently using pipes: |
| 133 | + |
| 134 | +```python |
| 135 | +@transform('*.unsorted.gz', suffix('.unsorted.gz'), '.sorted.gz') |
| 136 | +def sortFile(infile, outfile): |
| 137 | + statement = '''gunzip < %(infile)s | sort -t %(tmpdir)s | gzip > %(outfile)s''' |
| 138 | + P.run(statement) |
| 139 | +``` |
| 140 | + |
| 141 | +The pipeline automatically inserts code to check for error return codes when multiple commands are combined in a pipe. |
| 142 | + |
| 143 | +## Running commands on a cluster |
| 144 | + |
| 145 | +To run commands on a cluster, set `to_cluster=True`: |
| 146 | + |
| 147 | +```python |
| 148 | +@files('*.unsorted.gz', suffix('.unsorted.gz'), '.sorted.gz') |
| 149 | +def sortFile(infile, outfile): |
| 150 | + to_cluster = True |
| 151 | + statement = '''gunzip < %(infile)s | sort -t %(tmpdir)s | gzip > %(outfile)s''' |
| 152 | + P.run(statement) |
| 153 | +``` |
| 154 | + |
| 155 | +Pipelines will use command line options such as `--cluster-queue` and `--cluster-priority` for global job control. For instance, to change the priority when starting the pipeline: |
| 156 | + |
| 157 | +```bash |
| 158 | +python <pipeline_script.py> --cluster-priority=-20 |
| 159 | +``` |
| 160 | + |
| 161 | +To set job-specific options, you can define additional variables: |
| 162 | + |
| 163 | +```python |
| 164 | +@files('*.unsorted.gz', suffix('.unsorted.gz'), '.sorted.gz') |
| 165 | +def sortFile(infile, outfile): |
| 166 | + to_cluster = True |
| 167 | + job_queue = 'longjobs.q' |
| 168 | + job_priority = -10 |
| 169 | + job_options = "-pe dedicated 4 -R y" |
| 170 | + statement = '''gunzip < %(infile)s | sort -t %(tmpdir)s | gzip > %(outfile)s''' |
| 171 | + P.run(statement) |
| 172 | +``` |
| 173 | + |
| 174 | +The statement above will run in the queue `longjobs.q` with a priority of `-10`. It will also be executed in the parallel environment `dedicated`, using at least four cores. |
| 175 | + |
| 176 | +## Combining commands |
| 177 | + |
| 178 | +To combine commands, use `&&` to ensure they execute in the intended order: |
| 179 | + |
| 180 | +```python |
| 181 | +statement = """ |
| 182 | +module load cutadapt && |
| 183 | +cutadapt ... |
| 184 | +""" |
| 185 | + |
| 186 | +P.run(statement) |
| 187 | +``` |
| 188 | + |
| 189 | +Without `&&`, the command would fail because the `cutadapt` command would execute as part of the `module load` statement. |
| 190 | + |
| 191 | +## Useful information regarding decorators |
| 192 | + |
| 193 | +For a full list of Ruffus decorators that control pipeline flow, see the [Ruffus documentation](http://www.ruffus.org.uk/decorators/decorators.html). |
| 194 | + |
| 195 | +Here are some examples of modifying an input file name to transform it into the output filename: |
| 196 | + |
| 197 | +### Using Suffix |
| 198 | + |
| 199 | +```python |
| 200 | +@transform(pairs, suffix('.fastq.gz'), ('_trimmed.fastq.gz', '_trimmed.fastq.gz')) |
| 201 | +``` |
| 202 | + |
| 203 | +This will transform an input `<name_of_file>.fastq.gz` into an output `<name_of_file>_trimmed.fastq.gz`. |
| 204 | + |
| 205 | +### Using Regex |
| 206 | + |
| 207 | +```python |
| 208 | +@follows(mkdir("new_folder.dir")) |
| 209 | +@transform(pairs, regex('(\S+).fastq.gz'), ('new_folder.dir/\1_trimmed.fastq.gz', 'new_folder.dir/\1_trimmed.fastq.gz')) |
| 210 | +``` |
| 211 | + |
| 212 | +### Using Formatter |
| 213 | + |
| 214 | +```python |
| 215 | +@follows(mkdir("new_folder.dir")) |
| 216 | +@transform(pairs, formatter('(\S+).fastq.gz'), ('new_folder.dir/{SAMPLE[0]}_trimmed.fastq.gz', 'new_folder.dir/{SAMPLE[0]}_trimmed.fastq.gz')) |
| 217 | +``` |
| 218 | + |
| 219 | +This documentation aims to provide a comprehensive guide to writing your own workflows and pipelines. For more advanced usage, please refer to the original CGAT-core and Ruffus documentation. |
| 220 | + |
0 commit comments