Diese Seite wurde von der Cloud Translation API übersetzt.
Switch to English

Genomische Varianten speichern und laden

Auf dieser Seite wird beschrieben, wie Sie VCF-Dateien mit dem Tool Variant Transforms transformieren und für umfangreiche Analysen direkt in BigQuery laden.

Wenn Sie eine große Anzahl von Dateien laden, lesen Sie die Empfehlungen zur Leistungsverbesserung und Kostensenkung unter Große Eingabemengen verarbeiten.

VCF-Dateien in BigQuery laden und transformieren

Hinweis

Sie benötigen die folgenden Komponenten, um das Tool ausführen zu können:

Tool ausführen

Sie können das Tool mit einem Docker-Image ausführen, in dem alle erforderlichen Binärdateien und Abhängigkeiten installiert sind.

So führen Sie das Tool mit einem Docker-Image aus:

  1. Verwenden Sie den folgenden Befehl, um die neueste Version von Variant Transforms zu erhalten.

    docker pull gcr.io/cloud-lifesciences/gcp-variant-transforms
    
  2. Kopieren Sie den folgenden Text und speichern Sie ihn in einer Datei namens script.sh. Ersetzen Sie dabei die Variablen durch die entsprechenden Ressourcen aus dem Google Cloud-Projekt.

    #!/bin/bash
    # Parameters to replace:
    # The GOOGLE_CLOUD_PROJECT is the project that contains your BigQuery dataset.
    GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
    INPUT_PATTERN=gs://BUCKET/*.vcf
    OUTPUT_TABLE=GOOGLE_CLOUD_PROJECT:BIGQUERY_DATASET.BIGQUERY_TABLE
    TEMP_LOCATION=gs://BUCKET/temp
    
    COMMAND="vcf_to_bq \
        --input_pattern ${INPUT_PATTERN} \
        --output_table ${OUTPUT_TABLE} \
        --temp_location ${TEMP_LOCATION} \
        --job_name vcf-to-bigquery \
        --runner DataflowRunner"
    docker run -v ~/.config:/root/.config \
        gcr.io/cloud-lifesciences/gcp-variant-transforms \
        --project "${GOOGLE_CLOUD_PROJECT}" \
        --zones us-west1-b \
        "${COMMAND}"
    

    Wenn Sie als Speicherort Ihrer VCF-Dateien einen Cloud Storage-Bucket angeben, können Sie eine einzelne Datei auswählen oder einen Platzhalter (*) verwenden, um mehrere Dateien gleichzeitig zu laden. Die zulässigen Dateiformate sind unter anderem GZIP, BZIP und VCF. Weitere Informationen finden Sie unter Mehrere Dateien laden.

    Beachten Sie, dass das Tool bei komprimierten Dateien länger für die Ausführung braucht, da komprimierte Dateien nicht fragmentiert werden können. Informationen zum Zusammenführen von Stichproben aus verschiedenen Dateien finden Sie unter Varianten zusammenführen.

    Beachten Sie, dass die temporären Dateien, die zur Ausführung des Tools notwendig sind, im Verzeichnis TEMP_LOCATION gespeichert werden. Das kann ein beliebiges Verzeichnis in Cloud Storage sein, für das Sie Schreibzugriff haben.

  3. Führen Sie den folgenden Befehl aus, um script.sh ausführbar zu machen:

    chmod +x script.sh
    
  4. Führen Sie script.sh aus.

    ./script.sh
    
  5. Die Ausführung des Jobs kann abhängig von verschiedenen Faktoren, unter anderem der Datenmenge, von wenigen Minuten bis hin zu einer Stunde oder länger dauern.

    Da das Tool Dataflow verwendet, können Sie zur Dataflow-Konsole wechseln, um eine detaillierte Ansicht des Jobs erhalten. Dort werden z. B. die Anzahl der verarbeiteten Datensätze, die Anzahl der Worker und ausführliche Fehlerlogs angezeigt.

  6. Führen Sie nach Abschluss des Jobs den folgenden Befehl aus, um eine Liste aller Tabellen in Ihrem Dataset zu erhalten. Überprüfen Sie, ob sich die neue Tabelle mit den VCF-Daten in der Liste befindet:

    bq ls --format=pretty GOOGLE_CLOUD_PROJECT:BIGQUERY_DATASET
    

    Außerdem können Sie sich Details zur Tabelle ansehen, z. B. das Schema und den Zeitpunkt der letzten Änderung:

    bq show --format=pretty GOOGLE_CLOUD_PROJECT:BIGQUERY_DATASET.BIGQUERY_TABLE
    

Zonen und Regionen einstellen

Google Cloud verwendet in Zonen unterteilte Regionen, um den geografischen Standort von physischen Computerressourcen zu definieren.

