Jalankan Praktik Terbaik GATK

Pemberitahuan: Tutorial ini menunjukkan cara menjalankan alur kerja yang telah ditetapkan dalam kasus penggunaan terbatas, tetapi tidak dimaksudkan untuk dijalankan dalam produksi. Untuk mengetahui informasi tentang cara melakukan pemrosesan data genomik di lingkungan produksi di Google Cloud, lihat Arsitektur referensi pemrosesan data genom.

Halaman ini menjelaskan cara menjalankan pipeline analisis genom sekunder di Google Cloud menggunakan Praktik Terbaik Genome Analysis Toolkit (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 keseluruhan (WGS). Alur kerja ini ditulis dalam Workflow Definition Language (WDL) Broad Institute dan dijalankan 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 mengetahui cara:

• Jalankan 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 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. Di konsol Google Cloud, pada halaman pemilih project, pilih atau buat project Google Cloud.

   Catatan: Jika tidak berencana untuk menyimpan resource yang Anda buat dalam prosedur ini, buatlah project, bukan memilih project yang ada. Setelah menyelesaikan langkah ini, Anda dapat menghapus project, yang menghapus semua resource yang terkait dengan project ini.

   Buka pemilih project

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

4. Aktifkan API Cloud Life Sciences, Compute Engine, and Cloud Storage.

   Mengaktifkan API

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. Di konsol Google Cloud, pada halaman pemilih project, pilih atau buat project Google Cloud.

   Catatan: Jika tidak berencana untuk menyimpan resource yang Anda buat dalam prosedur ini, buatlah project, bukan memilih project yang ada. Setelah menyelesaikan langkah ini, Anda dapat menghapus project, yang menghapus semua resource yang terkait dengan project ini.

   Buka pemilih project

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

10. Aktifkan API Cloud Life Sciences, Compute Engine, and Cloud Storage.

    Mengaktifkan API

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 menerapkan kuota resource untuk mencegah penggunaan yang tidak disengaja. Dengan meningkatkan kuota, Anda dapat meluncurkan lebih banyak virtual machine secara bersamaan, sehingga meningkatkan throughput dan mengurangi waktu penyelesaian.

    Untuk mendapatkan hasil terbaik dalam tutorial ini, Anda harus meminta kuota tambahan di atas kuota default project Anda. Rekomendasi untuk penambahan kuota tercantum 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 (minimum 320)
    • Alamat IP yang sedang digunakan: 51 (minimal 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 gsutil mb. Karena persyaratan dalam mesin Cromwell, jangan gunakan karakter garis bawah (_) dalam nama bucket atau Anda akan mengalami error.

gsutil mb gs://BUCKET

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

Download file contoh

Jalankan perintah berikut untuk mendownload skrip WDL dan 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 merupakan file BAM yang tidak disejajarkan.

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 menengah, 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 mendapatkan pesan error yang menyatakan "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 VPC dan subnetwork:

      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 tanda --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 mencantumkan output di bucket Cloud Storage Anda:

   gsutil ls gs://BUCKET/FOLDER/output/

Anda dapat melihat file perantara yang dibuat oleh pipeline dan memilih file 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.

Salin file input

Pipeline dapat berjalan dengan file BAM yang tidak selaras yang disimpan di Cloud Storage. Jika file menggunakan format yang berbeda, seperti align BAM atau FASTQ, 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:

gsutil -m -o 'GSUtil:parallel_composite_upload_threshold=150M' cp FILE \
    gs://BUCKET/FOLDER

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

Alat command line gsutil 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 Anda yang tidak selaras, 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 bagian Menjalankan pipeline menggunakan data sampel, menggunakan file PairedEndSingleSampleWf.hg38.inputs.json yang telah diupdate.

Jika data Anda tidak terdiri dari file BAM yang tidak selaras, dan berisi genom referensi, pengurutan exome, 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 dijalankan, gcloud CLI akan otomatis menggunakan region dan zona default berdasarkan lokasi pembuatan project Google Cloud Anda. Hal ini dapat menghasilkan 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 kembali pipeline:

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

  Guna mengetahui informasi tambahan tentang cara menetapkan region dan zona default untuk project Google Cloud, 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 terkait format file input. Untuk menghindari masalah, Anda dapat memvalidasi bahwa file lulus ValidateSamFile.

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

  gsutil 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 dalam project Google Cloud yang bukan milik Anda, Anda harus memberikan izin kepada akun layanan untuk mengakses bucket.

Pembersihan

Menghapus file perantara di bucket Cloud Storage

Saat Anda menjalankan pipeline, file perantara akan disimpan dalam 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 ini mungkin memerlukan waktu beberapa menit untuk dijalankan karena ukuran file dalam direktori.

gsutil du -sh gs://BUCKET/FOLDER/work

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

gsutil -m rm gs://BUCKET/FOLDER/work/**

Menghapus project

Cara termudah untuk menghapus 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 mempelajari beberapa tutorial dan panduan memulai, menggunakan kembali project dan bukan menghapusnya akan mencegah Anda melebihi 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 Delete project.
3. Pada dialog, ketik project ID, lalu klik Shut down untuk menghapus project.

Langkah selanjutnya

• Tutorial ini menunjukkan cara menjalankan alur kerja yang telah ditetapkan dalam kasus penggunaan terbatas, tetapi tidak dimaksudkan untuk dijalankan dalam produksi. Untuk mengetahui informasi tentang cara melakukan pemrosesan data genomik di lingkungan produksi di Google Cloud, lihat Arsitektur referensi pemrosesan data genom.
• Situs GATK dan forum Broad Institute menyediakan lebih banyak informasi latar belakang, dokumentasi, dan dukungan untuk alat GATK dan WDL.