datamapplot 0.1.0__tar.gz

datamapplot-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Tutte Institute for Mathematics and Computing
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

datamapplot-0.1.0/PKG-INFO

@@ -0,0 +1,111 @@
+Metadata-Version: 2.1
+Name: datamapplot
+Version: 0.1.0
+Summary: A library for presentation and publication ready plots of data maps
+Home-page: https://github.com/TutteInstitute/datamapplot
+Author: Leland McInnes
+Author-email: leland.mcinnes@gmail.com
+Maintainer: Leland McInnes
+Maintainer-email: leland.mcinnes@gmail.com
+License: MIT License
+Keywords: data map,visualization,topic modelling,cluster,clustering
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Development Status :: 4 - Beta
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+License-File: LICENSE
+
+.. -*- mode: rst -*-
+
+.. image:: doc/datamapplot_text_horizontal.png
+  :width: 600
+  :alt: DataMapPlot logo
+  :align: center
+
+===========
+DataMapPlot
+===========
+
+Creating beautiful plots of data maps. DataMapPlot is a small library designed to help you make beautiful data map
+plots for inclusion in presentations, posters and papers. The focus is on producing static plots that are great
+looking with as little work for you as possible. All you need to do is label clusters of points in the data map and
+DataMapPlot will take care of the rest. While this involves automating most of the aesthetic choices, the library
+provides a wide variety of ways to customize the resulting plot to your needs.
+
+--------
+Examples
+--------
+
+Some examples of the kind of output that DataMapPlot can provide.
+
+A basic plot, with some highlighted labels:
+
+.. image:: examples/plot_cord19.png
+   :width: 1024
+   :alt: A data map plot of the CORD-19 dataset
+   :align: center
+
+Using darkmode and some custom font choices:
+
+.. image:: examples/plot_arxiv_ml.png
+   :width: 1024
+   :alt: A data map plot of papers from ArXiv ML
+   :align: center
+
+Alternative custom styling:
+
+.. image:: examples/plot_wikipedia.png
+   :width: 1024
+   :alt: A data map plot of Simple Wikipedia
+   :align: center
+
+Custom arrow styles, fonts, and colour maps:
+
+.. image:: examples/plot_simple_arxiv.png
+   :width: 1024
+   :alt: A styled data map plot of papers from ArXiv ML
+   :align: center
+
+------------
+Installation
+------------
+
+DataMapPlot requires a few libraries, but all are widely available and easy to install:
+
+ * Numpy
+ * Matplotlib
+ * Scikit-learn
+ * Pandas
+ * Datashader
+ * Scikit-image
+ * Numba
+
+To install DataMapPlot you can use pip:
+
+.. code:: bash
+
+    pip install datamapplot
+
+or use conda with conda-forge
+
+.. code:: bash
+
+    conda install -c conda-forge datamapplot
+
+
+-------
+License
+-------
+
+DataMapPlot is MIT licensed. See the LICENSE file for details.
+
+------------
+Contributing
+------------
+
+Contributions are more than welcome! If you have ideas for features of projects please get in touch. Everything from
+code to notebooks to examples and documentation are all *equally valuable* so please don't feel you can't contribute.
+To contribute please `fork the project <https://github.com/TutteInstitute/datamapplot/issues#fork-destination-box>`_ make your
+changes and submit a pull request. We will do our best to work through any issues with you and get your code merged in.

datamapplot-0.1.0/README.rst

