Skip to content

Commit e5a896b

Browse files
fishidahoclaude
andauthored
Optionally reduce complexity of codebase (#554)
* Bring all seven C901 functions under the complexity limit `ruff check --select C901 --duplicate` at max-complexity=10 flagged seven functions. Each is now under the limit by extracting the phases it was interleaving; no logic moved between phases and no control flow changed. score_cell_type_alignment 26 -> 7 load_factors 15 -> <5 plot_cell_type_alignment 14 -> <5 bicv 12 -> <5 cell_type_alignment 12 -> <5 export_factors 11 -> <5 plot_condition_factors 11 -> <5 The largest single win is a genuine duplicate rather than a split: `cell_type_alignment` and `score_cell_type_alignment` each carried their own copy of the permutation-null and Mann-Whitney p-value computation, identical but for the variable names, which is why pylint's duplicate-code check never paired them. Both now call `_component_p_values`. The `n_permutations` dispatch keeps its exact original shape -- a negative value still leaves the p-values at 1.0 rather than falling through to the asymptotic test, which a plain `if > 0 / else` would have changed. Verified with a golden harness of 69 keys covering all seven functions: every returned frame, series and array, the rendered PNG hash of eleven plot configurations, and the type and message of ten error paths. The harness is bit-identical before and after, and was confirmed deterministic across repeat runs first. 90 passed / 1 skipped, ruff clean, `ty` clean over `scrise/`, and no new duplicate-code pairs. Note these extractions add lines rather than remove them, since each helper gains a docstring: the five touched files grow by 159 lines net. Cutting file length means splitting modules, which is a separate structural decision. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_016VJRB1RMUAb1id11XZ6KWS * Split the two largest modules along their existing seams Extracting helpers for C901 added lines rather than removing them, so the two files over 650 lines are now split. Both seams already existed; no function moved between concerns and no body changed. factorization.py 686 -> 417 + factor_io.py 316 annotation_alignment 695 -> 439 + alignment_stats.py 291 `factor_io` takes everything that moves a decomposition to and from disk -- OPQ quantization of the projections, the packed barcode matrix, and the raw-data reattachment -- leaving `factorization` concerned with computing a decomposition rather than storing one. `alignment_stats` takes the pure numeric routines: AUROC enrichment, tau, the two effect sizes, and both p-value nulls. None of them touch AnnData, so they are now testable and reusable on plain arrays, and `annotation_alignment` keeps the AnnData plumbing and result assembly. Every name stays importable from the path it was already on: `scrise.factorization.export_factors` and `scrise.annotation_alignment.compute_tau` both still resolve, and to the same objects as via the new modules. `scrise.__all__` is unchanged and the `analysis/` figure scripts import unchanged. Verified with the same 69-key golden harness used for the complexity work -- every frame, series and array, eleven plot PNG hashes, and ten error messages, all bit-identical. 90 passed / 1 skipped, ruff clean, `ty` clean over `scrise/`, C901 clean, vulture clean, and no new duplicate-code pairs. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_016VJRB1RMUAb1id11XZ6KWS * Import the split-out names from where they are defined The split left `factorization` re-exporting `export_factors`/`load_factors` purely so old import paths kept resolving, which meant two places to look for one function. Every call site now names the module that defines what it wants, and the shim is gone rather than papered over. scrise/__init__.py factor_io, alignment_stats scrise/tests/test_contracts.py factor_io scrise/tests/test_annotation_alignment.py alignment_stats docs/api.md both, under their own headings `factorization.__all__` and `annotation_alignment.__all__` now list only what those modules define. `annotation_alignment` still imports the statistics helpers, because `cell_type_alignment` and `score_cell_type_alignment` call them -- that is a real dependency, not a re-export, and they are no longer advertised as part of that module's surface. `scrise/__init__.py` keeps aggregating the whole public API, so `from scrise import export_factors` and `from scrise import compute_tau` are unchanged for callers; they now resolve to the defining module, and `scrise.export_factors is factor_io.export_factors`. Also carries the docstring trims made directly to `factor_io` and `alignment_stats`. Verified: the 69-key golden harness is still bit-identical, 90 passed / 1 skipped, ruff and C901 clean, `ty` clean over `scrise/`, every `analysis/` module imports, and `mkdocs build --strict` resolves both new `:::` module references. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_016VJRB1RMUAb1id11XZ6KWS --------- Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
1 parent 83ecb3b commit e5a896b

11 files changed

Lines changed: 964 additions & 733 deletions

‎docs/api.md‎

Lines changed: 18 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,13 +6,19 @@
66
options:
77
members:
88
- pf2
9-
- export_factors
10-
- load_factors
119
- correct_conditions
1210
- order_components_by_energy
1311
- canonical_component_signs
1412
- match_components_across_ranks
1513

14+
## Factor Import/Export
15+
16+
::: scrise.factor_io
17+
options:
18+
members:
19+
- export_factors
20+
- load_factors
21+
1622
## Rank Selection
1723

1824
::: scrise.rank_selection
@@ -24,6 +30,16 @@
2430

2531
::: scrise.annotation_alignment
2632

33+
### Alignment Statistics
34+
35+
::: scrise.alignment_stats
36+
options:
37+
members:
38+
- compute_auroc_per_cell_type
39+
- compute_tau
40+
- compute_eta_squared
41+
- compute_kruskal_epsilon_squared
42+
2743
## Quantization & Compression
2844

2945
::: scrise.opq

‎scrise/__init__.py‎

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,17 @@
11
from parafac2.normalize import prepare_dataset
22

33
from . import plotting
4+
from .alignment_stats import compute_tau
45
from .annotation_alignment import (
56
CellTypeAlignmentResults,
67
ComponentAlignmentResult,
78
cell_type_alignment,
8-
compute_tau,
99
score_cell_type_alignment,
1010
)
11+
from .factor_io import export_factors, load_factors
1112
from .factorization import (
1213
canonical_component_signs,
1314
correct_conditions,
14-
export_factors,
15-
load_factors,
1615
match_components_across_ranks,
1716
order_components_by_energy,
1817
pf2,

‎scrise/alignment_stats.py‎

Lines changed: 283 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,283 @@
1+
from __future__ import annotations
2+
3+
import numpy as np
4+
import pandas as pd
5+
import scipy.stats as sp
6+
7+
8+
def compute_auroc_per_cell_type(
9+
loadings: np.ndarray,
10+
cell_type_codes: np.ndarray,
11+
n_types: int,
12+
) -> np.ndarray:
13+
"""Compute AUROC for each cell type vs all other cells.
14+
15+
Parameters
16+
----------
17+
loadings : np.ndarray
18+
1D array of cell loadings of shape (n_cells,).
19+
cell_type_codes : np.ndarray
20+
1D array of integer cell type assignments in [0, n_types - 1].
21+
n_types : int
22+
Total number of unique cell types.
23+
24+
Returns
25+
-------
26+
np.ndarray
27+
1D array of AUROC values for each cell type of shape (n_types,).
28+
"""
29+
n_cells = loadings.size
30+
if n_cells == 0 or n_types <= 1:
31+
return np.full(n_types, 0.5, dtype=float)
32+
33+
ranks = sp.rankdata(loadings, method="average")
34+
counts = np.bincount(cell_type_codes, minlength=n_types).astype(float)
35+
rank_sums = np.bincount(cell_type_codes, weights=ranks, minlength=n_types).astype(
36+
float
37+
)
38+
39+
aurocs = np.full(n_types, 0.5, dtype=float)
40+
for k in range(n_types):
41+
n1 = counts[k]
42+
n0 = n_cells - n1
43+
if n1 > 0 and n0 > 0:
44+
u1 = rank_sums[k] - n1 * (n1 + 1.0) / 2.0
45+
aurocs[k] = u1 / (n1 * n0)
46+
47+
return aurocs
48+
49+
50+
def compute_tau(
51+
enrichment_scores: np.ndarray | pd.Series,
52+
baseline: float = 0.0,
53+
) -> float:
54+
"""Compute tissue specificity index tau (Yanai et al., 2005).
55+
56+
tau = sum(1 - x_hat) / (n_types - 1), where x_hat = x / max(x).
57+
58+
When computed over AUROC enrichment values:
59+
- tau -> 1 indicates the component is specific/private to a single cell type.
60+
- tau -> 0 indicates the component is evenly distributed across cell types.
61+
62+
Parameters
63+
----------
64+
enrichment_scores : np.ndarray | pd.Series
65+
1D array of enrichment values (e.g. AUROC) across cell types.
66+
baseline : float, optional (default: 0.0)
67+
Baseline value subtracted before calculating tau. Values below baseline are clipped to 0.
68+
69+
Returns
70+
-------
71+
float
72+
Tau index in [0.0, 1.0].
73+
"""
74+
x = np.asarray(enrichment_scores, dtype=float)
75+
n = x.size
76+
if n <= 1:
77+
return 0.0
78+
79+
if baseline > 0.0:
80+
x = np.maximum(0.0, x - baseline)
81+
82+
max_val = np.nanmax(x)
83+
if max_val <= 0.0 or not np.isfinite(max_val):
84+
return 0.0
85+
86+
x_hat = x / max_val
87+
tau = np.sum(1.0 - x_hat) / (n - 1.0)
88+
return float(np.clip(tau, 0.0, 1.0))
89+
90+
91+
def compute_eta_squared(
92+
loadings: np.ndarray,
93+
cell_type_codes: np.ndarray,
94+
n_types: int,
95+
) -> float:
96+
"""Compute omnibus eta-squared (loading ~ cell_type).
97+
98+
Proportion of loading variance explained by cell-type identity.
99+
100+
Parameters
101+
----------
102+
loadings : np.ndarray
103+
1D array of cell loadings (shape: n_cells,).
104+
cell_type_codes : np.ndarray
105+
1D array of integer cell type assignments (shape: n_cells,).
106+
n_types : int
107+
Number of unique cell types.
108+
109+
Returns
110+
-------
111+
float
112+
Eta-squared value in [0.0, 1.0].
113+
"""
114+
y = np.asarray(loadings, dtype=float)
115+
n_cells = y.size
116+
if n_cells <= 1 or n_types <= 1:
117+
return 0.0
118+
119+
y_mean = np.mean(y)
120+
ss_total = np.sum((y - y_mean) ** 2)
121+
if ss_total <= 0.0:
122+
return 0.0
123+
124+
counts = np.bincount(cell_type_codes, minlength=n_types).astype(float)
125+
valid = counts > 0
126+
sums = np.bincount(cell_type_codes, weights=y, minlength=n_types)
127+
128+
means = np.zeros(n_types, dtype=float)
129+
means[valid] = sums[valid] / counts[valid]
130+
131+
ss_between = np.sum(counts[valid] * (means[valid] - y_mean) ** 2)
132+
eta2 = ss_between / ss_total
133+
return float(np.clip(eta2, 0.0, 1.0))
134+
135+
136+
def compute_kruskal_epsilon_squared(
137+
loadings: np.ndarray,
138+
cell_type_codes: np.ndarray,
139+
n_types: int,
140+
) -> float:
141+
"""Compute Kruskal-Wallis epsilon-squared effect size.
142+
143+
Non-parametric measure of association between loading and cell type.
144+
145+
Parameters
146+
----------
147+
loadings : np.ndarray
148+
1D array of cell loadings (shape: n_cells,).
149+
cell_type_codes : np.ndarray
150+
1D array of integer cell type assignments (shape: n_cells,).
151+
n_types : int
152+
Number of unique cell types.
153+
154+
Returns
155+
-------
156+
float
157+
Epsilon-squared value in [0.0, 1.0].
158+
"""
159+
y = np.asarray(loadings, dtype=float)
160+
n_cells = y.size
161+
if n_cells <= 1 or n_types <= 1:
162+
return 0.0
163+
164+
groups = [
165+
y[cell_type_codes == k]
166+
for k in range(n_types)
167+
if np.sum(cell_type_codes == k) > 0
168+
]
169+
if len(groups) <= 1:
170+
return 0.0
171+
172+
try:
173+
stat, _ = sp.kruskal(*groups)
174+
if not np.isfinite(stat) or stat < 0:
175+
return 0.0
176+
eps2 = stat / (n_cells - 1.0)
177+
return float(np.clip(eps2, 0.0, 1.0))
178+
except (ValueError, ZeroDivisionError):
179+
return 0.0
180+
181+
182+
def _validate_and_encode_cell_types(
183+
cell_types: pd.Series | np.ndarray | list,
184+
) -> tuple[np.ndarray, list[str]]:
185+
"""Encode cell types to integer codes and return category names."""
186+
if isinstance(cell_types, pd.Series) and isinstance(
187+
cell_types.dtype, pd.CategoricalDtype
188+
):
189+
categories = list(cell_types.cat.categories)
190+
codes = cell_types.cat.codes.to_numpy()
191+
# If there are unused categories or NaN, retain only observed categories
192+
observed = np.unique(codes[codes >= 0])
193+
if len(observed) < len(categories):
194+
# Remap to dense 0..K-1
195+
remap = {old: new for new, old in enumerate(observed)}
196+
categories = [categories[old] for old in observed]
197+
codes = np.array([remap.get(c, -1) for c in codes], dtype=int)
198+
return codes, categories
199+
200+
s = pd.Series(cell_types)
201+
cat = pd.Categorical(s)
202+
categories = [str(c) for c in cat.categories]
203+
codes = cat.codes
204+
return codes, categories
205+
206+
207+
def _permutation_p_values(
208+
y: np.ndarray,
209+
codes: np.ndarray,
210+
n_types: int,
211+
n_cells: int,
212+
aurocs: np.ndarray,
213+
n_permutations: int,
214+
rng: np.random.Generator,
215+
) -> np.ndarray:
216+
"""Empirical one-sided p-values against a rank-permutation null."""
217+
ranks = sp.rankdata(y, method="average")
218+
counts = np.bincount(codes, minlength=n_types).astype(float)
219+
null_counts = np.zeros(n_types, dtype=int)
220+
221+
for _ in range(n_permutations):
222+
perm_ranks = rng.permutation(ranks)
223+
perm_sums = np.bincount(codes, weights=perm_ranks, minlength=n_types).astype(
224+
float
225+
)
226+
for k in range(n_types):
227+
n1 = counts[k]
228+
n0 = n_cells - n1
229+
if n1 > 0 and n0 > 0:
230+
u_null = perm_sums[k] - n1 * (n1 + 1.0) / 2.0
231+
auc_null = u_null / (n1 * n0)
232+
if auc_null >= aurocs[k]:
233+
null_counts[k] += 1
234+
235+
return (1.0 + null_counts) / (1.0 + n_permutations)
236+
237+
238+
def _asymptotic_p_values(y: np.ndarray, codes: np.ndarray, n_types: int) -> np.ndarray:
239+
"""One-sided Mann-Whitney U p-values, used when ``n_permutations == 0``."""
240+
p_values = np.ones(n_types, dtype=float)
241+
for k in range(n_types):
242+
pos = y[codes == k]
243+
neg = y[codes != k]
244+
if pos.size > 0 and neg.size > 0:
245+
res = sp.mannwhitneyu(pos, neg, alternative="greater")
246+
p_values[k] = float(res.pvalue)
247+
return p_values
248+
249+
250+
def _component_p_values(
251+
y: np.ndarray,
252+
codes: np.ndarray,
253+
n_types: int,
254+
n_cells: int,
255+
aurocs: np.ndarray,
256+
n_permutations: int,
257+
rng: np.random.Generator,
258+
) -> np.ndarray:
259+
"""Per-cell-type p-values for one component's loadings.
260+
261+
Shared by :func:`cell_type_alignment` and
262+
:func:`score_cell_type_alignment`, which compute this identically. A
263+
single cell type (or no cells) leaves every p-value at 1.0, since there
264+
is nothing to be enriched against.
265+
"""
266+
if n_types <= 1 or n_cells == 0:
267+
return np.ones(n_types, dtype=float)
268+
if n_permutations > 0:
269+
return _permutation_p_values(
270+
y, codes, n_types, n_cells, aurocs, n_permutations, rng
271+
)
272+
if n_permutations == 0:
273+
return _asymptotic_p_values(y, codes, n_types)
274+
return np.ones(n_types, dtype=float)
275+
276+
277+
def _as_generator(
278+
random_state: int | np.random.Generator | None,
279+
) -> np.random.Generator:
280+
"""Accept a seed, an existing Generator, or None."""
281+
if isinstance(random_state, np.random.Generator):
282+
return random_state
283+
return np.random.default_rng(random_state)

0 commit comments

Comments
 (0)