Menjalankan Praktik Terbaik GATK

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 penerapan Praktik Terbaik GATK untuk penemuan varian dalam data pengurutan seluruh genom (WGS). Alur kerja ditulis dalam Workflow Definition Language (WDL) Broad Institute dan berjalan di runner WDL Cromwell.

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 akan menggunakan komponen Google Cloudyang dapat ditagih berikut:

  • Compute Engine
  • Cloud Storage

Untuk membuat perkiraan biaya berdasarkan proyeksi penggunaan Anda, gunakan kalkulator harga.

Pengguna Google Cloud baru 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.

    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. If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

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

    gcloud init

  8. After initializing the gcloud CLI, update it and install the required components: 

    gcloud components update
gcloud components install beta

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

    Go to project selector

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

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

    Enable the APIs

  12. Install the Google Cloud CLI.

  13. If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

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

    gcloud init

  15. After initializing the gcloud CLI, update it and install the required components: 

    gcloud components update
gcloud components install beta
  16. Instal git untuk mendownload file yang diperlukan.

    Download git

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

    Untuk mendapatkan hasil terbaik dalam tutorial ini, Anda harus meminta kuota tambahan di atas default project Anda. 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 Standard (GB): 10.500 (minimum 320)
    • Alamat IP yang Digunakan: 51 (minimal 2)

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

    18. 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 output 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 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:

      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 ada 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 akan 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:

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

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

    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 diselaraskan, 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 lainnya tentang cara menyalin file ke bucket Cloud Storage, lihat bagian tentang Menyalin data ke Cloud Storage.

    gcloud CLI memverifikasi checksum secara otomatis, jadi 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 disejajarkan, buat salinan PairedEndSingleSampleWf.hg38.inputs.json, lalu perbarui jalur untuk mengarah ke file Anda di bucket Cloud Storage. Kemudian, Anda dapat mengikuti langkah-langkah dalam Menjalankan pipeline menggunakan data contoh, menggunakan file PairedEndSingleSampleWf.hg38.inputs.json yang telah diperbarui.

    Jika data Anda tidak terdiri dari file BAM yang tidak selaras, dan berisi genom referensi, pengurutan eksom, panel bertarget, 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, gcloud 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 kembali pipeline:

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

      Untuk mengetahui informasi tambahan tentang cara menetapkan region dan zona default untuk Google Cloud project, 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 proses GATK Anda gagal, Anda dapat memeriksa log dengan menjalankan perintah berikut:

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

    • Jika Anda mengalami error izin, periksa apakah akun layanan Anda memiliki akses baca ke file input dan akses tulis ke jalur bucket output. Jika Anda menulis file output ke bucket di projectGoogle 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:

    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. Setelah memilih kotak centang di samping nama project, klik Hapus project
    3. Pada dialog, ketik project ID, lalu klik Shut down untuk menghapus project.

    Langkah berikutnya

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