multiscoresplot 1.0.3__tar.gz → 1.0.5__tar.gz

multiscoresplot-1.0.5/.github/workflows/docs.yml

@@ -0,0 +1,27 @@
+name: Deploy Docs
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.12"
+
+      - name: Configure git for gh-deploy
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+
+      - name: Deploy to GitHub Pages
+        run: uv run --group docs mkdocs gh-deploy --force

{multiscoresplot-1.0.3 → multiscoresplot-1.0.5}/.pre-commit-config.yaml

@@ -10,6 +10,7 @@ repos:
       - id: check-toml
       - id: check-added-large-files
         args: ["--maxkb=500"]
+        exclude: '^uv\.lock$'
 
   - repo: https://github.com/astral-sh/ruff-pre-commit
     rev: v0.9.9

{multiscoresplot-1.0.3 → multiscoresplot-1.0.5}/PKG-INFO

@@ -1,10 +1,11 @@
 Metadata-Version: 2.4
 Name: multiscoresplot
-Version: 1.0.3
+Version: 1.0.5
 Summary: Multi-dimensional gene set scoring and visualization for single-cell transcriptomics
-Project-URL: Homepage, https://github.com/andrecmacedo/multiscoresplot
-Project-URL: Repository, https://github.com/andrecmacedo/multiscoresplot
-Project-URL: Issues, https://github.com/andrecmacedo/multiscoresplot/issues
+Project-URL: Homepage, https://github.com/AndreMacedo88/multiscoresplot
+Project-URL: Documentation, https://AndreMacedo88.github.io/multiscoresplot/
+Project-URL: Repository, https://github.com/AndreMacedo88/multiscoresplot
+Project-URL: Issues, https://github.com/AndreMacedo88/multiscoresplot/issues
 Author: Andre Macedo
 License-Expression: MIT
 License-File: LICENSE
