Skip to content

Commit 0de3096

Browse files
fishidahoclaude
andcommitted
Align the training-cell loadings with the rows they are regressed against
Fixes #546. `_bicv_trial` built the held-out gene regression's design matrix by concatenating per-condition blocks in condition order: Z = np.concatenate( [(P_train[i] @ B) * A[i] for i in range(n_cond) if np.any(cond_train == i)], axis=0, ) but regressed it against `X_train_test_genes`, which stays in the training cells' natural row order. `P_train[i]` lists condition `i`'s cells in their within-condition order, so concatenating produces `Z` sorted by condition. The two orderings coincide only when conditions happen to be stored as contiguous blocks. On pooled data -- a Perturb-seq screen, or anything not physically sorted by sample before sequencing -- conditions are interleaved, and row `k` of `Z` then describes a different cell from row `k` of the expression it is paired with. Every held-out R2X the function reports is computed from that least-squares fit. `_train_cell_loadings` scatters each condition's block back to the positions its cells actually occupy. Same asymptotic cost, and identical output in the contiguous case. Three of the four new tests fail against the previous implementation and pass against this one; the fourth asserts the no-op on contiguous input, and passes either way by construction. That split is deliberate -- without the "differ when interleaved" test, an implementation that quietly reverted to concatenation would still satisfy the rest. The missing-condition case is also covered: when a fold leaves some condition with no training cells, concatenation produced the right number of rows in the wrong order, which is the same defect in a form that is even harder to notice. Why every existing test missed this: `_make_test_data` builds conditions as contiguous blocks, which is precisely the case where the bug is invisible. The end-to-end test added here stores the same cells interleaved. Reported by @aarmey, with the diagnosis and the suggested fix. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
1 parent 0d344ac commit 0de3096

2 files changed

Lines changed: 145 additions & 5 deletions

File tree

‎scrise/rank_selection.py‎

