multiscoresplot 1.0.0__tar.gz → 1.0.2__tar.gz

{multiscoresplot-1.0.0 → multiscoresplot-1.0.2}/.gitignore

@@ -1,5 +1,7 @@
 CLAUDE.md
+RELEASE.md
 .claude
+test_data/*.h5ad
 
 # Byte-compiled / optimized / DLL files
 __pycache__/
@@ -99,4 +101,4 @@ dmypy.json
 *.swp
 *.swo
 *~
-.DS_Store
+.DS_Store

multiscoresplot-1.0.2/PKG-INFO

@@ -0,0 +1,256 @@
+Metadata-Version: 2.4
+Name: multiscoresplot
+Version: 1.0.2
+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
+Author: Andre Macedo
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: anndata>=0.10
+Requires-Dist: matplotlib>=3.7
+Requires-Dist: numpy>=1.24
+Requires-Dist: pyucell>=0.5
+Requires-Dist: scanpy>=1.9
+Requires-Dist: scikit-learn>=1.3
+Provides-Extra: interactive
+Requires-Dist: plotly>=5.0; extra == 'interactive'
+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/)
+[![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.**
+
+Color dimensionality reduction plots (UMAP, PCA, etc.) using a multi-dimensional color space derived from gene set scores — so you can visualize the activity of multiple gene programs simultaneously in a single plot.
+
+## Installation
+
+```bash
+pip install multiscoresplot
+```
+
+For interactive Plotly plots:
+
+```bash
+pip install 'multiscoresplot[interactive]'
+```
+
+## Quick Start
+
+```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()),
+)
+```
+
+## Pipeline
+
+multiscoresplot follows a 5-step pipeline:
+
+### 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)
+
+# Options
+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
+)
+```
+
+### Step 2 — Blend to RGB (2–3 gene sets)
+
+For 2–3 gene sets, use multiplicative blending from white. Each gene set darkens toward its base color proportional 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)])
+```
+
+### Step 3 — Reduce to RGB (2+ gene sets)
+
+For any number of gene sets (2 or more), use dimensionality reduction to map scores to 3 RGB channels. Built-in methods: PCA, NMF, and ICA.
+
+```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")
+```
+
+### Step 4 — Plot embedding
+
+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"],
+)
+
+# Options
+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 Plotly 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"],  # extra adata.obs columns
+    legend=True,
+    legend_loc="lower right",
+    point_size=2,
+    width=600,
+    height=500,
+)
+```
+
+### Step 5 — Standalone legend
+
+Render the color-space legend 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"])
+```
+
+## Extensibility — Custom reducers
+
+Register your own dimensionality reduction method:
+
+```python
+def my_umap_reducer(X, n_components, **kwargs):
+    """X: (n_cells, n_gene_sets), returns (n_cells, 3) 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
+
+msp.register_reducer("umap", my_umap_reducer, component_prefix="UMAP")
+
+# Now use it like any built-in method
+rgb = msp.reduce_to_rgb(scores, method="umap")
+```
+
+## 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    |
+
+## Development
+
+```bash
+git clone https://github.com/andrecmacedo/multiscoresplot.git
+cd multiscoresplot
+
+# Install in editable mode with dev dependencies
+pip install -e ".[interactive]"
+pip install ruff pre-commit pytest pytest-cov mypy
+
+# Run tests
+pytest
+
+# Lint & format
+ruff check src/ tests/
+ruff format src/ tests/
+
+# Type check
+mypy src/
+
+# Set up pre-commit hooks
+pre-commit install
+```
+
+## License
+
+[MIT](LICENSE)

multiscoresplot-1.0.2/README.md

@@ -0,0 +1,224 @@
+# 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/)
+[![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.**
+
+Color dimensionality reduction plots (UMAP, PCA, etc.) using a multi-dimensional color space derived from gene set scores — so you can visualize the activity of multiple gene programs simultaneously in a single plot.
+
+## Installation
+
+```bash
+pip install multiscoresplot
+```
+
+For interactive Plotly plots:
+
+```bash
+pip install 'multiscoresplot[interactive]'
+```
+
+## Quick Start
+
+```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()),
+)
+```
+
+## Pipeline
+
+multiscoresplot follows a 5-step pipeline:
+
+### 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)
+
+# Options
+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
+)
+```
+
+### Step 2 — Blend to RGB (2–3 gene sets)
+
+For 2–3 gene sets, use multiplicative blending from white. Each gene set darkens toward its base color proportional 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)])
+```
+
+### Step 3 — Reduce to RGB (2+ gene sets)
+
+For any number of gene sets (2 or more), use dimensionality reduction to map scores to 3 RGB channels. Built-in methods: PCA, NMF, and ICA.
+
+```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")
+```
+
+### Step 4 — Plot embedding
+
+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"],
+)
+
+# Options
+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 Plotly 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"],  # extra adata.obs columns
+    legend=True,
+    legend_loc="lower right",
+    point_size=2,
+    width=600,
+    height=500,
+)
+```
+
+### Step 5 — Standalone legend
+
+Render the color-space legend 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"])
+```
+
+## Extensibility — Custom reducers
+
+Register your own dimensionality reduction method:
+
+```python
+def my_umap_reducer(X, n_components, **kwargs):
+    """X: (n_cells, n_gene_sets), returns (n_cells, 3) 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
+
+msp.register_reducer("umap", my_umap_reducer, component_prefix="UMAP")
+
+# Now use it like any built-in method
+rgb = msp.reduce_to_rgb(scores, method="umap")
+```
+
+## 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    |
+
+## Development
+
+```bash
+git clone https://github.com/andrecmacedo/multiscoresplot.git
+cd multiscoresplot
+
+# Install in editable mode with dev dependencies
+pip install -e ".[interactive]"
+pip install ruff pre-commit pytest pytest-cov mypy
+
+# Run tests
+pytest
+
+# Lint & format
+ruff check src/ tests/
+ruff format src/ tests/
+
+# Type check
+mypy src/
+
+# Set up pre-commit hooks
+pre-commit install
+```
+
+## License
+
+[MIT](LICENSE)

{multiscoresplot-1.0.0 → multiscoresplot-1.0.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "multiscoresplot"
-version = "1.0.0"
+version = "1.0.2"
 description = "Multi-dimensional gene set scoring and visualization for single-cell transcriptomics"
 readme = "README.md"
 license = "MIT"
@@ -79,7 +79,20 @@ warn_unused_configs = true
 disallow_untyped_defs = false
 
 [[tool.mypy.overrides]]
-module = ["pyucell", "pyucell.*", "anndata", "anndata.*", "scanpy", "scanpy.*", "pandas", "pandas.*", "sklearn", "sklearn.*", "plotly", "plotly.*"]
+module = [
+    "pyucell",
+    "pyucell.*",
+    "anndata",
+    "anndata.*",
+    "scanpy",
+    "scanpy.*",
+    "pandas",
+    "pandas.*",
+    "sklearn",
+    "sklearn.*",
+    "plotly",
+    "plotly.*",
+]
 ignore_missing_imports = true
 disable_error_code = ["import-untyped"]
 

{multiscoresplot-1.0.0 → multiscoresplot-1.0.2}/src/multiscoresplot/__init__.py

@@ -25,4 +25,4 @@ __all__ = [
     "render_legend",
     "score_gene_sets",
 ]
-__version__ = "1.0.0"
+__version__ = "1.0.2"

multiscoresplot-1.0.0/PKG-INFO

@@ -1,85 +0,0 @@
-Metadata-Version: 2.4
-Name: multiscoresplot
-Version: 1.0.0
-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
-Author: Andre Macedo
-License-Expression: MIT
-License-File: LICENSE
-Classifier: Development Status :: 5 - Production/Stable
-Classifier: Intended Audience :: Science/Research
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
-Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
-Classifier: Topic :: Scientific/Engineering :: Visualization
-Classifier: Typing :: Typed
-Requires-Python: >=3.10
-Requires-Dist: anndata>=0.10
-Requires-Dist: matplotlib>=3.7
-Requires-Dist: numpy>=1.24
-Requires-Dist: pyucell>=0.5
-Requires-Dist: scanpy>=1.9
-Requires-Dist: scikit-learn>=1.3
-Provides-Extra: interactive
-Requires-Dist: plotly>=5.0; extra == 'interactive'
-Description-Content-Type: text/markdown
-
-# multiscoresplot
-
-[![CI](https://github.com/andrecmacedo/multiscoresplot/actions/workflows/ci.yml/badge.svg)](https://github.com/andrecmacedo/multiscoresplot/actions/workflows/ci.yml)
-[![PyPI](https://img.shields.io/pypi/v/multiscoresplot)](https://pypi.org/project/multiscoresplot/)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-
-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.
-
-## Installation
-
-```bash
-pip install multiscoresplot
-```
-
-## Quick Start
-
-```python
-import multiscoresplot  # more to come!
-```
-
-## Pipeline
-
-1. **Score** -- Calculate gene set scores per cell
-2. **Color space** -- Build a color space where each axis/vertex maps to a gene set
-3. **Project** -- Map each cell into the color space based on its scores
-4. **Plot** -- Color dimensionality reduction coordinates using the projected colors
-5. **Legend** -- Render a simplex/ternary plot as the colorbar
-
-## Development
-
-```bash
-# Install in editable mode with all dev dependencies
-pip install -e ".[dev,test,type]"
-
-# Run tests
-pytest
-
-# Lint & format
-ruff check src/ tests/
-ruff format src/ tests/
-
-# Type check
-mypy src/
-
-# Set up pre-commit hooks
-pre-commit install
-```
-
-## License
-
-[MIT](LICENSE)

multiscoresplot-1.0.0/README.md

@@ -1,53 +0,0 @@
-# multiscoresplot
-
-[![CI](https://github.com/andrecmacedo/multiscoresplot/actions/workflows/ci.yml/badge.svg)](https://github.com/andrecmacedo/multiscoresplot/actions/workflows/ci.yml)
-[![PyPI](https://img.shields.io/pypi/v/multiscoresplot)](https://pypi.org/project/multiscoresplot/)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-
-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.
-
-## Installation
-
-```bash
-pip install multiscoresplot
-```
-
-## Quick Start
-
-```python
-import multiscoresplot  # more to come!
-```
-
-## Pipeline
-
-1. **Score** -- Calculate gene set scores per cell
-2. **Color space** -- Build a color space where each axis/vertex maps to a gene set
-3. **Project** -- Map each cell into the color space based on its scores
-4. **Plot** -- Color dimensionality reduction coordinates using the projected colors
-5. **Legend** -- Render a simplex/ternary plot as the colorbar
-
-## Development
-
-```bash
-# Install in editable mode with all dev dependencies
-pip install -e ".[dev,test,type]"
-
-# Run tests
-pytest
-
-# Lint & format
-ruff check src/ tests/
-ruff format src/ tests/
-
-# Type check
-mypy src/
-
-# Set up pre-commit hooks
-pre-commit install
-```
-
-## License
-
-[MIT](LICENSE)