Skip to content

Commit 4db09c7

Browse files
author
Aaron Meyer
committed
Include weights in energy-based component ordering
1 parent 3fd8765 commit 4db09c7

5 files changed

Lines changed: 34 additions & 25 deletions

File tree

‎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

‎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/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_golden_regression.py‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -57,10 +57,10 @@ def test_pf2_golden_values_on_fixed_synthetic_fixture():
5757
# Component weights, order, and which gene dominates each component are
5858
# a much coarser (and thus more robust-to-numerical-noise) fingerprint
5959
# of the fit than raw factor values.
60-
np.testing.assert_allclose(weights, [22.2080, 56.6194, 24.3079], rtol=1e-2)
60+
np.testing.assert_allclose(weights, [56.6194, 24.3079, 22.2080], rtol=1e-2)
6161

6262
top_gene_per_component = np.argmax(np.abs(C), axis=0)
63-
np.testing.assert_array_equal(top_gene_per_component, [12, 13, 5])
63+
np.testing.assert_array_equal(top_gene_per_component, [13, 5, 12])
6464

6565

6666
if __name__ == "__main__":

‎scrise/tests/test_invariants.py‎

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -121,10 +121,15 @@ def test_order_components_by_energy_is_a_permutation(
121121

122122
new_A = np.array(ordered.uns["Pf2_A"])
123123
new_C = np.array(ordered.varm["Pf2_C"])
124-
new_energy = np.linalg.norm(new_A, axis=0) * np.linalg.norm(new_C, axis=0)
124+
new_weights = np.array(ordered.uns["Pf2_weights"])
125+
new_energy = (
126+
np.abs(new_weights)
127+
* np.linalg.norm(new_A, axis=0)
128+
* np.linalg.norm(new_C, axis=0)
129+
)
125130
assert np.all(np.diff(new_energy) <= 1e-6)
126131

127-
energy = np.linalg.norm(A, axis=0) * np.linalg.norm(C, axis=0)
132+
energy = np.abs(weights) * np.linalg.norm(A, axis=0) * np.linalg.norm(C, axis=0)
128133
order = np.argsort(energy)[::-1]
129134
np.testing.assert_allclose(
130135
np.array(ordered.obsm["weighted_projections"]), before_wp[:, order], atol=1e-5

0 commit comments

Comments
 (0)