duckhts

DuckDB-Erweiterung zum Lesen von HTS-Dateiformaten über htslib

Maintainer: sounkou-bioinfo

Installation und Laden

INSTALL duckhts FROM community;
LOAD duckhts;

Beispiel

-- Load the extension
LOAD duckhts;

-- Read a VCF/BCF file (tidy FORMAT columns)
SELECT CHROM, POS, REF, ALT, SAMPLE_ID
FROM read_bcf('test/data/formatcols.vcf.gz', tidy_format := true)
LIMIT 5;

-- Read a BAM/SAM file
SELECT QNAME, RNAME, POS, READ_GROUP_ID, SAMPLE_ID
FROM read_bam('test/data/rg.sam.gz')
LIMIT 5;

Über duckhts

DuckHTS stellt DuckDB-Tabellenfunktionen für gängige High-Throughput-Sequencing-(HTS-)Formate über htslib bereit. Fragen Sie VCF-, BCF-, BAM-, CRAM-, FASTA-, FASTQ-, GTF-, GFF- und tabix-indizierte Dateien direkt in SQL ab.

Die Erweiterung enthält außerdem Sequenz-Hilfs-UDFs, SAM-Flag-Prädikathelfer und HTS-Metadatenhelfer.

In dieser Erweiterung enthaltene Funktionen:

Diagnose

• duckhts_htslib_version(): Gibt die Laufzeitversion zurück, die die mit DuckHTS geladene htslib-Bibliothek meldet. Rduckhts verwendet diesen Wert, um eine nachgelagerte Linking-Receipt abzulehnen, deren Quell-/Header-Version nicht zur geladenen Bibliothek passt.
• duckhts_htslib_features(): Gibt das von hts_features() gemeldete htslib-Laufzeit-Feature-Bitfeld zurück. Verwenden Sie duckhts_htslib_feature_string() für die zugehörige Build-Beschreibung.
• duckhts_htslib_feature_string(): Gibt die Laufzeit-Build-Feature-Beschreibung von htslib zurück, einschließlich konfigurierter Transports, Kompressionsbibliotheken, Compiler und Build-Flags. DuckHTS speichert sie einmal beim Laden der Erweiterung, sodass parallele SQL-Aufrufe unveränderlichen Text lesen.
• duckhts_simd_backend(): Gibt das aktuelle DuckHTS-SIMD-Dispatch-Label zurück. Bei expliziten Skalar- oder konkreten Backend-Anfragen ist das die angeforderte Policy; bei auto das einzige ausgewählte Backend, wenn alle logischen Kernel dasselbe Backend auflösen, oder mixed, wenn Auto-Dispatch pro Kernel mehrere Backends auflöst. Verwenden Sie duckhts_simd_kernel_info() für Details pro Kernel.
• duckhts_simd_requested_backend(): Gibt die aktuelle explizite SIMD-Backend-Anfrage zurück, üblicherweise auto, sofern nicht SELECT backend FROM duckhts_simd_set_backend('auto'|'scalar'|backend) aufgerufen wurde. Das ausgewählte Backend pro Kernel kann unter Auto-Dispatch auf x86, ARM, wasm und skalar-only Builds abweichen.
• duckhts_simd_backend_compiled(backend): Gibt zurück, ob ein konkretes DuckHTS-SIMD-Backend in diesen Build einkompiliert wurde. Das ist unabhängig davon, ob die aktuelle CPU/Laufzeit dieses Backend ausführen kann; beispielsweise kann avx512 kompiliert, aber auf dem laufenden Host nicht CPU-unterstützt sein.
• duckhts_simd_backend_cpu_supported(backend): Gibt zurück, ob die aktuelle CPU/Laufzeit ein konkretes DuckHTS-SIMD-Backend unterstützt, unabhängig davon, ob DuckHTS eine Implementierung dafür kompiliert hat. Verfügbarkeit ist die Schnittmenge aus kompiliert und CPU-unterstützt.
• duckhts_simd_backend_available(backend): Gibt zurück, ob ein konkretes SIMD-Backend im aktuellen Prozess nutzbar ist. Verfügbarkeit bedeutet, dass das Backend in DuckHTS einkompiliert und von der aktuellen CPU/Laufzeit unterstützt wird. auto ist eine Auswahl-Anfrage und kein konkretes Backend und wird hier nicht als verfügbar gemeldet.
• duckhts_simd_info(): Gibt eine Zeile pro bekanntem konkretem DuckHTS-SIMD-Backend mit erweiterungseigenen Diagnosen zu selectable, compiled, CPU-supported, available, selected, requested und Dispatch-Modus zurück. Verfügbarkeit ist die Schnittmenge aus kompiliert und CPU-/laufzeitunterstützt. selectable gibt an, ob das Backend einen auswählbaren Implementierungspfad hat; explizite Auswahl erfordert weiterhin available = TRUE. selected ist TRUE, wenn die aktuelle Dispatch-Tabelle dieses Backend für mindestens einen logischen Kernel verwendet. auto ist eine Auswahl-Anfrage und keine konkrete Backend-Zeile.
• duckhts_simd_kernel_info(): Gibt eine Zeile pro logischem DuckHTS-SIMD-Kernel zurück und zeigt das von der aktuellen unveränderlichen Dispatch-Tabelle ausgewählte konkrete Backend, die ausgewählte Fähigkeit, die angeforderte Backend-Policy, ob scalar als Fallback pro Kernel verwendet wurde, und den Dispatch-Modus. Das ist die maßgebliche Diagnose für gemischtes Auto-Dispatch, wenn unterschiedliche Kernel unterschiedliche Backends auflösen.
• duckhts_simd_set_backend(backend): Wählt die DuckHTS-SIMD-Dispatch-Policy für diesen Prozess explizit über einen Ein-Zeilen-Tabellenfunktionsaufruf und gibt das aktuelle Dispatch-Label in einer Backend-Spalte zurück. Verwenden Sie auto für Laufzeit-Dispatch pro Kernel oder scalar für eine portable Baseline; nicht verfügbare plattformspezifische Anfragen wie avx512 auf CPUs ohne AVX-512 lösen einen Fehler aus statt stillschweigend zurückzufallen.
• duckhts_duckdb_type_supported(type_name): Gibt zurück, ob die aktuell geöffnete DuckDB-Laufzeit einen logischen Typ mit dem angegebenen Namen über duckdb_types() bekanntgibt. Das ist eine katalogweite Laufzeitprüfung für Feature-Gating von SQL/Makros über DuckDB-Versionen.
• duckhts_duckdb_supports_variant(): Gibt zurück, ob die aktuell geöffnete DuckDB-Laufzeit den logischen Typ VARIANT bekanntgibt. Nutzen Sie das, um optionales SQL zu steuern, das DuckDB-VARIANT-Unterstützung voraussetzt.
• duckhts_duckdb_supports_geometry(): Gibt zurück, ob die aktuell geöffnete DuckDB-Laufzeit den logischen Typ GEOMETRY bekanntgibt. Nutzen Sie das, um optionales SQL zu steuern, das DuckDB-GEOMETRY-Unterstützung voraussetzt.

Variantenannotation