Sie können das Tool Variant Transforms in jeder Region oder Zone ausführen, in der Dataflow unterstützt wird.

Ändern Sie die Region, in der das Tool ausgeführt wird, indem Sie die Docker-Umgebungsvariable COMMAND und den gcloud-Befehl der Cloud Life Sciences API aktualisieren. Wenn Sie die Jobverarbeitung auf Europa beschränken möchten, sieht das Docker-Image-Skript aus dem vorherigen Abschnitt zum Beispiel so aus:

#!/bin/bash
# Parameters to replace:
# The GOOGLE_CLOUD_PROJECT is the project that contains your BigQuery dataset.
GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
INPUT_PATTERN=gs://BUCKET/*.vcf
OUTPUT_TABLE=GOOGLE_CLOUD_PROJECT:BIGQUERY_DATASET.BIGQUERY_TABLE
TEMP_LOCATION=gs://BUCKET/temp

COMMAND="vcf_to_bq \
    --input_pattern ${INPUT_PATTERN} \
    --output_table ${OUTPUT_TABLE} \
    --temp_location ${TEMP_LOCATION} \
    --job_name vcf-to-bigquery \
    --runner DataflowRunner
    --region europe-west1
    --zone europe-west1-b"
docker run -v ~/.config:/root/.config \
    gcr.io/cloud-lifesciences/gcp-variant-transforms \
    --project "${GOOGLE_CLOUD_PROJECT}" \
    --zones europe-west1-b \
    "${COMMAND}"

Informationen zum Festlegen des Standorts eines BigQuery-Datasets finden Sie unter Dataset erstellen.

Mehrere Dateien laden

Sie können mit dem Flag --input_pattern im obigen Skript angeben, welche VCF-Dateien in BigQuery geladen werden sollen. Setzen Sie das Flag folgendermaßen, um z. B. alle VCF-Dateien im Cloud Storage-Bucket my-bucket zu laden:

--input_pattern=gs://my-bucket/*.vcf

Beim Laden mehrerer Dateien mit dem Tool Variant Transforms werden die folgenden Vorgänge ausgeführt:

  1. Ein zusammengeführtes BigQuery-Schema wird erstellt, das Daten aus allen übereinstimmenden VCF-Dateien enthält, die im Flag --input_pattern aufgeführt sind. Zum Beispiel werden die von den VCF-Dateien gemeinsam verwendeten Felder INFO und FORMAT zusammengeführt. Bei diesem Schritt wird davon ausgegangen, dass in mehreren Dateien mit demselben Schlüssel definierte Felder kompatibel sind.

  2. Datensätze aus allen VCF-Dateien werden in eine einzige Tabelle geladen. Alle fehlenden Felder werden in der zugehörigen Spalte auf null gesetzt.

In einem dritten Schritt können Sie auch Stichproben zusammenführen. Weitere Informationen finden Sie unter Varianten zusammenführen.

Beim Laden der VCF-Dateien müssen ihre Felddefinitionen und -werte konsistent sein. Andernfalls schlägt das Tool fehl. Bei entsprechender Einstellung kann das Tool versuchen, Inkonsistenzen zu beheben. Weitere Informationen finden Sie unter Fehlerhafte Dateien verarbeiten.

Daten vorhandenen BigQuery-Tabellen anfügen

Sie können vorhandenen BigQuery-Tabellen Daten anfügen, indem Sie beim Ausführen des Tools Variant Transforms das Flag --append hinzufügen.

Sie erzielen die besten Ergebnisse beim Anfügen von Daten, wenn das verwendete Schema dem Schema in der vorhandenen Tabelle entspricht. Wenn das Schema der angefügten Daten eine Spalte mit demselben Namen wie eine Spalte in der vorhandenen Tabelle enthält, müssen beide Spalten neben dem Namen auch denselben Datentyp und Modus haben. Andernfalls gibt das Tool Variant Transforms einen Fehler zurück.

Sie können Daten anfügen, die ein anderes Schema als die vorhandene Tabelle haben, indem Sie zusätzlich zum Flag --append das Flag --update_schema_on_append hinzufügen. Neue Spalten aus den angefügten Daten werden dem vorhandenen Schema hinzugefügt. Im vorhandenen Schema werden die Zeilenwerte der neuen Spalten auf NULL gesetzt. Wenn das vorhandene Schema über Spalten verfügt, die in den angefügten Daten nicht vorhanden sind, sind die Werte der Zeilen in den angefügten Datenspalten ebenfalls NULL.

Fehlerhafte Dateien verarbeiten

Sie haben mehrere Möglichkeiten, fehlerhafte oder nicht kompatible Dateien zu verarbeiten. Bevor Sie VCF-Dateien laden, können Sie mit dem Präprozessor-Tool für VCF-Dateien prüfen, ob fehlerhafte oder inkompatible Dateien vorhanden sind.

