GATK Best Practices ausführen

Auf dieser Seite wird erläutert, wie eine Pipeline in Google Cloud mit GATK Best Practices des Broad Institute ausgeführt wird.

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.

Ziele

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 dieser Anleitung werden kostenpflichtige Komponenten von Google Cloud verwendet, darunter:

  • Compute Engine
  • Cloud Storage

Der Preisrechner kann eine Kostenschätzung anhand Ihrer voraussichtlichen Nutzung generieren. Neuen Cloud Platform-Nutzern steht möglicherweise eine kostenlose Testversion zur Verfügung.

Hinweis

  1. Melden Sie sich bei Ihrem Google-Konto an.

    Wenn Sie noch kein Konto haben, melden Sie sich hier für ein neues Konto an.

  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 Cloud-Projekt muss aktiviert sein. So prüfen Sie, ob die Abrechnung für Ihr Projekt aktiviert ist.

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

    Aktivieren Sie die APIs

  5. Installieren und initialisieren Sie das Cloud SDK.
  6. Aktualisieren und installieren Sie gcloud-Komponenten:
    gcloud components update &&
    gcloud components install beta
  7. Installieren Sie Git, um die erforderlichen Dateien herunterzuladen.

    Git herunterladen

  8. 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, sodass Ihnen ein höherer Durchsatz und eine kürzere Bearbeitungszeit zugutekommen.

    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

Laden Sie das WDL- und das Hilfsskript herunter:

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

Die Pipeline wird mit WGS-Daten aus Build 38 des menschlichen Referenzgenoms ausgeführt. Die Eingabedateien sind nicht ausgerichtete BAM-Dateien.

So führen Sie die Pipeline aus:

  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:

    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/
    
  5. Der Befehl gibt eine Vorgangs-ID im folgenden Format zurück: Running [operations/OPERATION_ID]. Anhand der Vorgangs-ID 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, sollten Ihre Daten also mit den GATK Best Practices kompatibel sein.

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. Das gcloud-Tool verwendet automatisch eine Standardregion und eine Standardzone, die sich nach dem Standort richten, 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

Die Pipeline speichert während der Ausführung Zwischendateien in gs://BUCKET/FOLDER/work. Sie können die Dateien nach Abschluss des Workflows entfernen, um die Kosten für Cloud Storage zu reduzieren.

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 alle 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 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 .
  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 umfassendere Hintergrundinformationen, Dokumentationen und Support bezüglich der GATK-Tools und WDL.