• duckvep_ensembl_regions(core_schema, reference_chunks_table, assembly, species_id := 1): Ordnet eine gekachelte Referenzsequenz einer Ensembl-Core-Assembly zu und weist dichte DuckVEP-Sequenzregion-Ordinalzahlen zu. core_schema muss die Ensembl-Tabellen seq_region und coord_system enthalten. reference_chunks_table muss die Spalten chrom, nullbasierter Start, halb-offenes Ende und seq enthalten, üblicherweise materialisiert aus fasta_nuc(…, include_seq := TRUE). Chunks müssen von null an zusammenhängend sein, ihre Sequenzlängen müssen zu ihren Intervallen passen, und jeder FASTA-Contig muss genau einer Ensembl-Region gleicher Länge entsprechen. In der gelieferten FASTA fehlende Regionen werden bewusst ausgeschlossen. Die gelieferte Referenz definiert daher die exakt modellierte Pfadmenge: eine Primary-Assembly-FASTA erzeugt ein Primary-Path-Modell, während alternative Haplotypen oder Patches ihre benannten Sequenzpfade in den Referenz-Chunks benötigen. Dieses Makro wendet keine Ensembl-assembly_exception-Projektionen an, führt X/Y-PAR-Pfade nicht zusammen und markiert keine zirkulären Sequenzregionen; gewöhnliche mitochondriale Koordinaten können modelliert werden, aber ein Intervall, das vom Ende einer zirkulären Sequenz zu ihrem Anfang wrappt, wird nicht akzeptiert.
• duckvep_ensembl_transcripts(core_schema, reference_chunks_table, assembly, species_id := 1): Erzeugt die validierte DuckVEP-Transkriptrelation aus Ensembl-Core-Tabellen und passender gekachelter FASTA-Sequenz. Dieser mitgelieferte Builder kompiliert die VEP-116-Ensembl-Core-Auswahl; er baut keine VEP—refseq- oder —merged-Transkriptsätze. Bevor dichte Ordinalzahlen zugewiesen werden, müssen Transkripte aktuell sein und eine nichtleere stabile ID haben; Artifact-Biotype- oder readthrough_tra-Transkripte werden ausgeschlossen. Das Ergebnis enthält die exakten Resident-Loader-Spalten, stabile/Quell-Identifikatoren, Biotypen, versionierte RefSeq-Accessions aus MANE-Select- und MANE-Plus-Clinical-Attributen sofern vorhanden, eine verschachtelte Ranked-Exon-Projektion, reife miRNA-cDNA-Attribute, projiziert in genomische Exon-Segmente, und unterstützte Translation-SeqEdits. MANE-Accessions bleiben kalte DuckDB-Spalten, während nur Auswahl-Flags in das residente C-Modell eingehen. GENCODE-Basic- und Primary-Zugehörigkeit bleibt in transcript_flags für spätere Filterung erhalten; dieses Makro filtert das Modell nicht vorab auf eines der Sets. Die vorbereitete Sequenz enthält die phasenangepasste CDS plus die vollständige transkriptorientierte pre-CDS- und post-CDS-gespleißte Sequenz; das Legacy-Feld post_cds_bases bleibt als die ersten drei post-CDS-Basen. Codon-Tabellen-IDs kommen aus der Ensembl-Relation seq_region_attrib und defaulten genau wie VEP 116 auf Tabelle 1; jede von BioPerl/VEP unterstützte NCBI-Tabellen-ID wird akzeptiert, ungültige oder widersprüchliche Quellattribute lehnen den Import ab. Einzelrest-Edits initial_met, _selenocysteine, amino_acid_sub und _stop_codon_rt bleiben als dünnes Referenzpeptid-Overlay erhalten. Transkriptebene Sequenzkorrekturen, einschließlich eingefügter oder gelöschter Transkriptbasen relativ zum Genom, und andere Translation-SeqEdit-Formen scheitern geschlossen, indem die Sequenz mit einem expliziten Grund zurückgehalten wird. Transkriptzeilen bleiben spezifisch für den exakt ausgewählten Sequenzpfad, einschließlich getrennter X/Y-PAR- und Alternativ-Haplotyp-stabiler IDs. Das Makro klappt keine alt_allele-Äquivalenzgruppen zusammen, verwendet keine IS_PAR-Metadaten zum Zusammenführen von Consequence-Zeilen und hebt Transkripte nicht über einen zirkulären Sequenzursprung.
• duckvep_ensembl_regulation_features(funcgen_schema, regions_table): Erzeugt die VEP-116-kompatible Intervallrelation für Ensembl-RegulatoryFeature- und MotifFeature-Zeilen auf den für ein DuckVEP-Modell ausgewählten Sequenzregionen. funcgen_schema must contain regulatory_feature, feature_type, and motif_feature; regions_table is the output of duckvep_ensembl_regions(…). Matching VEP’s database and cache source, epigenetically_modified_region (EMAR) RegulatoryFeature rows are excluded before dense ordinals are assigned. The result maps source sequence-region IDs to model ordinals, validates one-based inclusive coordinates and source feature types, and preserves stable/source IDs, feature metadata, binding-matrix IDs, regulatory-build IDs, and motif scores as cold relation columns. feature_kind is the compact resident code: 1 regulatory region or 2 transcription-factor binding site. Pass the five hot columns regulation_feature_index, seq_region, feature_start, feature_end, and feature_kind to duckvep_model_load(interval_feature_query := …); the remaining columns stay relational for late projection.
• duckvep_model_receipt(regions_table, transcripts_table, source_name, source_version, assembly, source_manifest_sha256, reference_sha256, transcript_filter, regulation_features_table := NULL): Erzeugt eine deterministische Receipt für vorbereitete DuckVEP-Regions- und Transkriptrelationen plus eine optionale vorbereitete Regulation-Feature-Relation. Die ursprünglichen acht positionalen Argumente bleiben gültig. Wenn regulation_features_table namentlich übergeben wird, validiert die Receipt außerdem ihre dichten Ordinalzahlen, Regionsübereinstimmung, Intervallgeometrie und Feature-Arten; zählt regulatorische Regionen und Motiv-Features; und nimmt ihre fünf residenten Spalten in den Modell-Hash auf. Sie gibt die deklarierte Provenienz als source_name, source_version, assembly, source_manifest_sha256, reference_sha256 und transcript_filter zurück; zählt Transkript-, Sequenz-, reife-miRNA- und Peptid-Edit-Inhalt; und hasht jedes semantische Resident-Modellfeld in stabiler Ordinalreihenfolge. source_manifest_sha256 sollte ein kanonisches Manifest identifizieren, das jede exakte verwendete Core- und Funcgen-Eingabe enthält. Der deklarierte transcript_filter oder das Quellmanifest sollte außerdem festhalten, ob die Referenz nur Primary-Pfade enthält oder alternative/Patch-Pfade einschließt und ob assembly_exception-Vorverarbeitung angewendet wurde. Die Receipt enthält keine Uhrzeit, sodass identische Eingaben denselben Modell-Hash ergeben.
• duckvep_model_load(name, sequence_region_query, transcript_query, exon_query, mature_mirna_query := NULL, peptide_edit_query := NULL, interval_feature_query := NULL, reference_fasta := NULL, transcript_coverage_complete := FALSE): Lädt ein unveränderliches Consequence-Modell unter einem vom Aufrufer gewählten Namen in die aktuelle DuckDB-Datenbankinstanz. Der residente Kernel ist quellneutral: Aufrufer können jeden Transkriptkatalog vorbereiten, der diesen Modellvertrag erfüllt. Drei erforderliche Abfrage-Strings lesen committed, nicht-temporäre DuckDB-Relationen: sortierte UINTEGER-Sequenzregion-Ordinalzahlen; dichte Transkriptzeilen mit genomischer Spanne, Strang, Gen-Ordinal, Flags, optionaler CDS-Spanne/Sequenz/Codon-Tabelle; und transkriptgeordnete Exon-Zeilen mit genomischen und cDNA-Spannen plus Phase. Jede Exon-cDNA-Spanne muss in Transkriptreihenfolge zusammenhängend und gleich lang wie ihre genomische Exon-Spanne sein. Transkriptmodelle, die Basen relativ zum Genom einfügen oder löschen, benötigen daher ein zukünftiges explizites Mapping und werden von dieser Schnittstelle nicht akzeptiert. Die optionale mature_mirna_query liest transcript_index UINTEGER, mature_mirna_start UBIGINT und mature_mirna_end UBIGINT geordnet nach Transkript und Start. Die optionale peptide_edit_query liest transcript_index UINTEGER, protein_position UINTEGER und alternate_amino_acid VARCHAR eindeutig geordnet nach Transkript und Proteinposition. Die optionale interval_feature_query liest regulation_feature_index UINTEGER, seq_region UINTEGER, feature_start UINTEGER, feature_end UINTEGER und feature_kind UTINYINT geordnet nach Region, Start und Index; Art 1 ist RegulatoryFeature und Art 2 MotifFeature. Das Laden hält diese Hot-Spalten in einem kompakten SoA und baut einen separaten cgranges-Seed-Index, während Identifikatoren und Funcgen-Metadaten gewöhnliche DuckDB-Spalten bleiben. Die Transkriptprojektion akzeptiert 11 Basis-Spalten, 12 Spalten mit dem Legacy-post_cds_bases-BLOB von bis zu drei Basen oder 13 Spalten, die mit vollständigen transkriptorientierten pre_cds_sequence- und post_cds_sequence-BLOBs enden. Vollständige Flanken ermöglichen VEP-Start/Stop-Prädikate für längenändernde Edits, die einen CDS-Start oder -Ende kreuzen. reference_fasta ermöglicht referenzvalidiertes, VEP-artiges 3-Prime-HGVS-Shifting. Wenn übergeben, muss die Sequenzregion-Abfrage seq_region UINTEGER, sequence_length UBIGINT und seq_region_name VARCHAR zurückgeben; das Laden erfordert einen bestehenden FASTA-Index und prüft jeden deklarierten Namen und die exakte Länge, ohne den Index zu erzeugen oder zu ändern. Das benannte Modell pinnt offene Lese-Deskriptoren für die validierte FASTA, .fai und optionales .gzi. Linux-Worker öffnen diese Deskriptoren über /proc/self/fd erneut, Windows behält die aufgelöste Quelle unter Deny-Write-Sharing, und andere POSIX-Worker verwenden unabhängige aufgelöste Quell-Handles mit Identitätsprüfungen statt gemeinsamem /dev/fd-Seek-Zustand. Jeder Annotations-Worker besitzt sein veränderliches faidx-Handle, wiederverwendet enthaltene sortierte Referenzanfragen und lehnt erkennbare Ersetzung oder In-Place-Quellmutation um einen Cache-Miss-Fetch ab. Sequenzregion-Ordinalzahlen sind exakte Modellpfade: das Laden führt keine Contig-Synonym-, PAR-, Patch-, Haplotyp-, assembly_exception- oder Circular-Origin-Projektion aus. Aufrufer müssen jedes deklarierte Pfad-Mapping vor dem Laden oder Konstruieren von Ereignissen anwenden. Explizites NULL für jeden optionalen Abfrage- oder Referenzparameter entspricht dem Weglassen. Der Standard ist ein partielles Transkriptmodell: eine Variante ohne geladenes Transkript ist unresolved, nicht intergenic. Das Setzen von transcript_coverage_complete := TRUE erfordert sequence_length UBIGINT und erlaubt unterstützte intergene Ergebnisse nach Koordinatengrenzenprüfungen. Das Laden validiert und verengt das Modell einmal und gibt eine TRUE-Zeile zurück. Mehrere benannte Modelle können koexistieren.
• duckvep_model_drop(name): Entfernt ein benanntes resident DuckVEP-Consequence-Modell und gibt dessen Transkript- und Regulation-Feature-Intervallindizes, Sequenzen und gecachten Worker-Zustand frei. Gibt FALSE zurück, wenn der Name fehlt oder das Modell von einem Annotationsvektor verwendet wird.
• duckvep_allele_geometry(position, reference, alternate): Interpretiert ein literales biallelisches Allel mit derselben verlustfreien Geometrieautorität, die DuckVEP verwendet. position ist positiv und einsbasiert; REF und ALT sind nichtleere A/C/G/T/N-Strings von höchstens 65.535 Basen und müssen sich nach ASCII-Case-Folding unterscheiden. kind_code ist stabil: 0 SNV, 1 Insertion, 2 Deletion, 3 längenändernde Ersetzung und 4 Multi-Base-Substitution. anchor_side_code ist 0 für keinen behaltenen Anker, 1 für einen linken Anker und 2 für einen rechten Anker. Alle Koordinatenfelder sind nicht-null, nullbasierte halb-offene Intervalle außer insertion_boundary0, das nur bei einer Interbase-Insertion nicht-null ist. Differenz-Offsets und -Längen sind nicht-null Indizes in das hochgeladene REF und ALT. Das Ergebnis trennt die hochgeladene REF-Spanne, die VEP-116-VariationFeature-Spanne und die vollständig minimierte semantische Referenzbearbeitung. Eine reine Insertion hat gleichen Feature-/Edit-Start und -Ende plus insertion_boundary0. Diese Funktion splittet keine multiallelischen Records und richtet Allele nicht links aus: führen Sie duckhts_bcftools_norm(…, split_multiallelic := TRUE) zuerst aus, wenn kanonische exakte Schlüssel oder quellenübergreifende Joins Normalisierung erfordern. Verwenden Sie feature_start0/feature_end0 für VEP-Consequence-Feature-Überlappung, edit_start0/edit_end0 für Affected-Reference-Zusatzprovider und eine explizite Insertion-Flank-Policy, wenn interbase TRUE ist; die hochgeladene rohe REF-Spanne ist kein biologisch betroffenes Intervall.
• duckvep_annotate(events_table, model_name, hgvs := FALSE, upstream_distance := 5000, downstream_distance := 5000, rich := FALSE): Annotiert eine schmale kanonische Ereignisrelation gegen ein resident DuckVEP-Modell über eine schemafeste, pipe-freundliche Oberfläche. events_table benennt eine koordinatengeordnete Relation mit event_index UBIGINT, seq_region UINTEGER, positiver einsbasierter Position, reference VARCHAR, alternate VARCHAR, end_position UBIGINT, structural_type VARCHAR, copy_change VARCHAR, mate_seq_region UINTEGER und mate_position UBIGINT. Eine Zeile steht für ein ALT-Allel. Halten Sie Genotyp, Phase-Set, Konfidenzintervall, roh-ALT, Orientierung und andere Provenienz in der Quellrelation; joinen Sie ausgewählte Annotationen über event_index zurück, statt breite Payloads mit der Transkriptzahl zu multiplizieren. Literale Reference/Alternate-Zeilen sind Small Variants; ein typisiertes Ende/Spanne oder unterstütztes symbolisches ALT ist strukturell; ein vollständiges Mate-Koordinatenpaar ist ein Breakend. Widersprüchliche oder unvollständige Geometrie schlägt fehl statt geraten zu werden, einschließlich Uneinigkeit zwischen unterstütztem symbolischem ALT und expliziten structural_type-Werten. Für VCF-Span-SVs bereiten Sie position als POS + 1 nach Entfernen des linken Ankers vor; die Insertionsposition ist die Interbase-Stelle nach POS. DEL impliziert LOSS und DUP/TDUP implizieren GAIN, wenn copy_change NULL ist. Das Filtern des global koordinatengeordneten Ereignisstroms bewahrt die von jedem nativen Transkript- und Regulation-Feature-Sweep benötigte Reihenfolge; das Makro verbirgt keine Sortierung. Das event seq_region ist eine exakte Ordinalzahl im geladenen Modell; die Annotation entfernt keine Contig-Präfixe und projiziert keine PAR-, Patch-, Alternativ-Haplotyp- oder Circular-Origin-Koordinaten. X/Y-PAR- und Alternativpfad-Transkriptzeilen bleiben daher pfadspezifisch genau wie vorbereitet. Jedes Ereignis wird unabhängig annotiert: Genotyp- und Phase-Set-Spalten werden nicht zu Haplotypen kombiniert. Der stabile kompakte Vertrag umfasst SO/Regions-Masken, IMPACT/Status/Reason-Codes, einsbasierte cDNA/CDS/Protein-Positionen, Aminosäure-Bytes, NMD-Vorhersage/Escape-Codes und Overlap-Objekt-Ordinalzahlen. protein_position ist die betroffene einsbasierte Proteinrest-/Codon-Ordinalzahl, die von codon-level Evidence wie PS1/PM5 verwendet wird. rich := TRUE fügt Consequence, IMPACT, Region, Aminosäure, NMD, Overlap-Objekt, duckvep_status und duckvep_reason-Text aus demselben nativen Durchlauf hinzu und behält jedes kompakte Feld; FALSE oder explizites NULL lässt diese Präsentationsspalten NULL. hgvs := TRUE fusioniert ereignisunabhängige HGVSc/HGVSn/HGVSp in die Small-Variant-Spur, ohne die Kandidatensuche zu wiederholen; es komponiert mit rich := TRUE in einem Durchlauf; strukturelle und Breakend-HGVS bleiben NULL. DuckHTS-Audit-Status/Reason-Felder unterscheiden eine unaufgelöste Berechnung von einer tatsächlich fehlenden Consequence und sind keine Ensembl-CSQ-Felder. Null deaktiviert jedes gerichtete Transkriptfenster. Dekodieren Sie consequence_mask erst nach dem Filtern durch Join mit duckvep_so_terms(); joinen Sie transcript_index, gene_index oder regulation_feature_index an die vorbereiteten Modellrelationen für stabile Identifikatoren, Biotyp, MANE/GENCODE/CCDS-Flags und andere Präsentationsmetadaten. Diese typisierte Rich-Projektion beansprucht nicht das vollständige serialisierte VEP-CSQ-Vokabular: Exon/Intron-Ordinalzahlen, Codon-Strings, Distanztext, CANONICAL/APPRIS/TSL, existing variation und ergänzende Prädiktoren erfordern ihre deklarierten Modell- oder Annotationsrelationen.
• duckvep_so_terms(): Gibt die erzeugten Sequence-Ontology-Metadaten hinter den stabilen Consequence-Mask-Bits von DuckVEP zurück: Bit-Index, Einzelbit-Maske, Term, Impact-Code und -Label, VEP-Severity-Rang und Evaluator-Tier. Filter and aggregate compact annotation rows numerically first, then expand only selected mask bits with (annotation.consequence_mask & term.consequence_mask) <> 0. The relation is generated from the same pinned VEP-116 class-model metadata as the native consequence engine; it is not a second hand-maintained term inventory.

