<div align="center">
<h1>miso-plot</h1>
<p align="center">
<img src="https://github.com/Aleksandra795/miso-plot/raw/main/docs/miso_logo.png" alt="miso-plot logo" width="300"/>
</p>
<p align="center">
<em>A lightweight visualization tool for clustered high-density data</em>
</p>
<p>
<a href="https://pypi.org/project/miso-plot/"><img src="https://img.shields.io/pypi/v/miso-plot.svg?color=blue" alt="PyPI"></a>
<a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"></a>
<img src="https://img.shields.io/badge/Python-3.8%2B-blue.svg" alt="Python 3.8+">
<a href="https://github.com/Aleksandra795/miso-plot/actions"><img src="https://github.com/Aleksandra795/miso-plot/actions/workflows/python-tests.yml/badge.svg" alt="Build"></a>
</p>
</div>
<hr/>
<h2>Overview</h2>
<p><strong>miso-plot</strong> 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.</p>
<p>Typical use cases include:</p>
<ul>
<li>visual inspection of clustering quality in large datasets,</li>
<li>density-based highlighting of local data structures,</li>
<li>generation of publication-quality scatter plots.</li>
</ul>
<hr/>
<h2>Installation</h2>
<pre><code class="language-bash">
pip install miso-plot
</code></pre>
<p>Or install the latest development version directly from GitHub:</p>
<pre><code class="language-bash">
pip install git+https://github.com/Aleksandra795/miso-plot.git
</code></pre>
<hr/>
<h2>Quick Example</h2>
<pre><code class="language-python">
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()
</code></pre>
<p align="center">
<img src="https://github.com/Aleksandra795/miso-plot/raw/main/docs/exemplary_data_scatterplot.png" alt="Example scatter plot" width="500"/>
</p>
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 <i>m</i> fraction of its overall density.
<pre><code class="language-python">
# 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()
</code></pre>
<p align="center">
<img src="https://github.com/Aleksandra795/miso-plot/raw/main/docs/exemplary_data_miso_05.png" alt="Example miso plot" width="500"/>
</p>
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.
<p align="center">
<img src="https://github.com/Aleksandra795/miso-plot/raw/main/docs/cytof_example.png" alt="Example miso plot" width="800"/>
</p>
<hr/>
<h2>API Overview</h2>
<p><code>miso_plot(X, Y, labels, cmap='miso24', m=0.5, lam=20, ax=None, alpha=0.3, marker='s', size=10)</code></p>
<p>Generates a smoothed scatter plot with adaptive density highlighting.</p>
<table>
<thead>
<tr><th>Parameter</th><th>Type</th><th>Description</th></tr>
</thead>
<tbody>
<tr><td><code>X</code>, <code>Y</code></td><td><code>np.ndarray</code></td><td>Coordinates of points</td></tr>
<tr><td><code>labels</code></td><td><code>np.ndarray</code></td><td>Cluster labels for each point</td></tr>
<tr><td><code>cmap</code></td><td><code>str</code> or <code>list</code></td><td>Colormap ('miso24', matplotlib/seaborn name, or list of hex)</td></tr>
<tr><td><code>m</code></td><td><code>float</code></td><td>Density threshold</td></tr>
<tr><td><code>lam</code></td><td><code>int</code></td><td>Smoothing parameter</td></tr>
<tr><td><code>ax</code></td><td><code>matplotlib.axes.Axes</code> or <code>None</code></td><td>Optional existing Axes; creates a new one if None</td></tr>
<tr><td><code>alpha</code></td><td><code>float</code></td><td>Transparency of points</td></tr>
<tr><td><code>marker</code></td><td><code>str</code></td><td>Marker style</td></tr>
<tr><td><code>size</code></td><td><code>int</code></td><td>Size of each point</td></tr>
</tbody>
</table>
The <i>m</i> 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.
<p align="center">
<img src="https://github.com/Aleksandra795/miso-plot/raw/main/docs/m_parameter.png" alt="m parameter" width="1000"/>
</p>
<hr/>
<h2>Color Palettes</h2>
<p>Built-in palette: <strong>miso24</strong><br/>
Designed for cluster visualization (24 clusters) with high perceptual separation.</p>
<p align="center">
<img src="https://github.com/Aleksandra795/miso-plot/raw/main/docs/miso24_palette.png" alt="miso24 palette" width="800"/>
</p>
<p>You may also pass:</p>
<ul>
<li>any matplotlib/seaborn palette name (e.g. 'viridis', 'tab10'),</li>
<li>a custom list of hex colors (e.g. ['ff0000', '00ff00', '0000ff']).</li>
</ul>
<hr/>
<h2>Citation</h2>
<p>If you use <strong>miso-plot</strong> or the underlying method in your research or publications, please cite:</p>
<blockquote>
Suwalska, A.; Polanska, J.<br/>
<em>GMM-Based Expanded Feature Space as a Way to Extract Useful Information for Rare Cell Subtypes Identification in Single-Cell Mass Cytometry.</em><br/>
<strong>Int. J. Mol. Sci.</strong> 2023, 24(18), 14033.<br/>
<a href="https://doi.org/10.3390/ijms241814033">https://doi.org/10.3390/ijms241814033</a><br/>
(<a href="https://www.mdpi.com/1422-0067/24/18/14033">Open Access</a>)
</blockquote>
<hr/>
<h2>License</h2>
<p>This project is distributed under the <a href="LICENSE">MIT License</a>.</p>
<hr/>
<div align="center">
Created with ❤️ and scientific curiosity.
</div>
Raw data
{
"_id": null,
"home_page": null,
"name": "miso-plot",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "visualization, clustering, data science, umap, big data, matplotlib",
"author": null,
"author_email": "Aleksandra Suwalska <aleksandra.suwalska@polsl.pl>",
"download_url": "https://files.pythonhosted.org/packages/fb/56/a074804c39fa48a1038676b04c783dbfd0f00144a84bffd1d966dec076d3/miso_plot-0.1.2.tar.gz",
"platform": null,
"description": " <div align=\"center\">\r\n \r\n <h1>miso-plot</h1>\r\n \r\n <p align=\"center\">\r\n <img src=\"https://github.com/Aleksandra795/miso-plot/raw/main/docs/miso_logo.png\" alt=\"miso-plot logo\" width=\"300\"/>\r\n </p>\r\n <p align=\"center\">\r\n <em>A lightweight visualization tool for clustered high-density data</em>\r\n </p>\r\n <p>\r\n <a href=\"https://pypi.org/project/miso-plot/\"><img src=\"https://img.shields.io/pypi/v/miso-plot.svg?color=blue\" alt=\"PyPI\"></a>\r\n <a href=\"LICENSE\"><img src=\"https://img.shields.io/badge/License-MIT-yellow.svg\" alt=\"License: MIT\"></a>\r\n <img src=\"https://img.shields.io/badge/Python-3.8%2B-blue.svg\" alt=\"Python 3.8+\">\r\n <a href=\"https://github.com/Aleksandra795/miso-plot/actions\"><img src=\"https://github.com/Aleksandra795/miso-plot/actions/workflows/python-tests.yml/badge.svg\" alt=\"Build\"></a>\r\n </p>\r\n \r\n </div>\r\n \r\n <hr/>\r\n \r\n <h2>Overview</h2>\r\n \r\n <p><strong>miso-plot</strong> is a simple yet efficient Python library for visualizing large clustered datasets.\r\n It was designed for fast exploration of high-density 2D embeddings such as UMAP, t-SNE, or PCA outputs,\r\n using adaptive density smoothing and perceptually uniform color palettes.</p>\r\n \r\n <p>Typical use cases include:</p>\r\n <ul>\r\n <li>visual inspection of clustering quality in large datasets,</li>\r\n <li>density-based highlighting of local data structures,</li>\r\n <li>generation of publication-quality scatter plots.</li>\r\n </ul>\r\n \r\n \r\n <hr/>\r\n \r\n <h2>Installation</h2>\r\n \r\n <pre><code class=\"language-bash\">\r\n pip install miso-plot\r\n </code></pre>\r\n \r\n <p>Or install the latest development version directly from GitHub:</p>\r\n \r\n <pre><code class=\"language-bash\">\r\n pip install git+https://github.com/Aleksandra795/miso-plot.git\r\n </code></pre>\r\n \r\n <hr/>\r\n \r\n <h2>Quick Example</h2>\r\n \r\n <pre><code class=\"language-python\">\r\nimport numpy as np\r\nimport matplotlib.pyplot as plt\r\nfrom sklearn.datasets import make_blobs\r\nfrom miso_plot import miso_plot\r\n\r\n# Generate synthetic clustered data\r\nX, labels = make_blobs(n_samples=50000, centers=6, n_features=2, random_state=42)\r\nY = X[:, 1]\r\nX = X[:, 0]\r\n\r\n# Plot simple scatterplot of the data\r\nplt.figure()\r\nplt.scatter(X, Y, s=10, c=labels, alpha=0.5, cmap='tab10')\r\nplt.xlabel(\"x\")\r\nplt.ylabel(\"y\")\r\nplt.title(\"simple scatter plot\")\r\nplt.grid(True)\r\nplt.show()\r\n </code></pre>\r\n<p align=\"center\">\r\n <img src=\"https://github.com/Aleksandra795/miso-plot/raw/main/docs/exemplary_data_scatterplot.png\" alt=\"Example scatter plot\" width=\"500\"/>\r\n </p>\r\n\r\nBecause often the clusters overlap substantially, identifying their true centers is challenging.\r\nmiso-plot facilitates this process by visualizing each cluster\u2019s density distribution, highlighting regions representing the top <i>m</i> fraction of its overall density.\r\n\r\n<pre><code class=\"language-python\">\r\n# Show cluster density centers with miso-plot\r\nfig, ax = plt.subplots()\r\nplt.scatter(X, Y, s=10, c='#D6D6D6', alpha=0.5)\r\nmiso_plot(X, Y, labels, cmap=\"tab10\", m=0.5, ax=ax) \r\nplt.xlabel(\"x\")\r\nplt.ylabel(\"y\")\r\nplt.title(\"mISO plot, m=0.5\")\r\nplt.grid(True)\r\nplt.show()\r\n </code></pre>\r\n \r\n <p align=\"center\">\r\n <img src=\"https://github.com/Aleksandra795/miso-plot/raw/main/docs/exemplary_data_miso_05.png\" alt=\"Example miso plot\" width=\"500\"/>\r\n </p>\r\n \r\n The usefulness of miso-plot is best illustrated using real experimental data.\r\n Below is an example based on single-cell mass cytometry data from Samusik et al. (2016) \u2014 \u201cAutomated mapping of phenotype space with single-cell data\u201d (Nature Methods, 13, 493\u2013496; DOI: 10.1038/nmeth.3863) \u2014 containing 24 manually annotated bone marrow cell subtypes.\r\n 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.\r\n\r\n<p align=\"center\">\r\n <img src=\"https://github.com/Aleksandra795/miso-plot/raw/main/docs/cytof_example.png\" alt=\"Example miso plot\" width=\"800\"/>\r\n </p>\r\n\r\n <hr/>\r\n \r\n <h2>API Overview</h2>\r\n \r\n <p><code>miso_plot(X, Y, labels, cmap='miso24', m=0.5, lam=20, ax=None, alpha=0.3, marker='s', size=10)</code></p>\r\n <p>Generates a smoothed scatter plot with adaptive density highlighting.</p>\r\n \r\n <table>\r\n <thead>\r\n <tr><th>Parameter</th><th>Type</th><th>Description</th></tr>\r\n </thead>\r\n <tbody>\r\n <tr><td><code>X</code>, <code>Y</code></td><td><code>np.ndarray</code></td><td>Coordinates of points</td></tr>\r\n <tr><td><code>labels</code></td><td><code>np.ndarray</code></td><td>Cluster labels for each point</td></tr>\r\n <tr><td><code>cmap</code></td><td><code>str</code> or <code>list</code></td><td>Colormap ('miso24', matplotlib/seaborn name, or list of hex)</td></tr>\r\n <tr><td><code>m</code></td><td><code>float</code></td><td>Density threshold</td></tr>\r\n <tr><td><code>lam</code></td><td><code>int</code></td><td>Smoothing parameter</td></tr>\r\n <tr><td><code>ax</code></td><td><code>matplotlib.axes.Axes</code> or <code>None</code></td><td>Optional existing Axes; creates a new one if None</td></tr>\r\n <tr><td><code>alpha</code></td><td><code>float</code></td><td>Transparency of points</td></tr>\r\n <tr><td><code>marker</code></td><td><code>str</code></td><td>Marker style</td></tr>\r\n <tr><td><code>size</code></td><td><code>int</code></td><td>Size of each point</td></tr>\r\n </tbody>\r\n </table>\r\n\r\nThe <i>m</i> parameter has the strongest impact on the visual output of miso-plot.\r\nIts 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.\r\nCommon choices include 0.25 (top 75% of the densest regions) and 0.75 (top 25%), depending on the desired level of detail.\r\n \r\n <p align=\"center\">\r\n <img src=\"https://github.com/Aleksandra795/miso-plot/raw/main/docs/m_parameter.png\" alt=\"m parameter\" width=\"1000\"/>\r\n </p>\r\n\r\n <hr/>\r\n \r\n <h2>Color Palettes</h2>\r\n \r\n <p>Built-in palette: <strong>miso24</strong><br/>\r\n Designed for cluster visualization (24 clusters) with high perceptual separation.</p>\r\n \r\n <p align=\"center\">\r\n <img src=\"https://github.com/Aleksandra795/miso-plot/raw/main/docs/miso24_palette.png\" alt=\"miso24 palette\" width=\"800\"/>\r\n </p>\r\n\r\n <p>You may also pass:</p>\r\n <ul>\r\n <li>any matplotlib/seaborn palette name (e.g. 'viridis', 'tab10'),</li>\r\n <li>a custom list of hex colors (e.g. ['ff0000', '00ff00', '0000ff']).</li>\r\n </ul>\r\n \r\n <hr/>\r\n \r\n \r\n <h2>Citation</h2>\r\n \r\n <p>If you use <strong>miso-plot</strong> or the underlying method in your research or publications, please cite:</p>\r\n \r\n <blockquote>\r\n Suwalska, A.; Polanska, J.<br/>\r\n <em>GMM-Based Expanded Feature Space as a Way to Extract Useful Information for Rare Cell Subtypes Identification in Single-Cell Mass Cytometry.</em><br/>\r\n <strong>Int. J. Mol. Sci.</strong> 2023, 24(18), 14033.<br/>\r\n <a href=\"https://doi.org/10.3390/ijms241814033\">https://doi.org/10.3390/ijms241814033</a><br/>\r\n (<a href=\"https://www.mdpi.com/1422-0067/24/18/14033\">Open Access</a>)\r\n </blockquote>\r\n \r\n <hr/>\r\n \r\n <h2>License</h2>\r\n \r\n <p>This project is distributed under the <a href=\"LICENSE\">MIT License</a>.</p>\r\n \r\n <hr/>\r\n \r\n <div align=\"center\">\r\n Created with \u2764\ufe0f and scientific curiosity.\r\n </div>\r\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Simple visualization tool for clustered high-density data.",
"version": "0.1.2",
"project_urls": {
"Bug Tracker": "https://github.com/Aleksandra795/miso-plot/issues",
"Homepage": "https://github.com/Aleksandra795/miso-plot"
},
"split_keywords": [
"visualization",
" clustering",
" data science",
" umap",
" big data",
" matplotlib"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "e11940879c8727e46c01065e37f93327d129f915c46cc03ec6c8e24b91bf5174",
"md5": "0ce678488eb1cb3445a553f636d14207",
"sha256": "ea7ce7e2f6c6ccdba6014a0f2cff82bce71e91f5320854c17c798367faa2a596"
},
"downloads": -1,
"filename": "miso_plot-0.1.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "0ce678488eb1cb3445a553f636d14207",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 8063,
"upload_time": "2025-10-19T23:08:38",
"upload_time_iso_8601": "2025-10-19T23:08:38.757878Z",
"url": "https://files.pythonhosted.org/packages/e1/19/40879c8727e46c01065e37f93327d129f915c46cc03ec6c8e24b91bf5174/miso_plot-0.1.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "fb56a074804c39fa48a1038676b04c783dbfd0f00144a84bffd1d966dec076d3",
"md5": "fd23298607f7a5bfa54e8e7c79d58e89",
"sha256": "834f6447ea8997a89699e2dd81db8967ce7f5bd0b86a00c1b56e4748e313c51d"
},
"downloads": -1,
"filename": "miso_plot-0.1.2.tar.gz",
"has_sig": false,
"md5_digest": "fd23298607f7a5bfa54e8e7c79d58e89",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 8032,
"upload_time": "2025-10-19T23:08:40",
"upload_time_iso_8601": "2025-10-19T23:08:40.097306Z",
"url": "https://files.pythonhosted.org/packages/fb/56/a074804c39fa48a1038676b04c783dbfd0f00144a84bffd1d966dec076d3/miso_plot-0.1.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-19 23:08:40",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Aleksandra795",
"github_project": "miso-plot",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "numpy",
"specs": []
},
{
"name": "matplotlib",
"specs": []
},
{
"name": "pandas",
"specs": []
}
],
"lcname": "miso-plot"
}
JSON
