Menjalankan Praktik Terbaik GATK

Pemberitahuan: Tutorial ini menunjukkan cara menjalankan alur kerja standar dalam kasus penggunaan terbatas, tetapi tidak dimaksudkan untuk dijalankan dalam produksi.

Halaman ini menjelaskan cara menjalankan pipeline analisis genomik sekunder di Google Cloud menggunakan Praktik Terbaik Toolkit Analisis Genomik (GATK). Praktik Terbaik GATK disediakan oleh Broad Institute.

Alur kerja yang digunakan dalam tutorial ini adalah implementasi Praktik Terbaik GATK untuk penemuan varian dalam data pengurutan genom secara keseluruhan (WGS). Alur kerja ditulis dalam Workflow Definition Language (WDL) Broad Institute dan berjalan di runner WDL Cromwell.

Catatan: Anda bertanggung jawab untuk mematuhi persyaratan Perjanjian Lisensi Pengguna Akhir GATK, termasuk persyaratan atribusi.

Tujuan

Setelah menyelesaikan tutorial ini, Anda akan tahu cara:

• Menjalankan pipeline menggunakan Praktik Terbaik GATK dengan data dari build 38 genom referensi manusia
• Menjalankan pipeline menggunakan Praktik Terbaik GATK menggunakan data Anda sendiri

Biaya

Dalam dokumen ini, Anda akan menggunakan komponen Google Cloud yang dapat ditagih berikut:

• Compute Engine
• Cloud Storage

Untuk membuat perkiraan biaya berdasarkan proyeksi penggunaan Anda, gunakan kalkulator harga. Pengguna baru Google Cloud mungkin memenuhi syarat untuk mendapatkan uji coba gratis.

Sebelum memulai

1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

3. Make sure that billing is enabled for your Google Cloud project.

4. Enable the Cloud Life Sciences, Compute Engine, and Cloud Storage APIs.

   Enable the APIs

5. Install the Google Cloud CLI.

6. To initialize the gcloud CLI, run the following command:

   gcloud init

7. Update and install gcloud components:

   gcloud components update
   gcloud components install beta

8. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

9. Make sure that billing is enabled for your Google Cloud project.

10. Enable the Cloud Life Sciences, Compute Engine, and Cloud Storage APIs.

    Enable the APIs

11. Install the Google Cloud CLI.

12. To initialize the gcloud CLI, run the following command:

    gcloud init

13. Update and install gcloud components:

    gcloud components update
    gcloud components install beta

14. Instal git untuk mendownload file yang diperlukan.

    Download git

15. Secara default, Compute Engine memiliki kuota resource untuk mencegah penggunaan yang tidak disengaja. Dengan meningkatkan kuota, Anda dapat meluncurkan lebih banyak virtual machine secara serentak, yang akan meningkatkan throughput dan mengurangi waktu penyelesaian.

    Untuk mendapatkan hasil terbaik dalam tutorial ini, Anda harus meminta kuota tambahan di atas kuota default project. Rekomendasi untuk penambahan kuota diberikan dalam daftar berikut, dan kuota minimum yang diperlukan untuk menjalankan tutorial. Buat permintaan kuota Anda di region us-central1:

    • CPU: 101 (minimum 17)
    • Persistent Disk Standar (GB): 10.500 (minimal 320)
    • Alamat IP yang digunakan: 51 (minimum 2)

    Anda dapat mengosongkan kolom permintaan kuota lainnya untuk mempertahankan kuota saat ini.

    Catatan: Jika project Anda dibuat menggunakan uji coba gratis, Anda harus meminta kuota yang lebih tinggi untuk menjalankan Praktik Terbaik GATK di Google Cloud.

Membuat bucket Cloud Storage

Buat bucket Cloud Storage menggunakan perintah gcloud storage buckets create. Karena persyaratan di mesin Cromwell, jangan gunakan karakter garis bawah (_) dalam nama bucket atau Anda akan mengalami error.