Reader

• read_bcf(path, region := NULL, index_path := NULL, tidy_format := FALSE, additional_csq_column_types := NULL, scan_mode := 'auto', decompression_threads := 0, decode_error_policy := 'null'): Liest VCF- und BCF-Variantendaten mit typisiertem INFO, FORMAT, typisierten CSQ/ANN/BCSQ-Unterfeldern, optionaler tidy Sample-Ausgabe, optionalen CSQ-Typüberschreibungen im bcftools-Stil, expliziter scan_mode-Steuerung (‘auto’ oder dateiweit ‘sequential’), optionalen htslib-Dekompressions-Worker-Threads über decompression_threads (Standard 0 für Single-Thread-Reads) und decode_error_policy (‘null’, ‘warn’ oder ‘error’) für korrupte BCF-Header-vs-Payload-Dekodierabweichungen. Kommagetrennte indizierte Regionen verwenden den nativen Multi-Region-Iterator von htslib und geben einen Record einmal aus, wenn angeforderte Regionen überlappen.
• read_bcf_v2(path, region := NULL, index_path := NULL, tidy_format := FALSE, additional_csq_column_types := NULL, scan_mode := 'auto', decompression_threads := 0, decode_error_policy := 'null', samples := NULL, samples_file := NULL, exclude_samples := NULL, exclude_samples_file := NULL, force_samples := FALSE, include_info := TRUE, include_format := TRUE, include_vep := TRUE, info_fields := NULL, format_fields := NULL, vep_fields := NULL): Experimenteller Klon von read_bcf(…) für zerstörungsfreies Benchmarking von Scan-Optimierungen des aktuellen Schemas. Sie bewahrt standardmäßig das weite/tidy Ausgabeschema von read_bcf, streamt Voll-Datei-Scans standardmäßig statt indizierte Contigs automatisch zu iterieren, akzeptiert denselben scan_mode- und decode_error_policy-Vertrag (‘null’, ‘warn’ oder ‘error’) wie read_bcf und teilt den nativen deduplizierenden Multi-Region-Iterator von read_bcf. Sie setzt htslib-VCF-Text max_unpack aus DuckDB-Projection-Pushdown, sodass nicht projizierter INFO/FORMAT-Text früher übersprungen werden kann, hält INFO/FORMAT/GT-Dekodierpuffer und geparste VEP/CSQ-Records im lokalen Scan-Zustand über Ausgabe-Chunks, wiederholt VEP-abgeleitete Werte korrekt über tidy Sample-Zeilen, unterstützt v2-only htslib-Sample-Pushdown über kommagetrennte samples/exclude_samples-Strings oder samples_file/exclude_samples_file-Listen, kann nur angeforderte INFO/FORMAT/VEP-Felder über include_info/include_format/include_vep und kommagetrennte info_fields/format_fields/vep_fields-Steuerungen binden, lehnt format_fields ab, wenn keine Samples ausgewählt sind, behandelt tidy_format := true mit include_format := false als eine Zeile pro Variante, weil keine SAMPLE_ID/FORMAT-Spalten gebunden sind, und zählt VCF-Textzeilen ohne Parsing, wenn keine Spalten projiziert werden.
• read_bcf_appender(path, target_table, region := NULL, tidy_format := TRUE, overwrite := TRUE, include_file_offset := FALSE, region_threads := 1, decompression_threads := 0, decode_error_policy := 'null'): Experimenteller nebenwirkender Benchmark-Helfer, der BCF/VCF mit htslib liest und eine schmale skalare tidy Tabelle über DuckDBs Chunk-Appender-API anhängt. Die Zieltabelle wird im Standardschema mit den Spalten CHROM, POS, REF, ALT, SAMPLE_ID und FORMAT_GT erzeugt; setzen Sie include_file_offset := TRUE, um FILE_OFFSET als Dateireihenfolge-Token hinzuzufügen. Kommagetrennte Regionen verwenden die nativen deduplizierenden Multi-Region-Iteratoren von htslib. region_threads steuert höchstens 16 Worker-Handles, die Primary-Contig-Jobs iterativ beanspruchen: jeder Contig behält seine vollständige angeforderte Intervallmenge in einem nativen Iterator, sodass wiederholte, überlappende oder record-überspannende Intervalle für jede Thread-Anzahl dasselbe Zielschema und dieselbe Zeilenmenge erzeugen. Die Header-Contig-Zahl erzeugt keine Worker-Threads und öffnet keine Handles, und eine auf einen Contig beschränkte Anfrage verwendet einen Iterator. Parallele Zeilenankunft ist ungeordnet; verwenden Sie ORDER BY FILE_OFFSET, wenn die Dateireihenfolge zählt. decompression_threads konfiguriert htslib-Worker pro offenem Region-Worker-Handle, sodass die Gesamtzahl der Helfer-Threads als Region-Worker mal Dekompressions-Worker skaliert. Die Operation läuft in einer internen Transaktion und meldet fehlerhafte Records als DuckDB-Fehler; decode_error_policy steuert korrupte BCF-FORMAT/GT-Header-vs-Payload-Abweichungen mit ‘null’, ‘warn’ oder ‘error’. target_table muss ein unqualifizierter SQL-Identifikator sein. Dies dient dem Vergleich appender-basierter Materialisierung mit read_bcf(…)-Abfragepipelines, nicht als vollständiger Ersatz für die typisierte read_bcf-Oberfläche.
• read_bam(path, standard_tags := FALSE, auxiliary_tags := FALSE, region := NULL, index_path := NULL, reference := NULL, sequence_encoding := 'string', quality_representation := 'string', cigar_representation := 'string', scan_mode := 'auto', decompression_threads := 2): Liest SAM-, BAM- und CRAM-Alignments mit optionalen typisierten SAMtags und Hilfs-Tag-Maps. Verwenden Sie sequence_encoding := ‘nt16’, um SEQ als UTINYINT[] zurückzugeben, quality_representation := ‘phred’, um QUAL als UTINYINT[] zurückzugeben, und cigar_representation := ‘binary’, um gepackte BAM-CIGAR-Operationen als UINTEGER[] statt SAM-Text zurückzugeben. scan_mode := ‘sequential’ erzwingt einen vollständigen Datei-Streaming-Scan statt indexgestützter Count-/Parallelpfade und ist mit region inkompatibel. decompression_threads steuert htslib-Worker-Threads pro Datei und ist standardmäßig 2; verwenden Sie 0, um Worker-Threads zu deaktivieren.
• read_fasta(path, region := NULL, index_path := NULL, gzi_path := NULL, sequence_encoding := 'string', scan_mode := 'auto'): Liest FASTA-Records oder indizierte FASTA-Regionen als Sequenzzeilen. Verwenden Sie sequence_encoding := ‘nt16’, um SEQUENCE als UTINYINT[] (htslib-nt16-4-Bit-Codes) statt VARCHAR zurückzugeben. Bei bgzip-komprimierter FASTA kann gzi_path auf eine explizite .gzi-Sidecar zeigen, wenn sie nicht neben der FASTA liegt. scan_mode := ‘sequential’ erzwingt vollständiges Datei-Streaming/Zählen statt indexgestützter Count-Pfade und ist mit region inkompatibel.
• read_bed(path, region := NULL, index_path := NULL, scan_mode := 'auto'): Liest BED3–BED12-Intervalldateien mit kanonischen typisierten Spalten und optionaler tabix-gestützter Regionsfilterung. scan_mode := ‘sequential’ erzwingt vollständiges Datei-Streaming/Zählen statt indexgestützter Count-Pfade und ist mit region inkompatibel.
• fasta_nuc(path, bed_path := NULL, bin_width := NULL, region := NULL, index_path := NULL, gzi_path := NULL, bed_index_path := NULL, include_seq := FALSE): Berechnet die Nukleotidzusammensetzung im bedtools-nuc-Stil für übergebene BED-Intervalle oder erzeugte Festbreiten-Bins über eine FASTA-Referenz. Bei bgzip-komprimierter FASTA kann gzi_path auf eine explizite .gzi-Sidecar zeigen, wenn sie nicht neben der FASTA liegt.
• read_fastq(path, interleaved := FALSE, mate_path := NULL, sequence_encoding := 'string', quality_representation := 'string', input_quality_encoding := 'phred33', scan_mode := 'auto'): Liest Single-End-, Paired-End- oder interleaved FASTQ-Dateien mit optionaler Legacy-Qualitätsdekodierung. Standardmäßig werden FASTQ-Qualitäten als modernes Phred+33-Eingabe interpretiert. Verwenden Sie sequence_encoding := ‘nt16’, um SEQUENCE als UTINYINT[] zurückzugeben, und quality_representation := ‘phred’, um QUALITY als UTINYINT[] statt VARCHAR zurückzugeben. input_quality_encoding akzeptiert ‘phred33’, ‘auto’, ‘phred64’ oder ‘solexa64’. scan_mode := ‘sequential’ erzwingt rohes Streaming/Zählen statt indexgestützter Count-Pfade.
• read_bigwig(path, region := NULL, blocks_per_iteration := 64): Liest gespeicherte BigWig-Signalintervalle als CHROM, START0, END0 und VALUE. Koordinaten sind nullbasiert halb-offen. region verwendet die einsbasierte inklusive Syntax von htslib; kommagetrennte Anfragen werden pro Contig zusammengeführt und geben jedes gespeicherte Intervall einmal aus. Vollständige Scans beanspruchen nichtleere Contigs über DuckDB-Worker, und Multi-Region-Scans beanspruchen zusammengeführte Bereiche. Jeder Worker besitzt sein veränderliches Datei-Handle und seinen Iterator. blocks_per_iteration steuert das libBigWig-Iterator-Batching, nicht die Anzahl der DuckDB-Worker. Lokale, native Remote- und Browser-wasm-Reads nutzen alle den htslib-hFILE-Transport von DuckHTS statt eines zweiten libcurl-Stacks.
• read_gff(path, header_names := NULL, header := FALSE, column_types := NULL, auto_detect := FALSE, attributes_map := FALSE, attributes_list := FALSE, attributes_pairs := FALSE, strict := FALSE, region := NULL, index_path := NULL, scan_mode := 'auto'): Liest GFF-Annotationen mit optionalen rohen Skalar- und reicheren Listen-/Paar-geparsten Attributspalten, strikter GFF3-Strukturvalidierung und indizierter Regionsfilterung. Kommagetrennte indizierte Regionen verwenden den nativen Multi-Region-Iterator von htslib und geben eine Zeile einmal aus, wenn angeforderte Regionen überlappen. scan_mode := ‘sequential’ erzwingt vollständiges Datei-Streaming/Zählen statt indexgestützter Count-Pfade und ist mit region inkompatibel.
• read_gtf(path, header_names := NULL, header := FALSE, column_types := NULL, auto_detect := FALSE, attributes_map := FALSE, attributes_list := FALSE, attributes_pairs := FALSE, region := NULL, index_path := NULL, scan_mode := 'auto'): Liest GTF-Annotationen mit optionalen rohen Skalar- und reicheren Listen-/Paar-geparsten Attributspalten und indizierter Regionsfilterung. Kommagetrennte indizierte Regionen verwenden den nativen Multi-Region-Iterator von htslib und geben eine Zeile einmal aus, wenn angeforderte Regionen überlappen. scan_mode := ‘sequential’ erzwingt vollständiges Datei-Streaming/Zählen statt indexgestützter Count-Pfade und ist mit region inkompatibel.
• read_tabix(path, header_names := NULL, header := FALSE, column_types := NULL, auto_detect := FALSE, region := NULL, index_path := NULL, scan_mode := 'auto'): Liest generische tabix-indizierte Textdaten mit optionaler Header-Behandlung und Typinferenz. Kommagetrennte indizierte Regionen verwenden den nativen Multi-Region-Iterator von htslib und geben eine Zeile einmal aus, wenn angeforderte Regionen überlappen. scan_mode := ‘sequential’ erzwingt vollständiges Datei-Streaming/Zählen statt indexgestützter Count-Pfade und ist mit region inkompatibel.
• fasta_index(path, index_path := NULL): Erzeugt einen FASTA-Index (.fai) und gibt eine einzelne Zeile mit den Spalten success (BOOLEAN) und index_path (VARCHAR) zurück.
• hts_union_query(reader, pattern, params := ''): Erzeugt einen UNION-ALL-BY-NAME-Abfrage-String, der jede zu einem Glob-Muster passende Datei über die benannte Reader-Funktion liest. The result includes a ‘filename’ column identifying the source file for each row. Assign to a variable with SET VARIABLE and execute via query(getvariable(…)). Optional params string is appended to each reader call. In R, use the typed rduckhts_*_multi() helpers instead, which accept file vectors with optional per-file parameters and create DuckDB tables directly.
• hts_region_union_query(reader, path, regions, params := ''): Erzeugt einen UNION-ALL-BY-NAME-Abfrage-String, der eine HTS-Datei über getrennte Tabellenfunktions-Scans pro Region liest. The result adds filename, duckhts_region_shard_id, and duckhts_region_shard columns so benchmark queries can compare region-sharded execution and explicit ordered writes. Pass regions as a DuckDB list of region strings; params is appended to each reader call and should not include region. The generated UNION ALL does not deduplicate records; adjacent or overlapping shards can duplicate BAM alignments or BCF/VCF records that span shard boundaries, so add explicit shard-local filters or downstream deduplication when exact once-only semantics are required.

