docs: Fix cross-references, update tutorial, and enforce strict mkdocs build

.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

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

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"],

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.

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

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.

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(