flow-linalg 0.1.2

faer-based linear algebra primitives for flow cytometry: compensation and spectral unmixing
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77

# flow-linalg

Pure-Rust linear algebra primitives for flow cytometry, built on [`faer`](https://crates.io/crates/faer).

[![crates.io](https://img.shields.io/crates/v/flow-linalg.svg)](https://crates.io/crates/flow-linalg)
[![docs.rs](https://docs.rs/flow-linalg/badge.svg)](https://docs.rs/flow-linalg)
[![MIT](https://img.shields.io/crates/l/flow-linalg.svg)](LICENSE)

## 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

| Feature | Description |
|---------|-------------|
| `compensation` | Spillover matrix inversion and per-event compensation |
| `unmixing` | *(stub)* Spectral unmixing — future implementation |

## Installation

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

## Public API

```rust
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

```bash
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