@@ -0,0 +1,92 @@
+.. -*- mode: rst -*-
+
+.. image:: doc/datamapplot_text_horizontal.png
+  :width: 600
+  :alt: DataMapPlot logo
+  :align: center
+
+===========
+DataMapPlot
+===========
+
+Creating beautiful plots of data maps. DataMapPlot is a small library designed to help you make beautiful data map
+plots for inclusion in presentations, posters and papers. The focus is on producing static plots that are great
+looking with as little work for you as possible. All you need to do is label clusters of points in the data map and
+DataMapPlot will take care of the rest. While this involves automating most of the aesthetic choices, the library
+provides a wide variety of ways to customize the resulting plot to your needs.
+
+--------
+Examples
+--------
+
+Some examples of the kind of output that DataMapPlot can provide.
+
+A basic plot, with some highlighted labels:
+
+.. image:: examples/plot_cord19.png
+   :width: 1024
+   :alt: A data map plot of the CORD-19 dataset
+   :align: center
+
+Using darkmode and some custom font choices:
+
+.. image:: examples/plot_arxiv_ml.png
+   :width: 1024
+   :alt: A data map plot of papers from ArXiv ML
+   :align: center
+
+Alternative custom styling:
+
+.. image:: examples/plot_wikipedia.png
+   :width: 1024
+   :alt: A data map plot of Simple Wikipedia
+   :align: center
+
+Custom arrow styles, fonts, and colour maps:
+
+.. image:: examples/plot_simple_arxiv.png
+   :width: 1024
+   :alt: A styled data map plot of papers from ArXiv ML
+   :align: center
+
+------------
+Installation
+------------
+
+DataMapPlot requires a few libraries, but all are widely available and easy to install:
+
+ * Numpy
+ * Matplotlib
+ * Scikit-learn
+ * Pandas
+ * Datashader
+ * Scikit-image
+ * Numba
+
+To install DataMapPlot you can use pip:
+
+.. code:: bash
+
+    pip install datamapplot
+
+or use conda with conda-forge
+
+.. code:: bash
+
+    conda install -c conda-forge datamapplot
+
+
+-------
+License
+-------
+
+DataMapPlot is MIT licensed. See the LICENSE file for details.
+
+------------
+Contributing
+------------
+
+Contributions are more than welcome! If you have ideas for features of projects please get in touch. Everything from
+code to notebooks to examples and documentation are all *equally valuable* so please don't feel you can't contribute.
+To contribute please `fork the project <https://github.com/TutteInstitute/datamapplot/issues#fork-destination-box>`_ make your
+changes and submit a pull request. We will do our best to work through any issues with you and get your code merged in.

datamapplot-0.1.0/datamapplot/__init__.py

