TileDB-VCF
Überblick
TileDB-VCF ist eine leistungsstarke C++-Bibliothek mit Python- und CLI-Schnittstellen für die effiziente Speicherung und den Abruf von genomischen Variantendaten (Variant-Call-Daten). Aufbauend auf TileDBs Sparse-Array-Technologie ermöglicht es die skalierbare Aufnahme von VCF/BCF-Dateien, die inkrementelle Hinzufügung von Proben ohne aufwändige Merge-Vorgänge und effiziente parallele Abfragen von lokal oder in der Cloud gespeicherten Variantendaten.
Wann diese Fähigkeit eingesetzt werden sollte
Diese Fähigkeit sollte eingesetzt werden, wenn:
- TileDB-VCF-Konzepte und Arbeitsabläufe erlernt werden sollen
- Genomanalysen und Pipelines prototypisiert werden
- Mit kleinen bis mittelgroßen Datensätzen (< 1000 Proben) gearbeitet wird
- Eine inkrementelle Hinzufügung neuer Proben zu bestehenden Datensätzen erforderlich ist
- Eine effiziente Abfrage bestimmter genomischer Regionen über viele Proben hinweg benötigt wird
- Mit in der Cloud gespeicherten Variantendaten (S3, Azure, GCS) gearbeitet wird
- Teilmengen großer VCF-Datensätze exportiert werden müssen
- Variantendatenbanken für Kohortenstudien aufgebaut werden
- Bildungsprojekte und Methodenentwicklung durchgeführt werden
- Die Leistung bei Variantendatenoperationen kritisch ist
Schnellstart
Installation
Bevorzugte Methode: Conda/Mamba
# Geben Sie die folgenden zwei Zeilen ein, wenn Sie auf einem M1 Mac sind
CONDA_SUBDIR=osx-64
conda config --env --set subdir osx-64
# Erstellen Sie die Conda-Umgebung
conda create -n tiledb-vcf "python<3.10"
conda activate tiledb-vcf
# Mamba ist eine schnellere und zuverlässigere Alternative zu conda
conda install -c conda-forge mamba
# Installieren Sie TileDB-Py und TileDB-VCF, abgestimmt auf andere nützliche Bibliotheken
mamba install -y -c conda-forge -c bioconda -c tiledb tiledb-py tiledbvcf-py pandas pyarrow numpy
Alternative: Docker-Images
docker pull tiledb/tiledbvcf-py # Python-Schnittstelle
docker pull tiledb/tiledbvcf-cli # Kommandozeilen-Schnittstelle
Grundlegende Beispiele
Einen Datensatz erstellen und befüllen:
import tiledbvcf
# Neuen Datensatz erstellen
ds = tiledbvcf.Dataset(uri="my_dataset", mode="w",
cfg=tiledbvcf.ReadConfig(memory_budget=1024))
# VCF-Dateien aufnehmen (müssen Einzelproben-Dateien mit Indizes sein)
# Anforderungen:
# - VCFs müssen Einzelproben-Dateien sein (keine Mehrproben-Dateien)
# - Sie müssen Indizes haben: .csi (bcftools) oder .tbi (tabix)
ds.ingest_samples(["sample1.vcf.gz", "sample2.vcf.gz"])
Variantendaten abfragen:
# Vorhandenen Datensatz zum Lesen öffnen
ds = tiledbvcf.Dataset(uri="my_dataset", mode="r")
# Bestimmte Regionen und Proben abfragen
df = ds.read(
attrs=["sample_name", "pos_start", "pos_end", "alleles", "fmt_GT"],
regions=["chr1:1000000-2000000", "chr2:500000-1500000"],
samples=["sample1", "sample2", "sample3"]
)
print(df.head())
Nach VCF exportieren:
import os
# Zwei VCF-Proben exportieren
ds.export(
regions=["chr21:8220186-8405573"],
samples=["HG00101", "HG00097"],
output_format="v",
output_dir=os.path.expanduser("~"),
)
Kernfunktionen
1. Erstellung und Aufnahme von Datensätzen
Erstellen Sie TileDB-VCF-Datensätze und nehmen Sie schrittweise Variantendaten aus mehreren VCF/BCF-Dateien auf. Dies eignet sich für den Aufbau populationsgenomischer Datenbanken und Kohortenstudien.
Anforderungen:
- Nur Einzelproben-VCFs: Mehrproben-VCFs werden nicht unterstützt
- Indexdateien erforderlich: VCF/BCF-Dateien müssen Indizes haben (.csi oder .tbi)
Häufige Operationen:
- Neue Datensätze mit optimierten Array-Schemata erstellen
- Einzelne oder mehrere VCF/BCF-Dateien parallel aufnehmen
- Neue Proben schrittweise hinzufügen, ohne vorhandene Daten erneut zu verarbeiten
- Speichernutzung und Komprimierungseinstellungen konfigurieren
- Verschiedene VCF-Formate und INFO/FORMAT-Felder verarbeiten
- Unterbrochene Aufnahmevorgänge fortsetzen
- Datenintegrität während der Aufnahme validieren
2. Effizientes Abfragen und Filtern
Abfragen von Variantendaten mit hoher Leistung über genomische Regionen, Proben und Variantenattribute hinweg. Dies eignet sich für Assoziationsstudien, Variantenentdeckung und Populationsanalysen.
Häufige Operationen:
- Bestimmte genomische Regionen abfragen (einzeln oder mehrere)
- Nach Probennamen oder Probengruppen filtern
- Bestimmte Variantenattribute extrahieren (Position, Allele, Genotypen, Qualität)
- Effizient auf INFO- und FORMAT-Felder zugreifen
- Räumliche und attributbasierte Filterung kombinieren
- Große Abfrageergebnisse streamen
- Aggregationen über Proben oder Regionen durchführen
3. Datenexport und Interoperabilität
Exportieren Sie Daten in verschiedenen Formaten für nachgelagerte Analysen oder die Integration mit anderen Genomik-Tools. Dies eignet sich zum Teilen von Datensätzen, zum Erstellen von Analyseteilmengen oder zur Einspeisung in andere Pipelines.
Häufige Operationen:
- Export in Standard-VCF/BCF-Formate
- TSV-Dateien mit ausgewählten Feldern erstellen
- Proben-/regionsspezifische Teilmengen erstellen
- Datenherkunft und Metadaten beibehalten
- Verlustfreier Datenexport unter Beibehaltung aller Annotationen
- Komprimierte Ausgabeformate
- Streaming-Exporte für große Datensätze
4. Populationsgenomik-Workflows
TileDB-VCF zeichnet sich in groß angelegten populationsgenomischen Analysen aus, die einen effizienten Zugriff auf Variantendaten über viele Proben und genomische Regionen hinweg erfordern.
Häufige Workflows:
- Datenvorbereitung für genomweite Assoziationsstudien (GWAS)
- Seltene-Varianten-Burden-Tests
- Populationsstratifikationsanalyse
- Allelfrequenzberechnungen über Populationen hinweg
- Qualitätskontrolle in großen Kohorten
- Variantenannotation und -filterung
- Vergleichende Analyse zwischen Populationen
Wichtige Konzepte
Array-Schema und Datenmodell
TileDB-VCF-Datenmodell:
- Varianten werden als dünn besetzte Arrays mit genomischen Koordinaten als Dimensionen gespeichert
- Proben werden als Attribute gespeichert, was eine effiziente probenspezifische Abfrage ermöglicht
- INFO- und FORMAT-Felder bleiben mit ursprünglichen Datentypen erhalten
- Automatische Komprimierung und Blockbildung (Chunking) für optimale Speicherung
Schema-Konfiguration:
# Benutzerdefiniertes Schema mit spezifischen Kachelausdehnungen
config = tiledbvcf.ReadConfig(
memory_budget=2048, # MB
region_partition=(0, 3095677412), # Vollständiges Genom
sample_partition=(0, 10000) # Bis zu 10k Proben
)
Koordinatensysteme und Regionen
Wichtig: TileDB-VCF verwendet 1-basierte genomische Koordinaten gemäß dem VCF-Standard:
- Positionen sind 1-basiert (die erste Base ist Position 1)
- Bereiche sind an beiden Enden inklusive
- Die Region „chr1:1000-2000“ umfasst die Positionen 1000-2000 (insgesamt 1001 Basen)
Formate für Regionsspezifikation:
# Einzelne Region
regions = ["chr1:1000000-2000000"]
# Mehrere Regionen
regions = ["chr1:1000000-2000000", "chr2:500000-1500000"]
# Vollständiges Chromosom
regions = ["chr1"]
# BED-Stil (0-basiert, halboffen, intern konvertiert)
regions = ["chr1:999999-2000000"] # Äquivalent zu 1-basiert chr1:1000000-2000000
Speicherverwaltung
Leistungsüberlegungen:
- Angemessenes Speicherbudget festlegen basierend auf dem verfügbaren Systemspeicher
- Streaming-Abfragen verwenden für sehr große Ergebnismengen
- Große Aufnahmen partitionieren, um Speichererschöpfung zu vermeiden
- Kachel-Cache konfigurieren für wiederholten Regionszugriff
- Parallele Aufnahme verwenden für mehrere Dateien
- Regionsabfragen optimieren durch Kombinieren nahegelegener Regionen
Cloud-Speicher-Integration
TileDB-VCF arbeitet nahtlos mit Cloud-Speichern zusammen:
# S3-Datensatz
ds = tiledbvcf.Dataset(uri="s3://bucket/dataset", mode="r")
# Azure Blob Storage
ds = tiledbvcf.Dataset(uri="azure://container/dataset", mode="r")
# Google Cloud Storage
ds = tiledbvcf.Dataset(uri="gcs://bucket/dataset", mode="r")
Häufige Fallstricke
- Speichererschöpfung während der Aufnahme: Angemessenes Speicherbudget und Batch-Verarbeitung für große VCF-Dateien verwenden
- Ineffiziente Regionsabfragen: Nahegelegene Regionen kombinieren anstatt viele separate Abfragen durchzuführen
- Fehlende Probennamen: Sicherstellen, dass die Probennamen in den VCF-Headern mit den Probenspezifikationen in der Abfrage übereinstimmen
- Koordinatensystem-Verwirrung: Denken Sie daran, dass TileDB-VCF wie der VCF-Standard 1-basierte Koordinaten verwendet
- Große Ergebnismengen: Streaming oder Paginierung für Abfragen mit Millionen von Varianten verwenden
- Cloud-Berechtigungen: Sicherstellen einer ordnungsgemäßen Authentifizierung für den Cloud-Speicherzugriff
- Gleichzeitiger Zugriff: Mehrere Schreiber auf denselben Datensatz können zu Datenkorruption führen – verwenden Sie geeignete Sperrmechanismen
CLI-Nutzung
TileDB-VCF bietet eine Kommandozeilen-Schnittstelle mit den folgenden Unterbefehlen:
Verfügbare Unterbefehle:
create– Erstellt einen leeren TileDB-VCF-Datensatzstore– Nimmt Proben in einen TileDB-VCF-Datensatz aufexport– Exportiert Daten aus einem TileDB-VCF-Datensatzlist– Listet alle Probennamen auf, die in einem TileDB-VCF-Datensatz vorhanden sindstat– Gibt Statistiken auf hoher Ebene zu einem TileDB-VCF-Datensatz ausutils– Hilfsprogramme für die Arbeit mit einem TileDB-VCF-Datensatzversion– Gibt die Versionsinformationen aus und beendet das Programm
# Leeren Datensatz erstellen
tiledbvcf create --uri my_dataset
# Proben aufnehmen (erfordert Einzelproben-VCFs mit Indizes)
tiledbvcf store --uri my_dataset --samples sample1.vcf.gz,sample2.vcf.gz
# Daten exportieren
tiledbvcf export --uri my_dataset \
--regions "chr1:1000000-2000000" \
--sample-names "sample1,sample2"
# Alle Proben auflisten
tiledbvcf list --uri my_dataset
# Datensatzstatistiken anzeigen
tiledbvcf stat --uri my_dataset
Erweiterte Funktionen
Allelfrequenzanalyse
# Allelfrequenzen berechnen
af_df = tiledbvcf.read_allele_frequency(
uri="my_dataset",
regions=["chr1:1000000-2000000"],
samples=["sample1", "sample2", "sample3"]
)
Probenqualitätskontrolle
# Proben-QC durchführen
qc_results = tiledbvcf.sample_qc(
uri="my_dataset",
samples=["sample1", "sample2"]
)
Benutzerdefinierte Konfigurationen
# Erweiterte Konfiguration
config = tiledbvcf.ReadConfig(
memory_budget=4096,
tiledb_config={
"sm.tile_cache_size": "1000000000",
"vfs.s3.region": "us-east-1"
}
)
Ressourcen
Hilfe erhalten
Open-Source-Ressourcen zu TileDB-VCF
Open-Source-Dokumentation:
- TileDB Academy: https://cloud.tiledb.com/academy/
- Leitfaden zur Populationsgenomik: https://cloud.tiledb.com/academy/structure/life-sciences/population-genomics/
- TileDB-VCF GitHub: https://github.com/TileDB-Inc/TileDB-VCF
TileDB-Cloud-Ressourcen
Für groß angelegte/Produktions-Genomik:
- TileDB-Cloud Plattform: https://cloud.tiledb.com
- TileDB Academy (Gesamte Dokumentation): https://cloud.tiledb.com/academy/
Erste Schritte:
- Kostenlose Kontoerstellung: https://cloud.tiledb.com
- Kontakt: [email protected] für Unternehmensanforderungen
Skalierung zur TileDB-Cloud
Wenn Ihre Genomik-Workloads die Verarbeitung auf einem einzelnen Knoten überschreiten, bietet TileDB-Cloud unternehmensweite Funktionen für Produktions-Genomik-Pipelines.
Hinweis: Dieser Abschnitt behandelt die Funktionen von TileDB-Cloud basierend auf der verfügbaren Dokumentation. Vollständige API-Details und aktuelle Funktionalität finden Sie in der offiziellen TileDB-Cloud-Dokumentation und der API-Referenz.
Einrichten von TileDB-Cloud
1. Konto erstellen und API-Token abrufen
# Auf https://cloud.tiledb.com registrieren
# API-Token in Ihren Kontoeinstellungen generieren
2. TileDB-Cloud Python-Client installieren
# Basisinstallation
uv pip install tiledb-cloud
# Mit genomspezifischer Funktionalität
uv pip install tiledb-cloud[life-sciences]
3. Authentifizierung konfigurieren
# Umgebungsvariable mit Ihrem API-Token setzen
export TILEDB_REST_TOKEN="your_api_token"
import tiledb.cloud
# Authentifizierung erfolgt automatisch über TILEDB_REST_TOKEN
# Keine explizite Anmeldung im Code erforderlich
Migration von Open Source zu TileDB-Cloud
Groß angelegte Aufnahme
# TileDB-Cloud: Verteilte VCF-Aufnahme
import tiledb.cloud.vcf
# Spezialisiertes VCF-Aufnahme-Modul verwenden
# Hinweis: Die genaue API erfordert die TileDB-Cloud-Dokumentation
# Dies stellt die verfügbare Funktionsstruktur dar
tiledb.cloud.vcf.ingestion.ingest_vcf_dataset(
source="s3://my-bucket/vcf-files/",
output="tiledb://my-namespace/large-dataset",
namespace="my-namespace",
acn="my-s3-credentials",
ingest_resources={"cpu": "16", "memory": "64Gi"}
)
Verteilte Abfrageverarbeitung
# TileDB-Cloud: VCF-Abfrage über verteilte Speicher hinweg
import tiledb.cloud.vcf
import tiledbvcf
# Den URI des Datensatzes definieren
dataset_uri = "tiledb://TileDB-Inc/gvcf-1kg-dragen-v376"
# Alle Proben aus dem Datensatz abrufen
ds = tiledbvcf.Dataset(dataset_uri, tiledb_config=cfg)
samples = ds.samples()
# Attribute und Bereiche für die Abfrage definieren
attrs = ["sample_name", "fmt_GT", "fmt_AD", "fmt_DP"]
regions = ["chr13:32396898-32397044", "chr13:32398162-32400268"]
# Die Leseoperation durchführen, die verteilt ausgeführt wird
df = tiledb.cloud.vcf.read(
dataset_uri=dataset_uri,
regions=regions,
samples=samples,
attrs=attrs,
namespace="my-namespace", # Gibt an, welches Konto belastet wird
)
df.to_pandas()
Unternehmensfunktionen
Datenaustausch und Zusammenarbeit
# TileDB-Cloud bietet Funktionen zum Datenaustausch auf Unternehmensebene
# durch namespace-basierte Berechtigungen und Gruppenverwaltung
# Auf gemeinsam genutzte Datensätze über TileDB-Cloud-URIs zugreifen
dataset_uri = "tiledb://shared-namespace/population-study"
# Zusammenarbeit über gemeinsam genutzte Notebooks und Rechenressourcen
# (Die genaue API erfordert die TileDB-Cloud-Dokumentation)
Kostenoptimierung
- Serverless Computing: Nur für die tatsächliche Rechenzeit bezahlen
- Automatische Skalierung: Automatisches Hoch- und Herunterskalieren basierend auf der Arbeitslast
- Spot-Instances: Kostenoptimierte Rechenleistung für Batch-Jobs verwenden
- Daten-Tiering: Automatische Verwaltung von heißen und kalten Speichermedien
Sicherheit und Compliance
- Ende-zu-Ende-Verschlüsselung: Daten werden während der Übertragung und im Ruhezustand verschlüsselt
- Zugriffskontrollen: Feingranulare Berechtigungen und Prüfprotokolle
- HIPAA/SOC2-Konformität: Unternehmenssicherheitsstandards
- VPC-Unterstützung: Bereitstellung in privaten Cloud-Umgebungen
Checkliste für die Migration
✅ Zur TileDB-Cloud migrieren, wenn folgende Bedingungen vorliegen:
- Datensätze > 1000 Proben
- Verarbeitung von > 100 GB VCF-Daten erforderlich
- Verteiltes Rechnen erforderlich
- Mehrere Teammitglieder benötigen Zugriff
- Unternehmenssicherheit/-konformität erforderlich
- Kostenoptimiertes Serverless-Computing gewünscht
- 24/7-Produktionsbetrieb erforderlich
Erste Schritte mit TileDB-Cloud
- Kostenlos starten: TileDB-Cloud bietet eine kostenlose Testversion zur Evaluierung
- Migrationsunterstützung: Das TileDB-Team bietet Unterstützung bei der Migration
- Schulung: Zugang zu genomspezifischen Tutorials