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