DataMapPlot: turning a labelled point cloud into a figure for a paper

Two functions and a lot of automated aesthetics

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, or simple interactive plots, that look good with as little work as possible.

The workflow it proposes is unusually compressed. All you need to do is label clusters of points in the data map and DataMapPlot takes care of the rest. While this involves automating most of the aesthetic choices, the library provides a wide variety of ways to customise the resulting plot to your needs.

There are essentially only two functions, `create_plot` and `create_interactive_plot`. They take the coordinates of a data map and an array or a list of labels for the data points, and a variety of further options can be used to customise the output. The basic example is three lines:

import datamapplot

datamapplot.create_plot(data_map_coords, data_map_labels, **style_keywords)

The project is by Leland McInnes, who is listed as both author and maintainer, and it is MIT licensed. The primary language is Python, the package requires 3.10 or newer with classifiers through 3.13, and the development status is declared as Beta.

It is on PyPI and on conda-forge, and the project publishes to both. The last push was on 2026-10-07, and the recent releases are release-0.7.3 from 2026-05-31, release-0.7.2 from 2026-05-23 and release-0.7.1 from 2026-03-18.

What the examples show, and the datasets behind them

The example gallery is the documentation, because the point of the library is what the output looks like.

The static examples are named for their datasets. There is a basic plot of the CORD-19 dataset with some highlighted labels, a plot of papers from ArXiv ML using dark mode and custom font choices, a word cloud style variant with labels over points, an alternative custom styling example built on Simple Wikipedia, and one with custom arrow styles, fonts and colour maps.

The interactive examples are videos of the interaction, and there are four of them. The ArXiv one shows searching and zooming, the CORD-19 one shows zooming and panning, the Wikipedia one shows panning and zooming, and the custom CORD-19 one shows searching and zooming again. The `examples/` directory holds both the animations as GIFs and as MP4s, and the data itself as `.npz` files, with separate files for the data map, the cluster labels and, for ArXiv, a set of per-layer cluster label files numbered from layer zero to layer four.

Those layer files are the most informative thing in the directory listing. A single-layer data map has one set of labels, and a hierarchical one has several, and the library handles a multi-layer map with a labelled hierarchy, which is a much harder layout problem than labelling one flat set of points.

The hover data file for ArXiv suggests the interactive plots carry more than positions, and the CORD-19 subset includes citation counts and publish dates, so the interactive output can show metadata about a point rather than only a label.

The dependency list, and what each entry is doing there

The `pyproject.toml` lists nineteen runtime dependencies, and reading them tells you the architecture of the two output paths.

The static path is matplotlib at 3.8 or newer, with datashader at 0.16 or newer for rasterising large point sets, pyarrow, and the colour libraries colorcet and colorspacious.

The interactive path needs a template engine and a bundler, so there is jinja2, rcssmin and rjsmin, which are CSS and JavaScript minifiers, and the HTML output is assembled from templates.

The data handling is numpy at 2.0 or newer, pandas, and numba at 0.56 or newer, which is what makes the point cloud processing fast enough to be usable on a real embedding. Scikit-learn at 1.1 or newer and scikit-image at 0.22 or newer are there for the layout work, since a labelled data map plot needs to place labels without overlapping them, and pylabeladjust.

Two more entries are worth naming. `dask[complete]` at 2026.1.2 or newer. And `requests` plus `platformdirs`, which together suggest the library fetches and caches data, which is confirmed by the console script the project registers, `dmp_offline_cache = datamapplot.offline_mode_caching:main`.

That script is a real feature rather than an afterthought. An interactive plot that embeds a data map needs the data with it, and the offline cache lets you produce a self-contained artefact and then work on it away from the network.

The test setup, which is the most interesting part of the repository

The `Makefile` is a testing Makefile, and the targets describe how the project checks a plotting library, which is harder than it sounds for a Python package.

There is a `test` target that runs `test-static` and `test-ui` together. The static side is pytest with the `--mpl` flag, which is the matplotlib image comparison plugin, along with coverage, and a summary report. The interactive side changes directory into `datamapplot/interactive_tests` and runs `npx playwright test`.

So there are two kinds of test, and both are visual. The static one compares generated figures against baseline images, and the interactive one drives the exported HTML in a real browser with Playwright. There is also a `test-ui-fast` variant that inverts the `@slow` tag, which is a thoughtful way to keep the inner loop short without dropping coverage of the slow paths.

The baseline maintenance targets are `update-static-baseline`, which runs pytest with `--mpl-generate-path=datamapplot/tests/baseline` for the static marker, and `update-interactive-baseline`, which runs the interactive pytest marker and then `npx playwright test --update-snapshots`.

