flow-linalg

Pure-Rust linear algebra primitives for flow cytometry, built on faer.

Overview

flow-linalg provides the core matrix operations needed for fluorescence compensation and (future) spectral unmixing in flow cytometry pipelines. It requires no system BLAS/LAPACK — pure Rust via faer.

Features

Installation

[dependencies]
flow-linalg = { version = "0.1.2", features = ["compensation"] }

Public API

use flow_linalg::compensation::{
    invert_spillover, apply_compensation_inv, compensate_channels,
    estimate_spillover, SingleStainControl,
};
use faer::MatRef;

// Estimate spillover from single-stain positive/negative populations
let spillover = estimate_spillover(&controls, n_detectors)?;

// Invert a spillover matrix (partial-pivot LU decomposition)
let inv = invert_spillover(spillover.as_ref())?;

// Apply pre-inverted matrix to raw channel data (rayon-parallelized per channel)
let result = apply_compensation_inv(&raw_channels, inv.as_ref(), &channel_names)?;

// Convenience: invert + apply + filter to requested channels
let compensated = compensate_channels(&raw_channels, spillover.as_ref(), &matrix_names, &needed)?;

Algorithms

• Spillover estimation: Per-control column from median(positive) − median(negative), diagonal-normalized so S[j][j] = 1.
• Spillover inversion: Partial-pivot LU decomposition via faer. Validates matrix is square and non-singular before inversion.
• Compensation application: Per-event matrix-vector multiply, parallelized across output channels with rayon. Validates event count consistency across input channels.

Scope

This crate is intentionally narrow — it owns:

• Spillover matrix estimation from single-stain controls
• Spillover matrix inversion
• Compensation matrix application to event vectors
• (Future) Ordinary least-squares and non-negative least-squares for spectral unmixing
• (Future) Condition number and quality metrics for compensation matrices

It does not own: FCS file parsing, spillover keyword extraction, transform application, or GUI concerns.

Tests

cargo test -p flow-linalg --features compensation

Unit tests covering identity matrices, known spillover removal, channel filtering, spillover estimation recovery, and error cases.

License

MIT