gcloud storage buckets create gs://BUCKET

Pipeline menghasilkan hasil, log, dan file perantara ke bucket ini.

Mendownload file contoh

Jalankan perintah berikut untuk mendownload WDL dan skrip helper:

git clone https://github.com/broadinstitute/wdl-runner.git
git clone https://github.com/gatk-workflows/broad-prod-wgs-germline-snps-indels.git

Repositori gatk-workflows/broad-prod-wgs-germline-snps-indels berisi file berikut yang diperlukan untuk menjalankan pipeline:

• *.wdl: Definisi alur kerja
• *.inputs.json: Parameter input, termasuk jalur ke file BAM dan genom referensi
• *.options.json: Opsi runtime alur kerja

Anda dapat menemukan file definisi pipeline Cromwell yang digunakan untuk menjalankan pipeline WDL di repositori broadinstitute/wdl-runner/wdl_runner/.

Menjalankan pipeline menggunakan data sampel

Bagian ini menunjukkan cara menjalankan pipeline dengan data WGS menggunakan build 38 dari genom referensi manusia. File input adalah file BAM yang tidak selaras.

Untuk menjalankan pipeline, selesaikan langkah-langkah berikut:

1. Buat variabel lingkungan GATK_GOOGLE_DIR yang mengarah ke folder yang berisi file pipeline Broad:

   export GATK_GOOGLE_DIR="${PWD}"/broad-prod-wgs-germline-snps-indels

2. Buat variabel lingkungan GATK_OUTPUT_DIR yang mengarah ke bucket Cloud Storage dan folder untuk output alur kerja, file work perantara, dan logging:

   export GATK_OUTPUT_DIR=gs://BUCKET/FOLDER

3. Ubah direktori ke folder /wdl_runner di repositori yang Anda download. Direktori ini berisi file definisi pipeline untuk menjalankan pipeline berbasis WDL di Google Cloud:

   cd wdl-runner/wdl_runner/

4. Menjalankan pipeline:

   Penting: Jika Anda melihat pesan error yang bertuliskan "ERROR: (gcloud.beta.lifesciences.pipelines.run) INVALID_ARGUMENT: Error: validating pipeline: zones and regions cannot be specified together", lihat Pemecahan masalah.

   Pilih salah satu opsi berikut, bergantung pada apakah Anda menggunakan VPC default atau VPC kustom:

   VPC Default

   gcloud beta lifesciences pipelines run \
   --pipeline-file wdl_pipeline.yaml \
   --location us-central1 \
   --regions us-central1 \
   --inputs-from-file WDL=${GATK_GOOGLE_DIR}/PairedEndSingleSampleWf.wdl,\
   WORKFLOW_INPUTS=${GATK_GOOGLE_DIR}/PairedEndSingleSampleWf.hg38.inputs.json,\
   WORKFLOW_OPTIONS=${GATK_GOOGLE_DIR}/PairedEndSingleSampleWf.options.json \
   --env-vars WORKSPACE=${GATK_OUTPUT_DIR}/work,\
   OUTPUTS=${GATK_OUTPUT_DIR}/output \
   --logging ${GATK_OUTPUT_DIR}/logging/

   VPC Kustom

   1. Buat variabel lingkungan NETWORK dan SUBNETWORK untuk menentukan nama jaringan dan subnetwork VPC Anda:

      export NETWORK=VPC_NETWORK
      export SUBNETWORK=VPC_SUBNET

   2. Edit file PairedEndSingleSampleWf.options.json yang berada di direktori broad-prod-wgs-germline-snps-indels dan ubah zona agar hanya menyertakan zona dalam region subnet Anda. Misalnya, jika Anda menggunakan subnet us-central1, kolom zones akan terlihat seperti ini: "zones": "us-central1-a us-central1-b us-central1-c us-central1-f".

   3. gcloud beta lifesciences pipelines run \
      --pipeline-file wdl_pipeline.yaml \
      --location us-central1 \
      --regions us-central1 \
      --network ${NETWORK} \
      --subnetwork ${SUBNETWORK} \
      --inputs-from-file WDL=${GATK_GOOGLE_DIR}/PairedEndSingleSampleWf.wdl,\
      WORKFLOW_INPUTS=${GATK_GOOGLE_DIR}/PairedEndSingleSampleWf.hg38.inputs.json,\
      WORKFLOW_OPTIONS=${GATK_GOOGLE_DIR}/PairedEndSingleSampleWf.options.json \
      --env-vars WORKSPACE=${GATK_OUTPUT_DIR}/work,\
      OUTPUTS=${GATK_OUTPUT_DIR}/output,\
      NETWORK=${NETWORK},\
      SUBNETWORK=${SUBNETWORK} \
      --logging ${GATK_OUTPUT_DIR}/logging/