Lines changed: 26 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -76,6 +76,31 @@ def _max_feasible_rank(
7676
return int(min(min_train_cells, n_train_genes))
7777

7878

79+
def _train_cell_loadings(
80+
P_train: list[np.ndarray],
81+
B: np.ndarray,
82+
A: np.ndarray,
83+
cond_train: np.ndarray,
84+
n_cond: int,
85+
) -> np.ndarray:
86+
"""Per-cell loadings for the training cells, in the cells' own row order.
87+
88+
`P_train[i]` lists condition ``i``'s cells in their within-condition order,
89+
so the blocks have to be *scattered back* to the positions those cells
90+
occupy, not concatenated in condition order. The two agree only when
91+
conditions happen to be stored as contiguous blocks; on pooled data, where
92+
conditions are interleaved, concatenating silently misaligns this against
93+
the expression matrix it is regressed on.
94+
"""
95+
rank = B.shape[1]
96+
Z = np.empty((cond_train.size, rank), dtype=np.float64)
97+
for i in range(n_cond):
98+
sel = cond_train == i
99+
if np.any(sel):
100+
Z[sel] = (P_train[i] @ B) * A[i]
101+
return Z
102+
103+
79104
def _bicv_trial(
80105
X: anndata.AnnData,
81106
rank: int,
@@ -127,10 +152,7 @@ def _bicv_trial(
127152

128153
# Estimate gene loadings for the held-out genes from the train cells.
129154
cond_train = cond_idx[train_cell_mask]
130-
Z = np.concatenate(
131-
[(P_train[i] @ B) * A[i] for i in range(n_cond) if np.any(cond_train == i)],
132-
axis=0,
133-
)
155+
Z = _train_cell_loadings(P_train, B, A, cond_train, n_cond)
134156
means_test_genes = means[test_gene_mask]
135157
X_train_test_genes = (
136158
_dense(X[train_cell_mask][:, test_gene_mask].X) - means_test_genes

‎scrise/tests/test_rank_selection.py‎

Lines changed: 119 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@
77
import pandas as pd
88
import pytest
99

10-
from ..rank_selection import bicv
10+
from ..rank_selection import _train_cell_loadings, bicv
1111

1212

1313
def _make_test_data(
@@ -150,3 +150,121 @@ def test_bicv_adata_alias():
150150
X = _make_test_data()
151151
results = bicv(adata=X, ranks=[2], n_repeats=1, random_state=0, max_iter=10)
152152
assert isinstance(results, pd.DataFrame)
153+
154+
155+
# ---------------------------------------------------------------------------
156+
# Alignment of the training-cell loadings (issue #546)
157+
# ---------------------------------------------------------------------------
158+
159+
160+
def _loading_fixture(cond_train: np.ndarray, rank: int = 3):
161+
"""Per-condition projections plus a B and A that make each block identifiable.
162+
163+
`A[i]` is `(i + 1) * ones`, so a row of the result reveals which condition
164+
it was built from: any row belonging to condition `i` is exactly `(i + 1)`
165+
times the corresponding row of `P_train[i] @ B`.
166+
"""
167+
n_cond = int(cond_train.max()) + 1
168+
rng = np.random.default_rng(0)
169+
B = rng.normal(size=(rank, rank))
170+
A = np.column_stack([np.arange(1, n_cond + 1)] * rank).astype(float)
171+
P_train = [
172+
rng.normal(size=(int(np.sum(cond_train == i)), rank)) for i in range(n_cond)
173+
]
174+
return P_train, B, A, n_cond
175+
176+
177+
def test_train_cell_loadings_match_the_rows_they_are_regressed_against():
178+
"""Row k of the loadings must describe the cell at row k of the matrix.
179+
180+
Regression test for #546. The loadings were built by concatenating
181+
per-condition blocks in condition order, while the expression they are
182+
regressed against stays in the cells' natural order. Those two orderings
183+
coincide only when conditions are stored contiguously, so on pooled data --
184+
where conditions are interleaved -- the least-squares fit silently paired
185+
each cell's loading with a different cell's expression.
186+
"""
187+
cond_train = np.tile(np.arange(4), 25) # fully interleaved
188+
P_train, B, A, n_cond = _loading_fixture(cond_train)
189+
190+
Z = _train_cell_loadings(P_train, B, A, cond_train, n_cond)
191+
192+
assert Z.shape == (cond_train.size, B.shape[1])
193+
# Each condition's rows must land where that condition's cells actually are.
194+
for i in range(n_cond):
195+
sel = cond_train == i
196+
np.testing.assert_allclose(Z[sel], (P_train[i] @ B) * A[i])
197+
198+
# And the identifying scale must survive: a row's magnitude tells you its
199+
# condition, which is exactly what the misalignment used to scramble.
200+
for k in range(cond_train.size):
201+
i = int(cond_train[k])
202+
np.testing.assert_allclose(
203+
Z[k], (P_train[i] @ B)[int(np.sum(cond_train[:k] == i))] * A[i]
204+
)
205+
206+
207+
def test_train_cell_loadings_agree_with_concatenation_when_contiguous():
208+
"""The fix is a no-op on contiguously stored conditions.
209+
210+
That is the case every previous test used, which is why this went unnoticed:
211+
concatenating in condition order and scattering by position give the same
212+
array whenever conditions are already grouped.
213+
"""
214+
cond_train = np.repeat(np.arange(4), 25) # contiguous blocks
215+
P_train, B, A, n_cond = _loading_fixture(cond_train)
216+
217+
scattered = _train_cell_loadings(P_train, B, A, cond_train, n_cond)
218+
concatenated = np.concatenate(
219+
[(P_train[i] @ B) * A[i] for i in range(n_cond)], axis=0
220+
)
221+
np.testing.assert_array_equal(scattered, concatenated)
222+
223+
224+
def test_train_cell_loadings_differ_from_concatenation_when_interleaved():
225+
"""...and is *not* a no-op otherwise, which is the whole point.
226+
227+
Without this, the two tests above would both pass on the unfixed code.
228+
"""
229+
cond_train = np.tile(np.arange(4), 25)
230+
P_train, B, A, n_cond = _loading_fixture(cond_train)
231+
232+
scattered = _train_cell_loadings(P_train, B, A, cond_train, n_cond)
233+
concatenated = np.concatenate(
234+
[(P_train[i] @ B) * A[i] for i in range(n_cond)], axis=0
235+
)
236+
assert not np.allclose(scattered, concatenated)
237+
238+
239+
def test_train_cell_loadings_handle_a_condition_with_no_training_cells():
240+
"""A condition may be absent from a fold; its rows simply do not exist."""
241+
cond_train = np.array([0, 2, 0, 2, 2]) # condition 1 has no train cells
242+
n_cond = 3
243+
rng = np.random.default_rng(0)
244+
rank = 2
245+
B = rng.normal(size=(rank, rank))
246+
A = rng.normal(size=(n_cond, rank))
247+
P_train = [
248+
rng.normal(size=(int(np.sum(cond_train == i)), rank)) for i in range(n_cond)
249+
]
250+
251+
Z = _train_cell_loadings(P_train, B, A, cond_train, n_cond)
252+
assert Z.shape == (5, rank)
253+
assert np.all(np.isfinite(Z))
254+
np.testing.assert_allclose(Z[cond_train == 0], (P_train[0] @ B) * A[0])
255+
np.testing.assert_allclose(Z[cond_train == 2], (P_train[2] @ B) * A[2])
256+
257+
258+
def test_bicv_runs_on_interleaved_conditions():
259+
"""End to end: `bicv` must accept data whose conditions are not grouped."""
260+
adata = _make_test_data()
261+
cond = adata.obs["condition_unique_idxs"].to_numpy()
262+
order = np.argsort(
263+
[int(np.sum(cond[:k] == cond[k])) for k in range(cond.size)], kind="stable"
264+
)
265+
shuffled = adata[order].copy()
266+
reshuffled = shuffled.obs["condition_unique_idxs"].to_numpy()
267+
assert int(np.sum(reshuffled[1:] != reshuffled[:-1])) > cond.size // 2
268+
269+
result = bicv(shuffled, ranks=[2, 3], n_repeats=1, random_state=0, max_iter=50)
270+
assert np.isfinite(result["R2X"]).all()

0 commit comments

Comments
 (0)