Nicht kompatible Felder verarbeiten

Wenn Sie mehrere VCF-Dateien laden, führt das Tool Variant Transforms alle INFO- und HEADER-Felder zusammen, um einen "repräsentativen Header" zu generieren. Dieser wird dann verwendet, um das BigQuery-Schema zu erstellen. Wenn in mehreren Dateien derselbe Schlüssel definiert ist, muss seine Definition in allen Dateien kompatibel sein. Es gelten die folgenden Kompatibilitätsregeln:

  • Felder sind kompatibel, wenn die Werte in den Feldern Number und Type identisch sind. Anmerkungsfelder, die mit dem Flag --annotation_fields angegeben werden, müssen auch im Feld Description denselben Wert haben.
  • Felder, die unterschiedliche Werte für Type enthalten, sind in den folgenden Fällen kompatibel:

    • Die Felder Integer und Float sind kompatibel und verwenden beide den Typ Float.
    • Sie führen das Tool Variant Transforms mit dem Flag --allow_incompatible_records aus. Damit werden Konflikte zwischen inkompatiblen Feldern wie String und Integer automatisch gelöst. Dadurch werden inkompatible Typen nicht unbemerkt ignoriert.
  • Felder mit unterschiedlichen Werten im Feld Number sind in den folgenden Fällen kompatibel:

    • Die Werte enthalten "wiederholte" Zahlen, die miteinander kompatibel sind, z. B.:

      • Number=. (unbekannte Zahl)
      • Alle Werte für Number größer als 1
      • Number=G (ein Wert pro Genotyp) und Number=R (ein Wert für jede Alternative und Referenz)
      • Number=A (ein Wert für jede Alternative), nur wenn bei Ausführung des Tools --split_alternate_allele_info_fields auf False eingestellt ist
    • Sie führen das Tool Variant Transforms mit dem Flag --allow_incompatible_records aus. Damit werden Konflikte zwischen inkompatiblen Feldern wie Number=1 und Number=. automatisch gelöst. Dadurch werden inkompatible Typen nicht unbemerkt ignoriert.

Header-Datei angeben

Bei Ausführung des Tools Variant Transforms können Sie das Flag --representative_header_file mit einer Header-Datei übergeben, mit der das BigQuery-Schema generiert werden kann. In der Datei werden die Header angegeben, die aus allen zu ladenden Dateien zusammengeführt werden.

Das Tool Variant Transforms liest nur die Headerinformationen aus der Datei und ignoriert alle VCF-Datensätze. Das heißt, Dateien können nur die Headerfelder enthalten oder echte VCF-Dateien sein.

Dateien, die nur Headerfelder enthalten, haben die folgenden Vorteile:

  • Die Ausführung der Pipeline ist schneller, insbesondere wenn Sie eine große Anzahl von Dateien laden. Das Tool Variant Transforms generiert anhand der Header-Datei das BigQuery-Schema und überspringt den Schritt, Header dateiübergreifend zusammenzuführen. Dies ist besonders nützlich, wenn die VCF-Header in allen Dateien gleich sind.

  • Für fehlende Headerfelder können Definitionen angegeben werden.

  • Inkompatible Felddefinitionen können dateiübergreifend gelöst werden.

Header ableiten

Es kann vorkommen, dass bei Ausführung des Tools Variant Transforms Felder ohne Definition vorhanden sind oder das Tool Headerdefinitionen ignorieren soll, die nicht mit Feldwerten kompatibel sind. In diesem Fall sollte das Tool die korrekten Headerdefinitionen für diese Felder ableiten.

Sie können das Flag --infer_headers übergeben. Das Tool leitet dann die Werte für TYPE und NUMBER für undefinierte Felder ab. Es leitet die Werte anhand der Feldwerte in allen VCF-Dateien ab.

Beim Übergeben dieses Flags wird auch ein repräsentativer Header ausgegeben, der abgeleitete Definitionen und Definitionen aus Headern enthält.

Inkompatible Datensätze zulassen

Das Tool Variant Transforms schlägt in den folgenden Fällen fehl:

  • Felddefinition und Feldwerte sind inkonsistent.
  • Ein Feld hat in zwei verschiedenen VCF-Dateien zwei inkonsistente Definitionen.

In beiden Fällen können Sie das Flag --allow_incompatible_records übergeben. Dadurch löst das Tool Konflikte in Headerdefinitionen automatisch. Darüber hinaus wandelt das Tool Feldwerte so um, dass sie mit dem BigQuery-Schema übereinstimmen, falls zwischen der Definition und dem Wert eines Felds eine Inkonsistenz besteht. (Der Wert des Felds Integer wird beispielsweise in String umgewandelt, damit er dem Feldschema vom Typ String entspricht.)

Nächste Schritte