miso-plot 0.1.2

Simple visualization tool for clustered high-density data.

miso-plot

A lightweight visualization tool for clustered high-density data

---

Overview

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.

---

Installation

 pip install miso-plot
 

Or install the latest development version directly from GitHub:

 pip install git+https://github.com/Aleksandra795/miso-plot.git
 

---

Quick Example

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.

---

API Overview

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.

---

Color Palettes

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']).

---

Citation

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)

---

License

This project is distributed under the MIT License.

---

Created with ❤️ and scientific curiosity.