Coordinates & key types#

The value types used as grove keys: the stranded GenomicCoordinate, the integer point key Numeric, and the 2-bit DNA k-mer key Kmer. See the User Guide for semantics and usage.

class pygenogrove.GenomicCoordinate#

Bases: pybind11_object

A stranded genomic interval: closed [start, end] coordinates (0-based, both inclusive) plus a strand.

Strand is one of: - ‘+’ : forward / plus strand - ‘-’ : reverse / minus strand - ‘.’ : no strand information (strand-agnostic) - ‘*’ : wildcard — matches any strand in overlap queries

Overlap requires BOTH coordinate overlap AND strand compatibility: equal strands overlap, and ‘*’ matches any strand. Sorting is coordinate-first (start, then end, then strand).

Parameters:

strand (str) – One of ‘+’, ‘-’, ‘.’, ‘*’ (a single character).
start (int) – Start position (0-based, inclusive).
end (int) – End position (0-based, inclusive).

property end#: End position (read-only — see set_range)

static overlaps(a: pygenogrove.GenomicCoordinate, b: pygenogrove.GenomicCoordinate) → bool#: Check if two coordinates overlap: coordinates must intersect AND strands must be compatible (equal, or one is the wildcard ‘*’).

set_range(self: pygenogrove.GenomicCoordinate, start: int, end: int) → None#

Atomically set both endpoints.

Do NOT call this on a coordinate that has already been inserted into a Grove — mutating a stored key silently corrupts B+ tree ordering. Use this only on coordinates not yet inserted (e.g. queries you intend to reuse).

set_strand(self: pygenogrove.GenomicCoordinate, strand: str) → None#

Set the strand (‘+’, ‘-’, ‘.’, ‘*’).

Same warning as set_range: do NOT call this on a coordinate already inserted into a Grove — strand participates in B+ tree ordering, so mutating a stored key corrupts it silently.

property start#: Start position (read-only — see set_range)

property strand#: Strand character (read-only — see set_strand)

class pygenogrove.Numeric#

Bases: pybind11_object

A simple integer point key: wraps a single int value (not a range).

Overlap is exact equality (numeric(5) overlaps numeric(5) only), so a NumericGrove behaves as a B+ tree for point lookups. Ordering is by the integer value.

Parameters:: value (int) – The wrapped integer value. Defaults to INT_MIN (the aggregation sentinel) when omitted.

static overlaps(a: pygenogrove.Numeric, b: pygenogrove.Numeric) → bool#: Check if two Numerics overlap — true iff they are equal.

set_value(self: pygenogrove.Numeric, value: int) → None#

Set the integer value.

Do NOT call this on a Numeric already inserted into a Grove — the value participates in B+ tree ordering, so mutating a stored key silently corrupts it. Use only on values not yet inserted (e.g. queries you intend to reuse).

property value#: The wrapped integer value (read-only — see set_value)

class pygenogrove.Kmer#

Bases: pybind11_object

A DNA k-mer: a length-k sequence over {A, C, G, T}, stored as a compact 2-bit encoding (so k <= 32). Immutable.

Overlap is exact equality — same bases AND same length — so a KmerGrove behaves as a k-mer dictionary for membership lookups. Ordering is by length first, then by the 2-bit encoding (lexicographic A < C < G < T).

Parameters:: sequence (str) – A DNA sequence over A/C/G/T (case-insensitive), length 0..32.

property encoding#: The 2-bit encoding as a 64-bit integer.

static is_valid(sequence: str) → bool#: Whether a sequence contains only A/C/G/T (case-insensitive).

property k#: The k-mer length.

max_k = 32#

static overlaps(a: pygenogrove.Kmer, b: pygenogrove.Kmer) → bool#: Check if two k-mers overlap — true iff identical (same bases and same length).