Konverter

• duckhts_bcf_convert_parquet_sql(path, output, columns := []::VARCHAR[], region := NULL, index_path := NULL, tidy_format := FALSE, additional_csq_column_types := NULL, decompression_threads := 0, where_sql := NULL, compression := 'zstd', row_group_size := 100000, partition_by := []::VARCHAR[], include_metadata := TRUE, header_text := NULL, metadata := map([]::VARCHAR[], []::VARCHAR[]), metadata_json_file := NULL, overwrite := FALSE, write_format_version := '1'): Erzeugt eine DuckDB-COPY-Anweisung, die read_bcf(…) Ausgabe nach Parquet mit DuckHTS-Schlüssel-Wert-Metadaten, erhaltenem oder korrigiertem VCF header text, Benutzermetadaten aus metadata := map(…), ausgewählten Spalten, Filtern und Partitionsspalten konvertiert. Optionales metadata_json_file wird vom Aufrufer verwaltet und erfordert, dass die json-Erweiterung von DuckDB beim Aufruf des Builders verfügbar ist; verwenden Sie Metadata-Maps für CRAN-/offline-sichere Workflows. Clients führen den zurückgegebenen SQL-String aus; der R-Wrapper ist ein dünner DBI-Helfer, der diese Ausführung übernimmt.
• duckhts_bam_convert_parquet_sql(path, output, columns := []::VARCHAR[], region := NULL, index_path := NULL, reference := NULL, standard_tags := FALSE, auxiliary_tags := FALSE, sequence_encoding := NULL, quality_representation := NULL, cigar_representation := NULL, decompression_threads := 2, where_sql := NULL, compression := 'zstd', row_group_size := 100000, partition_by := []::VARCHAR[], include_metadata := TRUE, header_text := NULL, metadata := map([]::VARCHAR[], []::VARCHAR[]), metadata_json_file := NULL, overwrite := FALSE, write_format_version := '1'): Erzeugt eine DuckDB-COPY-Anweisung, die read_bam(…) Ausgabe nach Parquet mit DuckHTS-Schlüssel-Wert-Metadaten, erhaltenem oder korrigiertem SAM header text, Benutzermetadaten aus metadata := map(…), ausgewählten Spalten, Filtern und Partitionsspalten konvertiert. Optionales metadata_json_file wird vom Aufrufer verwaltet und erfordert, dass die json-Erweiterung von DuckDB beim Aufruf des Builders verfügbar ist; verwenden Sie Metadata-Maps für CRAN-/offline-sichere Workflows. Clients führen den zurückgegebenen SQL-String aus; der R-Wrapper ist ein dünner DBI-Helfer, der diese Ausführung übernimmt.
• duckhts_gff_convert_parquet_sql(path, output, columns := []::VARCHAR[], region := NULL, index_path := NULL, header := NULL, header_names := []::VARCHAR[], auto_detect := NULL, column_types := []::VARCHAR[], attributes_map := FALSE, attributes_list := FALSE, attributes_pairs := FALSE, strict := FALSE, where_sql := NULL, compression := 'zstd', row_group_size := 100000, partition_by := []::VARCHAR[], include_metadata := TRUE, header_text := NULL, metadata := map([]::VARCHAR[], []::VARCHAR[]), metadata_json_file := NULL, overwrite := FALSE, write_format_version := '1'): Erzeugt eine DuckDB-COPY-Anweisung, die read_gff(…) Ausgabe nach Parquet mit DuckHTS-Schlüssel-Wert-Metadaten, erhaltenem oder korrigiertem GFF/tabix header text, Benutzermetadaten aus metadata := map(…), ausgewählten Spalten, Filtern und Partitionsspalten konvertiert. Optionales metadata_json_file wird vom Aufrufer verwaltet und erfordert, dass die json-Erweiterung von DuckDB beim Aufruf des Builders verfügbar ist; verwenden Sie Metadata-Maps für CRAN-/offline-sichere Workflows. Clients führen den zurückgegebenen SQL-String aus; der R-Wrapper ist ein dünner DBI-Helfer, der diese Ausführung übernimmt.
• duckhts_tabix_convert_parquet_sql(path, output, columns := []::VARCHAR[], region := NULL, index_path := NULL, header := NULL, header_names := []::VARCHAR[], auto_detect := NULL, column_types := []::VARCHAR[], where_sql := NULL, compression := 'zstd', row_group_size := 100000, partition_by := []::VARCHAR[], include_metadata := TRUE, header_text := NULL, metadata := map([]::VARCHAR[], []::VARCHAR[]), metadata_json_file := NULL, overwrite := FALSE, write_format_version := '1'): Erzeugt eine DuckDB-COPY-Anweisung, die read_tabix(…) Ausgabe nach Parquet mit DuckHTS-Schlüssel-Wert-Metadaten, erhaltenem oder korrigiertem tabix header text, Benutzermetadaten aus metadata := map(…), ausgewählten Spalten, Filtern und Partitionsspalten konvertiert. Optionales metadata_json_file wird vom Aufrufer verwaltet und erfordert, dass die json-Erweiterung von DuckDB beim Aufruf des Builders verfügbar ist; verwenden Sie Metadata-Maps für CRAN-/offline-sichere Workflows. Clients führen den zurückgegebenen SQL-String aus; der R-Wrapper ist ein dünner DBI-Helfer, der diese Ausführung übernimmt.

Coverage

• read_pileup(path, region := NULL, index_path := NULL, min_mapq := 0, flag_mask := 1796): Erzeugt ein regionsbezogenes BAM-Pileup mit einer Zeile pro abgedeckter Position und gibt chrom, einsbasierte Position, Tiefe, beobachtete Basen und Phred+33-Qualitäten nach SAM-Flag- und MAPQ-Filterung aus. This is a compact htslib pileup view, not samtools mpileup text parity.
• bam_bin_counts(path, bin_width, chrom := NULL, reference := NULL, index_path := NULL, mapq := 0, require_flags := 0, exclude_flags := 0, rmdup := 'none', stats := NULL): Zählt BAM- oder CRAM-Read-Starts in Festbreiten-Bins. Returns one row per bin across the selected contig span, including zero-count bins, with total, forward, and reverse counts; rmdup := 'streaming' applies the WisecondorX-style larp/larp2 consecutive-position deduplication, rmdup := 'flag' drops SAM duplicate-flagged reads, and stats := 'gc', 'mq', or 'gc,mq' adds per-bin pre/post-filter GC and MAPQ sufficient statistics, including reference GC when reference is provided.
• duckhts_bam_bed_coverage(path, bed_path, reference := NULL, index_path := NULL, bed_index_path := NULL, mapq := 0, min_baseq := 0, min_read_len := 0, require_flags := 0, exclude_flags := 1796, min_depth := 1, max_depth := 1000000, decompression_threads := 0, fragment_mode := FALSE, strand_outputs := TRUE, processing_threads := 0): Berechnet samtools-coverage-artige regionale Zusammenfassungen für BAM- oder CRAM-Eingabe über ein BED-Zielset und gibt eine Zeile pro BED-Intervall mit DuckHTS-spezifischen Pre-/Post-Filter-Read-Zählungen, abgedeckten Basen, Abdeckungsprozentsatz, mittlerer Tiefe, mittlerer baseQ, mittlerer mapQ und strangspezifischen Post-Filter-Zusammenfassungen im Read-Modus zurück. Indexed BAM/CRAM input is required in the current implementation. decompression_threads controls htslib worker threads for BAM/CRAM decoding; use 0 to disable them.
• duckhts_mosdepth(prefix, path, chrom := NULL, by := NULL, fasta := NULL, read_groups := NULL, no_per_base := FALSE, threads := 2, processing_threads := 2, flag := 1796, include_flag := 0, fast_mode := FALSE, fragment_mode := FALSE, use_median := FALSE, mapq := 0, min_frag_len := -1, max_frag_len := -1, precision_digits := 2, quantize := NULL, thresholds := NULL, index_path := NULL, overwrite := FALSE): Schreibt native mosdepth-kompatible Coverage-Ausgaben für indizierte BAM- oder CRAM-Eingabe. Produces mosdepth-style summary, global distribution, per-base BED.gz + CSI, optional window/BED region outputs, optional quantized BED.gz + CSI, and optional threshold counts for by; fast_mode defaults to FALSE to match upstream mosdepth, default mode performs CIGAR-aware coverage with mate-overlap correction, fragment_mode switches coverage to full-fragment insert spans for proper pairs, use_median switches by outputs from mean to median, read_groups filters by comma-separated RG IDs, min_frag_len and max_frag_len filter on absolute template length, fasta is required for CRAM when htslib needs a reference, precision_digits controls decimal places in the text outputs, and processing_threads enables parallel contig processing (0 = sequential, >0 = number of worker threads).

Intervalle

• duckhts_cgranges_create(name): Erzeugt einen leeren sitzungsbezogenen cgranges-Registry-Eintrag, der mit Intervallen gefüllt und für Überlappungsabfragen finalisiert werden kann.
• duckhts_cgranges_add(name, chrom, start, end[, label]): Hängt ein Intervall an einen sitzungsbezogenen cgranges-Registry-Eintrag vor der Finalisierung an. Labels may be BIGINT-like, DOUBLE, VARCHAR, or BOOLEAN.
• duckhts_cgranges_index(name): Finalisiert einen gefüllten cgranges-Registry-Eintrag und erzeugt seinen unveränderlichen Überlappungsindex für nachfolgende Abfragen.
• duckhts_cgranges_destroy(name): Zerstört einen sitzungsbezogenen cgranges-Registry-Eintrag und gibt seinen indizierten Intervallspeicher frei, wenn er nicht aktiv genutzt wird.
• duckhts_cgranges_from_query(name, query, chrom_col, start_col, end_col[, label_col]): Führt eine SQL-Abfrage auf einer erweiterungseigenen DuckDB-Connection aus, hängt ihre Intervallzeilen an einen sitzungsbezogenen cgranges-Registry-Eintrag an und lässt den gefüllten Index für die explizite Finalisierung mit duckhts_cgranges_index(…) bereit.
• duckhts_cgranges_from_table(name, table_name, chrom_col, start_col, end_col[, label_col]): Reservierter Komfortkonstruktor für die Massenbefüllung von cgranges aus einem Tabellennamen. The current implementation is intentionally deferred and directs callers to duckhts_cgranges_from_query(…).
• duckhts_cgranges_has_overlap(name, chrom, start, end[, mode]): Vektorisiertes Skalarprädikat, um Provider-Zeilen durch einen finalisierten sitzungsbezogenen cgranges-Index zu streamen. Returns TRUE when the query interval overlaps at least one indexed interval, or when mode = ‘contain’ and it fully contains at least one indexed interval; NULL inputs return NULL.
• duckhts_cgranges_count_overlaps(name, chrom, start, end[, mode]): Vektorisierter Skalar-Überlappungszähler, um Provider-Zeilen durch einen finalisierten sitzungsbezogenen cgranges-Index zu streamen. Returns the number of indexed intervals that overlap the query interval, or with mode = ‘contain’ the number fully contained by it; NULL inputs return NULL.
• duckhts_cgranges_overlaps_list(name, chrom, start, end[, mode]): Vektorisierter Skalar-Überlappungsexpander, um Provider-Zeilen durch einen finalisierten sitzungsbezogenen cgranges-Index zu streamen. Returns a LIST of hit STRUCTs that can be expanded with UNNEST, preserving provider columns while emitting one row per matching indexed interval. Because scalar return types are fixed, labels are returned as text with label_type describing the original cgranges label kind; NULL inputs return NULL.
• duckhts_cgranges_overlaps(name, chrom, start, end, mode := 'overlap', query_row_id := NULL): Fragt einen finalisierten sitzungsbezogenen cgranges-Registry-Eintrag ab und gibt eine Zeile pro überlappendem oder enthaltendem indiziertem Intervall zurück, wobei der ursprüngliche Label-Typ und die Intervallkoordinaten erhalten bleiben.
• duckhts_cgranges_overlaps_bulk(name, query, chrom_col, start_col, end_col, mode := 'overlap', query_row_id_col := NULL): Run a SQL query that yields overlap probes, stream those rows through a finalized session-scoped cgranges registry entry, and return one row per matching indexed interval. The probe query runs on the extension-owned helper connection, so it must reference regular tables/views rather than connection-local temp tables. When query_row_id_col is omitted, query_row_id defaults to the 1-based probe row ordinal.
• regionkey(chrom, start, end, strand := 0): Kodiert ein genomisches Intervall als offiziellen RegionKey-kompatiblen 64-Bit-Integer ohne Vorzeichen. Start and end use 0-based half-open interval semantics, matching BED-style coordinates; strand accepts -1, 0, or 1.
• regionkey_hex(rk): Stellt einen RegionKey als seine 16-stellige hexadezimale Kleinschreibung dar.
• parse_regionkey_hex(hex): Parst einen 16-stelligen hexadezimalen RegionKey-String zurück in seinen UBIGINT-Code. Invalid or non-hex strings return NULL.
• encode_regionkey(chrom_code, start, end, strand_code): Kodiert die rohen Upstream-RegionKey-Felder direkt: Chromosom-Code, nullbasierter Start, nullbasiertes Ende und Strang-Code (0 = unbekannt, 1 = +, 2 = -).
• extract_regionkey_chrom(rk): Extrahiert den rohen Upstream-RegionKey-Chromosom-Code.
• extract_regionkey_startpos(rk): Extrahiert die rohe Upstream-RegionKey-nullbasierte Startposition.
• extract_regionkey_endpos(rk): Extrahiert die rohe Upstream-RegionKey-nullbasierte Endposition.
• extract_regionkey_strand(rk): Extrahiert den rohen Upstream-RegionKey-Strang-Code (0 = unbekannt, 1 = +, 2 = -).
• decode_regionkey(rk): Dekodiert einen RegionKey in seine rohen Upstream-Numerischen Felder: chrom_code, start, end und strand_code.
• reverse_regionkey(rk): Dekodiert einen RegionKey in ein STRUCT mit chrom, chrom_code, start, end, strand und strand_code.
• extend_regionkey(rk, size): Erweitert ein RegionKey-Intervall um eine feste Anzahl Basen auf beiden Seiten und klemmt auf den offiziellen 28-Bit-RegionKey-Positionsbereich.
• are_overlapping_regions(chrom_a, start_a, end_a, chrom_b, start_b, end_b): Gibt TRUE zurück, wenn zwei explizite nullbasierte halb-offene Intervalle auf demselben kanonischen Chromosom überlappen.
• are_overlapping_region_regionkey(chrom, start, end, rk): Gibt TRUE zurück, wenn ein nullbasiertes halb-offenes Intervall das übergebene RegionKey-Intervall überlappt.
• are_overlapping_regionkeys(rka, rkb): Gibt TRUE zurück, wenn zwei RegionKeys überlappen.

Qualitätskontrolle

• duckhts_fastq_qc(sequence, quality [, max_cycles]): Aggregate canonical sequence and Phred+33 quality strings directly into exact read/base/Q20/Q30/Q40, nucleotide, quality-sum, and per-cycle sufficient statistics. The nested cycles list supports mean-quality, nucleotide-content, GC, and read-length curves without expanding one SQL row per base. Rows with any NULL input are ignored. Per-cycle state defaults to at most 1,048,576 cycles; pass a constant max_cycles per aggregate group to choose a larger explicit limit, up to 16,777,216.

Metadaten

• detect_quality_encoding(path, max_records := 10000): Inspiziert den beobachteten Qualitäts-ASCII-Bereich einer FASTQ-Datei und meldet kompatible Legacy-Kodierungen mit einer heuristisch geratenen Kodierung.
• duckhts_samtools_idxstats(path, output := NULL, index_path := NULL, threads := 0, overwrite := FALSE): Schreibt samtools-idxstats-kompatible TAB-getrennte Ausgabe für BAM-, CRAM- oder SAM-Eingabe. Indexed BAM uses hts_idx_get_stat(...) for the fast path; CRAM, SAM, and unindexed BAM fall back to a full scan while preserving samtools-style contig rows plus the final * row.
• read_hts_header(path, format := NULL, mode := NULL): Inspiziert HTS-Header in geparster, roher oder kombinierter Form über unterstützte Formate. Raw VCF/BCF mode includes the final #CHROM sample header line so the returned text is suitable for Parquet metadata and future VCF/BCF regeneration.
• read_hts_index(path, format := NULL, index_path := NULL): Inspiziert übergeordnete HTS-Index-Metadaten wie Sequenznamen und Mapped-Zählungen.
• read_hts_index_spans(path, format := NULL, index_path := NULL): Expandiert Index-Metadaten in Span- und Chunk-Zeilen, geeignet für Low-Level-Indexinspektion.
• read_hts_index_raw(path, format := NULL, index_path := NULL): Gibt den rohen On-Disk-HTS-Index-Blob zusammen mit grundlegenden identifizierenden Metadaten zurück.

Kompression

