doc/user/tutorial-gatk-variantfiltration.textile

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