Toil DocumentationRelease 3.16.0a1

UCSC Computational Genomics Lab

May 04, 2018

Getting Started

1 Installation 31.1 Preparing Your Python Runtime Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31.2 Basic Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41.3 Installing Toil with Extra Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41.4 Building from Source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

2 Quickstart Examples 72.1 Running a basic workflow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72.2 Running a basic CWL workflow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82.3 Running a basic WDL workflow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92.4 A (more) real-world example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92.5 Launching a Toil Workflow in AWS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152.6 Running a CWL Workflow on AWS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162.7 Running a Workflow with Autoscaling - Cactus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

3 Introduction 213.1 Job Store . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213.2 Batch System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223.3 Provisioner . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

4 Commandline Options 234.1 The Job Store . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234.2 Commandline Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234.3 Restart Option . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274.4 Running Workflows with Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284.5 Setting Options directly with the Toil Script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

5 Toil Debugging 315.1 Introspecting the Jobstore . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315.2 Stats and Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

6 Running in the Cloud 336.1 Managing a Cluster of Virtual Machines (Provisioning) . . . . . . . . . . . . . . . . . . . . . . . . . 336.2 Storage (Toil jobStore) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

7 Cloud Platforms 357.1 Running in AWS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

i

7.2 Running in Azure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 417.3 Running in Google Compute Engine (GCE) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 427.4 Cluster Utilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 467.5 Status Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 477.6 Stats Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 497.7 Clean Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 497.8 Launch-Cluster Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 497.9 Ssh-Cluster Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 517.10 Rsync-Cluster Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 517.11 destroy-cluster Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 517.12 Kill Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52

8 HPC Environments 53

9 CWL in Toil 559.1 Running CWL Locally . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 559.2 Running CWL in the Cloud . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55

10 WDL in Toil 5710.1 How to Run a WDL file in Toil . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5710.2 ENCODE Example from ENCODE-DCC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5710.3 GATK Examples from the Broad . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5810.4 toilwdl.py Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5910.5 WDL Specifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59

11 Developing a Workflow 6111.1 Scripting Quick Start . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6111.2 Job Basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6211.3 Invoking a Workflow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6211.4 Specifying Commandline Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6311.5 Resuming a Workflow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6411.6 Functions and Job Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6411.7 Workflows with Multiple Jobs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6511.8 Dynamic Job Creation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6711.9 Promises . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6711.10 Promised Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6911.11 FileID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7011.12 Managing files within a workflow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7011.13 Using Docker Containers in Toil . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7311.14 Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7411.15 Checkpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7511.16 Encapsulation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7511.17 Depending on Toil . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7611.18 Best Practices for Dockerizing Toil Workflows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77

12 Toil Class API 79

13 Job Store API 81

14 Toil Job API 8914.1 FunctionWrappingJob . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8914.2 JobFunctionWrappingJob . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8914.3 EncapsulatedJob . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9014.4 Promise . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92

ii

15 Job Methods API 95

16 Job.Runner API 101

17 Job.FileStore API 103

18 Batch System API 10718.1 Batch System Enivronmental Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10718.2 Batch System API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107

19 Job.Service API 111

20 Exceptions API 113

21 Running Tests 11521.1 Running Tests (pytest) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11621.2 Test Environment Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11621.3 Using Docker with Quay . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11721.4 Running Mesos Tests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117

22 Developing with Docker 11922.1 Making Your Own Toil Docker Image . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11922.2 Running a Cluster Locally . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120

23 Maintainers Guidelines 12323.1 Naming Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12323.2 Pull Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12423.3 Multi-Author Pull Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124

24 Toil Architecture 12524.1 Optimizations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12724.2 Toil support for Common Workflow Language . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128

25 Auto-Deployment 13125.1 Auto Deployment with Sibling Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13225.2 Auto-Deploying a Package Hierarchy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13325.3 Relying on Shared Filesystems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134

26 Environment Variables 135

27 Static Azure Clusters 13727.1 Launch a leader node in Azure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .