Local Preprocessing¶
Everything on this page happens entirely on the node, before any communication. Nothing here requires the other modality.
The active/shared duality¶
MaxFuse needs two matrices per modality:
| Matrix | What it is | Role |
|---|---|---|
| Active | Complete, modality-specific, preprocessed | Graphs, CCA, final embeddings |
| Shared | Feature-aligned subset, one-to-one across modalities | Seed matching only |
The shared set exists because a protein marker name has a corresponding RNA gene name. It is typically a tiny fraction of the active set: about 10% for the Antibodies dataset and 0.6% for Tonsils. That thinness is the whole reason the refinement loop exists.
The shared matrices must stay aligned
Column j of node 1's shared matrix must correspond to column j of node 2's. If you filter features, both nodes must drop the same columns. Nothing in the pipeline can detect a mis-pairing: it will produce a confident, wrong matching.
The preprocessing pipeline¶
Order matters.
- Build shared feature sets. Align both modalities on pre-established biological correspondences (RNA gene ↔ protein marker).
- Variability filtering (shared). Keep features whose standard deviation across cells exceeds a modality-specific threshold.
- Normalise by target total. Scale each cell to the median total count of its dataset.
log(X+1)transform. Stabilises variance, reduces skew.- HVG selection (active, RNA-type only). Seurat V3 method; highest normalised dispersion within expression-level bins.
- Scale to zero mean, unit variance across features.
- Variability filtering (active). By standard deviation, applied last.
cli preprocess data cite_seq_and_pbmc --out ./data/preprocessed
cli preprocess info cite_seq_and_pbmc
Dataset parameters¶
| Dataset | Type | Top HVGs | Filter (active) | Filter (shared) | Active shape | Shared shape |
|---|---|---|---|---|---|---|
| Antibodies | CITE-seq | — | 1e-5 | 1e-5 | 10,000 × 1,707 | 10,000 × 177 |
| Antibodies | PBMC | n/a | 1e-5 | 1e-5 | 10,000 × 224 | 10,000 × 177 |
| Tonsils | scRNA-seq | 5,000 | 1e-5 | 0.5 | 12,977 × 5,000 | 12,977 × 32 |
| Tonsils | CODEX | n/a | 1e-5 | 0.1 | 178,919 × 46 | 178,919 × 32 |
Read this table for the ratios, not the numbers. Antibodies gives 177 shared columns out of 1,707 active RNA features (~10%); Tonsils gives 32 out of 5,000 (~0.6%). The Tonsils seed matching is built on a far thinner slice, which is a large part of why it is the harder dataset throughout the results.
Note also the asymmetric shared thresholds on Tonsils (0.5 for scRNA vs 0.1 for CODEX). CODEX has only 57 raw features, so an aggressive threshold would leave nothing. Scale filtering thresholds to the feature-space size of each modality.
Meta-cells¶
For modalities with a high signal-to-noise ratio (CITE-seq, scRNA-seq), cells are optionally aggregated into meta-cells: Leiden clustering builds communities, and each community's cells are averaged to a centroid.
- Controlled by
meta_cell_size(thesis default: 2). - Applied to one modality only; the other stays at original resolution (non-meta).
- The centroid graph, not the single-cell graph, is then used downstream.
Meta-cells are not free
Aggregation trades structural fidelity for speed. In the results, the meta-modality shows consistently lower cohesiveness, meaning MaxFuse invents cluster structure absent from the original data, along with worse MRRE-missing scores. Use meta-cells when you can afford that cost, not by default. See Comparison with Centralized MaxFuse.
Graph construction and smoothing targets¶
Each node then builds a k-NN graph (nearest_neighbors: 15) on its active data and clusters
it with Leiden. Those clusters become the shrinkage targets for fuzzy smoothing.
This is the mechanism that makes weak linkage tractable: the graph comes from the rich all-feature space, and the smoothing it induces is applied to the poor shared-feature space.
where \(C\) is the neighbourhood (or cluster-centroid) average. Note that \(\omega = 1\) means no smoothing, and smaller \(\omega\) means stronger smoothing. Weak linkage therefore calls for a lower \(\omega\): the Tonsils configuration uses 0.3 where Antibodies uses 0.7.
Anti-patterns¶
- Dropping shared columns independently per modality. Breaks the correspondence silently.
- Applying HVG selection to protein modalities. It is RNA-specific.
- One filtering threshold across modalities. Scale it to each feature space.
- Building meta-cells on low-SNR modalities. The centroid stops being meaningful.
- Skipping
log(X+1). High-count features then dominate the correlation.