polaranges

Draft for a Rust-first genomic range library built on top of Polars and ruranges-core.

The first goal is a RangeFrame wrapper that:

1. owns a polars::DataFrame,
2. validates interval semantics (Start, End, non-null, Start < End),
3. factorizes match_by columns into dense u32 group ids,
4. calls the overlap kernels in ruranges-core, and
5. uses the returned row indices to gather rows back out of Polars.

This keeps the heavy overlap logic in Rust while leaning on Polars for table storage and projection.

Why row indices first?

Polars does not have a pandas-style index, and that is fine here. The natural primitive from ruranges-core is a pair of row-id vectors:

• left[i] is a row in the query RangeFrame
• right[i] is the matching row in the target RangeFrame

That means the library can expose both:

• overlap_pairs(...) -> OverlapPairs
• overlap(...) -> RangeFrame

where overlap() is only sugar for self.take_rows(&pairs.left).

This is the same shape as pyrunges: the high-level operation is a thin layer over a low-level kernel that returns row matches.

Current draft scope

The draft in src/ keeps v1 intentionally narrow:

• generic RangeFrame with configurable start/end column names
• overlap_pairs()
• overlap()
• row gathering with take_rows()
• pure Rust match_by factorization for strings, booleans, and integer columns

The draft currently normalizes coordinates to i64 before calling ruranges-core. That keeps the first version simple and fully Rust-native. A later optimization can add zero-copy dispatch for i32 and i64.