miso-plot is a simple yet efficient Python library for visualizing large clustered datasets. It was designed for fast exploration of high-density 2D embeddings such as UMAP, t-SNE, or PCA outputs, using adaptive density smoothing and perceptually uniform color palettes.
Typical use cases include:
- visual inspection of clustering quality in large datasets,
- density-based highlighting of local data structures,
- generation of publication-quality scatter plots.
pip install miso-plot
Or install the latest development version directly from GitHub:
pip install git+https://github.com/Aleksandra795/miso-plot.git
import numpy as np
import matplotlib.pyplot as plt
from sklearn.datasets import make_blobs
from miso_plot import miso_plot
# Generate synthetic clustered data
X, labels = make_blobs(n_samples=50000, centers=6, n_features=2, random_state=42)
Y = X[:, 1]
X = X[:, 0]
# Plot simple scatterplot of the data
plt.figure()
plt.scatter(X, Y, s=10, c=labels, alpha=0.5, cmap='tab10')
plt.xlabel("x")
plt.ylabel("y")
plt.title("simple scatter plot")
plt.grid(True)
plt.show()
Because often the clusters overlap substantially, identifying their true centers is challenging. miso-plot facilitates this process by visualizing each cluster’s density distribution, highlighting regions representing the top m fraction of its overall density.
# Show cluster density centers with miso-plot
fig, ax = plt.subplots()
plt.scatter(X, Y, s=10, c='#D6D6D6', alpha=0.5)
miso_plot(X, Y, labels, cmap="tab10", m=0.5, ax=ax)
plt.xlabel("x")
plt.ylabel("y")
plt.title("mISO plot, m=0.5")
plt.grid(True)
plt.show()
The usefulness of miso-plot is best illustrated using real experimental data. Below is an example based on single-cell mass cytometry data from Samusik et al. (2016) — “Automated mapping of phenotype space with single-cell data” (Nature Methods, 13, 493–496; DOI: 10.1038/nmeth.3863) — containing 24 manually annotated bone marrow cell subtypes. miso-plot clearly reveals the dominant spatial organization of these subtypes on the UMAP projection while suppressing outliers and low-density noise, making the overall cluster structure easier to interpret.
miso_plot(X, Y, labels, cmap='miso24', m=0.5, lam=20, ax=None, alpha=0.3, marker='s', size=10)
Generates a smoothed scatter plot with adaptive density highlighting.
| Parameter | Type | Description |
|---|---|---|
X, Y | np.ndarray | Coordinates of points |
labels | np.ndarray | Cluster labels for each point |
cmap | str or list | Colormap ('miso24', matplotlib/seaborn name, or list of hex) |
m | float | Density threshold |
lam | int | Smoothing parameter |
ax | matplotlib.axes.Axes or None | Optional existing Axes; creates a new one if None |
alpha | float | Transparency of points |
marker | str | Marker style |
size | int | Size of each point |
The m parameter has the strongest impact on the visual output of miso-plot. Its default value is 0.5, corresponding to the median density isoline, but it can be adjusted to control how much of the cluster density is visualized. Common choices include 0.25 (top 75% of the densest regions) and 0.75 (top 25%), depending on the desired level of detail.
Built-in palette: miso24
Designed for cluster visualization (24 clusters) with high perceptual separation.
You may also pass:
- any matplotlib/seaborn palette name (e.g. 'viridis', 'tab10'),
- a custom list of hex colors (e.g. ['ff0000', '00ff00', '0000ff']).
If you use miso-plot or the underlying method in your research or publications, please cite:
Suwalska, A.; Polanska, J.
GMM-Based Expanded Feature Space as a Way to Extract Useful Information for Rare Cell Subtypes Identification in Single-Cell Mass Cytometry.
Int. J. Mol. Sci. 2023, 24(18), 14033.
https://doi.org/10.3390/ijms241814033
(Open Access)
This project is distributed under the MIT License.