doc/user/reference/crunch-utility-libraries.textile

   1 ---
   2 layout: default
   3 navsection: userguide
   4 title: "Crunch utility libraries"
   5 navorder: 331
   6 ---
   7
   8 h1. Crunch utility libraries
   9
  10 Several utility libraries are included with Arvados. They are intended to make it quicker and easier to write your own crunch scripts.
  11
  12 h4. Python SDK extras
  13
  14 The Python SDK adds some convenience features that are particularly useful in crunch scripts, in addition to the standard set of API calls.
  15
  16 <div class="offset1">
  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 h4. 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 h4(#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 h4. 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 </div>
  72
  73 h4. arvados_ipc.py
  74
  75 Manage child processes and FIFOs (pipes).
  76
  77 <div class="offset1">
  78
  79 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.
  80
  81 <pre>
  82 from arvados_ipc import *
  83
  84 children = {}
  85 pipes = {}
  86
  87 pipe_setup(pipes, 'hellopipe')
  88 if 0 == named_fork(children, 'child_a'):
  89     pipe_closeallbut(pipes, ('hellopipe', 'w'))
  90     os.write(pipes['hellopipe', 'w'], "Hello, parent.")
  91     os._exit(0)
  92
  93 pipe_closeallbut(pipes, ('hellopipe', 'r'))
  94 with os.fdopen(pipes['hellopipe', 'r'], 'rb') as f:
  95     message = f.read()
  96     sys.stderr.write("Child says: " + message + "\n")
  97
  98 if not waitpid_and_check_children(children):
  99     raise Exception("Child process exited non-zero.")
 100 </pre>
 101
 102 The "crunch scripts" included with Arvados include some more examples of using the arvados_ipc module.
 103
 104 </div>
 105
 106 h3. 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 h4. arvados_bwa.py
 111
 112 Build and run the "bwa":http://bio-bwa.sourceforge.net/bwa.shtml program.
 113
 114 <div class="offset1">
 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 </div>
 138
 139 h4. arvados_gatk2.py
 140
 141 Extract and run the "Genome Analysis Toolkit":http://www.broadinstitute.org/gatk/ programs.
 142
 143 <div class="offset1">
 144
 145 The module retrieves the binary distribution tarball from Keep, using the job's @gatk_tbz@ parameter.
 146
 147 <pre>
 148 arvados_gatk2.run(
 149     args=[
 150         '-nct', 8,
 151         '-T', 'BaseRecalibrator',
 152         '-R', ref_fasta_files[0],
 153         '-I', input_bam_files[0],
 154         '-o', recal_file,
 155         ])
 156 </pre>
 157
 158 On qr1hi.arvadosapi.com, the binary distribution @GenomeAnalysisTK-2.6-4.tar.bz2@ is available in the collection @5790482512cf6d5d6dfd50b7fd61e1d1+86@.
 159
 160 The GATK data bundle is available in the collection @d237a90bae3870b3b033aea1e99de4a9+10820@.
 161
 162 <pre>
 163 {
 164  "script_parameters":{
 165   "gatk_tbz":"7e0a277d6d2353678a11f56bab3b13f2+87",
 166   "gatk_bundle":"d237a90bae3870b3b033aea1e99de4a9+10820",
 167   ...
 168  },
 169  ...
 170 }
 171 </pre>
 172
 173 </div>
 174
 175 h4. arvados_samtools.py
 176
 177 Build and run the "samtools":http://samtools.sourceforge.net/samtools.shtml program.
 178
 179 <div class="offset1">
 180
 181 The module retrieves the samtools source code from Keep, using the job's @samtools_tgz@ parameter.
 182
 183 <pre>
 184 import arvados_samtools
 185 arvados_samtools.run('view', ['-S', '-b', '-'],
 186                      stdin=open(sam_filename,'rb'),
 187                      stdout=open(bam_filename,'wb'))
 188 </pre>
 189
 190 On qr1hi.arvadosapi.com, the source distribution @samtools-0.1.19.tar.gz@ is available in the collection @c777e23cf13e5d5906abfdc08d84bfdb+74@.
 191
 192 <pre>
 193 {
 194  "script_parameters":{
 195   "samtools_tgz":"c777e23cf13e5d5906abfdc08d84bfdb+74",
 196   ...
 197  },
 198  ...
 199 }
 200 </pre>
 201
 202 </div>
 203
 204 h4. arvados_picard.py
 205
 206 Build and run the "picard":http://picard.sourceforge.net/command-line-overview.shtml program.
 207
 208 <div class="offset1">
 209
 210 The module retrieves the picard binary distribution from Keep, using the job's @picard_zip@ parameter.
 211
 212 <pre>
 213 import arvados_picard
 214 arvados_picard.run(
 215     'FixMateInformation',
 216     params={
 217         'i': input_bam_path,
 218         'o': '/dev/stdout',
 219         'quiet': 'true',
 220         'so': 'coordinate',
 221         'validation_stringency': 'LENIENT',
 222         'compression_level': 0
 223         },
 224     stdout=open('out.bam','wb'))
 225 </pre>
 226
 227 On qr1hi.arvadosapi.com, the binary distribution @picard-tools-1.82.zip@ is available in the collection @687f74675c6a0e925dec619cc2bec25f+77@.
 228
 229 <pre>
 230 {
 231  "script_parameters":{
 232   "picard_zip":"687f74675c6a0e925dec619cc2bec25f+77",
 233   ...
 234  },
 235  ...
 236 }
 237 </pre>
 238
 239 </div>
 240