xcell/lib.rs
1//! # xcell — a pure-Rust port of xCell 1.1.0
2//!
3//! [xCell](https://github.com/dviraran/xCell) (Aran, Hu & Butte, *Genome
4//! Biology* 2017) scores 64 immune and stromal cell types from bulk expression.
5//! This crate is a faithful, dependency-light Rust re-implementation of the
6//! xCell 1.1.0 pipeline, built on the [`gsva`] ssGSEA engine:
7//!
8//! 1. **`rawEnrichmentAnalysis`** — keep genes shared with xCell's universe,
9//! per-sample average-tie rank, unnormalized ssGSEA over the 489 signatures,
10//! subtract each signature's minimum, average signatures per cell type.
11//! 2. **`transformScores`** — per-cell-type power-curve calibration.
12//! 3. **`spillOver`** — per-sample non-negative least squares against the
13//! compensation matrix `K` to remove cross-cell-type spillover.
14//! 4. **`microenvironmentScores`** — append `ImmuneScore`, `StromaScore`, and
15//! `MicroenvironmentScore`.
16//!
17//! The bundled model data (signatures, gene universe, spillover matrix, and
18//! calibration table) is exported from the GPL-3 xCell package; this crate is
19//! therefore licensed **GPL-3.0-or-later**.
20//!
21//! ## Example
22//!
23//! ```no_run
24//! use xcell::{xcell_analysis, ExprMatrix, XCellModel, XCellParams};
25//!
26//! // expr: genes (rows, labelled by symbol) × samples (columns).
27//! let expr: ExprMatrix = xcell::io::read_tsv_matrix(&std::fs::read_to_string("expr.tsv").unwrap());
28//! let model = XCellModel::load();
29//! let scores = xcell_analysis(&expr, &model, &XCellParams::default());
30//! println!("{} rows × {} samples", scores.gene_sets.len(), scores.samples.len());
31//! ```
32//!
33//! Loading the embedded model on its own is cheap and infallible:
34//!
35//! ```
36//! let model = xcell::XCellModel::load();
37//! assert_eq!(model.cell_types.len(), 64);
38//! ```
39
40pub mod data;
41pub mod microenv;
42mod par;
43pub mod rawenrich;
44pub mod spillover;
45pub mod transform;
46pub mod xcell;
47
48pub use data::{SpillModel, XCellModel};
49pub use xcell::{xcell_analysis, XCellParams};
50
51// Re-export the gsva substrate xcell is built on, so downstream code can
52// construct inputs and read results without depending on gsva directly.
53pub use gsva::{io, EnrichmentResult, ExprMatrix, GeneSet, GeneSets};