Skip to content

Commit 15fdc6b

Browse files
aarmeyclaudeAaron Meyer
authored
Add property-based, contract, regression, and plotting tests (#536)
* Add property-based, contract, regression, and plotting tests Fills the gaps identified in the testing-strategy review: Hypothesis-driven invariant tests for the core factorization/OPQ primitives, explicit error-path tests for documented AnnData-key/parameter contracts, a golden regression fixture pinning pf2() output on fixed synthetic data, and smoke tests for the previously ~0-30%-covered plotting modules. Adds hypothesis as a dev dependency and a shared synthetic-data conftest, and gates CI on 85% coverage (currently 89%) via tool.coverage.report.fail_under. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> * Include weights in energy-based component ordering --------- Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com> Co-authored-by: Aaron Meyer <git@ameyer.me>
1 parent 20e486f commit 15fdc6b

13 files changed

Lines changed: 1126 additions & 21 deletions

‎docs/component_ordering.md‎

Lines changed: 13 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -39,19 +39,21 @@ footing (i.e. a fixed sign and a fixed ordering rule).
3939
RISE orders components by their intrinsic energy,
4040

4141
$$
42-
e_r = \lVert \mathbf{A}[:, r] \rVert \cdot \lVert \mathbf{C}[:, r] \rVert,
42+
e_r = |w_r| \cdot \lVert \mathbf{A}[:, r] \rVert \cdot \lVert \mathbf{C}[:, r] \rVert,
4343
$$
4444

45-
the product of the condition-factor and gene-factor column norms for
46-
component $r$. This quantity is directly determined by the fit: unlike the
47-
Gini coefficient, it is not distorted by the arbitrary rescaling that can
48-
occur between $\mathbf{A}$ and $\mathbf{C}$ during optimization (their
49-
product is fixed by the fit, but how that product is split between the two
50-
factors is not). Components are sorted from highest to lowest energy, so
51-
that low-energy components — typically the ones that appear only once the
52-
rank is increased — land at the high end of the ordering, while
53-
established, high-energy components stay near the front. This is
54-
implemented in [`RISE.order_components_by_energy`][RISE.factorization.order_components_by_energy]
45+
the product of the component weight, condition-factor column norm, and
46+
gene-factor column norm for component $r$. (Because standard PARAFAC2 factor
47+
normalization scales the columns of $\mathbf{A}$, $\mathbf{B}$, and
48+
$\mathbf{C}$ to unit length, this energy corresponds directly to $|w_r|$ while
49+
remaining invariant to any alternative scale distribution among the factors.)
50+
This quantity is directly determined by the fit: unlike the Gini coefficient,
51+
it is not distorted by arbitrary rescaling between factor matrices. Components
52+
are sorted from highest to lowest energy, so that low-energy components —
53+
typically the ones that appear only once the rank is increased — land at the
54+
high end of the ordering, while established, high-energy components stay near
55+
the front. This is implemented in
56+
[`RISE.order_components_by_energy`][RISE.factorization.order_components_by_energy]
5557
and is applied automatically inside [`RISE.pf2`][RISE.factorization.pf2].
5658

5759
## Sign convention

‎pyproject.toml‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -68,6 +68,7 @@ dev = [
6868
{ include-group = "analysis" },
6969
"pytest>=9.0",
7070
"pytest-cov>=7.0",
71+
"hypothesis>=6.140",
7172
"ty",
7273
"ruff>=0.16",
7374
]
@@ -84,3 +85,7 @@ filterwarnings = [
8485
"ignore::DeprecationWarning",
8586
"ignore::PendingDeprecationWarning:seaborn",
8687
]
88+
89+
[tool.coverage.report]
90+
fail_under = 85
91+
omit = ["scrise/tests/*"]

‎scrise/factorization.py‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -100,9 +100,9 @@ def order_components_by_energy(X: anndata.AnnData) -> anndata.AnnData:
100100
components of the new fit correspond to the N components of the old fit.
101101
102102
This function instead orders components by their intrinsic energy,
103-
``||A[:, r]|| * ||C[:, r]||`` (the product of the condition-factor and
104-
gene-factor column norms), which is directly determined by the fit and
105-
is not subject to the arbitrary rescaling that can occur between A and C.
103+
``|weights[r]| * ||A[:, r]|| * ||C[:, r]||`` (the product of component
104+
weights, condition-factor, and gene-factor column norms), which is
105+
directly determined by the fit and is not subject to arbitrary rescaling.
106106
Components are ordered from highest to lowest energy, so that low-energy
107107
components -- which tend to be the ones added when the rank is
108108
increased -- land at the high end of the ordering. This is consistent
@@ -142,7 +142,7 @@ def order_components_by_energy(X: anndata.AnnData) -> anndata.AnnData:
142142
A = A * signs
143143
C = C * signs
144144

145-
energy = np.linalg.norm(A, axis=0) * np.linalg.norm(C, axis=0)
145+
energy = np.abs(weights) * np.linalg.norm(A, axis=0) * np.linalg.norm(C, axis=0)
146146
order = np.argsort(energy)[::-1]
147147

148148
X.uns["Pf2_A"] = A[:, order]

‎scrise/tests/conftest.py‎

Lines changed: 135 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,135 @@
1+
"""
2+
Shared fixtures and synthetic-data factories for the scrise test suite.
3+
"""
4+
5+
from collections.abc import Mapping, Sequence
6+
from typing import Any, cast
7+
8+
import anndata
9+
import matplotlib
10+
import numpy as np
11+
import pandas as pd
12+
import pytest
13+
14+
matplotlib.use("Agg")
15+
16+
import matplotlib.pyplot as plt # noqa: E402
17+
18+
19+
@pytest.fixture(autouse=True)
20+
def _close_figures():
21+
"""Prevent matplotlib figures from accumulating across tests."""
22+
yield
23+
plt.close("all")
24+
25+
26+
def make_synthetic_pf2_data(
27+
n_cond: int = 5,
28+
n_genes: int = 40,
29+
rank: int = 3,
30+
seed: int = 0,
31+
cells_per_cond: tuple[int, int] = (60, 90),
32+
) -> anndata.AnnData:
33+
"""Build a synthetic AnnData with a known low-rank PARAFAC2-like structure.
34+
35+
Mirrors the generator originally written for ``test_rank_selection.py``
36+
so every test module shares one synthetic-data factory instead of
37+
hand-rolling its own. The data is a noisy realization of
38+
``(Z_i @ B) * A[i] @ C.T`` per condition ``i``, which is exactly the
39+
structure PARAFAC2 assumes, so a real ``pf2()`` fit on this data
40+
recovers ``A``/``B``/``C`` up to the usual permutation/sign/scale
41+
ambiguity.
42+
"""
43+
rng = np.random.default_rng(seed)
44+
B = rng.normal(size=(rank, rank))
45+
C = rng.normal(size=(n_genes, rank))
46+
A = rng.normal(size=(n_cond, rank))
47+
48+
X_list = []
49+
cond_idx = []
50+
for i in range(n_cond):
51+
n_cells = int(rng.integers(*cells_per_cond))
52+
Z = rng.normal(size=(n_cells, rank))
53+
signal = (Z @ B) * A[i] @ C.T
54+
noise = rng.normal(scale=0.2, size=signal.shape)
55+
X_list.append(signal + noise)
56+
cond_idx += [i] * n_cells
57+
58+
X = np.concatenate(X_list, axis=0).astype(np.float32)
59+
n_cells_total = X.shape[0]
60+
61+
obs = pd.DataFrame(
62+
{
63+
"condition_unique_idxs": pd.Categorical(cond_idx),
64+
"Condition": pd.Categorical([f"cond_{i}" for i in cond_idx]),
65+
}
66+
)
67+
var = pd.DataFrame(
68+
{"gene_name": [f"gene_{j}" for j in range(n_genes)]},
69+
index=[f"gene_{j}" for j in range(n_genes)],
70+
)
71+
72+
adata = anndata.AnnData(X=X, obs=obs, var=var)
73+
adata.var["means"] = np.zeros(n_genes)
74+
adata.obs_names = [f"cell_{i}" for i in range(n_cells_total)]
75+
return adata
76+
77+
78+
def make_mock_factored_adata(
79+
n_cells: int = 40,
80+
n_genes: int = 25,
81+
n_conditions: int = 6,
82+
rank: int = 3,
83+
seed: int = 0,
84+
with_embedding: bool = False,
85+
) -> anndata.AnnData:
86+
"""Build an AnnData already populated with (random, not fitted) RISE
87+
factors -- i.e. what ``pf2()`` would have attached -- for testing
88+
downstream consumers (reordering, plotting, export) without paying for
89+
an actual PARAFAC2 fit."""
90+
rng = np.random.default_rng(seed)
91+
92+
A = rng.normal(size=(n_conditions, rank)).astype(np.float32)
93+
C = rng.normal(size=(n_genes, rank)).astype(np.float32)
94+
B = rng.normal(size=(rank, rank)).astype(np.float32)
95+
weights = rng.random(rank).astype(np.float32)
96+
projections, _ = np.linalg.qr(rng.normal(size=(n_cells, rank)))
97+
projections = projections.astype(np.float32)
98+
99+
cond_idx = [i % n_conditions for i in range(n_cells)]
100+
obs = pd.DataFrame(
101+
{
102+
"Condition": pd.Categorical([f"cond_{i}" for i in cond_idx]),
103+
"condition_unique_idxs": pd.Categorical(cond_idx),
104+
"Cell Type": pd.Categorical([f"type_{i % 3}" for i in range(n_cells)]),
105+
}
106+
)
107+
var = pd.DataFrame(
108+
{"means": np.zeros(n_genes)},
109+
index=[f"gene_{j}" for j in range(n_genes)],
110+
)
111+
112+
obsm = {"projections": projections, "weighted_projections": projections @ B}
113+
if with_embedding:
114+
obsm["X_pf2_PaCMAP"] = rng.normal(size=(n_cells, 2)).astype(np.float32)
115+
116+
adata = anndata.AnnData(
117+
X=rng.normal(size=(n_cells, n_genes)).astype(np.float32),
118+
obs=obs,
119+
var=var,
120+
uns={"Pf2_A": A, "Pf2_B": B, "Pf2_weights": weights},
121+
varm=cast(Mapping[str, Sequence[Any]], {"Pf2_C": C}),
122+
obsm=cast(Mapping[str, Sequence[Any]], obsm),
123+
)
124+
adata.obs_names = [f"cell_{i}" for i in range(n_cells)]
125+
return adata
126+
127+
128+
@pytest.fixture
129+
def synthetic_pf2_adata():
130+
return make_synthetic_pf2_data()
131+
132+
133+
@pytest.fixture
134+
def mock_factored_adata():
135+
return make_mock_factored_adata()

‎scrise/tests/test_component_ordering.py‎

Lines changed: 8 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -66,15 +66,17 @@ def test_order_components_by_energy_descending():
6666
scales = np.array([0.01, 10.0, 1.0, 5.0])
6767
A = A * scales
6868
expected_energy_order = np.argsort(
69-
np.linalg.norm(A, axis=0) * np.linalg.norm(C, axis=0)
69+
np.abs(weights) * np.linalg.norm(A, axis=0) * np.linalg.norm(C, axis=0)
7070
)[::-1]
7171

7272
adata = _mock_adata(A.copy(), B.copy(), C.copy(), weights.copy(), projections)
7373
ordered = order_components_by_energy(adata)
7474

75-
new_energy = np.linalg.norm(
76-
np.array(ordered.uns["Pf2_A"]), axis=0
77-
) * np.linalg.norm(np.array(ordered.varm["Pf2_C"]), axis=0)
75+
new_energy = (
76+
np.abs(np.array(ordered.uns["Pf2_weights"]))
77+
* np.linalg.norm(np.array(ordered.uns["Pf2_A"]), axis=0)
78+
* np.linalg.norm(np.array(ordered.varm["Pf2_C"]), axis=0)
79+
)
7880
assert np.all(np.diff(new_energy) <= 1e-8)
7981

8082
# Check that the columns were permuted as expected (up to sign).
@@ -109,7 +111,7 @@ def test_order_components_by_energy_preserves_reconstruction():
109111

110112
# Column r of after_wp, weighted by A/C for that component, should match
111113
# some permuted (and consistently signed) column of before_wp.
112-
energy = np.linalg.norm(A, axis=0) * np.linalg.norm(C, axis=0)
114+
energy = np.abs(weights) * np.linalg.norm(A, axis=0) * np.linalg.norm(C, axis=0)
113115
order = np.argsort(energy)[::-1]
114116

115117
# B itself is left as the unflipped sign reference, so weighted_projections
@@ -128,7 +130,7 @@ def test_order_components_by_energy_reorders_weights_and_B():
128130
weights = np.arange(rank, dtype=float)
129131
projections, _ = np.linalg.qr(rng.normal(size=(n_cells, rank)))
130132

131-
energy = np.linalg.norm(A, axis=0) * np.linalg.norm(C, axis=0)
133+
energy = np.abs(weights) * np.linalg.norm(A, axis=0) * np.linalg.norm(C, axis=0)
132134
order = np.argsort(energy)[::-1]
133135

134136
adata = _mock_adata(A.copy(), B.copy(), C.copy(), weights.copy(), projections)

‎scrise/tests/test_contracts.py‎

Lines changed: 148 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,148 @@
1+
"""
2+
Contract / error-path tests.
3+
4+
Every public function in `scrise.factorization` and `scrise.rank_selection`
5+
documents required AnnData keys and value ranges in its docstring. These
6+
tests pin down what actually happens when a caller violates that contract
7+
(missing keys, wrong dtypes, out-of-range parameters) so a future change
8+
can't silently turn a clear error into a confusing downstream crash (or
9+
worse, a silently wrong result) without a test noticing.
10+
"""
11+
12+
from collections.abc import Mapping, Sequence
13+
from typing import Any, cast
14+
15+
import anndata
16+
import numpy as np
17+
import pandas as pd
18+
import pytest
19+
20+
from ..factorization import (
21+
correct_conditions,
22+
export_factors,
23+
order_components_by_energy,
24+
pf2,
25+
)
26+
from ..rank_selection import bicv
27+
from .conftest import make_synthetic_pf2_data
28+
29+
30+
def test_pf2_missing_condition_idxs_raises():
31+
"""pf2() requires X.obs['condition_unique_idxs']; without it the
32+
caller gets a clear KeyError rather than a cryptic failure deep inside
33+
the PARAFAC2 solver."""
34+
X = anndata.AnnData(X=np.random.rand(10, 5).astype(np.float32))
35+
with pytest.raises(KeyError, match="condition_unique_idxs"):
36+
pf2(X, rank=2, doEmbedding=False, compress=None)
37+
38+
39+
def test_correct_conditions_missing_condition_idxs_raises():
40+
X = anndata.AnnData(X=np.random.rand(10, 5).astype(np.float32))
41+
with pytest.raises(KeyError, match="condition_unique_idxs"):
42+
correct_conditions(X)
43+
44+
45+
def test_correct_conditions_none_X_raises_typeerror():
46+
"""correct_conditions has an explicit guard for X.X is None (e.g. a
47+
factors-only AnnData produced by export_factors) -- it should fail
48+
clearly rather than crash inside `.sum()`."""
49+
obs = pd.DataFrame({"condition_unique_idxs": [0, 0, 1, 1]})
50+
X = anndata.AnnData(X=None, obs=obs, shape=(4, 3))
51+
X.uns["Pf2_A"] = np.ones((2, 2))
52+
with pytest.raises(TypeError, match="X.X must not be None"):
53+
correct_conditions(X)
54+
55+
56+
@pytest.mark.parametrize("missing_key", ["Pf2_A", "Pf2_B", "Pf2_weights"])
57+
def test_order_components_by_energy_missing_uns_key_raises(missing_key):
58+
keys = {"Pf2_A", "Pf2_B", "Pf2_weights"}
59+
rank, n_genes, n_conditions = 2, 5, 3
60+
uns = {
61+
"Pf2_A": np.ones((n_conditions, rank)),
62+
"Pf2_B": np.ones((rank, rank)),
63+
"Pf2_weights": np.ones(rank),
64+
}
65+
del uns[missing_key]
66+
X = anndata.AnnData(
67+
X=np.zeros((6, n_genes), dtype=np.float32),
68+
uns=uns,
69+
varm=cast(Mapping[str, Sequence[Any]], {"Pf2_C": np.ones((n_genes, rank))}),
70+
)
71+
with pytest.raises(KeyError, match=missing_key):
72+
order_components_by_energy(X)
73+
assert missing_key in keys # sanity: parametrization matches the real keys
74+
75+
76+
@pytest.mark.parametrize(
77+
"missing",
78+
["uns:Pf2_A", "uns:Pf2_B", "uns:Pf2_weights", "varm:Pf2_C", "obsm:projections"],
79+
)
80+
def test_export_factors_missing_any_required_field_raises_keyerror(tmp_path, missing):
81+
n_cells, n_genes, rank = 10, 6, 2
82+
fields = {
83+
"uns:Pf2_A": ("uns", "Pf2_A", np.ones((3, rank))),
84+
"uns:Pf2_B": ("uns", "Pf2_B", np.ones((rank, rank))),
85+
"uns:Pf2_weights": ("uns", "Pf2_weights", np.ones(rank)),
86+
"varm:Pf2_C": ("varm", "Pf2_C", np.ones((n_genes, rank))),
87+
"obsm:projections": ("obsm", "projections", np.ones((n_cells, rank))),
88+
}
89+
uns, varm, obsm = {}, {}, {}
90+
dest = {"uns": uns, "varm": varm, "obsm": obsm}
91+
for key, (section, name, value) in fields.items():
92+
if key == missing:
93+
continue
94+
dest[section][name] = value
95+
96+
X = anndata.AnnData(
97+
X=np.zeros((n_cells, n_genes), dtype=np.float32), uns=uns, varm=varm, obsm=obsm
98+
)
99+
with pytest.raises(KeyError):
100+
export_factors(X, str(tmp_path / "out.h5ad"))
101+
102+
103+
@pytest.mark.parametrize(
104+
"kwargs",
105+
[
106+
{"held_out_cell_frac": 0.0},
107+
{"held_out_cell_frac": 1.0},
108+
{"held_out_cell_frac": -0.1},
109+
{"held_out_gene_frac": 0.0},
110+
{"held_out_gene_frac": 1.5},
111+
{"n_repeats": 0},
112+
{"n_repeats": -1},
113+
],
114+
)
115+
def test_bicv_rejects_invalid_arguments(kwargs):
116+
X = make_synthetic_pf2_data(n_cond=4, n_genes=20, rank=2, seed=0)
117+
with pytest.raises(ValueError):
118+
bicv(X, [2], **kwargs)
119+
120+
121+
def test_bicv_rejects_rank_exceeding_max_feasible_rank():
122+
X = make_synthetic_pf2_data(n_cond=3, n_genes=10, rank=2, seed=0)
123+
with pytest.raises(ValueError, match="exceeds the maximum feasible rank"):
124+
bicv(X, [10_000])
125+
126+
127+
def test_export_factors_output_directory_is_created(tmp_path):
128+
"""export_factors should create any missing parent directories for the
129+
output path rather than failing with FileNotFoundError."""
130+
n_cells, n_genes, rank = 10, 6, 2
131+
X = anndata.AnnData(
132+
X=np.zeros((n_cells, n_genes), dtype=np.float32),
133+
uns={
134+
"Pf2_A": np.random.rand(3, rank),
135+
"Pf2_B": np.random.rand(rank, rank),
136+
"Pf2_weights": np.random.rand(rank),
137+
},
138+
varm=cast(
139+
Mapping[str, Sequence[Any]], {"Pf2_C": np.random.rand(n_genes, rank)}
140+
),
141+
obsm=cast(
142+
Mapping[str, Sequence[Any]],
143+
{"projections": np.random.rand(n_cells, rank).astype(np.float32)},
144+
),
145+
)
146+
out_path = tmp_path / "nested" / "dir" / "out.h5ad"
147+
export_factors(X, str(out_path))
148+
assert out_path.exists()

0 commit comments

Comments
 (0)