@@ -0,0 +1,277 @@
+import numpy as np
+import pandas as pd
+import textwrap
+
+from matplotlib import pyplot as plt
+
+from datamapplot.palette_handling import (
+    palette_from_datamap,
+    palette_from_cmap_and_datamap,
+    deep_palette,
+    pastel_palette,
+)
+from datamapplot.plot_rendering import render_plot
+from datamapplot.medoids import medoid
+
+
+def create_plot(
+    data_map_coords,
+    labels,
+    *,
+    title=None,
+    sub_title=None,
+    noise_label="Unlabelled",
+    noise_color="#999999",
+    color_label_text=True,
+    label_wrap_width=16,
+    label_color_map=None,
+    figsize=(12, 12),
+    dynamic_label_size=False,
+    dpi=plt.rcParams["figure.dpi"],
+    force_matplotlib=False,
+    darkmode=False,
+    highlight_labels=None,
+    palette_hue_shift=0.0,
+    palette_hue_radius_dependence=1.0,
+    use_medoids=False,
+    cmap=None,
+    **render_plot_kwds,
+):
+    """Create a static plot from ``data_map_coords`` with text labels provided by ``labels``.
+    This is the primary function for DataMapPlot and provides the easiest interface to the
+    static plotting functionality. This function provides a number of options, but also
+    passes any further keyword options through to the lower level ``render_plot`` function
+    so be sure to check the documentation for ``render_plot`` to discover further keyword
+    arguments that can be used here as well.
+
+    Parameters
+    ----------
+    data_map_coords: ndarray of floats of shape (n_samples, 2)
+        The 2D coordinates for the data map. Usually this is produced via a
+        dimension reduction technique such as UMAP, t-SNE, PacMAP, PyMDE etc.
+
+    labels: ndarray of strings (object) of shape (n_samples,)
+        A string label each data point in the data map. There should ideally by
+        only up to 64 unique labels. Noise or unlabelled points should have the
+        same label as ``noise_label``, which is "Unlabelled" by default.
+
+    title: str or None (optional, default=None)
+        A title for the plot. If ``None`` then no title is used for the plot.
+        The title should be succint; three to seven words.
+
+    sub_title: str or None (optional, default=None)
+        A sub-title for the plot. If ``None`` then no sub-title is used for the plot.
+        The sub-title can be significantly longer then the title and provide more information\
+        about the plot and data sources.
+
+    noise_label: str (optional, default="Unlabelled")
+        The string used in the ``labels`` array to identify the unlabelled or noise points
+        in the dataset.
+
+    noise_color: str (optional, default="#999999")
+        The colour to use for unlabelled or noise points in the data map. This should usually
+        be a muted or neutral colour to distinguish background points from the labelled clusters.
+
+    color_label_text: bool (optional, default=True)
+        Whether to use colours for the text labels generated in the plot. If ``False`` then
+        the text labels will default to either black or white depending on ``darkmode``.
+
+    label_wrap_width: int (optional, default=16)
+        The number of characters to apply text-wrapping at when creating text labels for
+        display in the plot. Note that long words will not be broken, so you can choose
+        relatively small values if you want tight text-wrapping.
+
+    label_color_map: dict or None (optional, default=None)
+        A colour mapping to use to colour points/clusters in the data map. The mapping should
+        be keyed by the unique cluster labels in ``labels`` and take values that are hex-string
+        representations of colours. If ``None`` then a colour mapping will be auto-generated.
+
+    figsize: (int, int) (optional, default=(12,12))
+        How big to make the figure in inches (actual pixel size will depend on ``dpi``).
+
+    dynamic_label_size: bool (optional, default=False)
+        Whether to dynamically resize the text labels based on the relative sizes of the
+        clusters. This can be useful to help highlight larger clusters.
+
+    dpi: int (optional, default=plt.rcParams["figure.dpi"])
+        The dots-per-inch setting usd when rendering the plot.
+
+    force_matplotlib: bool (optional, default=False)
+        Force using matplotlib instead of datashader for rendering the scatterplot of the
+        data map. This can be useful if you wish to have a different marker_type, or variably
+        sized markers based on a marker_size_array, neither of which are supported by the
+        datashader based renderer.
+
+    darkmode: bool (optional, default=False)
+        Whether to render the plot in darkmode (with a dark background) or not.
+
+    highlight_labels: list of str or None (optional, default=None)
+        A list of unique labels that should have their text highlighted in the resulting plot.
+        Arguments supported by ``render_plot`` can allow for control over how highlighted labels
+        are rendered. By default they are simply rendered in bold text.
+
+    palette_hue_shift: float (optional, default=0.0)
+        A setting, in degrees clockwise, to shift the hue channel when generating a colour
+        palette and color_mapping for the labels.
+
+    palette_hue_radius_dependence: float (optional, default=1.0)
+        A setting that determines how dependent on the radius the hue channel is. Larger
+        values will result in more hue variation where there are more outlying points.
+
+    use_medoids: bool (optional, default=False)
+        Whether to use medoids instead of centroids to determine the "location" of the cluster,
+        both for the label indicator line, and for palette colouring. Note that medoids are
+        more computationally expensive, especially for large plots, so use with some caution.
+
+    cmap: matplotlib cmap or None (optional, default=None)
+        A linear matplotlib cmap colour map to use as the base for a generated colour mapping.
+        This *should* be a matplotlib cmap that is smooth and linear, and cyclic
+        (see the colorcet package for some good options). If not a cyclic cmap it will be
+        "made" cyclic by reflecting it. If ``None`` then a custom method will be used instead.
+
+    **render_plot_kwds
+        All opther keyword arguments are passed through the ``render_plot`` which provides
+        significant further control over the aesthetics of the plot.
+
+    Returns
+    -------
+
+    fig: matplotlib.Figure
+        The figure that the resulting plot is rendered to.
+
+    ax: matpolotlib.Axes
+        The axes contained within the figure that the plot is rendered to.
+
+    """
+    cluster_label_vector = np.asarray(labels)
+    unique_non_noise_labels = [
+        label for label in np.unique(cluster_label_vector) if label != noise_label
+    ]
+    if use_medoids:
+        label_locations = np.asarray(
+            [
+                medoid(data_map_coords[cluster_label_vector == i])
+                for i in unique_non_noise_labels
+            ]
+        )
+    else:
+        label_locations = np.asarray(
+            [
+                data_map_coords[cluster_label_vector == i].mean(axis=0)
+                for i in unique_non_noise_labels
+            ]
+        )
+    label_text = [
+        textwrap.fill(x, width=label_wrap_width, break_long_words=False)
+        for x in unique_non_noise_labels
+    ]
+    if highlight_labels is not None:
+        highlight_labels = [
+            textwrap.fill(x, width=label_wrap_width, break_long_words=False)
+            for x in highlight_labels
+        ]
+
+    # If we don't have a color map, generate one
+    if label_color_map is None:
+        if cmap is None:
+            palette = palette_from_datamap(
+                data_map_coords,
+                label_locations,
+                hue_shift=palette_hue_shift,
+                radius_weight_power=palette_hue_radius_dependence,
+            )
+        else:
+            palette = palette_from_cmap_and_datamap(
+                cmap,
+                data_map_coords,
+                label_locations,
+                radius_weight_power=palette_hue_radius_dependence,
+            )
+        label_to_index_map = {
+            name: index for index, name in enumerate(unique_non_noise_labels)
+        }
+        color_list = [
+            palette[label_to_index_map[x]] if x in label_to_index_map else noise_color
+            for x in cluster_label_vector
+        ]
+        label_color_map = {
+            x: (
+                palette[label_to_index_map[x]]
+                if x in label_to_index_map
+                else noise_color
+            )
+            for x in np.unique(cluster_label_vector)
+        }
+    else:
+        color_list = [
+            label_color_map[x] if x != noise_label else noise_color
+            for x in cluster_label_vector
+        ]
+
+    # Darken and reduce chroma of label colors to get text labels
+    if color_label_text:
+        if darkmode:
+            label_text_colors = pastel_palette(
+                [label_color_map[x] for x in unique_non_noise_labels]
+            )
+        else:
+            label_text_colors = deep_palette(
+                [label_color_map[x] for x in unique_non_noise_labels]
+            )
+    else:
+        label_text_colors = None
+
+    if dynamic_label_size:
+        font_scale_factor = np.sqrt(figsize[0] * figsize[1])
+        cluster_sizes = np.sqrt(pd.Series(cluster_label_vector).value_counts())
+        label_size_adjustments = cluster_sizes - cluster_sizes.min()
+        label_size_adjustments /= label_size_adjustments.max()
+        label_size_adjustments *= (
+            render_plot_kwds.get("label_font_size", font_scale_factor) + 2
+        )
+        label_size_adjustments = dict(label_size_adjustments - 2)
+        label_size_adjustments = [
+            label_size_adjustments[x] for x in unique_non_noise_labels
+        ]
+    else:
+        label_size_adjustments = [0.0] * len(unique_non_noise_labels)
+
+    # Heuristics for point size and alpha values
+    n_points = data_map_coords.shape[0]
+    if data_map_coords.shape[0] < 100_000 or force_matplotlib:
+        magic_number = np.clip(128 * 4 ** (-np.log10(n_points)), 0.05, 64)
+        point_scale_factor = np.sqrt(figsize[0] * figsize[1])
+        point_size = magic_number * (point_scale_factor / 2)
+        alpha = np.clip(magic_number, 0.05, 1)
+    else:
+        point_size = int(np.sqrt(figsize[0] * figsize[1]) * dpi) // 2048
+        alpha = 1.0
+
+    if "point_size" in render_plot_kwds:
+        point_size = render_plot_kwds.pop("point_size")
+
+    if "alpha" in render_plot_kwds:
+        alpha = render_plot_kwds.pop("alpha")
+
+    fig, ax = render_plot(
+        data_map_coords,
+        color_list,
+        label_text,
+        label_locations,
+        title=title,
+        sub_title=sub_title,
+        point_size=point_size,
+        alpha=alpha,
+        label_colors=None if not color_label_text else label_text_colors,
+        highlight_colors=[label_color_map[x] for x in unique_non_noise_labels],
+        figsize=figsize,
+        noise_color=noise_color,
+        label_size_adjustments=label_size_adjustments,
+        dpi=dpi,
+        force_matplotlib=force_matplotlib,
+        darkmode=darkmode,
+        highlight_labels=highlight_labels,
+        **render_plot_kwds,
+    )
+
+    return fig, ax

