update readme, add new functions

Author: philinscience

README.md

@@ -5,25 +5,32 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 [![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](pyproject.toml)
 
-**scplotkit** is a publication-ready plotting toolkit for single-cell atlas
-analysis, built on top of [scanpy](https://scanpy.readthedocs.io) and
-[AnnData](https://anndata.readthedocs.io). It focuses on the figures that
-don't ship out of the box with scanpy: masked/highlighted embeddings,
-multi-view compositional bar plots and heatmaps, dataset overview panels, and
-Sankey diagrams over annotation hierarchies — all styled consistently and
-saved to disk with one call.
-
-- **scanpy-native** — works directly on `AnnData` objects, no intermediate data wrangling.
-- **Consistent styling** — a single `PlotConfig` controls fonts, DPI, and color palettes across every plot.
-- **No hidden assumptions** — column names, palettes, and grouping variables are always explicit arguments; sensible colors are auto-generated when you don't supply a palette.
-- **Two APIs** — a functional, scanpy-style API (`scplotkit.composition.stacked_barplots(...)`) and a stateful convenience class (`scplotkit.ScPlotter`) for when you're producing many figures against the same config/output directory.
+This is just a pile of plotting functions I kept rewriting from scratch for
+every single-cell project, finally bundled up so I stop copy-pasting them
+between notebooks. Built on top of [scanpy](https://scanpy.readthedocs.io) and
+[AnnData](https://anndata.readthedocs.io) — masked/highlighted UMAPs,
+composition bar plots and heatmaps, pseudobulk boxplots, marker gene panels,
+Sankeys/sunbursts/treemaps over annotation hierarchies, that kind of thing.
+Nothing statistical happening here, no new analysis — it's purely "make the
+plot I already know I want, and make it look the same every time."
+
+Not trying to be *the* single-cell plotting library, it's just what's in my
+toolbox. If you've got a plot you always reach for that isn't in here, please
+open a PR — genuinely happy to have other people's favorite ways of looking at
+single-cell (and maybe eventually spatial) data in here too. See
+[Contributing](#contributing) below.
+
+- **scanpy-native** — works directly on `AnnData` objects, no wrangling in between.
+- **One config, every plot** — a single `PlotConfig` controls fonts, DPI, and color palettes, so figures don't end up looking like they came from six different notebooks.
+- **Explicit over magic** — column names, palettes, and grouping variables are always arguments you pass in; if you don't give a palette, a colorblind-friendly one gets generated for you.
+- **Two ways to call it** — plain functions (`scplotkit.composition.stacked_barplots(...)`) if you like the scanpy-style API, or `scplotkit.ScPlotter` if you're making a bunch of figures and don't want to pass `config`/`output_dir` every single time.
 
 ## Installation
 
 ```bash
 pip install scplotkit
 
-# optional: Sankey diagrams (requires plotly + kaleido)
+# optional: Sankey/sunburst/treemap plots (needs plotly + kaleido)
 pip install "scplotkit[sankey]"
 ```
 
@@ -79,14 +86,14 @@ composition.stacked_barplots(adata, level_column="cell_type", sample_column="sam
 
 | Module | Plots |
 | --- | --- |
-| `scplotkit.embeddings` | Masked UMAP, highlighted UMAP overlays, gene expression on an embedding (masked or full) |
-| `scplotkit.composition` | Stacked composition bar plots (basic / clustered / grouped-clustered), multi-metadata variant, clustered composition heatmap |
-| `scplotkit.overview` | Samples/cells-per-category bar plots (incl. broken-axis), cells-per-patient boxplot, cell abundance bar plots, dataset-vs-dataset comparison (bars and paired boxplots) |
-| `scplotkit.markers` | Rank-genes-groups dot/matrix plots, custom marker-set matrix and stacked-violin plots, gene-panel expression heatmap with optional z-scoring and dendrograms |
-| `scplotkit.pseudobulk` | Per-sample pseudobulk boxplot for one gene, min-max-scaled multi-gene boxplot |
-| `scplotkit.ridgeline` | Ridgeline (joy) plots of a continuous value across groups, with optional per-condition overlay |
-| `scplotkit.enrichment` | Dot plot overview of over-representation analysis (ORA) results, e.g. from Enrichr/gseapy |
-| `scplotkit.sankey` | Sankey diagrams across 1-3 nested annotation levels |
+| `scplotkit.embeddings` | Masked UMAP, masked-and-highlighted UMAP overlay, gene expression on an embedding, two-gene co-expression color blend, per-group embedding density |
+| `scplotkit.composition` | Stacked composition bar plots (plain / clustered / clustered-within-group), a multi-metadata variant with color strips, a clustered composition heatmap, a cell-count bubble grid |
+| `scplotkit.overview` | Samples/cells-per-category bar plots (incl. broken-axis), cells-per-patient boxplot, cell abundance bar plots, dataset-vs-dataset comparisons (bars and paired boxplots) |
+| `scplotkit.markers` | `rank_genes_groups` dot/matrix plots, plus matrix and stacked-violin plots for your own marker gene sets |
+| `scplotkit.pseudobulk` | Per-sample pseudobulk boxplot for one gene, or several at once (optionally min-max scaled) |
+| `scplotkit.ridgeline` | Ridgeline (joy) plots of a continuous value across groups, with an optional per-condition overlay |
+| `scplotkit.enrichment` | Dot plot for over-representation analysis (ORA) results, e.g. from Enrichr/gseapy |
+| `scplotkit.sankey` | Sankeys, sunbursts, and treemaps over 1-3 nested annotation levels |
 
 ## Configuration
 
@@ -112,16 +119,23 @@ value up front.
 
 ## Documentation & tutorial
 
-Full API reference and a runnable tutorial (built on scanpy's public pbmc3k
-dataset) are in [`docs/`](docs/) and published at
-https://scplotkit.readthedocs.io. To build the docs locally:
+Full API reference and a runnable tutorial (on a real published atlas) live
+in [`docs/`](docs/) and are published at https://scplotkit.readthedocs.io. To
+build the docs locally:
 
 ```bash
 pip install -e ".[docs]"
 sphinx-build -b html docs docs/_build/html
 ```
 
-## Development
+## Contributing
+
+Got a plot you always end up making for single-cell (or spatial) data? Open a
+PR. No formal process here — just try to match the existing style (one
+function per plot, `config`/`output_dir` as the last two args, save via
+`save_figure` so it lands in the same place as everything else) and add it to
+`__all__` and the table above. Bug reports and "this default looks bad"
+complaints are just as welcome as new plots.
 
 ```bash
 pip install -e ".[dev]"

docs/index.md

@@ -1,13 +1,15 @@
 # scplotkit
 
-Publication-ready plotting for single-cell atlas analysis, built on top of
-[scanpy](https://scanpy.readthedocs.io) and [AnnData](https://anndata.readthedocs.io).
+A pile of plotting functions for single-cell analysis, built on top of
+[scanpy](https://scanpy.readthedocs.io) and [AnnData](https://anndata.readthedocs.io),
+bundled up so they don't have to be rewritten for every new project.
 
-scplotkit fills in the figures scanpy doesn't ship out of the box: masked and
-highlighted embeddings, multi-view compositional bar plots and heatmaps,
-dataset overview panels, marker-gene matrix/violin plots, and Sankey diagrams
-over annotation hierarchies — all styled consistently through a single
-{class}`~scplotkit.PlotConfig` and saved to disk with one call.
+Masked and highlighted embeddings, gene co-expression blends, compositional
+bar plots and heatmaps, dataset overview panels, marker-gene matrix/violin
+plots, Sankeys/sunbursts/treemaps over annotation hierarchies — all styled
+consistently through a single {class}`~scplotkit.PlotConfig` and saved to disk
+with one call. Nothing statistical, no new analysis, just the plots. PRs for
+your own favorite single-cell (or spatial) plots are very welcome.
 
 ```{toctree}
 :maxdepth: 2
@@ -31,5 +33,5 @@ plotter.masked_umap(adata, color_by="cell_type", mask_values=["CD4 T", "CD8 T"],
 plotter.stacked_barplots(adata, level_column="cell_type", sample_column="sample_id")
 ```
 
-See the {doc}`tutorial/tutorial` for a full walkthrough on a public dataset,
-or the {doc}`api` for the complete function reference.
+See the {doc}`tutorial/tutorial` for a full walkthrough on a real published
+atlas, or the {doc}`api` for the complete function reference.