• bgzip(path, output_path := NULL, threads := 4, level := -1, keep := TRUE, overwrite := FALSE): Komprimiert eine Klartextdatei nach BGZF und gibt den erzeugten Ausgabepfad und die Bytezahlen zurück.
• bgunzip(path, output_path := NULL, threads := 4, keep := TRUE, overwrite := FALSE): Dekomprimiert eine BGZF-komprimierte Datei und gibt den erzeugten Ausgabepfad und die Bytezahlen zurück.

Indexierung

• bam_index(path, index_path := NULL, min_shift := 0, threads := 4): Erzeugt einen BAM- oder CRAM-Index und meldet den geschriebenen Indexpfad und das Format.
• bcf_index(path, index_path := NULL, min_shift := NULL, threads := 4): Erzeugt einen TBI- oder CSI-Index für eine VCF- oder BCF-Datei und meldet den geschriebenen Indexpfad und das Format.
• tabix_index(path, preset := 'vcf', index_path := NULL, min_shift := 0, threads := 4, seq_col := NULL, start_col := NULL, end_col := NULL, comment_char := NULL, skip_lines := NULL): Erzeugt einen Tabix-Index für eine BGZF-komprimierte Textdatei anhand eines Presets oder expliziter Koordinatenspalten.

Varianten

• variantkey(chrom, pos, ref, alt): Kodiert eine normalisierte biallelische Variante als offiziellen VariantKey-kompatiblen 64-Bit-Integer ohne Vorzeichen. This DuckHTS wrapper accepts 1-based VCF/DuckHTS POS to match bcftools %VKX / +add-variantkey, internally converts to the upstream 0-based field, and preserves the official hashed nonreversible mode for large, ambiguous, and symbolic REF/ALT strings. Only CHROM, POS, REF, and ALT are encoded; END, SVLEN, mate breakend coordinates, and other SV metadata are not.
• variantkey_hex(vk): Stellt einen VariantKey als seine 16-stellige hexadezimale Kleinschreibung dar.
• parse_variantkey_hex(hex): Parst einen 16-stelligen hexadezimalen VariantKey-String zurück in seinen UBIGINT-Code. Invalid or non-hex strings return NULL.
• encode_variantkey(chrom_code, pos0, refalt_code): Kodiert die rohen Upstream-VariantKey-Felder direkt: Chromosom-Code, nullbasierte Position und 31-Bit-REF+ALT-Code.
• extract_variantkey_chrom(vk): Extrahiert den rohen Upstream-VariantKey-Chromosom-Code.
• extract_variantkey_pos(vk): Extrahiert das rohe Upstream-VariantKey-nullbasierte Positionsfeld.
• extract_variantkey_refalt(vk): Extrahiert den rohen Upstream-31-Bit-VariantKey-REF+ALT-Code.
• decode_variantkey(vk): Dekodiert einen VariantKey in seine rohen Upstream-Numerischen Felder: chrom_code, pos0 und refalt_code.
• reverse_variantkey(vk): Dekodiert einen VariantKey in ein STRUCT mit chrom, chrom_code, einsbasiertem pos, Upstream-nullbasiertem pos0, ref, alt, refalt_code und reversible. For hashed nonreversible keys, reversible is FALSE and ref/alt are returned as NULL because DuckHTS v1 does not ship the optional NRVK lookup sidecar.
• variantkey_range(chrom, pos_min, pos_max): Gibt die inklusiven minimalen und maximalen VariantKey-Grenzen für ein Chromosom plus einsbasierten VCF-Positionsbereich zurück, geeignet für numerische Bereichsfilterung auf vorberechneten VariantKeys.
• duckhts_contig_key(contig): Gibt einen konservativen Contig-Join-Schlüssel zurück, indem ein nichtleeres führendes chr-Präfix ohne Beachtung der Groß-/Kleinschreibung entfernt und M/MT nach MT normalisiert wird. X and Y are uppercased; all other suffixes are preserved. This does not map numeric sex chromosomes, accessions, patches, or alternate loci.
• bcftools_liftover(chrom, pos, ref, alt, chain_path, dst_fasta_ref, src_fasta_ref, max_snp_gap, max_indel_inc, lift_mt, end_pos, no_left_align): Row-oriented liftover kernel intended to mirror bcftools +liftover semantics as closely as possible while returning one STRUCT per input row with fields: src_chrom, src_pos, src_ref, src_alt, dest_chrom, dest_pos, dest_end, dest_ref, dest_alt, mapped, reverse_complemented, swap, reject_reason, and note. Set no_left_align := true to skip post-liftover left-alignment of lifted indels (mirrors –no-left-align in bcftools +liftover).
• duckdb_liftover(table_name, chrom_col, pos_col, ref_col := NULL, alt_col := NULL, chain_path := NULL, dst_fasta_ref := NULL, src_fasta_ref := NULL, max_snp_gap := 1, max_indel_inc := 250, lift_mt := false, end_pos_col := NULL, no_left_align := false): DuckDB-specific wrapper over bcftools_liftover that takes either a table name or a derived-table expression plus column-name strings for chrom/pos/ref/alt and returns the lifted table. The no_left_align parameter mirrors –no-left-align in bcftools +liftover.
• bcftools_norm_row(chrom, pos, ref, alt, fasta_ref, end_pos := NULL, svlen := NULL, fasta_index_path := NULL, gzi_path := NULL): Normalisiert eine Variantenzeile mit Left-Alignment-Semantik im bcftools/vt-Stil gegen eine FASTA-Referenz. The alt argument may be either a comma-delimited VARCHAR or a VARCHAR[] list. The returned STRUCT contains pos_normed, end_pos_normed, ref_normed, alt_normed (always VARCHAR[]), normed (TRUE/FALSE/NULL), and norm_status. Symbolic rows can use end_pos, and symbolic rows can use svlen. gVCF <NON_REF>/<*> reference-block alleles pass through with GVCFReferenceBlock, and mixed real-plus-gVCF-symbolic alleles normalize the real alleles while preserving symbolic alleles and caller-supplied reference-block END in site-preserving output.
• duckhts_bcftools_norm(table_name, fasta_ref, chrom_col := 'chrom', pos_col := 'pos', ref_col := 'ref', alt_col := 'alt', split_multiallelic := FALSE, end_pos_col := NULL, svlen_col := NULL, fasta_index_path := NULL, gzi_path := NULL): DuckDB table macro wrapper over bcftools_norm_row that normalizes variants from a table or derived-table expression while preserving the original columns. The input ALT column may be either VARCHAR or VARCHAR[]. The result appends pos_normed, end_pos_normed, ref_normed, alt_normed, normed, and norm_status; with split_multiallelic := TRUE, multiallelic sites are split before normalization and alt_normed becomes VARCHAR plus alt_index. This is a vt/vcfnorm-style row/table transform, not a full-record VCF/BCF rewrite: genotype, PL/GP/DS, and PS fields are preserved as caller columns unless a separate full-record writer/remapper layer is used.
• bcftools_score(bcf_path, summary_path_or_list, use := NULL, columns := 'PLINK', columns_file := NULL, q_score_thr := NULL, summaries_list_file := NULL, log_path := NULL, use_variant_id := FALSE, counts := FALSE, samples := NULL, force_samples := FALSE, regions := NULL, regions_file := NULL, regions_overlap := 1, targets := NULL, targets_file := NULL, targets_overlap := 0, apply_filters := NULL, include := NULL, exclude := NULL): Berechnet polygene Scores aus einem Genotyp-BCF/VCF und einer oder mehreren Summary-Statistics-Dateien mit bcftools-+score-kompatibler GT/DS/HDS/AP/GP/AS-Dosage-Semantik, Sample-Subsetting und Region-/Target-/FILTER-String-Steuerung. The second argument accepts a scalar path or a DuckDB LIST/array of paths; TSV/SSF summaries produce one PRS column per file in a single genotype scan, while GWAS-VCF summaries still produce one PRS column per FORMAT sample. Use summaries_list_file with a NULL second argument to read paths from a file or directory; list-file entries are interpreted as written, matching upstream bcftools +score --summaries behavior, while directory inputs scan supported regular summary files in lexicographic order and ignore index sidecars. Use log_path to write per-PRS loaded/matched/allele-mismatch/duplicate-marker audit counts.
• bcftools_munge_row(chrom, pos, a1, a2, id, p, z, or, beta, n, n_cas, n_con, info, frq, se, lp, ac, neff, neffdiv2, het_i2, het_p, het_lp, dire, fasta_ref, iffy_tag := 'IFFY', mismatch_tag := 'REF_MISMATCH', ns := NULL, nc := NULL, ne := NULL): Normalisiert eine Summary-Statistics-Zeile in GWAS-VCF-artige Felder (chrom/pos/ref/alt/Effektmetriken), löst die REF/ALT-Orientierung gegen eine FASTA-Referenz auf und wendet swap-bewusste Vorzeichen-/Frequenz-/Zähltransformationen an. The output flag alleles_swapped means REF/ALT orientation was swapped to match the FASTA reference.
• duckdb_munge(table_name, preset := '', column_map := map([''], ['']), column_map_file := '', fasta_ref := NULL, iffy_tag := 'IFFY', mismatch_tag := 'REF_MISMATCH', ns := NULL, nc := NULL, ne := NULL): DuckDB macro wrapper over bcftools_munge_row that maps source columns (via preset or explicit map) and returns normalized GWAS-VCF-style rows with lean outputs and explicit alleles_swapped semantics. Output columns: chrom, pos, id, ref, alt, alleles_swapped, filter, ns, ez, nc, es, se, lp, af, ac, ne (16 columns). For METAL meta-analysis output with SI/I2/CQ/ED columns, use duckdb_munge_metal.
• duckdb_munge_metal(table_name, preset := '', column_map := map([''], ['']), column_map_file := '', fasta_ref := NULL, iffy_tag := 'IFFY', mismatch_tag := 'REF_MISMATCH', ns := NULL, nc := NULL, ne := NULL): Extended munge macro with METAL meta-analysis output columns. Same as duckdb_munge but additionally emits: si (imputation info, from INFO input), i2 (Cochran’s I² heterogeneity, from HET_I2), cq (Cochran’s Q -log10 p, from HET_LP or -log10(HET_P)), and ed (effect direction string, from DIRE; +/- flipped on allele swap). The R wrapper rduckhts_munge() auto-dispatches to this macro when metal keys (INFO, HET_I2, HET_P, HET_LP, DIRE) are present in the resolved column map.

