doc/sdk/python/crunch-utility-libraries.html.textile.liquid

   1 ---
   2 layout: default
   3 navsection: sdk
   4 navmenu: Python
   5 title: "Crunch utility libraries"
   6
   7 ...
   8 {% comment %}
   9 Copyright (C) The Arvados Authors. All rights reserved.
  10
  11 SPDX-License-Identifier: CC-BY-SA-3.0
  12 {% endcomment %}
  13
  14 Several utility libraries are included with Arvados. They are intended to make it quicker and easier to write your own crunch scripts.
  15
  16 * "Python SDK extras":#pythonsdk
  17 * "Toolkit wrappers":#toolkit_wrappers
  18
  19 h2(#pythonsdk). Python SDK extras
  20
  21 The Python SDK adds some convenience features that are particularly useful in crunch scripts, in addition to the standard set of API calls.
  22
  23 In a crunch job, the environment variables @ARVADOS_API_HOST@ and @ARVADOS_API_TOKEN@ will be set up so the job has the privileges of the user who submitted the job.
  24
  25 <pre>
  26 import arvados
  27
  28 my_user = arvados.api().users().current().execute()
  29 my_uuid = my_user['uuid']
  30 </pre>
  31
  32 h3. Get the current job and task parameters
  33
  34 @arvados.current_job()@ and @arvados.current_task()@ are convenient ways to retrieve the current Job and Task, using the @JOB_UUID@ and @TASK_UUID@ environment variables provided to each crunch task process.
  35
  36 <pre>
  37 this_job = arvados.current_job()
  38 this_task = arvados.current_task()
  39 this_job_input = this_job['script_parameters']['input']
  40 this_task_input = this_task['parameters']['input']
  41 </pre>
  42
  43 h3(#one_task_per_input). Queue a task for each input file
  44
  45 A common pattern for a crunch job is to run one task to scan the input, and one task per input file to do the work.
  46
  47 The @one_task_per_input_file()@ function implements this pattern. Pseudocode:
  48
  49 <pre>
  50 if this is the job's first (default) task:
  51     for each file in the 'input' collection:
  52         queue a new task, with parameters['input'] = file
  53     exit
  54 else:
  55     return
  56 </pre>
  57
  58 Usage:
  59
  60 <pre>
  61 import arvados
  62 arvados.job_setup.one_task_per_input_file(if_sequence=0, and_end_task=True)
  63
  64 # Now do the work on a single file
  65 my_input = this_task['parameters']['input']
  66 </pre>
  67
  68 h3. Set the current task's output and success flag
  69
  70 Each task in a crunch job must make an API call to record its output and set its @success@ attribute to True. The object returned by @current_task()@ has a @set_output()@ method to make the process more succinct.
  71
  72 <pre>
  73 arvados.current_task().set_output(my_output_locator)
  74 </pre>
  75
  76 h3. arvados_ipc.py
  77
  78 Manage child processes and FIFOs (pipes).
  79
  80
  81 This module makes it easier to check the exit status of every child process you start, and close the unused end of each FIFO at the appropriate time.
  82
  83 <pre>
  84 from arvados_ipc import *
  85
  86 children = {}
  87 pipes = {}
  88
  89 pipe_setup(pipes, 'hellopipe')
  90 if 0 == named_fork(children, 'child_a'):
  91     pipe_closeallbut(pipes, ('hellopipe', 'w'))
  92     os.write(pipes['hellopipe', 'w'], "Hello, parent.")
  93     os._exit(0)
  94
  95 pipe_closeallbut(pipes, ('hellopipe', 'r'))
  96 with os.fdopen(pipes['hellopipe', 'r'], 'rb') as f:
  97     message = f.read()
  98     sys.stderr.write("Child says: " + message + "\n")
  99
 100 if not waitpid_and_check_children(children):
 101     raise Exception("Child process exited non-zero.")
 102 </pre>
 103
 104 The "crunch scripts" included with Arvados include some more examples of using the arvados_ipc module.
 105
 106 h2(#toolkit_wrappers). Toolkit wrappers
 107
 108 The following *arvados-&lowast;.py* modules provide "extract, build, run" helpers to make it easy to incorporate common analysis tools in your crunch scripts.
 109
 110 h3. arvados_bwa.py
 111
 112 Build and run the "bwa":http://bio-bwa.sourceforge.net/bwa.shtml program.
 113
 114 The module retrieves the bwa source code from Keep, using the job's @bwa_tbz@ parameter.
 115
 116 <pre>
 117 import arvados_bwa
 118 arvados_bwa.run('aln', [ref_basename, '-'],
 119                 stdin=open(fastq_filename,'rb'),
 120                 stdout=open(aln_filename,'wb'))
 121 </pre>
 122
 123 On qr1hi.arvadosapi.com, the source distribution @bwa-0.7.5a.tar.bz2@ is available in the collection @8b6e2c4916133e1d859c9e812861ce13+70@.
 124
 125 <pre>
 126 {
 127  "script_parameters":{
 128   "bwa_tbz":"8b6e2c4916133e1d859c9e812861ce13+70",
 129   ...
 130  },
 131  ...
 132 }
 133 </pre>
 134
 135 h3. arvados_gatk2.py
 136
 137 Extract and run the "Genome Analysis Toolkit":http://www.broadinstitute.org/gatk/ programs.
 138
 139 The module retrieves the binary distribution tarball from Keep, using the job's @gatk_tbz@ parameter.
 140
 141 <pre>
 142 arvados_gatk2.run(
 143     args=[
 144         '-nct', 8,
 145         '-T', 'BaseRecalibrator',
 146         '-R', ref_fasta_files[0],
 147         '-I', input_bam_files[0],
 148         '-o', recal_file,
 149         ])
 150 </pre>
 151
 152 On qr1hi.arvadosapi.com, the binary distribution @GenomeAnalysisTK-2.6-4.tar.bz2@ is available in the collection @5790482512cf6d5d6dfd50b7fd61e1d1+86@.
 153
 154 The GATK data bundle is available in the collection @d237a90bae3870b3b033aea1e99de4a9+10820@.
 155
 156 <pre>
 157 {
 158  "script_parameters":{
 159   "gatk_tbz":"7e0a277d6d2353678a11f56bab3b13f2+87",
 160   "gatk_bundle":"d237a90bae3870b3b033aea1e99de4a9+10820",
 161   ...
 162  },
 163  ...
 164 }
 165 </pre>
 166
 167 h3. arvados_samtools.py
 168
 169 Build and run the "samtools":http://samtools.sourceforge.net/samtools.shtml program.
 170
 171
 172 The module retrieves the samtools source code from Keep, using the job's @samtools_tgz@ parameter.
 173
 174 <pre>
 175 import arvados_samtools
 176 arvados_samtools.run('view', ['-S', '-b', '-'],
 177                      stdin=open(sam_filename,'rb'),
 178                      stdout=open(bam_filename,'wb'))
 179 </pre>
 180
 181 On qr1hi.arvadosapi.com, the source distribution @samtools-0.1.19.tar.gz@ is available in the collection @c777e23cf13e5d5906abfdc08d84bfdb+74@.
 182
 183 <pre>
 184 {
 185  "script_parameters":{
 186   "samtools_tgz":"c777e23cf13e5d5906abfdc08d84bfdb+74",
 187   ...
 188  },
 189  ...
 190 }
 191 </pre>
 192
 193
 194 h3. arvados_picard.py
 195
 196 Build and run the "picard":http://picard.sourceforge.net/command-line-overview.shtml program.
 197
 198
 199 The module retrieves the picard binary distribution from Keep, using the job's @picard_zip@ parameter.
 200
 201 <pre>
 202 import arvados_picard
 203 arvados_picard.run(
 204     'FixMateInformation',
 205     params={
 206         'i': input_bam_path,
 207         'o': '/dev/stdout',
 208         'quiet': 'true',
 209         'so': 'coordinate',
 210         'validation_stringency': 'LENIENT',
 211         'compression_level': 0
 212         },
 213     stdout=open('out.bam','wb'))
 214 </pre>
 215
 216 On qr1hi.arvadosapi.com, the binary distribution @picard-tools-1.82.zip@ is available in the collection @687f74675c6a0e925dec619cc2bec25f+77@.
 217
 218 <pre>
 219 {
 220  "script_parameters":{
 221   "picard_zip":"687f74675c6a0e925dec619cc2bec25f+77",
 222   ...
 223  },
 224  ...
 225 }
 226 </pre>
 227
 228