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.
Hinweise
- 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.
-
Wählen Sie in der Google Cloud Console auf der Seite der Projektauswahl ein Google Cloud-Projekt aus oder erstellen Sie eines.
-
Die Abrechnung für das Google Cloud-Projekt muss aktiviert sein.
-
Cloud Life Sciences, Compute Engine, and Cloud Storage APIs aktivieren.
- Installieren Sie die Google Cloud CLI.
-
Führen Sie folgenden Befehl aus, um die gcloud CLI zu initialisieren:
gcloud init
-
Aktualisieren und installieren Sie
gcloud
-Komponenten:gcloud components update
gcloud components install beta -
Wählen Sie in der Google Cloud Console auf der Seite der Projektauswahl ein Google Cloud-Projekt aus oder erstellen Sie eines.
-
Die Abrechnung für das Google Cloud-Projekt muss aktiviert sein.
-
Cloud Life Sciences, Compute Engine, and Cloud Storage APIs aktivieren.
- Installieren Sie die Google Cloud CLI.
-
Führen Sie folgenden Befehl aus, um die gcloud CLI zu initialisieren:
gcloud init
-
Aktualisieren und installieren Sie
gcloud
-Komponenten:gcloud components update
gcloud components install beta - Installieren Sie Git, um die erforderlichen Dateien herunterzuladen.
-
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:
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
Erstellen Sie die Umgebungsvariable
GATK_OUTPUT_DIR
, die auf den Cloud Storage-Bucket samt Pfad verweist, in dem die Ausgabe des Workflows (output
), diework
-Zwischendateien undlogging
gespeichert werden:export GATK_OUTPUT_DIR=gs://BUCKET/FOLDER
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/
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
Erstellen Sie die Umgebungsvariablen
NETWORK
undSUBNETWORK
, um den Namen Ihres VPC-Netzwerks und Subnetzwerks anzugeben:export NETWORK=VPC_NETWORK export SUBNETWORK=VPC_SUBNET
Bearbeiten Sie die Datei
PairedEndSingleSampleWf.options.json
im Verzeichnisbroad-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 Subnetzus-central1
verwenden, sieht das Feldzones
so aus:"zones": "us-central1-a us-central1-b us-central1-c us-central1-f"
.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/
Der Befehl gibt eine Vorgangs-ID im folgenden Format zurück:
Running [operations/OPERATION_ID]
. Mit dem Befehlgcloud 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)'
Der Befehl
operations describe
gibtdone: 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
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:
- Rufen Sie in der Google Cloud Console die Seite „Projekte“ auf.
- Wählen Sie in der Projektliste das Projekt aus, das Sie löschen möchten, und klicken Sie auf Delete project (Projekt löschen).
- 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.