multiscoresplot 1.0.6__tar.gz → 2.0.0__tar.gz

{multiscoresplot-1.0.6 → multiscoresplot-2.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: multiscoresplot
-Version: 1.0.6
+Version: 2.0.0
 Summary: Multi-dimensional gene set scoring and visualization for single-cell transcriptomics
 Project-URL: Homepage, https://github.com/AndreMacedo88/multiscoresplot
 Project-URL: Documentation, https://AndreMacedo88.github.io/multiscoresplot/
@@ -71,16 +71,11 @@ gene_sets = {
 # 1. Score gene sets per cell
 scores = msp.score_gene_sets(adata, gene_sets, inplace=True)
 
-# 2. Map scores to RGB colors
+# 2. Map scores to RGB colors (returns RGBResult with metadata)
 rgb = msp.reduce_to_rgb(scores, method="pca")
 
-# 3. Plot
-msp.plot_embedding(
-    adata, rgb,
-    basis="umap",
-    method="pca",
-    gene_set_names=list(gene_sets.keys()),
-)
+# 3. Plot — method & gene_set_names auto-detected from RGBResult
+msp.plot_embedding(adata, rgb, basis="X_umap")
 ```
 
 ## Pipeline
@@ -106,7 +101,7 @@ scores = msp.score_gene_sets(
 
 ### Step 2 — Map scores to RGB
 
-Convert gene set scores into per-cell RGB colors. Two options depending on how many gene sets you want to visualize:
+Convert gene set scores into per-cell RGB colors. Both functions return an `RGBResult` that carries the RGB array plus metadata (method, gene set names, colors) used automatically by the plotting functions.
 
 **Blend (2–3 gene sets)** — multiplicative blending from white, where each gene set darkens toward its base color proportional to the score.
 
@@ -131,26 +126,22 @@ rgb = msp.reduce_to_rgb(scores, method="ica")
 Scatter plot of embedding coordinates colored by RGB values, with an integrated color-space legend.
 
 ```python
-# Static matplotlib plot
-msp.plot_embedding(
-    adata, rgb,
-    basis="umap",
-    method="pca",
-    gene_set_names=["qNSCs", "aNSCs", "TAP", "NB"],
-)
+# Static matplotlib plot — method & gene_set_names auto-detected from RGBResult
+msp.plot_embedding(adata, rgb, basis="X_umap")
 
 # Options
 ax = msp.plot_embedding(
     adata, rgb,
-    basis="umap",
-    method="pca",
-    gene_set_names=["qNSCs", "aNSCs", "TAP", "NB"],
+    basis="X_umap",
     legend=True,              # show color legend (default)
     legend_style="inset",     # "inset" or "side"
     legend_loc="lower right", # legend position
+    legend_size=0.30,         # legend size (fraction of plot)
+    legend_resolution=128,    # legend image resolution
     point_size=3,
     alpha=0.8,
     figsize=(6, 6),
+    dpi=100,                  # figure resolution
     title="SVZ lineage",
     show=False,               # return axes instead of displaying
 )
@@ -161,16 +152,14 @@ ax = msp.plot_embedding(
 ```python
 msp.plot_embedding_interactive(
     adata, rgb,
-    basis="umap",
+    basis="X_umap",
     scores=scores,
-    method="nmf",
-    gene_set_names=["qNSCs", "aNSCs", "TAP", "NB"],
-    hover_columns=["n_counts", "cell_type"],  # extra adata.obs columns
+    hover_columns=["n_counts", "cell_type", "Dcx"],  # obs columns or gene names
     legend=True,
     legend_loc="lower right",
     point_size=2,
-    width=600,
-    height=500,
+    figsize=(6.5, 6.0),      # figure size in inches
+    dpi=100,                  # pixels = figsize * dpi
 )
 ```
 
@@ -225,16 +214,17 @@ Full documentation is available at **[AndreMacedo88.github.io/multiscoresplot](h
 
 ## API Reference
 
-| Function                                            | Description                               |
-| --------------------------------------------------- | ----------------------------------------- |
-| `score_gene_sets(adata, gene_sets)`                 | Score gene sets per cell via pyUCell      |
-| `blend_to_rgb(scores)`                              | Multiplicative blend to RGB (2–3 sets)    |
-| `reduce_to_rgb(scores, method="pca")`               | Dimensionality reduction to RGB (2+ sets) |
-| `plot_embedding(adata, rgb, basis=...)`             | Static matplotlib scatter plot            |
-| `plot_embedding_interactive(adata, rgb, basis=...)` | Interactive Plotly scatter plot           |
-| `render_legend(ax, method)`                         | Draw color-space legend on axes           |
-| `register_reducer(name, fn)`                        | Register a custom reduction method        |
-| `get_component_labels(method)`                      | Get axis labels for a reduction method    |
+| Function / Class                                    | Description                                         |
+| --------------------------------------------------- | --------------------------------------------------- |
+| `score_gene_sets(adata, gene_sets)`                 | Score gene sets per cell via pyUCell                |
+| `blend_to_rgb(scores)`                              | Multiplicative blend to RGB (2–3 sets) → RGBResult  |
+| `reduce_to_rgb(scores, method="pca")`               | Dimensionality reduction to RGB (2+ sets) → RGBResult |
+| `RGBResult`                                         | RGB array + metadata (method, gene set names, colors) |
+| `plot_embedding(adata, rgb, basis=...)`             | Static matplotlib scatter plot                      |
+| `plot_embedding_interactive(adata, rgb, basis=...)` | Interactive Plotly scatter plot                     |
+| `render_legend(ax, method)`                         | Draw color-space legend on axes                     |
+| `register_reducer(name, fn)`                        | Register a custom reduction method                  |
+| `get_component_labels(method)`                      | Get axis labels for a reduction method              |
 
 ## Development
 

{multiscoresplot-1.0.6 → multiscoresplot-2.0.0}/README.md

@@ -38,16 +38,11 @@ gene_sets = {
 # 1. Score gene sets per cell
 scores = msp.score_gene_sets(adata, gene_sets, inplace=True)
 
-# 2. Map scores to RGB colors
+# 2. Map scores to RGB colors (returns RGBResult with metadata)
 rgb = msp.reduce_to_rgb(scores, method="pca")
 
-# 3. Plot
-msp.plot_embedding(
-    adata, rgb,
-    basis="umap",
-    method="pca",
-    gene_set_names=list(gene_sets.keys()),
-)
+# 3. Plot — method & gene_set_names auto-detected from RGBResult
+msp.plot_embedding(adata, rgb, basis="X_umap")
 ```
 
 ## Pipeline
@@ -73,7 +68,7 @@ scores = msp.score_gene_sets(
 
 ### Step 2 — Map scores to RGB
 
-Convert gene set scores into per-cell RGB colors. Two options depending on how many gene sets you want to visualize:
+Convert gene set scores into per-cell RGB colors. Both functions return an `RGBResult` that carries the RGB array plus metadata (method, gene set names, colors) used automatically by the plotting functions.
 
 **Blend (2–3 gene sets)** — multiplicative blending from white, where each gene set darkens toward its base color proportional to the score.
 
@@ -98,26 +93,22 @@ rgb = msp.reduce_to_rgb(scores, method="ica")
 Scatter plot of embedding coordinates colored by RGB values, with an integrated color-space legend.
 
 ```python
-# Static matplotlib plot
-msp.plot_embedding(
-    adata, rgb,
-    basis="umap",
-    method="pca",
-    gene_set_names=["qNSCs", "aNSCs", "TAP", "NB"],
-)
+# Static matplotlib plot — method & gene_set_names auto-detected from RGBResult
+msp.plot_embedding(adata, rgb, basis="X_umap")
 
 # Options
 ax = msp.plot_embedding(
     adata, rgb,
-    basis="umap",
-    method="pca",
-    gene_set_names=["qNSCs", "aNSCs", "TAP", "NB"],
+    basis="X_umap",
     legend=True,              # show color legend (default)
     legend_style="inset",     # "inset" or "side"
     legend_loc="lower right", # legend position
+    legend_size=0.30,         # legend size (fraction of plot)
+    legend_resolution=128,    # legend image resolution
     point_size=3,
     alpha=0.8,
     figsize=(6, 6),
+    dpi=100,                  # figure resolution
     title="SVZ lineage",
     show=False,               # return axes instead of displaying
 )
@@ -128,16 +119,14 @@ ax = msp.plot_embedding(
 ```python
 msp.plot_embedding_interactive(
     adata, rgb,
-    basis="umap",
+    basis="X_umap",
     scores=scores,
-    method="nmf",
-    gene_set_names=["qNSCs", "aNSCs", "TAP", "NB"],
-    hover_columns=["n_counts", "cell_type"],  # extra adata.obs columns
+    hover_columns=["n_counts", "cell_type", "Dcx"],  # obs columns or gene names
     legend=True,
     legend_loc="lower right",
     point_size=2,
-    width=600,
-    height=500,
+    figsize=(6.5, 6.0),      # figure size in inches
+    dpi=100,                  # pixels = figsize * dpi
 )
 ```
 
@@ -192,16 +181,17 @@ Full documentation is available at **[AndreMacedo88.github.io/multiscoresplot](h
 
 ## API Reference
 
-| Function                                            | Description                               |
-| --------------------------------------------------- | ----------------------------------------- |
-| `score_gene_sets(adata, gene_sets)`                 | Score gene sets per cell via pyUCell      |
-| `blend_to_rgb(scores)`                              | Multiplicative blend to RGB (2–3 sets)    |
-| `reduce_to_rgb(scores, method="pca")`               | Dimensionality reduction to RGB (2+ sets) |
-| `plot_embedding(adata, rgb, basis=...)`             | Static matplotlib scatter plot            |
-| `plot_embedding_interactive(adata, rgb, basis=...)` | Interactive Plotly scatter plot           |
-| `render_legend(ax, method)`                         | Draw color-space legend on axes           |
-| `register_reducer(name, fn)`                        | Register a custom reduction method        |
-| `get_component_labels(method)`                      | Get axis labels for a reduction method    |
+| Function / Class                                    | Description                                         |
+| --------------------------------------------------- | --------------------------------------------------- |
+| `score_gene_sets(adata, gene_sets)`                 | Score gene sets per cell via pyUCell                |
+| `blend_to_rgb(scores)`                              | Multiplicative blend to RGB (2–3 sets) → RGBResult  |
+| `reduce_to_rgb(scores, method="pca")`               | Dimensionality reduction to RGB (2+ sets) → RGBResult |
+| `RGBResult`                                         | RGB array + metadata (method, gene set names, colors) |
+| `plot_embedding(adata, rgb, basis=...)`             | Static matplotlib scatter plot                      |
+| `plot_embedding_interactive(adata, rgb, basis=...)` | Interactive Plotly scatter plot                     |
+| `render_legend(ax, method)`                         | Draw color-space legend on axes                     |
+| `register_reducer(name, fn)`                        | Register a custom reduction method                  |
+| `get_component_labels(method)`                      | Get axis labels for a reduction method              |
 
 ## Development
 

{multiscoresplot-1.0.6 → multiscoresplot-2.0.0}/docs/api/colorspace.md

@@ -2,6 +2,16 @@
 
 Color mapping from gene set scores to RGB (pipeline steps 2–3).
 
+Both `blend_to_rgb` and `reduce_to_rgb` return an `RGBResult` object that wraps
+the RGB array with metadata (method, gene set names, colors). This metadata is
+auto-detected by the plotting functions.
+
+## RGBResult
+
+::: multiscoresplot.RGBResult
+
+---
+
 ## Blending (2–3 gene sets)
 
 ::: multiscoresplot.blend_to_rgb

{multiscoresplot-1.0.6 → multiscoresplot-2.0.0}/docs/api/index.md

@@ -2,11 +2,12 @@
 
 ## Overview
 
-| Function | Description | Pipeline Step |
-|----------|-------------|---------------|
+| Function / Class | Description | Pipeline Step |
+|------------------|-------------|---------------|
 | [`score_gene_sets`](scoring.md) | Score gene sets per cell via pyUCell | Step 1 |
 | [`blend_to_rgb`](colorspace.md#multiscoresplot.blend_to_rgb) | Multiplicative blend to RGB (2–3 sets) | Step 2 |
 | [`reduce_to_rgb`](colorspace.md#multiscoresplot.reduce_to_rgb) | Dimensionality reduction to RGB (2+ sets) | Step 2 |
+| [`RGBResult`](colorspace.md#multiscoresplot.RGBResult) | Return type of `blend_to_rgb` / `reduce_to_rgb` with metadata | Step 2 |
 | [`plot_embedding`](plotting.md) | Static matplotlib scatter plot | Step 3 |
 | [`plot_embedding_interactive`](interactive.md) | Interactive Plotly scatter plot | Step 3 |
 | [`render_legend`](legend.md) | Draw color-space legend on axes | Optional |

multiscoresplot-2.0.0/docs/changelog.md

@@ -0,0 +1,35 @@
+# Changelog
+
+## 2.0.0
+
+### Breaking changes
+- `blend_to_rgb` and `reduce_to_rgb` now return `RGBResult` (carries RGB array + metadata). The object supports numpy array protocol, so `np.asarray(result)`, indexing, and comparisons still work.
+- `plot_embedding` and `plot_embedding_interactive`: `basis=` now takes the **full obsm key** (e.g. `"X_umap"`, `"umap_consensus"`). The old short form (`basis="umap"`) still works but emits a `DeprecationWarning`.
+- `plot_embedding`: `legend=True` (default) now **requires** a known method. Previously it silently skipped the legend when `method=None`; now it raises `ValueError`. Pass `legend=False` or provide `method=`, or use an `RGBResult`.
+- `plot_embedding_interactive`: `width`/`height` replaced by `figsize` (inches) + `dpi`. Pixel dimensions = `figsize * dpi`.
+
+### New features
+- **`RGBResult`**: new dataclass returned by `blend_to_rgb` / `reduce_to_rgb`. Carries `method`, `gene_set_names`, and `colors` metadata that plotting functions auto-detect.
+- **`plot_embedding`**: new params `legend_size`, `legend_resolution`, `dpi`.
+- **`plot_embedding_interactive`**: new param `legend_kwargs`. `figsize`/`dpi` replace `width`/`height`.
+- **Both plotting functions**: consistent `legend_size`, `legend_resolution`, and `legend_kwargs` params.
+- **`hover_columns`** now falls back to `adata.var_names` for gene expression values (sparse matrices supported).
+- **`gene_set_names`** behavior is now consistent between static and interactive plots.
+
+## 1.0.3
+
+- Fix badge display in README
+
+## 1.0.2
+
+- Fix legend not being plotted in interactive "direct" methods
+- Fix CI badge path in README
+
+## 1.0.1
+
+- Initial stable release
+- 5-step pipeline: score, blend, reduce, plot, legend
+- Built-in reducers: PCA, NMF, ICA
+- Pluggable reducer registry
+- Static matplotlib and interactive Plotly plotting
+- Color-space legends for direct and reduction modes

{multiscoresplot-1.0.6 → multiscoresplot-2.0.0}/docs/examples.md

@@ -38,10 +38,9 @@ def umap_reducer(X, n_components, **kwargs):
 # Register it
 msp.register_reducer("umap", umap_reducer, component_prefix="UMAP")
 
-# Use it
+# Use it — method auto-detected from RGBResult
 rgb = msp.reduce_to_rgb(scores, method="umap")
-msp.plot_embedding(adata, rgb, basis="umap", method="umap",
-                   gene_set_names=list(gene_sets.keys()))
+msp.plot_embedding(adata, rgb, basis="X_umap")
 ```
 
 ## Different Embeddings
@@ -56,12 +55,10 @@ rgb = msp.reduce_to_rgb(scores, method="pca")
 
 fig, axes = plt.subplots(1, 3, figsize=(18, 5))
 
-for ax, basis in zip(axes, ["umap", "pca", "X_scanorama"]):
+for ax, basis in zip(axes, ["X_umap", "X_pca", "X_scanorama"]):
     msp.plot_embedding(
         adata, rgb,
         basis=basis,
-        method="pca",
-        gene_set_names=list(gene_sets.keys()),
         ax=ax,
         title=basis.upper(),
         show=False,
@@ -86,9 +83,7 @@ for ax, method in zip(axes, ["pca", "nmf", "ica"]):
     rgb = msp.reduce_to_rgb(scores, method=method)
     msp.plot_embedding(
         adata, rgb,
-        basis="umap",
-        method=method,
-        gene_set_names=list(gene_sets.keys()),
+        basis="X_umap",
         ax=ax,
         title=method.upper(),
         show=False,
@@ -108,14 +103,12 @@ rgb = msp.reduce_to_rgb(scores, method="nmf")
 
 msp.plot_embedding_interactive(
     adata, rgb,
-    basis="umap",
+    basis="X_umap",
     scores=scores,
-    method="nmf",
-    gene_set_names=list(gene_sets.keys()),
-    hover_columns=["n_counts", "cell_type"],  # any adata.obs columns
+    hover_columns=["n_counts", "cell_type", "Dcx"],  # obs columns or gene names
     point_size=2,
-    width=800,
-    height=600,
+    figsize=(8.0, 6.0),
+    dpi=100,
 )
 ```
 
@@ -124,16 +117,16 @@ msp.plot_embedding_interactive(
 ```python
 ax = msp.plot_embedding(
     adata, rgb,
-    basis="umap",
-    method="pca",
-    gene_set_names=list(gene_sets.keys()),
+    basis="X_umap",
     point_size=5,
     alpha=0.6,
     figsize=(8, 8),
+    dpi=150,
     title="SVZ Neural Lineage",
     legend=True,
     legend_style="side",       # legend in a separate panel
     legend_loc="upper right",
+    legend_size=0.35,          # legend size (fraction of plot)
     show=False,
 )
 
@@ -156,10 +149,6 @@ two_sets = {
 scores = msp.score_gene_sets(adata, two_sets, inplace=True)
 rgb = msp.blend_to_rgb(scores)  # blue/red by default
 
-msp.plot_embedding(
-    adata, rgb,
-    basis="umap",
-    method="direct",
-    gene_set_names=list(two_sets.keys()),
-)
+# method="direct" and gene_set_names auto-detected from RGBResult
+msp.plot_embedding(adata, rgb, basis="X_umap")
 ```

{multiscoresplot-1.0.6 → multiscoresplot-2.0.0}/docs/getting-started.md

@@ -42,13 +42,8 @@ rgb = msp.blend_to_rgb(scores)
 #    Or reduce via dimensionality reduction (any number of gene sets)
 rgb = msp.reduce_to_rgb(scores, method="pca")
 
-# 4. Plot on a UMAP embedding (step 3 of the pipeline)
-msp.plot_embedding(
-    adata, rgb,
-    basis="umap",
-    method="pca",
-    gene_set_names=list(gene_sets.keys()),
-)
+# 4. Plot on a UMAP embedding — method & labels auto-detected from RGBResult
+msp.plot_embedding(adata, rgb, basis="X_umap")
 ```
 
 !!! tip "Which color mapping to use?"

{multiscoresplot-1.0.6 → multiscoresplot-2.0.0}/docs/index.md

@@ -29,16 +29,11 @@ gene_sets = {
 # 1. Score gene sets per cell
 scores = msp.score_gene_sets(adata, gene_sets, inplace=True)
 
-# 2. Map scores to RGB colors
+# 2. Map scores to RGB colors (returns RGBResult with metadata)
 rgb = msp.reduce_to_rgb(scores, method="pca")
 
-# 3. Plot
-msp.plot_embedding(
-    adata, rgb,
-    basis="umap",
-    method="pca",
-    gene_set_names=list(gene_sets.keys()),
-)
+# 3. Plot — method & gene_set_names auto-detected from RGBResult
+msp.plot_embedding(adata, rgb, basis="X_umap")
 ```
 
 [Get Started](getting-started.md){ .md-button .md-button--primary }

{multiscoresplot-1.0.6 → multiscoresplot-2.0.0}/docs/pipeline.md

@@ -143,53 +143,72 @@ as possible.
 Scatter plot of embedding coordinates (UMAP, PCA, etc.) colored by the RGB values,
 with an integrated color-space legend.
 
+Both `blend_to_rgb` and `reduce_to_rgb` return an `RGBResult` object that carries
+the RGB array together with metadata (method, gene set names, colors). The plotting
+functions detect this metadata automatically, so you don't need to repeat `method=`
+and `gene_set_names=`.
+
+!!! note "Full obsm key"
+    The `basis` parameter now takes the **full obsm key** (e.g., `"X_umap"`,
+    `"umap_consensus"`), not a short name. This lets you use any obsm key, not
+    just those prefixed with `X_`.
+
 ```python
-# Basic usage
-msp.plot_embedding(
-    adata, rgb,
-    basis="umap",
-    method="pca",
-    gene_set_names=["qNSCs", "aNSCs", "TAP", "NB"],
-)
+# Basic usage — method and gene_set_names auto-detected from RGBResult
+msp.plot_embedding(adata, rgb, basis="X_umap")
 
 # With customization
 ax = msp.plot_embedding(
     adata, rgb,
-    basis="umap",
-    method="pca",
-    gene_set_names=["qNSCs", "aNSCs", "TAP", "NB"],
+    basis="X_umap",
     legend=True,              # show color legend (default)
     legend_style="inset",     # "inset" or "side"
     legend_loc="lower right", # legend position
+    legend_size=0.30,         # legend size (fraction of plot)
+    legend_resolution=128,    # legend image resolution
     point_size=3,
     alpha=0.8,
     figsize=(6, 6),
+    dpi=100,                  # figure resolution
     title="SVZ lineage",
     show=False,               # return axes instead of displaying
 )
+
+# You can still override metadata from RGBResult
+msp.plot_embedding(
+    adata, rgb,
+    basis="X_umap",
+    method="pca",             # override RGBResult.method
+    gene_set_names=["A", "B", "C", "D"],  # override RGBResult.gene_set_names
+)
 ```
 
+If you pass a raw `(n_cells, 3)` numpy array instead of an `RGBResult`, you must
+provide `method=` explicitly when `legend=True`.
+
 ### Interactive Plot (requires Plotly)
 
 WebGL-accelerated scatter plot with hover info showing gene set scores, RGB channel
-values, and custom metadata.
+values, and custom metadata. Uses the same `RGBResult` metadata as `plot_embedding`.
 
 ```python
 msp.plot_embedding_interactive(
     adata, rgb,
-    basis="umap",
-    scores=scores,
-    method="nmf",
-    gene_set_names=["qNSCs", "aNSCs", "TAP", "NB"],
-    hover_columns=["n_counts", "cell_type"],
+    basis="X_umap",
+    scores=scores,                         # optional: explicit score DataFrame
+    hover_columns=["n_counts", "Dcx"],     # obs columns or gene names
     legend=True,
     legend_loc="lower right",
     point_size=2,
-    width=600,
-    height=500,
+    figsize=(6.5, 6.0),                    # figure size in inches
+    dpi=100,                               # pixels = figsize * dpi
 )
 ```
 
+!!! tip "Hover over genes"
+    `hover_columns` accepts both `adata.obs` column names **and** gene names from
+    `adata.var_names`. Gene names display the expression value from `adata.X`.
+
 !!! note
     Interactive plots require the `plotly` extra: `pip install 'multiscoresplot[interactive]'`
 

{multiscoresplot-1.0.6 → multiscoresplot-2.0.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "multiscoresplot"
-version = "1.0.6"
+version = "2.0.0"
 description = "Multi-dimensional gene set scoring and visualization for single-cell transcriptomics"
 readme = "README.md"
 license = "MIT"
@@ -94,6 +94,8 @@ module = [
     "sklearn.*",
     "plotly",
     "plotly.*",
+    "scipy",
+    "scipy.*",
 ]
 ignore_missing_imports = true
 disable_error_code = ["import-untyped"]

{multiscoresplot-1.0.6 → multiscoresplot-2.0.0}/src/multiscoresplot/__init__.py

@@ -1,6 +1,7 @@
 """multiscoresplot -- multi-dimensional gene set scoring visualization."""
 
 from multiscoresplot._colorspace import (
+    RGBResult,
     blend_to_rgb,
     get_component_labels,
     project_direct,
@@ -14,6 +15,7 @@ from multiscoresplot._plotting import plot_embedding
 from multiscoresplot._scoring import score_gene_sets
 
 __all__ = [
+    "RGBResult",
     "blend_to_rgb",
     "get_component_labels",
     "plot_embedding",
@@ -25,4 +27,4 @@ __all__ = [
     "render_legend",
     "score_gene_sets",
 ]
-__version__ = "1.0.6"
+__version__ = "2.0.0"