Skip to content

Commit de71f7a

Browse files
committed
cleaing docs
1 parent 4d0a6ce commit de71f7a

2 files changed

Lines changed: 3 additions & 30 deletions

File tree

‎docs/tutorial.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -92,7 +92,7 @@ plt.show()
9292

9393
### Select a Rank with Bi-Cross-Validation (BiCV)
9494

95-
$R^2X$ (in-sample fit) always increases with rank, so it cannot by itself identify an optimal rank — it can only reveal an elbow. Bi-cross-validation (BiCV) addresses this by holding out a random subset of cells *and* genes, fitting RISE on the remaining data, and scoring how well the fit predicts the held-out block. Because it is evaluated on unseen data, BiCV $R^2X$ penalizes overfitting and turns over near the rank that generalizes best, unlike the fit $R^2X$. In practice the curve more often flattens into a plateau than forms a sharp peak, so read the elbow where it stops climbing rather than trusting the single highest point -- past the plateau, neighbouring ranks can differ only in the fourth decimal.
95+
$R^2X$ (in-sample fit) always increases with rank, so it cannot by itself identify an optimal rank. Bi-cross-validation (BiCV) addresses this by holding out a random subset of cells *and* genes, fitting RISE on the remaining data, and scoring how well the fit predicts the held-out block. Because it is evaluated on unseen data, BiCV $R^2X$ penalizes overfitting and turns over near the rank that generalizes best, unlike the fit $R^2X$.
9696

9797
`scrise.rank_selection.bicv` exhaustively evaluates a list of candidate ranks, each with several repeated random train/test splits, and returns both the fit $R^2X$ and the BiCV $R^2X$ for every rank so you can inspect the full curve. Since PARAFAC2 fits use CANDELINC compression by default (`compress="auto"`), sweeping every rank in this way is cheap enough that there is no need to search for the best rank without evaluating every candidate.
9898

‎scrise/rank_selection.py‎

Lines changed: 2 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -8,14 +8,6 @@
88
predicts the held-out (test-cell x test-gene) block. Unlike the ordinary
99
in-sample fit R2X (which increases monotonically with rank), the BiCV R2X
1010
penalizes overfitting and typically peaks near the "true" rank of the data.
11-
12-
The held-out cells are scored through their own projections, whose scale has
13-
to be corrected for the size of the held-out slice -- see
14-
:func:`_holdout_scale`. Both held-out fractions default to one half, the
15-
split Owen and Perry recommend for bi-cross-validation
16-
(https://arxiv.org/abs/0908.2062); it is also the split at which the
17-
uncorrected score happened to be unbiased, so it is the setting under which
18-
older results are comparable to current ones.
1911
"""
2012

2113
import warnings
@@ -99,22 +91,7 @@ def _cell_loadings(
9991
def _holdout_scale(
10092
cond_train: np.ndarray, cond_test: np.ndarray, n_cond: int
10193
) -> np.ndarray:
102-
"""Per-held-out-cell factor correcting `A` for the held-out slice's size.
103-
104-
PARAFAC2 writes slice ``k`` as ``P_k (B diag(a_k)) C^T`` with ``P_k``
105-
orthonormal, so the reconstruction's Frobenius norm is
106-
``||(B diag(a_k)) C^T||``, independent of how many cells the slice holds:
107-
all of a slice's energy sits in ``a_k``. ``a_k`` is fit against
108-
``n_train_k`` cells, and a slice's energy grows like ``sqrt(n_k)``, so
109-
reusing it unchanged for ``n_test_k`` held-out cells overstates the
110-
predicted block by ``sqrt(n_train_k / n_test_k)`` -- a factor of two at
111-
the default split, which drove the held-out R2X negative and made the
112-
curve fall as the fit improved.
113-
114-
Correcting it needs only the cell counts, which is exact when the two
115-
halves of a condition have comparable per-cell energy -- true here,
116-
since the split is random within each condition.
117-
"""
94+
"""Per-held-out-cell factor correcting `A` for the held-out slice's size."""
11895
scale = np.ones(cond_test.size)
11996
train_counts = np.bincount(cond_train, minlength=n_cond)
12097
test_counts = np.bincount(cond_test, minlength=n_cond)
@@ -339,11 +316,7 @@ def bicv(
339316
held_out_cell_frac : float, optional (default: 0.5)
340317
Fraction of cells held out per condition in each BiCV trial.
341318
held_out_gene_frac : float, optional (default: 0.5)
342-
Fraction of genes held out in each BiCV trial. Both default to a
343-
half-and-half split, following Owen and Perry, who report that
344-
"in simulated examples we find that a method leaving out half the
345-
rows and half the columns performs well"
346-
(https://arxiv.org/abs/0908.2062).
319+
Fraction of genes held out in each BiCV trial.
347320
random_state : int, optional
348321
Random seed for reproducibility.
349322
tolerance : float, optional (default: 1e-6)

0 commit comments

Comments
 (0)