5. Perintah ini menampilkan ID operasi dalam format Running [operations/OPERATION_ID]. Anda dapat menggunakan perintah gcloud beta lifesciences describe untuk melacak status pipeline dengan menjalankan perintah berikut (pastikan nilai flag --location cocok dengan lokasi yang ditentukan pada langkah sebelumnya):

   gcloud beta lifesciences operations describe OPERATION_ID \
       --location=us-central1 \
       --format='yaml(done, error, metadata.events)'

6. Perintah operations describe menampilkan done: true saat pipeline selesai.

   Anda dapat menjalankan skrip yang disertakan dengan wdl_runner untuk memeriksa setiap 300 detik apakah tugas sedang berjalan, telah selesai, atau menampilkan error:

   ../monitoring_tools/monitor_wdl_pipeline.sh OPERATION_ID us-central1 300

7. Setelah pipeline selesai, jalankan perintah berikut untuk membuat daftar output di bucket Cloud Storage Anda:

   gcloud storage ls gs://BUCKET/FOLDER/output/

Anda dapat melihat file perantara yang dibuat oleh pipeline dan memilih file mana yang ingin disimpan, atau menghapusnya untuk mengurangi biaya yang terkait dengan Cloud Storage. Untuk menghapus file, lihat Menghapus file perantara di bucket Cloud Storage.

Menjalankan pipeline Praktik Terbaik GATK pada data Anda

Sebelum menjalankan pipeline pada data lokal, Anda perlu menyalin data ke bucket Cloud Storage.

Menyalin file input

Pipeline dapat berjalan dengan file BAM yang tidak selaras yang disimpan di Cloud Storage. Jika file Anda dalam format yang berbeda, seperti BAM atau FASTQ yang sejajar, Anda harus mengonversinya sebelum dapat diupload ke Cloud Storage. Anda dapat mengonversinya secara lokal, atau menggunakan Pipelines API untuk mengonversinya di cloud.

Contoh berikut menunjukkan cara menyalin satu file dari sistem file lokal ke bucket Cloud Storage:

gcloud storage cp FILE gs://BUCKET/FOLDER

Untuk contoh selengkapnya tentang cara menyalin file ke bucket Cloud Storage, lihat bagian Menyalin data ke Cloud Storage.

gcloud CLI memverifikasi checksum secara otomatis, sehingga saat transfer berhasil, data Anda kompatibel untuk digunakan dengan Praktik Terbaik GATK.

Menjalankan pipeline pada data Anda

Untuk menjalankan Praktik Terbaik GATK pada file BAM yang tidak diselaraskan, buat salinan PairedEndSingleSampleWf.hg38.inputs.json, lalu perbarui jalur agar mengarah ke file Anda di bucket Cloud Storage. Kemudian, Anda dapat mengikuti langkah-langkah di Menjalankan pipeline menggunakan data contoh, menggunakan file PairedEndSingleSampleWf.hg38.inputs.json yang telah diperbarui.

Jika data Anda tidak terdiri dari file BAM yang tidak diselaraskan, dan berisi genom referensi, pengurutan eksom, panel yang ditargetkan, dan data somatik, Anda harus menggunakan alur kerja yang berbeda. Lihat Forum Dukungan GATK dan repositori GitHub Broad Institute untuk mengetahui informasi selengkapnya.

