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

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