And there are two report targets, `report-static` which opens the `fig_comparison.html` file, and `report-interactive` which runs `npx playwright show-report`.

There is a separate `test-backend` target for the Python backend tests alone, without the image comparison, which is the target to run while iterating on logic rather than on appearance.

The `azure-pipelines.yml` and `azure-pipelines.screenshots.yml` files at the root wire this into Azure Pipelines, and the coverage badge in the README points at the same pipelines. The screenshots pipeline is a separate file, which suggests the image comparison runs on its own schedule or on its own trigger.

Installation, and the two routes to a plot

The installation section lists the required libraries and then gives the two commands.

DataMapPlot requires a few libraries, but all are widely available and easy to install: Numpy, Matplotlib, Scikit-learn, Pandas, Datashader, Scikit-image, Numba, Requests and Jinja2.

With pip:

pip install datamapplot

Or with conda and conda-forge:

conda install -c conda-forge datamapplot

The conda route is worth a second look for a project with a scientific environment already, because the dependency set here is exactly the kind that a conda environment already has pinned and that pip would resolve afresh.

The documentation is on Read the Docs, and it includes a FAQ that the README says may answer your questions. There is also a community projects gallery for examples of interactive maps built with the library by other people, which is the most efficient way to see what the interactive output is actually good for.

The static and interactive paths are worth separating in your head before you start. The static path produces a figure you will put in a paper, and it is a matplotlib artefact that you can edit afterwards. The interactive path produces a self-contained HTML file that somebody can open and explore, and it is the harder of the two to control precisely, because the layout happens in the browser.

Contributing, and the NumFOCUS note

The contributing section is short, and its emphasis is unusual.

Contributions are more than welcome, and if you have ideas for features or projects the maintainer asks you to get in touch. The specific note is that everything from code to notebooks to examples and documentation are all equally valuable, and you should not feel you cannot contribute.

The mechanics are the usual ones: fork the project, make your changes and submit a pull request, and the maintainer says they will do their best to work through issues and get changes merged.

The last paragraph is the one worth reading. The package makes heavy use of NumFOCUS sponsored projects and would not be possible without their support of those projects, and the maintainer asks you to consider contributing to NumFOCUS.

That is a fair description of the dependency list. Datashader, numba, dask, scikit-learn, scikit-image, pandas and numpy are all NumFOCUS or closely related projects, and a plotting library that leans on the whole scientific Python stack is only possible because that stack is funded. The request is a more useful recommendation than a generic contributing guide would be.

The `paper.bib` file at the repository root suggests there is a paper for the library, and the `WIDGET_INTERNALS_PLAN.md` is a design document for a widget feature, which tells you the interactive side is the part still being worked out.

Where DataMapPlot is the wrong choice

The first wrong case is a project that wants to draw something other than a labelled data map. The library makes the aesthetic choices and exposes them as options, which is exactly what you want for a figure and exactly what you do not want for a bespoke chart where the layout is the argument.

The second is a minimal dependency environment. A static plot pulls in datashader, numba, dask, scikit-image and scikit-learn, and the interactive path adds jinja2 and two minifiers. If your rendering pipeline has a locked-down dependency set, this is a large negotiation, and a hundred lines of matplotlib would avoid it.

The third is a team that needs to iterate on the figure after the fact. The static output is a figure you can edit in a vector editor, but the automated aesthetic choices are automated, and the reproduction of a specific label placement between runs is only as stable as the version of the libraries that do the placement.

The fourth is a project that needs the interactive plot to be a web application with data that changes. The interactive output is a file, with the data baked in and cached locally, and the offline caching script exists to support exactly that model.

The fifth is a user on Python below 3.10, or one who expects a 1.0. The project declares itself Beta, and it is on a 0.7 line, so the API can still move between minor versions.

What DataMapPlot does well is the narrow thing it names, which is producing a figure that looks considered, from a point cloud and a set of labels, without a week of matplotlib work.

Editorial conclusion

DataMapPlot suits a researcher who has a data map, in the sense of a set of points in a plane with cluster labels, and who needs a figure for a paper, a poster or a talk in an afternoon rather than a week of matplotlib tuning. It does not suit a project that needs a bespoke visualisation language, because the library makes the aesthetic choices and exposes them as options rather than as a drawing API, and it does not suit a minimal dependency environment, since a static plot still pulls in datashader, numba, dask and scikit-image. Before adopting it, look at the interactive output on your own data, because the README shows the animations for CORD-19, ArXiv ML and Wikipedia rather than describing the interaction, and note that the `make test-ui` target runs a Playwright suite over the interactive frontend, which is a sign of how much behaviour lives in the exported HTML.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. Releases
5. TutteInstitute/datamapplot on GitHub