GATK Best Practices ausführen

Auf dieser Seite wird erläutert, wie eine sekundäre Pipeline für genomische Analysen in Google Cloud mit den Best Practices für Genome Analysis Toolkit (GATK) ausgeführt wird. Die GATK Best Practices werden vom Broad Institute bereitgestellt.

Der Workflow in dieser Anleitung ist eine Implementierung der GATK Best Practices für die Variantenermittlung in WGS-Daten (Sequenzierung von Gesamtgenomen). Der Workflow ist in der Workflow Definition Language (WDL) des Broad Institute geschrieben und wird mit dem WDL-Runner Cromwell ausgeführt.

Lernziele

Nach Abschluss dieser Anleitung beherrschen Sie Folgendes:

  • Eine Pipeline gemäß den GATK Best Practices mit Daten aus Build 38 des menschlichen Referenzgenoms ausführen
  • Eine Pipeline gemäß den GATK Best Practices mit eigenen Daten ausführen

Kosten

In diesem Dokument verwenden Sie die folgenden kostenpflichtigen Komponenten von Google Cloud:

  • Compute Engine
  • Cloud Storage

Mit dem Preisrechner können Sie eine Kostenschätzung für Ihre voraussichtliche Nutzung vornehmen. Neuen Google Cloud-Nutzern steht möglicherweise eine kostenlose Testversion zur Verfügung.

Hinweise

  1. Melden Sie sich bei Ihrem Google Cloud-Konto an. Wenn Sie mit Google Cloud noch nicht vertraut sind, erstellen Sie ein Konto, um die Leistungsfähigkeit unserer Produkte in der Praxis sehen und bewerten zu können. Neukunden erhalten außerdem ein Guthaben von 300 $, um Arbeitslasten auszuführen, zu testen und bereitzustellen.
  2. Wählen Sie in der Google Cloud Console auf der Seite der Projektauswahl ein Google Cloud-Projekt aus oder erstellen Sie eines.

    Zur Projektauswahl

  3. Die Abrechnung für das Google Cloud-Projekt muss aktiviert sein.

  4. Cloud Life Sciences, Compute Engine, and Cloud Storage APIs aktivieren.

    Aktivieren Sie die APIs

  5. Installieren Sie die Google Cloud CLI.
  6. Führen Sie folgenden Befehl aus, um die gcloud CLI zu initialisieren:

    gcloud init
  7. Aktualisieren und installieren Sie gcloud-Komponenten:
    gcloud components update
    gcloud components install beta
  8. Wählen Sie in der Google Cloud Console auf der Seite der Projektauswahl ein Google Cloud-Projekt aus oder erstellen Sie eines.

    Zur Projektauswahl

  9. Die Abrechnung für das Google Cloud-Projekt muss aktiviert sein.

  10. Cloud Life Sciences, Compute Engine, and Cloud Storage APIs aktivieren.

    Aktivieren Sie die APIs

  11. Installieren Sie die Google Cloud CLI.
  12. Führen Sie folgenden Befehl aus, um die gcloud CLI zu initialisieren:

    gcloud init
  13. Aktualisieren und installieren Sie gcloud-Komponenten:
    gcloud components update
    gcloud components install beta
  14. Installieren Sie Git, um die erforderlichen Dateien herunterzuladen.

    Git herunterladen

  15. In Compute Engine sind standardmäßig Ressourcenkontingente festgelegt, um eine versehentliche Nutzung zu verhindern. Wenn Sie die Kontingente erhöhen, können Sie mehr virtuelle Maschinen gleichzeitig starten, was den Durchsatz erhöht und die Bearbeitungszeit verkürzt.

    Damit in dieser Anleitung die besten Ergebnisse erzielt werden, sollten Sie zusätzliche Kontingente anfordern, die über die Standardwerte Ihres Projekts hinausgehen. Empfehlungen für Kontingenterhöhungen können Sie der folgenden Liste entnehmen. Dort werden auch die zum Ausführen dieser Anleitung minimal erforderlichen Kontingente angegeben. Fordern Sie Ihre Kontingente in der Region us-central1 an:

    • CPUs: 101 (mindestens 17)
    • Standardwert für nichtflüchtigen Speicher (GB): 10.500 (mindestens 320)
    • IP-Adressen in Verwendung: 51 (mindestens 2)

    Sie können die anderen Felder für die Kontingentanforderung leer lassen, um die jeweiligen Kontingentwerte beizubehalten.

Cloud Storage-Bucket erstellen

Erstellen Sie mit dem Befehl gsutil mb einen Cloud Storage-Bucket. Aufgrund einer Anforderung in der Cromwell-Engine dürfen Sie im Bucket-Namen keinen Unterstrich (_) verwenden, da sonst ein Fehler auftritt.

gsutil mb gs://BUCKET

Die Pipeline gibt Ergebnisse, Logs und Zwischendateien in diesem Bucket aus.

Beispieldateien herunterladen

Führen Sie die folgenden Befehle aus, um das WDL- und das Hilfsskript herunterzuladen:

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

