doc/user/tutorial-gatk-variantfiltration.textile

   1 ---
   2 layout: default
   3 navsection: userguide
   4 title: "Tutorial: GATK VariantFiltration"
   5 navorder: 22
   6 ---
   7
   8 h1. Tutorial: GATK VariantFiltration
   9
  10 Here you will use the GATK VariantFiltration program to assign pass/fail scores to variants in a VCF file.
  11
  12 _This should be motivated better using a specific biomedical research
  13 or diagnostic question that involves this analysis_
  14
  15 _From conversation with Ward:  We should link to a discussion of the
  16 personal genome project and explain that it a freely available dataset
  17 that any researcher can use, which makes it appropriate to be used in these examples._
  18
  19 h3. Prerequisites
  20
  21 * Log in to a VM "using SSH":ssh-access.html
  22 * Put an "API token":api-tokens.html in your @ARVADOS_API_TOKEN@ environment variable
  23 * Put the API host name in your @ARVADOS_API_HOST@ environment variable
  24
  25 If everything is set up correctly, the command @arv -h user current@ will display your account information.
  26
  27 h3. Get the GATK binary distribution.
  28
  29 _Perhaps separate out this and the next sections and link to it so the user only
  30 has to do this if they really don't have GATK installed.  Also provide
  31 a way to determine if they do have it._
  32
  33 Download the GATK binary tarball[1] -- e.g., @GenomeAnalysisTK-2.6-4.tar.bz2@ -- and copy it to your Arvados VM.
  34
  35 _Is it necessary to copy it to the Arvados VM first, you could put it into
  36 keep from your desktop and/or use the workbench?  Also if we are
  37 telling them to copy it to the VM, maybe we should mention scp?_
  38
  39 Store it in Keep.
  40
  41 <pre>
  42 arv keep put --in-manifest GenomeAnalysisTK-2.6-4.tar.bz2
  43 </pre>
  44
  45 &darr;
  46
  47 _Make the itty bitty down arrows bigger, and maybe center them_
  48
  49 <pre>
  50 c905c8d8443a9c44274d98b7c6cfaa32+94+K@qr1hi
  51 </pre>
  52
  53 h3. Get the GATK resource bundle.
  54
  55 This can take a while to download, and should already be available in Arvados. For now let's just list the files and sizes, to make sure we have the correct collection ID.
  56
  57 <pre>
  58 arv keep ls -s d237a90bae3870b3b033aea1e99de4a9+10820+K@qr1hi
  59 </pre>
  60
  61 &darr;
  62
  63 <pre>
  64   50342 1000G_omni2.5.b37.vcf.gz
  65       1 1000G_omni2.5.b37.vcf.gz.md5
  66     464 1000G_omni2.5.b37.vcf.idx.gz
  67       1 1000G_omni2.5.b37.vcf.idx.gz.md5
  68   43981 1000G_phase1.indels.b37.vcf.gz
  69 ...
  70 </pre>
  71
  72 h3. Submit a job.
  73
  74 The Arvados distribution includes an example crunch script ("crunch_scripts/GATK2-VariantFiltration":https://arvados.org/projects/arvados/repository/revisions/master/entry/crunch_scripts/GATK2-VariantFiltration) that runs the GATK VariantFiltration tool with some default settings.
  75
  76 We will pass it the following parameters:
  77
  78 * input -- a collection containing the source VCF data. Here we will use an exome report from PGP participant hu34D5B9.
  79 * gatk_binary_tarball -- a collection containing the GATK 2 tarball.
  80 * gatk_bundle -- a collection containing the GATK resource bundle[2].
  81
  82 <pre>
  83 src_version=76588bfc57f33ea1b36b82ca7187f465b73b4ca4
  84 vcf_input=5ee633fe2569d2a42dd81b07490d5d13+82+K@qr1hi
  85 gatk_binary=c905c8d8443a9c44274d98b7c6cfaa32+94+K@qr1hi
  86 gatk_bundle=d237a90bae3870b3b033aea1e99de4a9+10820+K@qr1hi
  87
  88 read -rd $'\000' the_job <<EOF
  89 {
  90  "script":"GATK2-VariantFiltration",
  91  "script_version":"$src_version",
  92  "script_parameters":
  93  {
  94   "input":"$vcf_input",
  95   "gatk_binary_tarball":"$gatk_binary",
  96   "gatk_bundle":"$gatk_bundle"
  97  }
  98 }
  99 EOF
 100
 101 arv -h job create --job "$the_job"
 102 </pre>
 103
 104 Note the job UUID in the API response.
 105
 106 h3. Monitor job progress
 107
 108 _This was already covered in tutorial1_
 109
 110 There are three ways to monitor job progress:
 111
 112 # Go to Workbench, drop down the Compute menu, and click Jobs. The job you submitted should appear at the top of the list. Hit "Refresh" until it finishes.
 113 # Run @arv -h job get --uuid JOB_UUID_HERE@ to see the job particulars, notably the "tasks_summary" attribute which indicates how many tasks are done/running/todo.
 114 # Watch the crunch log messages and stderr from the job tasks:
 115
 116 <pre>
 117 curl -s -H "Authorization: OAuth2 $ARVADOS_API_TOKEN" \
 118   https://{{ site.arvados_api_host }}/arvados/v1/jobs/JOB_UUID_HERE/log_tail_follow
 119 </pre>
 120
 121
 122 _That's it?  Say something about the output we're going to get_
 123
 124 h3. Notes
 125
 126 fn1. Download the GATK tools &rarr; http://www.broadinstitute.org/gatk/download
 127
 128 fn2. Information about the GATK resource bundle &rarr; http://gatkforums.broadinstitute.org/discussion/1213/whats-in-the-resource-bundle-and-how-can-i-get-it