diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml index b9d8b928..11f84a2c 100644 --- a/.github/workflows/documentation.yml +++ b/.github/workflows/documentation.yml @@ -25,7 +25,7 @@ jobs: - name: MkDocs build run: | export ANNDATA_CUPY=0 - uv run --group docs mkdocs build + uv run --group docs mkdocs build --strict - name: Setup Pages if: github.event_name == 'push' && github.ref == 'refs/heads/main' uses: actions/configure-pages@v6 diff --git a/docs/api.md b/docs/api.md index b2fe75a4..a398a4cb 100644 --- a/docs/api.md +++ b/docs/api.md @@ -20,6 +20,14 @@ members: - bicv +## Annotation Alignment + +::: scrise.annotation_alignment + +## Quantization & Compression + +::: scrise.opq + ## Preprocessing ::: parafac2.normalize @@ -67,3 +75,7 @@ options: members: - plot_fms_diff_ranks + +### Cell-Type Alignment Plotting + +::: scrise.plotting.annotation_alignment diff --git a/docs/component_ordering.md b/docs/component_ordering.md index 1a441dea..af684516 100644 --- a/docs/component_ordering.md +++ b/docs/component_ordering.md @@ -53,8 +53,8 @@ are sorted from highest to lowest energy, so that low-energy components — typically the ones that appear only once the rank is increased — land at the high end of the ordering, while established, high-energy components stay near the front. This is implemented in -[`RISE.order_components_by_energy`][RISE.factorization.order_components_by_energy] -and is applied automatically inside [`RISE.pf2`][RISE.factorization.pf2]. +[`RISE.order_components_by_energy`][scrise.factorization.order_components_by_energy] +and is applied automatically inside [`RISE.pf2`][scrise.factorization.pf2]. ## Sign convention @@ -68,12 +68,12 @@ factor ($\mathbf{A}$) column for that component is flipped correspondingly, so that the reconstructed decomposition is unchanged; the eigen-state factor ($\mathbf{B}$) is left as the unflipped reference. This is implemented in -[`RISE.canonical_component_signs`][RISE.factorization.canonical_component_signs]. +[`RISE.canonical_component_signs`][scrise.factorization.canonical_component_signs]. ## Matching components across ranks As a small, optional addition, RISE also provides -[`RISE.match_components_across_ranks`][RISE.factorization.match_components_across_ranks], +[`RISE.match_components_across_ranks`][scrise.factorization.match_components_across_ranks], which implements the cross-rank matching primitive described above: given the (sign-canonicalized) gene factors of a rank-$N$ fit and a rank-$(N+1)$ fit, it performs Hungarian maximum-weight matching on cosine similarity and @@ -86,7 +86,7 @@ components carry over when moving to rank $N+1$) actually holds for a given dataset. ```python -from RISE import match_components_across_ranks +from scrise import match_components_across_ranks matched_pairs, unmatched_high = match_components_across_ranks( C_low=X_rank_n.varm["Pf2_C"], diff --git a/docs/index.md b/docs/index.md index ba070732..2ea8a72f 100644 --- a/docs/index.md +++ b/docs/index.md @@ -10,5 +10,6 @@ RISE does not require prior cell-type labels or clustering, reducing bias and en - [Tutorial](tutorial.md): Step-by-step walkthrough covering data preprocessing, rank selection, tensor decomposition, compression/export, and factor visualization. - [Unequal Cell Counts](unequal_cell_counts.md): Why disparate cell counts across conditions can bias RISE decompositions, and how to correct for it. +- [Component Ordering](component_ordering.md): How RISE stably orders components across refits and ranks using reconstruction energy and sign canonicalization. - [API Reference](api.md): Detailed specifications for factorization routines, rank selection, preprocessing, and plotting utilities. - [References](references.md): Key citations and methodology papers. diff --git a/docs/tutorial.md b/docs/tutorial.md index 339e05b7..07446af6 100644 --- a/docs/tutorial.md +++ b/docs/tutorial.md @@ -4,16 +4,16 @@ This tutorial demonstrates the complete RISE workflow for analyzing single-cell ## Installation -To add RISE to your Python package, add the following line to your `requirements.txt` and remake your virtual environment: +To add `scrise` to your Python environment, install it from PyPI: -```text -git+https://github.com/meyer-lab/RISE.git@main +```bash +pip install scrise ``` -For GPU acceleration support (which propagates to `parafac2[gpu]`): +For GPU acceleration support (propagated to `parafac2[gpu]`): -```text -RISE[gpu] @ git+https://github.com/meyer-lab/RISE.git@main +```bash +pip install "scrise[gpu]" ``` ## Preprocessing the Dataset diff --git a/scrise/plotting/rank_selection.py b/scrise/plotting/rank_selection.py index c38ce8a5..f4158dfd 100644 --- a/scrise/plotting/rank_selection.py +++ b/scrise/plotting/rank_selection.py @@ -19,7 +19,7 @@ def plot_bicv_r2x(results: pd.DataFrame, ax: Axes) -> None: Parameters ---------- results : pandas.DataFrame - Output of :func:`RISE.rank_selection.bicv`, with columns "Rank", + Output of :func:`scrise.rank_selection.bicv`, with columns "Rank", "Repeat", "Metric" ("Fit R2X" or "BiCV R2X"), and "R2X". ax : matplotlib.axes.Axes Matplotlib axes object to plot on. diff --git a/scrise/rank_selection.py b/scrise/rank_selection.py index af1a07e3..57a419a8 100644 --- a/scrise/rank_selection.py +++ b/scrise/rank_selection.py @@ -170,12 +170,12 @@ def bicv( """Evaluate rank via bi-cross-validation (BiCV) and in-sample fit R2X. For each candidate rank, computes both the ordinary in-sample fit R2X - (using the full dataset, as in :func:`RISE.factorization.rise_pca_r2x`) + (using the full dataset, as in :func:`scrise.factorization.rise_pca_r2x`) and the BiCV R2X (repeated ``n_repeats`` times with independent random cell/gene splits). The fit R2X increases monotonically with rank; the BiCV R2X penalizes overfitting and typically peaks near the rank that best generalizes to held-out data. Plot both with - :func:`RISE.plotting.plot_bicv_r2x` to select a rank. + :func:`scrise.plotting.plot_bicv_r2x` to select a rank. Parameters ---------- @@ -209,7 +209,7 @@ def bicv( pandas.DataFrame Long-form DataFrame with columns "Rank", "Repeat", "Metric" (one of "Fit R2X" or "BiCV R2X"), and "R2X". Ready to pass to - :func:`RISE.plotting.plot_bicv_r2x`. + :func:`scrise.plotting.plot_bicv_r2x`. """ if not (0 < held_out_cell_frac < 1) or not (0 < held_out_gene_frac < 1): raise ValueError(