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