datamapplot-0.1.0/datamapplot/medoids.py

@@ -0,0 +1,103 @@
+import numpy as np
+import numba
+
+
+@numba.njit(
+    [
+        "f4(f4[::1],f4[::1])",
+        numba.types.float32(
+            numba.types.Array(numba.types.float32, 1, "C", readonly=True),
+            numba.types.Array(numba.types.float32, 1, "C", readonly=True),
+        ),
+    ],
+    fastmath=True,
+    locals={
+        "result": numba.types.float32,
+        "diff": numba.types.float32,
+        "dim": numba.types.intp,
+        "i": numba.types.uint16,
+    },
+)
+def euclidean(x, y):
+    r"""Squared euclidean distance.
+
+    .. math::
+        D(x, y) = \sum_i (x_i - y_i)^2
+    """
+    result = 0.0
+    dim = x.shape[0]
+    for i in range(dim):
+        diff = x[i] - y[i]
+        result += diff * diff
+
+    return np.sqrt(result)
+
+
+@numba.njit(parallel=True, nogil=True)
+def chunked_parallel_pairwise_distances(X, Y=None, metric=euclidean, chunk_size=16):
+    if Y is None:
+        XX, symmetrical = X, True
+        row_size = col_size = X.shape[0]
+    else:
+        XX, symmetrical = Y, False
+        row_size, col_size = X.shape[0], Y.shape[0]
+
+    result = np.zeros((row_size, col_size), dtype=np.float32)
+    n_row_chunks = (row_size // chunk_size) + 1
+    for chunk_idx in numba.prange(n_row_chunks):
+        n = chunk_idx * chunk_size
+        chunk_end_n = min(n + chunk_size, row_size)
+        m_start = n if symmetrical else 0
+        for m in range(m_start, col_size, chunk_size):
+            chunk_end_m = min(m + chunk_size, col_size)
+            for i in range(n, chunk_end_n):
+                for j in range(m, chunk_end_m):
+                    result[i, j] = metric(X[i], XX[j])
+    return result
+
+
+@numba.njit()
+def pull_arms(data, arms, num_pulls_per_arm, estimates, pull_counts):
+    other_candidates = np.random.choice(
+        data.shape[0], size=num_pulls_per_arm, replace=False
+    ).astype(np.int32)
+    data_arm = data[arms]
+    data_other = data[other_candidates]
+
+    distance_sums = np.sum(
+        chunked_parallel_pairwise_distances(data_arm, data_other), axis=1
+    )
+
+    estimates *= pull_counts
+    estimates += distance_sums
+    pull_counts += num_pulls_per_arm
+    estimates /= pull_counts
+
+
+@numba.njit()
+def medoid(data, arm_budget=20):
+    pull_counts = np.zeros(data.shape[0], dtype=np.int32)
+    pull_budget = arm_budget * data.shape[0]
+    estimates = np.zeros(data.shape[0], dtype=np.float32)
+    current_active_arms = np.arange(data.shape[0])
+    n_rounds = int(np.ceil(np.log2(data.shape[0])))
+
+    while current_active_arms.shape[0] > 1:
+        num_pulls_per_arm = max(
+            1,
+            int(
+                min(
+                    data.shape[0],
+                    np.floor(pull_budget / (current_active_arms.shape[0] * n_rounds)),
+                )
+            ),
+        )
+        pull_arms(data, current_active_arms, num_pulls_per_arm, estimates, pull_counts)
+
+        median = np.median(estimates)
+        mask = estimates <= median
+        current_active_arms = current_active_arms[mask]
+        estimates = estimates[mask]
+        pull_counts = pull_counts[mask]
+
+    return data[current_active_arms[0]]