BuenColors Single Cell Demo¶

This notebook demonstrates the single-cell analysis features in BuenColors, designed to work with Scanpy and AnnData objects.

Installation¶

To use the single-cell features, you need to have scanpy and anndata installed:

pip install buencolors scanpy anndata

✓ Scanpy and AnnData are available

Load Example Dataset¶

We'll use the PBMC3k dataset, a standard example in single-cell analysis that contains ~3000 peripheral blood mononuclear cells.

100%|██████████| 23.5M/23.5M [00:01<00:00, 20.0MB/s]

Dataset shape: (2638, 1838)
Available observations: ['n_genes', 'percent_mito', 'n_counts', 'louvain']

Cell type distribution:
louvain
CD4 T cells          1144
CD14+ Monocytes       480
B cells               342
CD8 T cells           316
NK cells              154
FCGR3A+ Monocytes     150
Dendritic cells        37
Megakaryocytes         15
Name: count, dtype: int64

Clean UMAP Visualization¶

The clean_umap() function creates beautiful, publication-ready UMAP plots with:

• Minimal decorations (no borders, ticks, or frame)
• Custom L-shaped axis indicators with arrowheads
• Automatically ejected legend to the right side
• Shuffled cells to avoid non-random ordering artifacts

Basic Usage - Cell Type Coloring¶

<Figure size 1000x800 with 0 Axes>

Gene Expression Visualization¶

You can also color cells by gene expression levels:

Customizing Axis Indicators¶

You can customize the appearance of the axis indicators:

Comparison: Standard vs Clean UMAP¶

Let's compare the standard Scanpy UMAP with BuenColors' clean version:

Using BuenColors Palettes with UMAPs¶

You can combine clean_umap() with BuenColors' beautiful color palettes:

<Figure size 1000x800 with 0 Axes>

Multiple Color Variables¶

Create a multi-panel figure showing different aspects of your data:

Combining with Pretty Plot Style¶

For even better-looking plots, combine clean_umap() with the BuenColors pretty-plot style:

<Figure size 5000x4000 with 0 Axes>

Summary¶

The clean_umap() function provides:

1. Minimal decorations - Clean, publication-ready plots without unnecessary visual clutter
2. Custom axis indicators - Professional L-shaped axes with arrowheads
3. Auto-ejected legends - Legends placed outside the plot area to avoid obscuring data
4. Cell shuffling - Automatic randomization to prevent ordering artifacts
5. scVelo-style outlines - Concentric black/white ring outlines around points
6. Selective highlighting - Dim background cells and outline specific groups
7. Full customization - Compatible with all Scanpy UMAP parameters

Parameters¶

Parameter	Default	Description
adata	—	AnnData object containing UMAP coordinates
color	—	adata.obs column or gene name for coloring
outline_style	False	True = outline all cells; str/list = highlight group(s)
outline_width	(0.3, 0.05)	(bg_ring, white_gap) widths as fraction of point radius
ax	None	Existing matplotlib axis (creates new if None)
axis_len	0.2	Length of axis arrow indicators (axes fraction)
thickness	3.0	Line width of axis indicators
**kwargs	—	Additional arguments forwarded to sc.pl.umap()

Compatibility¶

Requires:

• anndata - for AnnData objects
• scanpy - for UMAP plotting
• matplotlib - for plotting (already a BuenColors dependency)

Selective Group Highlighting¶

Pass a group name (string) or list of names to outline_style to highlight only those clusters. All other cells are dimmed to emphasise the selection — a common style in trajectory and cell-type annotation figures.

Outline All Cells¶

Pass outline_style=True to add a black-and-white outline ring to every point. This uses Scanpy's native add_outline machinery for pixel-perfect centering.

scVelo-Style Outlines¶

clean_umap() supports scVelo-style concentric outline rings around points via the outline_style parameter. Three modes are available:

outline_style	Effect
True	Outline every cell
"Group" or ["G1", "G2"]	Dim all cells, outline only the specified group(s)
False (default)	No outlines

The ring widths are controlled by outline_width=(bg_width, gap_width), where each value is a fraction of the point radius.

Summary¶

The clean_umap() function provides:

1. Minimal decorations - Clean, publication-ready plots without unnecessary visual clutter
2. Custom axis indicators - Professional L-shaped axes with arrowheads
3. Auto-ejected legends - Legends placed outside the plot area to avoid obscuring data
4. Cell shuffling - Automatic randomization to prevent ordering artifacts
5. Full customization - Compatible with all Scanpy UMAP parameters

Parameters¶

• adata: AnnData object containing UMAP coordinates
• color: Column in adata.obs or gene name for coloring
• ax: Optional matplotlib axis (if None, creates new)
• axis_len: Length of axis indicators (default: 0.2)
• thickness: Line width of axis indicators (default: 3.0)
• **kwargs: Additional arguments passed to sc.pl.umap()

Compatibility¶

Requires:

• anndata - for AnnData objects
• scanpy - for UMAP plotting
• matplotlib - for plotting (already a BuenColors dependency)