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.

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 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. 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. 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.

    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. 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 gcloud storage buckets create 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.

gcloud storage buckets create 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

In diesem Abschnitt wird beschrieben, 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:

    gcloud storage 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:

gcloud storage 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.

Die gcloud CLI prüft 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 eine Standardregion und eine Standardzone verwendet, 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:

    gcloud storage 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.

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

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

gcloud storage 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