Refactors sparse matrix handling to implement row permutation logic and introduces a standalone tool for migrating indexes from MPHF 1.x to 2.x formats.
654 lines
26 KiB
Rust
654 lines
26 KiB
Rust
//! `PersistentSparseCompactIntMatrix` — row-major sparse integer matrix,
|
|
//! composed on top of [`PersistentSparseBitMatrix`] rather than
|
|
//! reimplementing it: the "which columns are non-zero" support is exactly
|
|
//! a sparse bit matrix (dictionary-deduplicated — presence patterns repeat
|
|
//! across rows, same measured benefit as the pure bit case), and only the
|
|
//! values layer is new.
|
|
//!
|
|
//! Unlike the support, values are **not** deduplicated: two rows can share
|
|
//! the same non-zero columns (same `dict_id`) while carrying different
|
|
//! counts, so a value run belongs to a row, never to a dictionary entry.
|
|
//! Two companion streams:
|
|
//! - `singleton_values.pciv`: one value per singleton row, dense over
|
|
//! `n_singleton`, indexed by the same `rank0(slot)` the support already
|
|
//! uses for its own `singleton` array (see
|
|
//! [`PersistentSparseBitMatrix::row_rank`]).
|
|
//! - `multi_values.pciv` + `multi_offsets` (`.efl`/`.efh`): one flat,
|
|
//! non-deduplicated value per `(multi row, occurrence)` pair, addressed
|
|
//! by a per-*row* Elias-Fano offset (indexed by `rank1(slot)`) —
|
|
//! deliberately distinct from the support's own `dict_offsets`, which is
|
|
//! keyed by `dict_id` and therefore locates a *shared* column range, not
|
|
//! a row's private value range.
|
|
//!
|
|
//! Both value streams reuse [`PersistentCompactIntVec`]'s 1-byte +
|
|
//! overflow encoding — tuned for exactly this crate's measured value
|
|
//! distribution (the large majority under 127, virtually all under 255).
|
|
|
|
use std::fs;
|
|
use std::io;
|
|
use std::path::{Path, PathBuf};
|
|
|
|
use ndarray::{Array1, Array2};
|
|
|
|
use crate::bitmatrix::RowRank;
|
|
use crate::builder::PersistentCompactIntVecBuilder;
|
|
use crate::eliasfano::{EliasFano, EliasFanoBuilder};
|
|
use crate::reader::PersistentCompactIntVec;
|
|
use crate::traits::{BitPartials, ColumnWeights, CountPartials};
|
|
use crate::{PersistentIntMatrix, PersistentSparseBitMatrix, PersistentSparseBitMatrixBuilder};
|
|
|
|
fn singleton_values_path(dir: &Path) -> PathBuf {
|
|
dir.join("singleton_values.pciv")
|
|
}
|
|
fn multi_values_path(dir: &Path) -> PathBuf {
|
|
dir.join("multi_values.pciv")
|
|
}
|
|
fn multi_offsets_base(dir: &Path) -> PathBuf {
|
|
dir.join("multi_offsets")
|
|
}
|
|
|
|
/// Lightweight disk probe: true iff a sparse count matrix has already been
|
|
/// written at `dir` — the marker [`PersistentCompactIntMatrix::open`]/
|
|
/// `detect_storage` check to route into this format, mirroring the
|
|
/// `sparse_meta.json` check the bit side does for `PersistentSparseBitMatrix`.
|
|
/// Also backs [`pack_sparse_compact_int_matrix`]'s own idempotency check.
|
|
pub(crate) fn is_present(dir: &Path) -> bool {
|
|
singleton_values_path(dir).exists()
|
|
}
|
|
|
|
/// Row batch size for [`PersistentSparseCompactIntMatrixBuilder::build_from_dense`].
|
|
const BUILD_FROM_DENSE_BATCH: usize = 4096;
|
|
|
|
// ── PersistentSparseCompactIntMatrix ────────────────────────────────────────
|
|
|
|
pub struct PersistentSparseCompactIntMatrix {
|
|
support: PersistentSparseBitMatrix,
|
|
singleton_values: PersistentCompactIntVec,
|
|
multi_values: PersistentCompactIntVec,
|
|
multi_offsets: EliasFano,
|
|
}
|
|
|
|
impl PersistentSparseCompactIntMatrix {
|
|
pub fn open(dir: &Path) -> io::Result<Self> {
|
|
Ok(Self {
|
|
support: PersistentSparseBitMatrix::open(dir)?,
|
|
singleton_values: PersistentCompactIntVec::open(&singleton_values_path(dir))?,
|
|
multi_values: PersistentCompactIntVec::open(&multi_values_path(dir))?,
|
|
multi_offsets: EliasFano::open(&multi_offsets_base(dir))?,
|
|
})
|
|
}
|
|
|
|
#[inline]
|
|
pub fn n(&self) -> usize {
|
|
self.support.n()
|
|
}
|
|
#[inline]
|
|
pub fn n_cols(&self) -> usize {
|
|
self.support.n_cols()
|
|
}
|
|
|
|
/// Calls `f(col, value)` once per non-zero column at `slot`, in
|
|
/// ascending column order — the shared decode branch behind every
|
|
/// accessor below. Zips the support's own column decode
|
|
/// ([`PersistentSparseBitMatrix::for_each_genome_in_row`]) with this
|
|
/// row's private slice of whichever value stream it belongs to.
|
|
#[inline]
|
|
pub(crate) fn for_each_cell_in_row(&self, slot: usize, mut f: impl FnMut(usize, u32)) {
|
|
match self.support.row_rank(slot) {
|
|
RowRank::Singleton(rank) => {
|
|
let v = self.singleton_values.get(rank);
|
|
self.support.for_each_genome_in_row(slot, |c| f(c, v));
|
|
}
|
|
RowRank::Multi(rank) => {
|
|
let start = self.multi_offsets.get(rank) as usize;
|
|
let mut i = 0usize;
|
|
self.support.for_each_genome_in_row(slot, |c| {
|
|
f(c, self.multi_values.get(start + i));
|
|
i += 1;
|
|
});
|
|
}
|
|
}
|
|
}
|
|
|
|
/// Column-major point lookup: value at column `c`, slot `slot` (0 if
|
|
/// absent).
|
|
pub fn get(&self, c: usize, slot: usize) -> u32 {
|
|
let mut found = 0u32;
|
|
self.for_each_cell_in_row(slot, |g, v| {
|
|
if g == c {
|
|
found = v;
|
|
}
|
|
});
|
|
found
|
|
}
|
|
|
|
pub fn row(&self, slot: usize) -> Box<[u32]> {
|
|
let mut out = vec![0u32; self.n_cols()];
|
|
self.fill_row(slot, &mut out);
|
|
out.into_boxed_slice()
|
|
}
|
|
|
|
/// Fill `buf[i]` with column `i`'s value at `slot` (0 if absent) —
|
|
/// mirrors [`PersistentSparseBitMatrix::fill_row`]'s signature.
|
|
pub fn fill_row(&self, slot: usize, buf: &mut [u32]) {
|
|
buf[..self.n_cols()].fill(0);
|
|
self.for_each_cell_in_row(slot, |g, v| buf[g] = v);
|
|
}
|
|
|
|
/// Like [`PersistentSparseBitMatrix::fill_sub_matrix`]: `out` has one
|
|
/// entry per column, each filled with that column's values at `slots`,
|
|
/// in `slots` order.
|
|
pub fn fill_sub_matrix(&self, slots: &[usize], out: &mut [Vec<u32>]) {
|
|
assert_eq!(out.len(), self.n_cols());
|
|
for col in out.iter_mut() {
|
|
col.clear();
|
|
col.resize(slots.len(), 0);
|
|
}
|
|
for (i, &slot) in slots.iter().enumerate() {
|
|
self.for_each_cell_in_row(slot, |g, v| out[g][i] = v);
|
|
}
|
|
}
|
|
|
|
/// Yields every `(idx into slots, col, value)` triple, row by row, in
|
|
/// `slots` order — mirrors
|
|
/// [`PersistentSparseBitMatrix::nonzero_iter`].
|
|
pub fn nonzero_iter<'a>(
|
|
&'a self,
|
|
slots: &'a [usize],
|
|
) -> impl Iterator<Item = (usize, usize, u32)> + 'a {
|
|
let mut next_slot = 0usize;
|
|
let mut cur_idx = 0usize;
|
|
let mut buf: Vec<(usize, u32)> = Vec::new();
|
|
let mut buf_pos = 0usize;
|
|
|
|
std::iter::from_fn(move || {
|
|
loop {
|
|
if buf_pos < buf.len() {
|
|
let (g, v) = buf[buf_pos];
|
|
buf_pos += 1;
|
|
return Some((cur_idx, g, v));
|
|
}
|
|
if next_slot >= slots.len() {
|
|
return None;
|
|
}
|
|
cur_idx = next_slot;
|
|
let slot = slots[next_slot];
|
|
next_slot += 1;
|
|
buf.clear();
|
|
self.for_each_cell_in_row(slot, |g, v| buf.push((g, v)));
|
|
buf_pos = 0;
|
|
}
|
|
})
|
|
}
|
|
|
|
/// Per-column sum, via a naive row-first accumulation.
|
|
pub fn sum(&self) -> Array1<u64> {
|
|
let mut sums = vec![0u64; self.n_cols()];
|
|
for slot in 0..self.n() {
|
|
self.for_each_cell_in_row(slot, |g, v| sums[g] += v as u64);
|
|
}
|
|
Array1::from(sums)
|
|
}
|
|
|
|
/// Per-column sum of squares — the marginal `partial_euclidean`/
|
|
/// `partial_relfreq_euclidean`/`partial_hellinger` reconstruct their
|
|
/// squared-difference formulas from, via `Σ(a-b)² = Σa²+Σb²-2Σab` (see
|
|
/// [`row_major_pairwise`](Self::row_major_pairwise)'s doc comment for
|
|
/// why that identity is what makes the row-major approach correct for
|
|
/// those three).
|
|
fn sum_sq(&self) -> Array1<u64> {
|
|
let mut sums = vec![0u64; self.n_cols()];
|
|
for slot in 0..self.n() {
|
|
self.for_each_cell_in_row(slot, |g, v| sums[g] += (v as u64) * (v as u64));
|
|
}
|
|
Array1::from(sums)
|
|
}
|
|
|
|
pub fn count_nonzero(&self) -> Array1<u64> {
|
|
let mut counts = vec![0u64; self.n_cols()];
|
|
for slot in 0..self.n() {
|
|
self.for_each_cell_in_row(slot, |g, _| counts[g] += 1);
|
|
}
|
|
Array1::from(counts)
|
|
}
|
|
|
|
/// Per-column count of values `>= threshold` — the marginal
|
|
/// `partial_threshold_jaccard` needs both for its `union` formula
|
|
/// (`count_geq[i] + count_geq[j] - inter[i,j]`) and for its diagonal.
|
|
/// `threshold == 1` is `count_nonzero()` exactly (`v >= 1 ⟺ v != 0`),
|
|
/// but this is only ever called with `threshold >= 1` by
|
|
/// [`partial_threshold_jaccard`](CountPartials::partial_threshold_jaccard)
|
|
/// (the `threshold == 0` case is closed-form there, no marginal needed).
|
|
fn count_geq(&self, threshold: u32) -> Array1<u64> {
|
|
let mut counts = vec![0u64; self.n_cols()];
|
|
for slot in 0..self.n() {
|
|
self.for_each_cell_in_row(slot, |g, v| {
|
|
if v >= threshold {
|
|
counts[g] += 1;
|
|
}
|
|
});
|
|
}
|
|
Array1::from(counts)
|
|
}
|
|
|
|
/// Shared row-major traversal behind every `CountPartials` formula
|
|
/// below: decodes each row once via
|
|
/// [`for_each_cell_in_row`](Self::for_each_cell_in_row) — the same
|
|
/// decode `sum`/`count_nonzero` already use — and for every pair of
|
|
/// columns actually co-present in that row, folds `kernel(i, a, j, b)`
|
|
/// into both `[i,j]` and `[j,i]` of the returned `n_cols × n_cols`
|
|
/// matrix. `kernel` must be symmetric in its (index, value) pair
|
|
/// arguments (every kernel used below is).
|
|
///
|
|
/// Unlike [`PersistentSparseBitMatrix::col_weights_and_pair_counts`],
|
|
/// this can't weight by how many rows share a `dict_id`: two rows can
|
|
/// share the same column *set* while carrying different *values* (see
|
|
/// this module's own doc comment), so every row still costs its own
|
|
/// `O(k̄²)` pass. What it still buys over the naive `O(n_cols² × n)`
|
|
/// column-pair scan: total cost is `O(Σ k̄²)` over actually-populated
|
|
/// rows, not `O(n_cols²)` full-column rescans — the same complexity
|
|
/// class the bit side reaches, just without the dict-multiplicity
|
|
/// shortcut.
|
|
///
|
|
/// Kernels here are all zero whenever either side is absent (`min`,
|
|
/// `a·b`, `√(a·b)`, a `threshold`-AND indicator) — cells absent from a
|
|
/// row's decode correctly contribute nothing, no separate handling
|
|
/// needed. Squared-difference formulas (`euclidean`/`relfreq_euclidean`/
|
|
/// `hellinger`) do *not* have that property — `(a-0)² = a² ≠ 0` — so
|
|
/// they never use this loop directly for their asymmetric-presence
|
|
/// contributions; they use it only for the `Σab`/`Σ√(ab)` cross term and
|
|
/// reconstruct the rest from per-column marginals (`sum`/`sum_sq`) at
|
|
/// the call site.
|
|
fn row_major_pairwise<T: Copy + Default + std::ops::AddAssign>(
|
|
&self,
|
|
mut kernel: impl FnMut(usize, u32, usize, u32) -> T,
|
|
) -> Array2<T> {
|
|
let n_cols = self.n_cols();
|
|
let mut acc = Array2::<T>::default((n_cols, n_cols));
|
|
let mut present: Vec<(usize, u32)> = Vec::new();
|
|
for slot in 0..self.n() {
|
|
present.clear();
|
|
self.for_each_cell_in_row(slot, |c, v| present.push((c, v)));
|
|
for p in 0..present.len() {
|
|
let (i, a) = present[p];
|
|
for &(j, b) in &present[p + 1..] {
|
|
let t = kernel(i, a, j, b);
|
|
acc[[i, j]] += t;
|
|
acc[[j, i]] += t;
|
|
}
|
|
}
|
|
}
|
|
acc
|
|
}
|
|
}
|
|
|
|
impl ColumnWeights for PersistentSparseCompactIntMatrix {
|
|
#[inline]
|
|
fn col_weights(&self) -> Array1<u64> {
|
|
self.sum()
|
|
}
|
|
#[inline]
|
|
fn partial_kmer_counts(&self) -> Array1<u64> {
|
|
self.count_nonzero()
|
|
}
|
|
}
|
|
|
|
impl CountPartials for PersistentSparseCompactIntMatrix {
|
|
/// `Σ min(a,b)` — zero whenever either side is absent, so
|
|
/// [`row_major_pairwise`](Self::row_major_pairwise) needs no correction
|
|
/// off-diagonal. Diagonal is `min(a,a) = a`, i.e. the column's own sum —
|
|
/// not `T::default()` — matching the dense `pairwise_matrix` convention
|
|
/// (`f(i,i)` is a genuine self-comparison, see that helper's doc
|
|
/// comment); `row_major_pairwise` never calls its kernel with `i == j`
|
|
/// (a row's decode never lists the same column twice), so it's patched
|
|
/// in here explicitly.
|
|
fn partial_bray(&self) -> Array2<u64> {
|
|
let mut m = self.row_major_pairwise(|_, a, _, b| (a as u64).min(b as u64));
|
|
let sum = self.sum();
|
|
for i in 0..self.n_cols() {
|
|
m[[i, i]] = sum[i];
|
|
}
|
|
m
|
|
}
|
|
|
|
/// `Σ(a-b)²`, reconstructed via `Σa²+Σb²-2Σab` — the `Σab` cross term is
|
|
/// the one part of this formula that's zero when either side is absent
|
|
/// (a row can't multiply an absent cell into anything), so it's the
|
|
/// only part [`row_major_pairwise`](Self::row_major_pairwise) computes;
|
|
/// the `Σa²`/`Σb²` marginals come from [`sum_sq`](Self::sum_sq).
|
|
fn partial_euclidean(&self) -> Array2<f64> {
|
|
let n = self.n_cols();
|
|
let dot = self.row_major_pairwise(|_, a, _, b| (a as f64) * (b as f64));
|
|
let sq = self.sum_sq();
|
|
let mut m = Array2::<f64>::zeros((n, n));
|
|
for i in 0..n {
|
|
for j in 0..n {
|
|
if i != j {
|
|
m[[i, j]] = sq[i] as f64 + sq[j] as f64 - 2.0 * dot[[i, j]];
|
|
}
|
|
}
|
|
}
|
|
m
|
|
}
|
|
|
|
/// `threshold == 1` is exactly presence (`a >= 1 ⟺ a != 0 ⟺` present in
|
|
/// the support) — shortcuts straight to `support`'s own
|
|
/// [`BitPartials::partial_jaccard`], which already has the dict-driven
|
|
/// shortcut this type's own values can't reuse (see
|
|
/// [`row_major_pairwise`](Self::row_major_pairwise)'s doc comment).
|
|
/// `threshold == 0` is the other degenerate case — every value is `>= 0`
|
|
/// (`u32`), so every column pair trivially co-occurs on every row,
|
|
/// closed-form, no traversal needed. General `threshold > 1` walks the
|
|
/// row-major decode, since only values actually `>= threshold` can ever
|
|
/// be absent from it (any lower value is already excluded from the
|
|
/// intersection/union, same reasoning as `partial_bray`).
|
|
fn partial_threshold_jaccard(&self, threshold: u32) -> (Array2<u64>, Array2<u64>) {
|
|
let n = self.n_cols();
|
|
if threshold == 0 {
|
|
// Diagonal included: f(i,i) = n rows too, trivially.
|
|
let full = Array2::from_elem((n, n), self.n() as u64);
|
|
return (full.clone(), full);
|
|
}
|
|
let count_geq = self.count_geq(threshold);
|
|
if threshold == 1 {
|
|
// `count_geq[i]` at threshold 1 is exactly `support`'s own
|
|
// `col_weights[i]` (both count columns present, i.e. nonzero),
|
|
// so `support.partial_jaccard`'s own diagonal already matches
|
|
// this method's `f(i,i) = count_geq[i]` convention — nothing
|
|
// left to patch.
|
|
return BitPartials::partial_jaccard(&self.support);
|
|
}
|
|
let mut inter =
|
|
self.row_major_pairwise(|_, a, _, b| (a >= threshold && b >= threshold) as u64);
|
|
let mut union = Array2::<u64>::zeros((n, n));
|
|
for i in 0..n {
|
|
for j in 0..n {
|
|
if i != j {
|
|
union[[i, j]] = count_geq[i] + count_geq[j] - inter[[i, j]];
|
|
}
|
|
}
|
|
}
|
|
for i in 0..n {
|
|
inter[[i, i]] = count_geq[i];
|
|
union[[i, i]] = count_geq[i];
|
|
}
|
|
(inter, union)
|
|
}
|
|
|
|
/// `Σ min(a/sa, b/sb)` — `min` isn't bilinear, so unlike
|
|
/// `partial_relfreq_euclidean` there's no marginal-based shortcut; it's
|
|
/// computed directly in the row-major pass, same shape as `partial_bray`
|
|
/// but with each side pre-scaled by its column's global sum (`sa`/`sb`,
|
|
/// looked up from `global` by the kernel's own column indices). Diagonal
|
|
/// is `Σ a/sa = sum[i]/global[i]` — same self-comparison convention as
|
|
/// `partial_bray`'s diagonal, patched in afterwards for the same reason
|
|
/// (`row_major_pairwise` never pairs a column with itself).
|
|
fn partial_relfreq_bray(&self, global: &Array1<u64>) -> Array2<f64> {
|
|
let mut m = self.row_major_pairwise(|i, a, j, b| {
|
|
let sa = global[i] as f64;
|
|
let sb = global[j] as f64;
|
|
let pa = if sa > 0.0 { a as f64 / sa } else { 0.0 };
|
|
let pb = if sb > 0.0 { b as f64 / sb } else { 0.0 };
|
|
pa.min(pb)
|
|
});
|
|
let sum = self.sum();
|
|
for i in 0..self.n_cols() {
|
|
m[[i, i]] = if global[i] > 0 {
|
|
sum[i] as f64 / global[i] as f64
|
|
} else {
|
|
0.0
|
|
};
|
|
}
|
|
m
|
|
}
|
|
|
|
/// `Σ(a/sa - b/sb)²`, reconstructed the same way as `partial_euclidean`
|
|
/// (`Σpa²+Σpb²-2Σpa·pb`), reusing the *same* raw `Σab`/`Σa²` passes —
|
|
/// just rescaled by the column's global sum at the finalisation step
|
|
/// below, not inside the row-major loop.
|
|
fn partial_relfreq_euclidean(&self, global: &Array1<u64>) -> Array2<f64> {
|
|
let n = self.n_cols();
|
|
let dot = self.row_major_pairwise(|_, a, _, b| (a as f64) * (b as f64));
|
|
let sq = self.sum_sq();
|
|
let mut m = Array2::<f64>::zeros((n, n));
|
|
for i in 0..n {
|
|
for j in 0..n {
|
|
if i != j {
|
|
let sa = global[i] as f64;
|
|
let sb = global[j] as f64;
|
|
let sq_a = if sa > 0.0 {
|
|
sq[i] as f64 / (sa * sa)
|
|
} else {
|
|
0.0
|
|
};
|
|
let sq_b = if sb > 0.0 {
|
|
sq[j] as f64 / (sb * sb)
|
|
} else {
|
|
0.0
|
|
};
|
|
let cross = if sa > 0.0 && sb > 0.0 {
|
|
dot[[i, j]] / (sa * sb)
|
|
} else {
|
|
0.0
|
|
};
|
|
m[[i, j]] = sq_a + sq_b - 2.0 * cross;
|
|
}
|
|
}
|
|
}
|
|
m
|
|
}
|
|
|
|
/// `Σ(√pa-√pb)² = Σpa+Σpb-2Σ√(pa·pb)` — `Σpa` is a plain marginal
|
|
/// (`sum()[i]/sa`, no co-presence restriction needed: it doesn't depend
|
|
/// on column `j` at all), only the cross term `Σ√(pa·pb) = Σ√(ab)/√(sa·sb)`
|
|
/// goes through the row-major pass (its `√(a·b)` kernel is zero exactly
|
|
/// when either side is absent, like every other cross term above).
|
|
fn partial_hellinger(&self, global: &Array1<u64>) -> Array2<f64> {
|
|
let n = self.n_cols();
|
|
let sqrt_dot = self.row_major_pairwise(|_, a, _, b| ((a as f64) * (b as f64)).sqrt());
|
|
let sum = self.sum();
|
|
let mut m = Array2::<f64>::zeros((n, n));
|
|
for i in 0..n {
|
|
for j in 0..n {
|
|
if i != j {
|
|
let sa = global[i] as f64;
|
|
let sb = global[j] as f64;
|
|
let pa_sum = if sa > 0.0 { sum[i] as f64 / sa } else { 0.0 };
|
|
let pb_sum = if sb > 0.0 { sum[j] as f64 / sb } else { 0.0 };
|
|
let cross = if sa > 0.0 && sb > 0.0 {
|
|
sqrt_dot[[i, j]] / (sa * sb).sqrt()
|
|
} else {
|
|
0.0
|
|
};
|
|
m[[i, j]] = pa_sum + pb_sum - 2.0 * cross;
|
|
}
|
|
}
|
|
}
|
|
m
|
|
}
|
|
}
|
|
|
|
// ── PersistentSparseCompactIntMatrixBuilder ─────────────────────────────────
|
|
|
|
pub struct PersistentSparseCompactIntMatrixBuilder {
|
|
support: PersistentSparseBitMatrixBuilder,
|
|
dir: PathBuf,
|
|
singleton_values: Vec<u32>,
|
|
multi_values: Vec<u32>,
|
|
multi_row_offsets: Vec<u64>,
|
|
}
|
|
|
|
impl PersistentSparseCompactIntMatrixBuilder {
|
|
pub fn new(n: usize, n_cols: usize, dir: &Path) -> io::Result<Self> {
|
|
fs::create_dir_all(dir)?;
|
|
Ok(Self {
|
|
support: PersistentSparseBitMatrixBuilder::new(n, n_cols, dir)?,
|
|
dir: dir.to_path_buf(),
|
|
singleton_values: Vec::new(),
|
|
multi_values: Vec::new(),
|
|
multi_row_offsets: Vec::new(),
|
|
})
|
|
}
|
|
|
|
/// Appends one row: `cols` sorted ascending, each `< n_cols`;
|
|
/// `values[i]` is the value at column `cols[i]`. Rows must be pushed
|
|
/// in slot order — same contract as
|
|
/// [`PersistentSparseBitMatrixBuilder::push_row`], which this
|
|
/// delegates the column side to.
|
|
///
|
|
/// Cardinality 0 or ≥2 both route through the multi/dict path (0 as a
|
|
/// genuine empty entry, same reasoning as the bit builder); only
|
|
/// cardinality exactly 1 takes the singleton shortcut.
|
|
pub fn push_row(&mut self, cols: &[u32], values: &[u32]) {
|
|
assert_eq!(cols.len(), values.len(), "cols/values length mismatch");
|
|
match cols.len() {
|
|
1 => self.singleton_values.push(values[0]),
|
|
_ => {
|
|
self.multi_row_offsets.push(self.multi_values.len() as u64);
|
|
self.multi_values.extend_from_slice(values);
|
|
}
|
|
}
|
|
self.support.push_row(cols);
|
|
}
|
|
|
|
/// Builds a sparse matrix from an already-built dense
|
|
/// [`PersistentCompactIntMatrix`] (`Columnar` or `Packed`) — same
|
|
/// batched-transpose shape as
|
|
/// [`PersistentSparseBitMatrixBuilder::build_from_dense`]: processes
|
|
/// rows in batches of [`BUILD_FROM_DENSE_BATCH`], driven by
|
|
/// `dense.nonzero_iter`, which walks each column once per batch
|
|
/// instead of one `get()` per cell in row-major order.
|
|
///
|
|
/// `nonzero_iter`'s triples arrive grouped by ascending column (outer
|
|
/// loop over columns) — so within a batch, each row's `(col, value)`
|
|
/// pairs are appended to its own buffer in strictly ascending column
|
|
/// order "for free", matching `push_row`'s ascending-`cols` contract
|
|
/// without an explicit sort.
|
|
pub fn build_from_dense(dense: &PersistentIntMatrix, dir: &Path) -> io::Result<Self> {
|
|
let n = dense.n();
|
|
let n_cols = dense.n_cols();
|
|
let mut builder = Self::new(n, n_cols, dir)?;
|
|
let mut row_cols: Vec<Vec<u32>> = vec![Vec::new(); BUILD_FROM_DENSE_BATCH];
|
|
let mut row_vals: Vec<Vec<u32>> = vec![Vec::new(); BUILD_FROM_DENSE_BATCH];
|
|
let mut start = 0;
|
|
while start < n {
|
|
let end = (start + BUILD_FROM_DENSE_BATCH).min(n);
|
|
let slots: Vec<usize> = (start..end).collect();
|
|
for (row, c, v) in dense.nonzero_iter(&slots) {
|
|
row_cols[row].push(c as u32);
|
|
row_vals[row].push(v);
|
|
}
|
|
for i in 0..(end - start) {
|
|
builder.push_row(&row_cols[i], &row_vals[i]);
|
|
row_cols[i].clear();
|
|
row_vals[i].clear();
|
|
}
|
|
start = end;
|
|
}
|
|
Ok(builder)
|
|
}
|
|
|
|
/// Row-permuted copy of `src`: row `s` of the result is row
|
|
/// `new_to_old[s]` of `src`. Same contract as
|
|
/// [`PersistentSparseBitMatrixBuilder::build_permuted`].
|
|
pub fn build_permuted(
|
|
src: &PersistentSparseCompactIntMatrix,
|
|
new_to_old: &[u32],
|
|
dir: &Path,
|
|
) -> io::Result<Self> {
|
|
let mut builder = Self::new(new_to_old.len(), src.n_cols(), dir)?;
|
|
let mut cols: Vec<u32> = Vec::new();
|
|
let mut vals: Vec<u32> = Vec::new();
|
|
for &old in new_to_old {
|
|
cols.clear();
|
|
vals.clear();
|
|
src.for_each_cell_in_row(old as usize, |c, v| {
|
|
cols.push(c as u32);
|
|
vals.push(v);
|
|
});
|
|
builder.push_row(&cols, &vals);
|
|
}
|
|
Ok(builder)
|
|
}
|
|
|
|
pub fn close(self) -> io::Result<()> {
|
|
let Self {
|
|
support,
|
|
dir,
|
|
singleton_values,
|
|
multi_values,
|
|
multi_row_offsets,
|
|
} = self;
|
|
support.close()?;
|
|
|
|
let mut sv = PersistentCompactIntVecBuilder::new(
|
|
singleton_values.len(),
|
|
&singleton_values_path(&dir),
|
|
)?;
|
|
for (i, &v) in singleton_values.iter().enumerate() {
|
|
sv.set(i, v);
|
|
}
|
|
sv.close()?;
|
|
|
|
let mut mv =
|
|
PersistentCompactIntVecBuilder::new(multi_values.len(), &multi_values_path(&dir))?;
|
|
for (i, &v) in multi_values.iter().enumerate() {
|
|
mv.set(i, v);
|
|
}
|
|
mv.close()?;
|
|
|
|
let universe = multi_values.len() as u64 + 1;
|
|
let mut mo =
|
|
EliasFanoBuilder::new(multi_row_offsets.len(), universe, &multi_offsets_base(&dir))?;
|
|
for &o in &multi_row_offsets {
|
|
mo.push(o);
|
|
}
|
|
mo.close()?;
|
|
|
|
Ok(())
|
|
}
|
|
|
|
pub fn finish(self) -> io::Result<PersistentSparseCompactIntMatrix> {
|
|
let dir = self.dir.clone();
|
|
self.close()?;
|
|
PersistentSparseCompactIntMatrix::open(&dir)
|
|
}
|
|
}
|
|
|
|
// ── pack_sparse_compact_int_matrix ──────────────────────────────────────────
|
|
|
|
/// Converts whichever dense count-matrix format is on disk at `dir`
|
|
/// (`Packed`, i.e. `matrix.pcmx`, or `Columnar`, i.e. `col_*.pciv` +
|
|
/// `meta.json`) into the sparse on-disk format in place — generic over the
|
|
/// dense source the same way [`super::bitmatrix::pack_sparse_bit_matrix`]
|
|
/// is: detects the format, transposes straight from it, and only removes
|
|
/// the old dense files once the new format is fully written (a crash
|
|
/// mid-conversion leaves the previous, still-valid format rather than a
|
|
/// half-written one). Idempotent — a no-op if `singleton_values.pciv`
|
|
/// already exists.
|
|
pub fn pack_sparse_compact_int_matrix(dir: &Path) -> io::Result<()> {
|
|
use crate::intmatrix::{ColumnarCompactIntMatrix, PackedCompactIntMatrix, col_path};
|
|
|
|
if is_present(dir) {
|
|
return Ok(());
|
|
}
|
|
|
|
let packed_path = dir.join("matrix.pcmx");
|
|
if packed_path.exists() {
|
|
let dense = PersistentIntMatrix::Packed(PackedCompactIntMatrix::open(&packed_path)?);
|
|
PersistentSparseCompactIntMatrixBuilder::build_from_dense(&dense, dir)?.close()?;
|
|
drop(dense);
|
|
fs::remove_file(&packed_path)?;
|
|
} else {
|
|
let dense = PersistentIntMatrix::Columnar(ColumnarCompactIntMatrix::open(dir)?);
|
|
let n_cols = dense.n_cols();
|
|
PersistentSparseCompactIntMatrixBuilder::build_from_dense(&dense, dir)?.close()?;
|
|
drop(dense);
|
|
for c in 0..n_cols {
|
|
let _ = fs::remove_file(col_path(dir, c));
|
|
}
|
|
let _ = fs::remove_file(dir.join("meta.json"));
|
|
}
|
|
Ok(())
|
|
}
|