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