Das Repository gatk-workflows/broad-prod-wgs-germline-snps-indels enthält die folgenden Dateien, die zum Ausführen der Pipeline benötigt werden:

  • *.wdl: Workflow-Definition
  • *.inputs.json: Eingabeparameter, einschließlich der Pfade zu den BAM-Dateien und dem Referenzgenom
  • *.options.json: Workflow-Laufzeitoptionen

Die Pipelinedefinitionsdatei für Cromwell zum Ausführen von WDL-Pipelines befindet sich im Repository broadinstitute/wdl-runner/wdl_runner/.

Pipeline mit Probendaten ausführen

Dieser Abschnitt zeigt, wie die Pipeline mit WGS-Daten unter Verwendung von Build 38 des menschlichen Referenzgenoms ausgeführt wird. Die Eingabedateien sind nicht ausgerichtete BAM-Dateien.

Führen Sie die folgenden Schritte aus, um die Pipeline auszuführen:

  1. Erstellen Sie die Umgebungsvariable GATK_GOOGLE_DIR, die auf den Ordner verweist, der die Broad-Pipelinedateien enthält:

    export GATK_GOOGLE_DIR="${PWD}"/broad-prod-wgs-germline-snps-indels
    
  2. Erstellen Sie die Umgebungsvariable GATK_OUTPUT_DIR, die auf den Cloud Storage-Bucket samt Pfad verweist, in dem die Ausgabe des Workflows (output), die work-Zwischendateien und logging gespeichert werden:

    export GATK_OUTPUT_DIR=gs://BUCKET/FOLDER
    
  3. Wechseln Sie im heruntergeladenen Repository zum Ordner /wdl_runner. Dieser Ordner enthält die Pipelinedefinitionsdatei zum Ausführen von WDL-basierten Pipelines in Google Cloud:

    cd wdl-runner/wdl_runner/
    
  4. Führen Sie die Pipeline aus:

    Wählen Sie je nachdem, ob Sie eine Standard-VPC oder eine benutzerdefinierte VPC verwenden, eine der folgenden Optionen aus:

    Standard-VPC

    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/
    

    Benutzerdefinierte VPC

    1. Erstellen Sie die Umgebungsvariablen NETWORK und SUBNETWORK, um den Namen Ihres VPC-Netzwerks und Subnetzwerks anzugeben:

      export NETWORK=VPC_NETWORK
      export SUBNETWORK=VPC_SUBNET
      
    2. Bearbeiten Sie die Datei PairedEndSingleSampleWf.options.json im Verzeichnis broad-prod-wgs-germline-snps-indels und ändern Sie die Zonen so, dass nur Zonen innerhalb der Region Ihres Subnetzes enthalten sind. Wenn Sie beispielsweise das Subnetz us-central1 verwenden, sieht das Feld zones so aus: "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. Der Befehl gibt eine Vorgangs-ID im folgenden Format zurück: Running [operations/OPERATION_ID]. Mit dem Befehl gcloud beta lifesciences describe können Sie den Status der Pipeline verfolgen. Führen Sie dazu folgenden Befehl aus (der Wert des Flags --location muss mit dem im vorherigen Schritt angegebenen Ort übereinstimmen):

    gcloud beta lifesciences operations describe OPERATION_ID \
        --location=us-central1 \
        --format='yaml(done, error, metadata.events)'
    
  6. Der Befehl operations describe gibt done: true zurück, wenn die Ausführung der Pipeline abgeschlossen ist.

    Sie können ein in wdl_runner enthaltenes Skript ausführen, um alle 300 Sekunden zu prüfen, ob der Job noch ausgeführt wird, abgeschlossen wurde oder ob ein Fehler aufgetreten ist:

    ../monitoring_tools/monitor_wdl_pipeline.sh OPERATION_ID us-central1 300
    
  7. Wenn die Ausführung der Pipeline abgeschlossen ist, können Sie den folgenden Befehl ausführen, um eine Liste der Ausgaben in Ihrem Cloud Storage-Bucket aufzurufen:

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

Sie können sich die Zwischendateien ansehen, die von der Pipeline erstellt wurden, und entscheiden, welche Sie behalten möchten. Alternativ können Sie die Dateien entfernen, um die mit Cloud Storage verbundenen Kosten zu reduzieren. Informationen zum Entfernen der Dateien finden Sie unter Zwischendateien in einem Cloud Storage-Bucket entfernen.

GATK Best Practices-Pipeline auf Daten anwenden

Bevor Sie die Pipeline auf Ihre lokalen Daten anwenden, müssen die Daten in einen Cloud Storage-Bucket kopiert werden.

Eingabedateien kopieren

Die Pipeline kann mit nicht ausgerichteten BAM-Dateien ausgeführt werden, die in Cloud Storage gespeichert sind. In einem anderen Format vorliegende Dateien, z. B. ausgerichtete BAM- oder FASTQ-Dateien, müssen konvertiert werden, bevor sie in Cloud Storage geladen werden können. Sie können sie lokal konvertieren oder die Pipelines API zur Konvertierung in der Cloud verwenden.

Im folgenden Beispiel erfahren Sie, wie Sie eine einzelne Datei aus einem lokalen Dateisystem in einen Cloud Storage-Bucket kopieren:

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