@@ -33,9 +34,10 @@ Description-Content-Type: text/markdown
 # multiscoresplot
 
 [![CI](https://github.com/AndreMacedo88/multiscoresplot/actions/workflows/ci.yml/badge.svg)](https://github.com/AndreMacedo88/multiscoresplot/actions/workflows/ci.yml)
-[![PyPI](https://img.shields.io/pypi/v/multiscoresplot)](https://pypi.org/project/multiscoresplot/)
+[![Docs](https://img.shields.io/badge/docs-GitHub%20Pages-blue)](https://AndreMacedo88.github.io/multiscoresplot/)
+[![PyPI](https://img.shields.io/pypi/v/multiscoresplot?cacheSeconds=3600)](https://pypi.org/project/multiscoresplot/)
+[![Python](https://img.shields.io/pypi/pyversions/multiscoresplot?cacheSeconds=3600)](https://pypi.org/project/multiscoresplot/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![Python](https://img.shields.io/pypi/pyversions/multiscoresplot)](https://pypi.org/project/multiscoresplot/)
 
 **Multi-dimensional gene set scoring and visualization for single-cell transcriptomics.**
 
@@ -230,7 +232,7 @@ rgb = msp.reduce_to_rgb(scores, method="umap")
 ## Development
 
 ```bash
-git clone https://github.com/andrecmacedo/multiscoresplot.git
+git clone https://github.com/AndreMacedo88/multiscoresplot.git
 cd multiscoresplot
 
 # Install in editable mode with dev dependencies

{multiscoresplot-1.0.3 → multiscoresplot-1.0.5}/README.md

@@ -1,9 +1,10 @@
 # multiscoresplot
 
 [![CI](https://github.com/AndreMacedo88/multiscoresplot/actions/workflows/ci.yml/badge.svg)](https://github.com/AndreMacedo88/multiscoresplot/actions/workflows/ci.yml)
-[![PyPI](https://img.shields.io/pypi/v/multiscoresplot)](https://pypi.org/project/multiscoresplot/)
+[![Docs](https://img.shields.io/badge/docs-GitHub%20Pages-blue)](https://AndreMacedo88.github.io/multiscoresplot/)
+[![PyPI](https://img.shields.io/pypi/v/multiscoresplot?cacheSeconds=3600)](https://pypi.org/project/multiscoresplot/)
+[![Python](https://img.shields.io/pypi/pyversions/multiscoresplot?cacheSeconds=3600)](https://pypi.org/project/multiscoresplot/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![Python](https://img.shields.io/pypi/pyversions/multiscoresplot)](https://pypi.org/project/multiscoresplot/)
 
 **Multi-dimensional gene set scoring and visualization for single-cell transcriptomics.**
 
@@ -198,7 +199,7 @@ rgb = msp.reduce_to_rgb(scores, method="umap")
 ## Development
 
 ```bash
-git clone https://github.com/andrecmacedo/multiscoresplot.git
+git clone https://github.com/AndreMacedo88/multiscoresplot.git
 cd multiscoresplot
 
 # Install in editable mode with dev dependencies

multiscoresplot-1.0.5/docs/api/colorspace.md

@@ -0,0 +1,25 @@
+# Color Space
+
+Color mapping from gene set scores to RGB (pipeline steps 2–3).
+
+## Blending (2–3 gene sets)
+
+::: multiscoresplot.blend_to_rgb
+
+---
+
+## Dimensionality Reduction (2+ gene sets)
+
+::: multiscoresplot.reduce_to_rgb
+
+---
+
+## Custom Reducers
+
+::: multiscoresplot.register_reducer
+
+---
+
+## Utility
+
+::: multiscoresplot.get_component_labels

multiscoresplot-1.0.5/docs/api/index.md

@@ -0,0 +1,27 @@
+# API Reference
+
+## Overview
+
+| Function | 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 3 |
+| [`plot_embedding`](plotting.md) | Static matplotlib scatter plot | Step 4 |
+| [`plot_embedding_interactive`](interactive.md) | Interactive Plotly scatter plot | Step 4b |
+| [`render_legend`](legend.md) | Draw color-space legend on axes | Step 5 |
+| [`register_reducer`](colorspace.md#multiscoresplot.register_reducer) | Register a custom reduction method | Extensibility |
+| [`get_component_labels`](colorspace.md#multiscoresplot.get_component_labels) | Get axis labels for a reduction method | Utility |
+
+## Module Layout
+
+All public functions are available directly from the top-level `multiscoresplot` namespace:
+
+```python
+import multiscoresplot as msp
+
+msp.score_gene_sets(...)
+msp.blend_to_rgb(...)
+msp.reduce_to_rgb(...)
+msp.plot_embedding(...)
+```

multiscoresplot-1.0.5/docs/api/interactive.md

@@ -0,0 +1,8 @@
+# Interactive Plotting
+
+WebGL-accelerated Plotly scatter plot with hover metadata (pipeline step 4b).
+
+!!! note
+    Requires the `plotly` extra: `pip install 'multiscoresplot[interactive]'`
+
+::: multiscoresplot.plot_embedding_interactive

multiscoresplot-1.0.5/docs/api/legend.md

@@ -0,0 +1,5 @@
+# Legend
+
+Color-space legend rendering for matplotlib axes (pipeline step 5).
+
+::: multiscoresplot.render_legend

multiscoresplot-1.0.5/docs/api/plotting.md

@@ -0,0 +1,5 @@
+# Plotting
+
+Static matplotlib scatter plot of embeddings colored by RGB values (pipeline step 4).
+
+::: multiscoresplot.plot_embedding

multiscoresplot-1.0.5/docs/api/scoring.md

@@ -0,0 +1,5 @@
+# Scoring
+
+Gene set scoring via pyUCell (pipeline step 1).
+
+::: multiscoresplot.score_gene_sets

multiscoresplot-1.0.5/docs/changelog.md

@@ -0,0 +1,19 @@
+# Changelog
+
+## 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.5/docs/examples.md

@@ -0,0 +1,165 @@
+# Examples
+
+## Custom Reducer — UMAP
+
+Register your own dimensionality reduction method and use it like any built-in:
+
+```python
+import multiscoresplot as msp
+
+
+def umap_reducer(X, n_components, **kwargs):
+    """Reduce score matrix to RGB via UMAP.
+
+    Parameters
+    ----------
+    X : ndarray of shape (n_cells, n_gene_sets)
+        Score matrix.
+    n_components : int
+        Number of output components (always 3 for RGB).
+
+    Returns
+    -------
+    ndarray of shape (n_cells, 3)
+        Embedding with values in [0, 1].
+    """
+    import umap
+
+    embedding = umap.UMAP(n_components=n_components, **kwargs).fit_transform(X)
+    # min-max normalize each column to [0, 1]
+    for j in range(embedding.shape[1]):
+        col = embedding[:, j]
+        lo, hi = col.min(), col.max()
+        if hi > lo:
+            embedding[:, j] = (col - lo) / (hi - lo)
+    return embedding
+
+
+# Register it
+msp.register_reducer("umap", umap_reducer, component_prefix="UMAP")
+
+# Use it
+rgb = msp.reduce_to_rgb(scores, method="umap")
+msp.plot_embedding(adata, rgb, basis="umap", method="umap",
+                   gene_set_names=list(gene_sets.keys()))
+```
+
+## Different Embeddings
+
+Plot the same RGB coloring on different embeddings to compare:
+
+```python
+import matplotlib.pyplot as plt
+
+scores = msp.score_gene_sets(adata, gene_sets, inplace=True)
+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"]):
+    msp.plot_embedding(
+        adata, rgb,
+        basis=basis,
+        method="pca",
+        gene_set_names=list(gene_sets.keys()),
+        ax=ax,
+        title=basis.upper(),
+        show=False,
+    )
+
+plt.tight_layout()
+plt.show()
+```
+
+## Comparing Reduction Methods
+
+Visualize how PCA, NMF, and ICA produce different colorings:
+
+```python
+import matplotlib.pyplot as plt
+
+scores = msp.score_gene_sets(adata, gene_sets, inplace=True)
+
+fig, axes = plt.subplots(1, 3, figsize=(18, 5))
+
+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()),
+        ax=ax,
+        title=method.upper(),
+        show=False,
+    )
+
+plt.tight_layout()
+plt.show()
+```
+
+## Interactive Plot with Hover Metadata
+
+Explore individual cells with hover tooltips:
+
+```python
+scores = msp.score_gene_sets(adata, gene_sets, inplace=True)
+rgb = msp.reduce_to_rgb(scores, method="nmf")
+
+msp.plot_embedding_interactive(
+    adata, rgb,
+    basis="umap",
+    scores=scores,
+    method="nmf",
+    gene_set_names=list(gene_sets.keys()),
+    hover_columns=["n_counts", "cell_type"],  # any adata.obs columns
+    point_size=2,
+    width=800,
+    height=600,
+)
+```
+
+## Customizing Plot Appearance
+
+```python
+ax = msp.plot_embedding(
+    adata, rgb,
+    basis="umap",
+    method="pca",
+    gene_set_names=list(gene_sets.keys()),
+    point_size=5,
+    alpha=0.6,
+    figsize=(8, 8),
+    title="SVZ Neural Lineage",
+    legend=True,
+    legend_style="side",       # legend in a separate panel
+    legend_loc="upper right",
+    show=False,
+)
+
+# Further customize the returned axes
+ax.set_xlabel("UMAP 1", fontsize=14)
+ax.set_ylabel("UMAP 2", fontsize=14)
+```
+
+## Direct Blend for 2–3 Gene Sets
+
+When you have exactly 2 or 3 gene sets, direct blending gives the most intuitive
+color mapping:
+
+```python
+two_sets = {
+    "Stem": ["Sox2", "Pax6", "Nes"],
+    "Neuronal": ["Dcx", "Tubb3", "Neurod1"],
+}
+
+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()),
+)
+```

multiscoresplot-1.0.5/docs/getting-started.md

@@ -0,0 +1,64 @@
+# Getting Started
+
+## Installation
+
+Install from PyPI:
+
+```bash
+pip install multiscoresplot
+```
+
+For interactive Plotly plots:
+
+```bash
+pip install 'multiscoresplot[interactive]'
+```
+
+## Prerequisites
+
+multiscoresplot expects an [AnnData](https://anndata.readthedocs.io/) object with:
+
+- A precomputed dimensionality reduction embedding (e.g., UMAP, PCA, or Scanorama) stored in `adata.obsm`
+- Gene expression data (raw or normalized) accessible for scoring
+
+## Minimal Working Example
+
+```python
+import multiscoresplot as msp
+
+# 1. Define your gene sets
+gene_sets = {
+    "Stem":       ["Sox2", "Pax6", "Nes"],
+    "Neuronal":   ["Dcx", "Tubb3", "Neurod1"],
+    "Astrocytic": ["Gfap", "Aqp4", "Aldh1l1"],
+}
+
+# 2. Score gene sets per cell (stores in adata.obs as score-<name>)
+scores = msp.score_gene_sets(adata, gene_sets, inplace=True)
+
+# 3. Map scores to RGB — choose one:
+#    Direct blend (2–3 gene sets only)
+rgb = msp.blend_to_rgb(scores)
+#    Or dimensionality reduction (any number of gene sets)
+rgb = msp.reduce_to_rgb(scores, method="pca")
+
+# 4. Plot on a UMAP embedding
+msp.plot_embedding(
+    adata, rgb,
+    basis="umap",
+    method="pca",
+    gene_set_names=list(gene_sets.keys()),
+)
+```
+
+!!! tip "Which color mapping to use?"
+    - **`blend_to_rgb`** — Best for 2–3 gene sets. Uses intuitive multiplicative blending from white, where each gene set darkens toward its assigned color.
+    - **`reduce_to_rgb`** — Works for any number of gene sets (2+). Uses PCA, NMF, or ICA to project scores into a 3D RGB space.
+
+    See the [Pipeline Guide](pipeline.md) for a detailed comparison.
+
+## Next Steps
+
+- [Pipeline Guide](pipeline.md) — Understand each step and when to use each method
+- [API Reference](api/index.md) — Full function signatures and parameters
+- [Examples](examples.md) — Custom reducers, plot customization, and more

multiscoresplot-1.0.5/docs/index.md

@@ -0,0 +1,46 @@
+# multiscoresplot
+
+**Multi-dimensional gene set scoring and visualization for single-cell transcriptomics.**
+
+Color dimensionality reduction plots (UMAP, PCA, etc.) using a multi-dimensional
+color space derived from gene set scores — visualize the activity of multiple gene
+programs simultaneously in a single plot.
+
+## Key Features
+
+- **Score** gene sets per cell using [UCell](https://github.com/Cem-Gulec/pyUCell)
+- **Blend** 2–3 gene sets to RGB via multiplicative blending
+- **Reduce** any number of gene sets to RGB via PCA / NMF / ICA
+- **Plot** static matplotlib or interactive Plotly scatter plots
+- **Extend** with custom dimensionality reduction methods
+
+## Quick Example
+
+```python
+import multiscoresplot as msp
+
+# Define gene sets of interest
+gene_sets = {
+    "qNSCs": ["Id3", "Aldoc", "Slc1a3"],
+    "aNSCs": ["Egfr", "Ascl1", "Mki67"],
+    "TAP":   ["Dll1", "Dcx", "Neurod1"],
+    "NB":    ["Dcx", "Sox11", "Tubb3"],
+}
+
+# 1. Score gene sets per cell
+scores = msp.score_gene_sets(adata, gene_sets, inplace=True)
+
+# 2. Map scores to RGB colors
+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()),
+)
+```
+
+[Get Started](getting-started.md){ .md-button .md-button--primary }
+[API Reference](api/index.md){ .md-button }

multiscoresplot-1.0.5/docs/pipeline.md

@@ -0,0 +1,149 @@
+# Pipeline Guide
+
+multiscoresplot follows a 5-step pipeline to go from gene sets to a colored embedding plot.
+
+## Step 1 — Score Gene Sets
+
+Calculate per-cell gene set scores using [pyUCell](https://github.com/Cem-Gulec/pyUCell).
+Scores are stored in `adata.obs` as `score-<name>` columns with values in [0, 1].
+
+```python
+scores = msp.score_gene_sets(adata, gene_sets, inplace=True)
+
+# With tuning parameters
+scores = msp.score_gene_sets(
+    adata, gene_sets,
+    max_rank=1500,    # rank cap (tune to median genes per cell)
+    chunk_size=1000,  # cells per batch
+    n_jobs=-1,        # parallelism (-1 = all cores)
+    inplace=False,    # don't store in adata.obs
+)
+```
+
+!!! note
+    `score_gene_sets` wraps pyUCell's ranking-based scoring. The `max_rank` parameter
+    controls how many top-ranked genes per cell are considered — set it close to the
+    median number of detected genes per cell for best results.
+
+## Step 2 — Blend to RGB (2–3 Gene Sets)
+
+For **2–3 gene sets**, multiplicative blending maps scores directly to colors. Starting from
+white, each gene set darkens the color toward its base hue proportionally to the score.
+
+```python
+# Default colors (2 sets: blue/red, 3 sets: R/G/B)
+rgb = msp.blend_to_rgb(scores)
+
+# Custom colors
+rgb = msp.blend_to_rgb(scores, colors=[(1, 0, 0), (0, 0.5, 1)])
+```
+
+**How it works:** Each cell starts as white `(1, 1, 1)`. For each gene set, the cell's
+color is multiplied element-wise by a blend between white and the gene set's base color,
+weighted by the score. High scores pull the color toward the base hue; low scores leave
+it near white. Cells with multiple high scores produce mixed colors.
+
+## Step 3 — Reduce to RGB (2+ Gene Sets)
+
+For **any number of gene sets**, dimensionality reduction projects the score matrix into
+3 components that become RGB channels.
+
+```python
+rgb = msp.reduce_to_rgb(scores, method="pca")  # default
+rgb = msp.reduce_to_rgb(scores, method="nmf")
+rgb = msp.reduce_to_rgb(scores, method="ica")
+```
+
+### Choosing a Reduction Method
+
+| Method | Best for | Properties |
+|--------|----------|------------|
+| **PCA** | General use | Linear, orthogonal components, preserves maximum variance. Components can mix positive and negative loadings. |
+| **NMF** | Interpretability | Non-negative components — each RGB channel corresponds to a non-negative combination of gene sets. Often more biologically intuitive. |
+| **ICA** | Independent signals | Maximizes statistical independence between components. Useful when gene programs are expected to be independent. |
+
+!!! tip
+    Start with **PCA** for exploration. Switch to **NMF** if you want components that are
+    easier to interpret biologically (since NMF coefficients are always non-negative).
+    Use **ICA** when you suspect the gene programs represent statistically independent signals.
+
+## Step 4 — Plot Embedding
+
+Scatter plot of embedding coordinates (UMAP, PCA, etc.) colored by the RGB values,
+with an integrated color-space legend.
+
+```python
+# Basic usage
+msp.plot_embedding(
+    adata, rgb,
+    basis="umap",
+    method="pca",
+    gene_set_names=["qNSCs", "aNSCs", "TAP", "NB"],
+)
+
+# With customization
+ax = msp.plot_embedding(
+    adata, rgb,
+    basis="umap",
+    method="pca",
+    gene_set_names=["qNSCs", "aNSCs", "TAP", "NB"],
+    legend=True,              # show color legend (default)
+    legend_style="inset",     # "inset" or "side"
+    legend_loc="lower right", # legend position
+    point_size=3,
+    alpha=0.8,
+    figsize=(6, 6),
+    title="SVZ lineage",
+    show=False,               # return axes instead of displaying
+)
+```
+
+### Step 4b — Interactive Plot (requires Plotly)
+
+WebGL-accelerated scatter plot with hover info showing gene set scores, RGB channel
+values, and custom metadata.
+
+```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"],
+    legend=True,
+    legend_loc="lower right",
+    point_size=2,
+    width=600,
+    height=500,
+)
+```
+
+!!! note
+    Interactive plots require the `plotly` extra: `pip install 'multiscoresplot[interactive]'`
+
+## Step 5 — Standalone Legend
+
+Render the color-space legend independently on any matplotlib axes.
+
+```python
+import matplotlib.pyplot as plt
+
+fig, ax = plt.subplots()
+
+# Direct mode (2-set square or 3-set triangle)
+msp.render_legend(ax, "direct", gene_set_names=["A", "B", "C"])
+
+# Reduction mode (RGB triangle with component labels)
+msp.render_legend(ax, "pca")
+msp.render_legend(ax, "nmf", component_labels=["NMF1", "NMF2", "NMF3"])
+```
+
+## Blend vs. Reduce — When to Use Which
+
+| | `blend_to_rgb` | `reduce_to_rgb` |
+|---|---|---|
+| **Gene sets** | 2–3 only | 2 or more |
+| **Color mapping** | Direct: each gene set has its own color | Learned: RGB channels are linear combinations of scores |
+| **Interpretability** | Immediate — colors correspond directly to gene sets | Requires the legend to interpret RGB channels |
+| **Best for** | Focused comparisons of 2–3 programs | Exploratory analysis of many programs simultaneously |