Pemecahan masalah

• Pipeline dikonfigurasi untuk menggunakan instance Compute Engine di region dan zona tertentu. Saat Anda menjalankan gcloud CLI, CLI akan otomatis menggunakan region dan zona default berdasarkan lokasi tempat project Google Cloud Anda dibuat. Hal ini dapat menyebabkan pesan error berikut saat menjalankan pipeline:

  "ERROR: (gcloud.beta.lifesciences.pipelines.run) INVALID_ARGUMENT: Error: validating pipeline: zones and regions cannot be specified together"

  Untuk mengatasi masalah ini, hapus region dan zona default dengan menjalankan perintah berikut, lalu jalankan pipeline lagi:

  gcloud config unset compute/zone
  gcloud config unset compute/region
  

  Untuk informasi tambahan tentang cara menetapkan region dan zona default untuk project Google Cloud Anda, lihat Mengubah zona atau region default.

• Jika Anda mengalami masalah saat menjalankan pipeline, lihat pemecahan masalah Cloud Life Sciences API.

• GATK memiliki ekspektasi yang ketat tentang format file input. Untuk menghindari masalah, Anda dapat memvalidasi bahwa file Anda lulus ValidateSamFile.

• Jika GATK gagal dijalankan, Anda dapat memeriksa log dengan menjalankan perintah berikut:

  gcloud storage ls gs://BUCKET/FOLDER/logging

• Jika Anda mengalami error izin, pastikan akun layanan Anda memiliki akses baca ke file input dan akses tulis ke jalur bucket output. Jika Anda menulis file output ke bucket di project Google Cloud yang bukan milik Anda, Anda harus memberikan izin akun layanan untuk mengakses bucket tersebut.

Pembersihan

Menghapus file perantara di bucket Cloud Storage

Saat Anda menjalankan pipeline, pipeline akan menyimpan file perantara di gs://BUCKET/FOLDER/work. Anda dapat menghapus file setelah alur kerja selesai untuk mengurangi biaya Cloud Storage.

Untuk melihat jumlah ruang yang digunakan di direktori work, jalankan perintah berikut. Perintah mungkin memerlukan waktu beberapa menit untuk dijalankan karena ukuran file dalam direktori.

gcloud storage du gs://BUCKET/FOLDER/work --readable-sizes --summarize

Untuk menghapus file perantara di direktori work, jalankan perintah berikut:

gcloud storage rm gs://BUCKET/FOLDER/work/**

Menghapus project

Cara termudah untuk menghilangkan penagihan adalah dengan menghapus project yang Anda gunakan untuk tutorial.

Untuk menghapus project:

Peringatan: Menghapus project memiliki konsekuensi berikut:

• Jika menggunakan project yang sudah ada, Anda juga akan menghapus pekerjaan lain yang telah dilakukan dalam project tersebut.
• Anda tidak dapat menggunakan kembali ID project untuk project yang telah dihapus. Jika Anda membuat project ID kustom yang akan digunakan di masa mendatang, hapus resource di dalam project tersebut. Langkah ini memastikan bahwa URL yang menggunakan project ID, seperti URL appspot.com, tetap tersedia.

Jika Anda menjelajahi beberapa tutorial dan panduan memulai, menggunakan kembali project, bukan menghapusnya, akan mencegah Anda melampaui batas kuota project.

1. Di konsol Google Cloud, buka halaman Project.

   Buka halaman Projects

2. Dalam daftar project, pilih project yang ingin Anda hapus, lalu klik Hapus project.
3. Pada dialog, ketik project ID, lalu klik Shut down untuk menghapus project.

Langkah selanjutnya

• Situs dan forum Broad Institute GATK memberikan informasi latar belakang, dokumentasi, dan dukungan lainnya untuk alat GATK dan WDL.