Weitere Beispiele zum Kopieren von Dateien in einen Cloud Storage-Bucket finden Sie im Abschnitt zum Kopieren von Daten in Cloud Storage.

Das Befehlszeilentool gsutil kontrolliert die Prüfsummen automatisch. Wenn die Übertragung erfolgreich war, sind Ihre Daten also mit den GATK Best Practices kompatibel.

Pipeline auf Daten anwenden

Wenn Sie die GATK Best Practices für eigene nicht ausgerichtete BAM-Dateien ausführen möchten, müssen Sie eine Kopie der Datei PairedEndSingleSampleWf.hg38.inputs.json erstellen und die Pfade so anpassen, dass sie auf Ihre Dateien in einem Cloud Storage-Bucket verweisen. Anschließend können Sie mit der aktualisierten Datei PairedEndSingleSampleWf.hg38.inputs.json den Schritten unter Pipeline mit Stichprobendaten ausführen folgen.

Falls Ihre Daten nicht aus nicht ausgerichteten BAM-Dateien bestehen und Referenzgenome, Exom-Sequenzierung, gezielte Panels und somatische Daten enthalten, müssen Sie andere Workflows verwenden. Weitere Informationen finden Sie im GATK-Supportforum und im GitHub-Repository des Broad Institute.

Fehlerbehebung

  • Die Konfiguration der Pipeline sieht die Verwendung von Compute Engine-Instanzen in bestimmten Regionen und Zonen vor. Wenn Sie die gcloud CLI ausführen, werden automatisch die Standardregion und -zone auf der Grundlage des Standorts verwendet, an dem Ihr Google Cloud-Projekt erstellt wurde. Bei der Ausführung der Pipeline kann dies zu folgender Fehlermeldung führen:

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

    Sie können dieses Problem beheben. Entfernen Sie dafür die Standardregion und die Standardzone mit den folgenden Befehlen und führen Sie dann die Pipeline noch einmal aus:

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

    Weitere Informationen zum Festlegen der Standardregion und -zone für Ihr Google Cloud-Projekt finden Sie unter Standardregion oder -zone ändern.

  • Informationen zu Problemen beim Ausführen der Pipeline finden Sie unter Cloud Life Sciences API – Fehlerbehebung.

  • GATK akzeptiert nur bestimmte Eingabedateiformate. Sie können Probleme vermeiden, wenn Sie Ihre Dateien vorab mithilfe des Tools ValidateSamFile auf Eignung prüfen.

  • Wenn Ihre GATK-Ausführung fehlschlägt, können Sie die Logs mit dem folgenden Befehl prüfen:

    gsutil ls gs://BUCKET/FOLDER/logging
    
  • Falls Berechtigungsfehler auftreten, sollten Sie prüfen, ob Ihr Dienstkonto Lesezugriff auf die Eingabedateien und Schreibzugriff auf den Pfad des Ausgabe-Buckets hat. Wenn Sie Ausgabedateien in einen Bucket außerhalb Ihres Google Cloud-Projekts schreiben, müssen Sie dem Dienstkonto Zugriff auf den Bucket gewähren.

Bereinigen

Zwischendateien im Cloud Storage-Bucket löschen

Wenn Sie die Pipeline ausführen, werden Zwischendateien in gs://BUCKET/FOLDER/work gespeichert. Sie können diese Dateien nach Abschluss des Workflows entfernen, um die Kosten für Cloud Storage zu verringern.

Führen Sie folgenden Befehl aus, um den im Verzeichnis work verwendeten Speicherplatz anzuzeigen. Die Ausführung des Befehls kann je nach Größe der Dateien im Verzeichnis einige Minuten dauern.

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

Führen Sie folgenden Befehl aus, um die Zwischendateien im Verzeichnis work zu entfernen:

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

Projekt löschen

Am einfachsten vermeiden Sie weitere Kosten durch Löschen des für die Anleitung erstellten Projekts.

So löschen Sie das Projekt:

  1. Rufen Sie in der Google Cloud Console die Seite „Projekte“ auf.

    Zur Seite "Projekte"

  2. Wählen Sie in der Projektliste das Projekt aus, das Sie löschen möchten, und klicken Sie auf Delete project (Projekt löschen). Klicken Sie auf das Kästchen neben dem Projektnamen und dann auf "Delete project" (Projekt löschen).
  3. Geben Sie im Dialogfeld die Projekt-ID ein und klicken Sie auf Shut down (Beenden), um das Projekt zu löschen.

Nächste Schritte

  • In dieser Anleitung wird beschrieben, wie Sie einen vordefinierten, nicht für die Produktion vorgesehenen Workflow in einem begrenzten Anwendungsfall ausführen. Informationen zum Ausführen der genomischen Datenverarbeitung in einer Produktionsumgebung in Google Cloud finden Sie unter Referenz-Architektur der genomischen Datenverarbeitung.
  • Auf der GATK-Website und in den Foren des Broad Institute erhalten Sie weitere Hintergrundinformationen, Dokumentationen und Support bezüglich der GATK-Tools und WDL.