Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 15 additions & 1 deletion docs/tutorial.md
Original file line number Diff line number Diff line change
Expand Up @@ -110,7 +110,21 @@ plt.tight_layout()
plt.show()
```

`bicv` returns a long-form DataFrame (columns `Rank`, `Repeat`, `Metric`, `R2X`) suitable for further analysis as well as plotting. Each BiCV trial holds out `held_out_cell_frac` of the cells within each condition and `held_out_gene_frac` of the genes (both default to 0.2); increase `n_repeats` for a smoother, less noisy BiCV curve at the cost of more compute.
`bicv` returns a long-form DataFrame (columns `Rank`, `Repeat`, `Metric`, `R2X`, plus the per-trial diagnostics below) suitable for further analysis as well as plotting. Each BiCV trial holds out `held_out_cell_frac` of the cells within each condition and `held_out_gene_frac` of the genes (both default to 0.2); increase `n_repeats` for a smoother, less noisy BiCV curve at the cost of more compute.

Each BiCV row also carries the diagnostics needed to audit the curve rather than just plot it:

| column | what it is for |
| :----- | :------------- |
| `Train Block R2X` | In-sample $R^2X$ on the block the model was fit to. A positive interpretation is typically this metric climbing while the held-out $R^2X$ turns over. |
| `NTrainGenes`, `NTestGenes`, `NTrainCells`, `NTestCells` | The realised block sizes which set the scale of the spread across repeats. |
| `Seed` | The seed that determines the trial's splits and initialisation, so a single trial can be replayed on its own. |

```python
# Does the held-out score turn over while the in-sample one keeps climbing?
trials = results[results["Metric"] == "BiCV R2X"]
print(trials.groupby("Rank")[["R2X", "Train Block R2X"]].mean())
```

If you plan to fit the final model with non-default `parafac2_nd` options (e.g. `normalize_slices=True`, see [Handling Unequal Cell Counts](unequal_cell_counts.md)), pass the same options to `bicv` via `parafac2_kwarg` so that rank selection is evaluated under the same fitting behavior:

Expand Down
204 changes: 163 additions & 41 deletions scrise/rank_selection.py
Original file line number Diff line number Diff line change
Expand Up @@ -12,23 +12,18 @@

import warnings
from collections.abc import Sequence
from typing import Any
from typing import Any, cast

import anndata
import numpy as np
import pandas as pd
import scipy.sparse as sps
from parafac2.utils import calc_W, condition_slices, project_data
from parafac2.utils import calc_W, condition_slices, project_data, rmatmul
from tqdm import tqdm

from ._pf2_utils import run_parafac2


def _dense(mat) -> np.ndarray:
"""Return a dense ndarray view of a (possibly sparse) matrix."""
return mat.toarray() if sps.issparse(mat) else np.asarray(mat)


def _split_cells_by_condition(
cond_idx: np.ndarray, held_out_frac: float, rng: np.random.Generator
) -> np.ndarray:
Expand Down Expand Up @@ -76,19 +71,86 @@ def _max_feasible_rank(
return int(min(min_train_cells, n_train_genes))


def _cell_loadings(
projections: list[np.ndarray],
B: np.ndarray,
A: np.ndarray,
cond: np.ndarray,
n_cond: int,
) -> np.ndarray:
"""Per-cell loadings for a set of cells, in those cells' own row order."""
rank = B.shape[1]
Z = np.empty((cond.size, rank), dtype=np.float64)
for i in range(n_cond):
sel = cond == i
if np.any(sel):
Z[sel] = (projections[i] @ B) * A[i]
return Z


# Nonzeros per row block when streaming column moments. Bounds the per-nonzero
# temporaries to a few hundred MB regardless of how large the matrix is.
_MOMENT_CHUNK_NNZ = 50_000_000


def _test_block_moments(
X_mat: Any, cell_mask: np.ndarray, gene_idx: np.ndarray
) -> tuple[np.ndarray, np.ndarray]:
"""Column sums and sums of squares over a cell subset, for chosen genes."""
n_genes = X_mat.shape[1]
wanted = np.zeros(n_genes, dtype=bool)
wanted[gene_idx] = True
sums = np.zeros(n_genes)
squares = np.zeros(n_genes)

if not sps.issparse(X_mat):
block = np.asarray(X_mat)[cell_mask]
# Both moments accumulate in float64. A float32 block summed in its own
# dtype carries ~1e-4 relative error over a few hundred thousand rows,
# which would reach the reported R2X through `ss_tot`.
return (
block.sum(axis=0, dtype=np.float64)[gene_idx],
np.sum(block.astype(np.float64) ** 2, axis=0)[gene_idx],
)

mat = X_mat.tocsr() if X_mat.format != "csr" else X_mat
n_rows = mat.shape[0]
start = 0
while start < n_rows:
stop = min(
n_rows,
max(
start + 1,
int(np.searchsorted(mat.indptr, mat.indptr[start] + _MOMENT_CHUNK_NNZ)),
),
)
lo, hi = int(mat.indptr[start]), int(mat.indptr[stop])
data = mat.data[lo:hi].astype(np.float64)
cols = mat.indices[lo:hi]
keep = wanted[cols] & np.repeat(
cell_mask[start:stop], np.diff(mat.indptr[start : stop + 1])
)
data, cols = data[keep], cols[keep]
sums += np.bincount(cols, weights=data, minlength=n_genes)
squares += np.bincount(cols, weights=data**2, minlength=n_genes)
start = stop

return sums[gene_idx], squares[gene_idx]


def _bicv_trial(
X: anndata.AnnData,
rank: int,
held_out_cell_frac: float,
held_out_gene_frac: float,
rng: np.random.Generator,
seed: int,
tolerance: float,
max_iter: int,
compress: int | tuple[int, int | None] | str | bool | None = "auto",
compression_kwarg: dict[str, Any] | None = None,
parafac2_kwarg: dict[str, Any] | None = None,
) -> float:
"""Run a single bi-cross-validation trial and return the held-out R2X.
) -> dict[str, float]:
"""Run a single bi-cross-validation trial and return its scores and shape.

Splits cells (stratified by condition) and genes into train/test blocks,
fits PARAFAC2 on the train-cell x train-gene block, then predicts the
Expand All @@ -103,7 +165,14 @@ def _bicv_trial(

R2X is then computed by reconstructing the held-out block from these
estimates and comparing against the (mean-centered) observed values.

Returns
-------
dict[str, float]
``BiCV R2X`` (the held-out block), ``Train Block R2X`` (in-sample, on
the block the model was fit to), the four block sizes, and ``Seed``.
"""
rng = np.random.default_rng(seed)
cond_idx = X.obs["condition_unique_idxs"].to_numpy().astype(int)
n_cond = int(cond_idx.max()) + 1
means = X.var["means"].to_numpy() if "means" in X.var else np.zeros(X.n_vars)
Expand All @@ -113,7 +182,7 @@ def _bicv_trial(
train_gene_mask, test_gene_mask = _split_genes(X.n_vars, held_out_gene_frac, rng)

X_train = X[train_cell_mask][:, train_gene_mask].copy()
(weights, (A, B, C), P_train), _ = run_parafac2(
(weights, (A, B, C), P_train), train_block_r2x = run_parafac2(
X_train,
rank=rank,
random_state=int(rng.integers(np.iinfo(np.int32).max)),
Expand All @@ -125,41 +194,72 @@ def _bicv_trial(
)
A = A * weights

# Everything below reaches the raw data through products against the raw
# matrix rather than materialising a block of it. Cells are restricted by
# slicing the rows (cheap on CSR, and keeps the product proportional to the
# rows actually wanted); genes are restricted by zeroing the dense operand,
# since a column slice of CSR is not.
#
# The dense operands below are deliberately float64, unlike `calc_W` and
# `parafac_update`, which cast theirs to the matrix dtype to avoid upcasting
# a float32 matrix. Here accuracy wins: `ss_res` is a difference of large
# terms and the scores are O(1e-2), whereas a float32 operand costs ~3e-2
# relative error on the product.
assert X.X is not None
X_mat = cast("np.ndarray | sps.csr_array", X.X)
n_genes = X.n_vars
test_gene_idx = np.flatnonzero(test_gene_mask)
means_test_genes = means[test_gene_mask]

# Estimate gene loadings for the held-out genes from the train cells.
# Z^T (X[train, test] - 1 mu^T) = (Z^T X[train])[:, test] - (Z^T 1) mu^T
cond_train = cond_idx[train_cell_mask]
Z = np.concatenate(
[(P_train[i] @ B) * A[i] for i in range(n_cond) if np.any(cond_train == i)],
axis=0,
)
means_test_genes = means[test_gene_mask]
X_train_test_genes = (
_dense(X[train_cell_mask][:, test_gene_mask].X) - means_test_genes
)
C_test = np.linalg.lstsq(Z, X_train_test_genes, rcond=None)[0].T
Z = _cell_loadings(P_train, B, A, cond_train, n_cond)
ZtY = np.asarray(
rmatmul(np.ascontiguousarray(Z.T), X_mat[train_cell_mask]), dtype=np.float64
)[:, test_gene_idx]
ZtY -= np.outer(Z.sum(axis=0), means_test_genes)
# `lstsq` on the rank x rank system keeps the minimum-norm
# behaviour when the fit is rank deficient.
C_test = np.linalg.lstsq(Z.T @ Z, ZtY, rcond=None)[0].T

# Estimate projections for the held-out cells from the train genes.
means_train_genes = means[train_gene_mask]
C_full = np.zeros((n_genes, C.shape[1]))
C_full[train_gene_mask] = C
cond_test = cond_idx[test_cell_mask]
X_test_train_genes = _dense(X[test_cell_mask][:, train_gene_mask].X)
W_test = calc_W(X_test_train_genes, means_train_genes, C)
W_test = calc_W(X_mat[test_cell_mask], means, C_full)
cond_slices_test = condition_slices(cond_test, n_cond)
P_test, _ = project_data(W_test, [A, B, C], cond_slices_test)

# Reconstruct and score the held-out test-cell x test-gene block.
X_test_test_genes = (
_dense(X[test_cell_mask][:, test_gene_mask].X) - means_test_genes
# Score the held-out block.
L = _cell_loadings(P_test, B, A, cond_test, n_cond)
LtY = np.asarray(
rmatmul(np.ascontiguousarray(L.T), X_mat[test_cell_mask]), dtype=np.float64
)[:, test_gene_idx]
LtY -= np.outer(L.sum(axis=0), means_test_genes)

col_sums, col_squares = _test_block_moments(X_mat, test_cell_mask, test_gene_idx)
n_test_cells = int(test_cell_mask.sum())
ss_tot = float(
np.sum(
col_squares
- 2.0 * means_test_genes * col_sums
+ n_test_cells * means_test_genes**2
)
)
ss_res, ss_tot = 0.0, 0.0
for i in range(n_cond):
sel = cond_test == i
if not np.any(sel):
continue
actual = X_test_test_genes[sel]
recon = ((P_test[i] @ B) * A[i]) @ C_test.T
ss_res += float(np.sum((actual - recon) ** 2))
ss_tot += float(np.sum(actual**2))
cross = float(np.sum(C_test.T * LtY))
ss_fit = float(np.sum((L.T @ L) * (C_test.T @ C_test)))
ss_res = ss_tot - 2.0 * cross + ss_fit

return 1.0 - ss_res / ss_tot
return {
"BiCV R2X": 1.0 - ss_res / ss_tot,
"Train Block R2X": float(train_block_r2x),
"NTrainGenes": int(train_gene_mask.sum()),
"NTestGenes": int(test_gene_mask.sum()),
"NTrainCells": int(train_cell_mask.sum()),
"NTestCells": int(test_cell_mask.sum()),
"Seed": int(seed),
}


def bicv(
Expand Down Expand Up @@ -228,9 +328,22 @@ def bicv(
Returns
-------
pandas.DataFrame
Long-form DataFrame with columns "Rank", "Repeat", "Metric"
(one of "Fit R2X" or "BiCV R2X"), and "R2X". Ready to pass to
Long-form DataFrame with columns "Rank", "Repeat", "Metric" (one of
"Fit R2X" or "BiCV R2X"), and "R2X". Ready to pass to
:func:`scrise.plotting.plot_bicv_r2x`.

BiCV rows carry per-trial diagnostics as additional columns:

``Train Block R2X``
In-sample R2X on the block the model was actually fit to.
``NTrainGenes``, ``NTestGenes``, ``NTrainCells``, ``NTestCells``
The realised block sizes, which set the scale of the spread across
repeats.
``Seed``
The seed that determines the trial's splits and initialisation.

These columns are NaN on "Fit R2X" rows, which come from an
unsplit fit on the full dataset.
"""
if X is None and adata is not None:
X = adata
Expand Down Expand Up @@ -279,23 +392,32 @@ def bicv(
compression_kwarg=compression_kwarg,
parafac2_kwarg=parafac2_kwarg,
)
# The full-data fit has no split, so the per-trial columns are absent
# here rather than zero.
rows.append({"Rank": rank, "Repeat": 0, "Metric": "Fit R2X", "R2X": fit_r2x})

for repeat in range(n_repeats):
bicv_r2x = _bicv_trial(
trial_seed = int(rng.integers(np.iinfo(np.int32).max))
trial = _bicv_trial(
X,
rank,
held_out_cell_frac,
held_out_gene_frac,
rng,
trial_seed,
tolerance,
max_iter,
compress,
compression_kwarg,
parafac2_kwarg,
)
rows.append(
{"Rank": rank, "Repeat": repeat, "Metric": "BiCV R2X", "R2X": bicv_r2x}
{
"Rank": rank,
"Repeat": repeat,
"Metric": "BiCV R2X",
"R2X": trial.pop("BiCV R2X"),
**trial,
}
)

results = pd.DataFrame(rows)
Expand Down
Loading