Sequenz-UDFs

• seq_revcomp(sequence): Berechnet das Reverse-Komplement einer DNA-Sequenz mit den Basen A, C, G, T und N. Overloaded: accepts either a VARCHAR text sequence (returns VARCHAR) or a UTINYINT[] of htslib nt16 codes as produced by read_bam(sequence_encoding := ‘nt16’) (returns UTINYINT[]); the nt16 overload is bit-identical to the text path after decoding, so BAM pipelines can reverse-complement without leaving the nt16 encoding.
• seq_canonical(sequence): Gibt das lexikografisch kleinere von einer Sequenz und ihrem Reverse-Komplement zurück. Overloaded: accepts either a VARCHAR text sequence (returns VARCHAR) or a UTINYINT[] of htslib nt16 codes as produced by read_bam(sequence_encoding := ‘nt16’) (returns UTINYINT[]); the nt16 overload compares by decoded base order and is bit-identical to the text path after decoding.
• seq_hash_2bit(sequence): Kodiert eine kurze DNA-Sequenz als 2-Bit-Integer-Hash ohne Vorzeichen. Overloaded to also accept a UTINYINT[] of htslib nt16 codes (from read_bam(sequence_encoding := ‘nt16’)); non-ACGT codes yield NULL, bit-identical to the text path.
• seq_encode_4bit(sequence): Kodiert eine IUPAC-DNA-Sequenz als Liste von 4-Bit-Basencodes und bewahrt Ambiguitätssymbole einschließlich N.
• seq_decode_4bit(codes): Dekodiert eine Liste von 4-Bit-IUPAC-DNA-Basencodes zurück in einen Sequenzstring.
• seq_gc_content(sequence): Berechnet den GC-Anteil einer DNA-Sequenz als Wert zwischen 0 und 1. Overloaded: accepts either a VARCHAR text sequence or a UTINYINT[] of htslib nt16 codes as produced by read_bam(sequence_encoding := ‘nt16’); the nt16 overload classifies codes directly and is bit-identical to the text path, so BAM pipelines can compute GC without decoding sequences back to text.
• seq_kmers(sequence, k, canonical := FALSE): Expandiert eine Sequenz in positionale k-mere mit optionaler Kanonisierung.

SAM-Flag-UDFs

• sam_flag_bits(flag): Dekodiert ein SAM-Flag in ein Struct boolescher Bitfelder mit expliziten SAM-orientierten Namen wie is_paired, is_proper_pair, is_next_segment_unmapped und is_supplementary.
• sam_flag_has(flag, mask): Prüft, ob irgendwelche Bits der übergebenen SAM-Flag-Maske in einem Flag-Wert gesetzt sind.
• is_forward_aligned(flag): Prüft, ob ein gemapptes Segment auf den Forward-Strang aligned ist. Returns NULL for unmapped segments because SAM flag 0x10 does not define genomic strand when 0x4 is set.
• is_paired(flag): Prüft, ob das SAM-Flag angibt, dass das Template mehrere Segmente in der Sequenzierung hat (0x1).
• is_proper_pair(flag): Prüft, ob das SAM-Flag angibt, dass jedes Segment laut Aligner korrekt aligned ist (0x2).
• is_unmapped(flag): Prüft, ob der Read selbst laut SAM-Flag unmapped ist.
• is_next_segment_unmapped(flag): Prüft, ob das nächste Segment im Template als unmapped markiert ist (0x8).
• is_reverse_complemented(flag): Prüft, ob SEQ reverse-komplementiert gespeichert ist (0x10); bei gemappten Reads entspricht das einem Reverse-Strang-Alignment.
• is_next_segment_reverse_complemented(flag): Prüft, ob SEQ des nächsten Segments im Template reverse-komplementiert gespeichert ist (0x20).
• is_first_segment(flag): Prüft, ob der Read als erstes Segment im Template markiert ist.
• is_last_segment(flag): Prüft, ob der Read als letztes Segment im Template markiert ist.
• is_secondary(flag): Prüft, ob das Alignment als secondary markiert ist.
• is_qc_fail(flag): Prüft, ob der Read Vendor- oder Pipeline-Qualitätsprüfungen nicht bestanden hat.
• is_duplicate(flag): Prüft, ob das Alignment als Duplikat markiert ist.
• is_supplementary(flag): Prüft, ob das Alignment als supplementary markiert ist.

CIGAR-Hilfen

• cigar_has_soft_clip(cigar): Prüft, ob ein CIGAR-String ein soft-geclipptes Segment (S) enthält. Überladen, um auch ein binäres UINTEGER[]-CIGAR zu akzeptieren (wie von read_bam(cigar_representation := ‘binary’) erzeugt); die binäre Überladung ist bitidentisch zum Textpfad.
• cigar_has_hard_clip(cigar): Prüft, ob ein CIGAR-String ein hard-geclipptes Segment (H) enthält. Überladen, um auch ein binäres UINTEGER[]-CIGAR zu akzeptieren (wie von read_bam(cigar_representation := ‘binary’) erzeugt); die binäre Überladung ist bitidentisch zum Textpfad.
• cigar_left_soft_clip(cigar): Gibt die linksseitige soft-geclippte Länge aus einem CIGAR-String zurück, oder null, wenn das Alignment nicht mit S beginnt. Überladen, um auch ein binäres UINTEGER[]-CIGAR zu akzeptieren (wie von read_bam(cigar_representation := ‘binary’) erzeugt); die binäre Überladung ist bitidentisch zum Textpfad.
• cigar_right_soft_clip(cigar): Gibt die rechtsseitige soft-geclippte Länge aus einem CIGAR-String zurück, oder null, wenn das Alignment nicht mit S endet. Überladen, um auch ein binäres UINTEGER[]-CIGAR zu akzeptieren (wie von read_bam(cigar_representation := ‘binary’) erzeugt); die binäre Überladung ist bitidentisch zum Textpfad.
• cigar_query_length(cigar): Gibt die query-verbrauchende Länge aus einem CIGAR-String zurück und zählt M, I, S, = und X. Überladen, um auch ein binäres UINTEGER[]-CIGAR zu akzeptieren (wie von read_bam(cigar_representation := ‘binary’) erzeugt); die binäre Überladung ist bitidentisch zum Textpfad.
• cigar_aligned_query_length(cigar): Gibt die alignierte Query-Länge aus einem CIGAR-String zurück und zählt M, = und X, schließt Clips und Insertions aber aus. Überladen, um auch ein binäres UINTEGER[]-CIGAR zu akzeptieren (wie von read_bam(cigar_representation := ‘binary’) erzeugt); die binäre Überladung ist bitidentisch zum Textpfad.
• cigar_reference_length(cigar): Gibt die referenzverbrauchende Länge aus einem CIGAR-String zurück und zählt M, D, N, = und X. Überladen, um auch ein binäres UINTEGER[]-CIGAR zu akzeptieren (wie von read_bam(cigar_representation := ‘binary’) erzeugt); die binäre Überladung ist bitidentisch zum Textpfad.
• cigar_has_op(cigar, op): Prüft, ob ein CIGAR-String mindestens eine Instanz des angeforderten Operators enthält. Überladen, um auch ein binäres UINTEGER[]-CIGAR zu akzeptieren (wie von read_bam(cigar_representation := ‘binary’) erzeugt); die binäre Überladung ist bitidentisch zum Textpfad.

Betriebshinweise:

• Reader-Tabellenfunktionen akzeptieren scan_mode := ‘sequential’, um wo zutreffend vollständiges Datei-Streaming/Zählen statt indexgestützter Count-/Parallelpfade zu erzwingen; Regionsabfragen bleiben indexgestützt und sind mit dem Sequential-Modus inkompatibel.
• Paired FASTQ wird über mate_path oder interleaved := true unterstützt.
• CRAM-Reads werden mit einer expliziten Referenzdatei unterstützt.
• GTF/GFF-Attribute können als geparste MAP mit attributes_map := true über read_gff oder read_gtf zurückgegeben werden.
• Optionale SAM-Tag-Spalten und eine Hilfs-Tag-Map sind über standard_tags und auxiliary_tags verfügbar.
• Tabix-Reader unterstützen header, header_names, Typinferenz mit auto_detect und explizite column_types.
• MSVC-Builds (windows_amd64/windows_arm64) werden nicht unterstützt; verwenden Sie MinGW/RTools unter Windows.

Hinzugefügte Funktionen

Überladene Funktionen

Diese Erweiterung fügt keine Funktionsüberladungen hinzu.

Hinzugefügte Typen

Diese Erweiterung fügt keine Typen hinzu.

Hinzugefügte Einstellungen

Diese Erweiterung fügt keine Einstellungen hinzu.