| 1 |
Metadata-Version: 2.1 |
| 2 |
Name: mpl-scatter-density |
| 3 |
Version: 0.8 |
| 4 |
Summary: Matplotlib helpers to make density scatter plots |
| 5 |
Home-page: https://github.com/astrofrog/mpl-scatter-density |
| 6 |
Author: Thomas Robitaille |
| 7 |
Author-email: [email protected] |
| 8 |
License: BSD |
| 9 |
Requires-Python: >=3.6 |
| 10 |
License-File: LICENSE |
| 11 |
Requires-Dist: numpy |
| 12 |
Requires-Dist: matplotlib>=3.0 |
| 13 |
Requires-Dist: fast-histogram>=0.3 |
| 14 |
Provides-Extra: test |
| 15 |
Requires-Dist: pytest; extra == "test" |
| 16 |
Requires-Dist: pytest-cov; extra == "test" |
| 17 |
Requires-Dist: pytest-mpl; extra == "test" |
| 18 |
|
| 19 |
|Azure Status| |Coverage Status| |
| 20 |
|
| 21 |
About |
| 22 |
----- |
| 23 |
|
| 24 |
Plotting millions of points can be slow. Real slow... :sleeping: |
| 25 |
|
| 26 |
So why not use density maps? :zap: |
| 27 |
|
| 28 |
The **mpl-scatter-density** mini-package provides functionality to make it easy |
| 29 |
to make your own scatter density maps, both for interactive and non-interactive |
| 30 |
use. Fast. The following animation shows real-time interactive use with 10 |
| 31 |
million points, but interactive performance is still good even with 100 million |
| 32 |
points (and more if you have enough RAM). |
| 33 |
|
| 34 |
.. image:: https://github.com/astrofrog/mpl-scatter-density/raw/main/images/demo_taxi.gif |
| 35 |
:alt: Demo of mpl-scatter-density with NY taxi data |
| 36 |
:align: center |
| 37 |
|
| 38 |
When panning, the density map is shown at a lower resolution to keep things |
| 39 |
responsive (though this is customizable). |
| 40 |
|
| 41 |
To install, simply do:: |
| 42 |
|
| 43 |
pip install mpl-scatter-density |
| 44 |
|
| 45 |
This package requires `Numpy <http://www.numpy.org>`_, `Matplotlib |
| 46 |
<http://www.matplotlib.org>`_, and `fast-histogram |
| 47 |
<https://github.com/astrofrog/fast-histogram>`_ - these will be installed |
| 48 |
by pip if they are missing. Both Python 2.7 and Python 3.x are supported, |
| 49 |
and the package should work correctly on Linux, MacOS X, and Windows. |
| 50 |
|
| 51 |
Usage |
| 52 |
----- |
| 53 |
|
| 54 |
There are two main ways to use **mpl-scatter-density**, both of which are |
| 55 |
explained below. |
| 56 |
|
| 57 |
scatter_density method |
| 58 |
~~~~~~~~~~~~~~~~~~~~~~ |
| 59 |
|
| 60 |
The easiest way to use this package is to simply import ``mpl_scatter_density``, |
| 61 |
then create Matplotlib axes as usual but adding a |
| 62 |
``projection='scatter_density'`` option (if your reaction is 'wait, what?', see |
| 63 |
`here <https://github.com/astrofrog/mpl-scatter-density/blob/master/README.rst#why-on-earth-have-you-defined-scatter_density-as-a-projection>`_). |
| 64 |
This will return a ``ScatterDensityAxes`` instance that has a |
| 65 |
``scatter_density`` method in addition to all the usual methods (``scatter``, |
| 66 |
``plot``, etc.). |
| 67 |
|
| 68 |
.. code:: python |
| 69 |
|
| 70 |
import numpy as np |
| 71 |
import mpl_scatter_density |
| 72 |
import matplotlib.pyplot as plt |
| 73 |
|
| 74 |
# Generate fake data |
| 75 |
|
| 76 |
N = 10000000 |
| 77 |
x = np.random.normal(4, 2, N) |
| 78 |
y = np.random.normal(3, 1, N) |
| 79 |
|
| 80 |
# Make the plot - note that for the projection option to work, the |
| 81 |
# mpl_scatter_density module has to be imported above. |
| 82 |
|
| 83 |
fig = plt.figure() |
| 84 |
ax = fig.add_subplot(1, 1, 1, projection='scatter_density') |
| 85 |
ax.scatter_density(x, y) |
| 86 |
ax.set_xlim(-5, 10) |
| 87 |
ax.set_ylim(-5, 10) |
| 88 |
fig.savefig('gaussian.png') |
| 89 |
|
| 90 |
Which gives: |
| 91 |
|
| 92 |
.. image:: https://github.com/astrofrog/mpl-scatter-density/raw/master/images/gaussian.png |
| 93 |
:alt: Result from the example script |
| 94 |
:align: center |
| 95 |
|
| 96 |
The ``scatter_density`` method takes the same options as ``imshow`` (for example |
| 97 |
``cmap``, ``alpha``, ``norm``, etc.), but also takes the following optional |
| 98 |
arguments: |
| 99 |
|
| 100 |
* ``dpi``: this is an integer that is used to determine the resolution of the |
| 101 |
density map. By default, this is 72, but you can change it as needed, or set |
| 102 |
it to ``None`` to use the default for the Matplotlib backend you are using. |
| 103 |
|
| 104 |
* ``downres_factor``: this is an integer that is used to determine how much to |
| 105 |
downsample the density map when panning in interactive mode. Set this to 1 |
| 106 |
if you don't want any downsampling. |
| 107 |
|
| 108 |
* ``color``: this can be set to any valid matplotlib color, and will be used |
| 109 |
to automatically make a monochromatic colormap based on this color. The |
| 110 |
colormap will fade to transparent, which means that this mode is ideal when |
| 111 |
showing multiple density maps together. |
| 112 |
|
| 113 |
Here is an example of using the ``color`` option: |
| 114 |
|
| 115 |
.. code:: python |
| 116 |
|
| 117 |
import numpy as np |
| 118 |
import matplotlib.pyplot as plt |
| 119 |
import mpl_scatter_density # noqa |
| 120 |
|
| 121 |
fig = plt.figure() |
| 122 |
ax = fig.add_subplot(1, 1, 1, projection='scatter_density') |
| 123 |
|
| 124 |
n = 10000000 |
| 125 |
|
| 126 |
x = np.random.normal(0.5, 0.3, n) |
| 127 |
y = np.random.normal(0.5, 0.3, n) |
| 128 |
|
| 129 |
ax.scatter_density(x, y, color='red') |
| 130 |
|
| 131 |
x = np.random.normal(1.0, 0.2, n) |
| 132 |
y = np.random.normal(0.6, 0.2, n) |
| 133 |
|
| 134 |
ax.scatter_density(x, y, color='blue') |
| 135 |
|
| 136 |
ax.set_xlim(-0.5, 1.5) |
| 137 |
ax.set_ylim(-0.5, 1.5) |
| 138 |
|
| 139 |
fig.savefig('double.png') |
| 140 |
|
| 141 |
Which produces the following output: |
| 142 |
|
| 143 |
.. image:: https://github.com/astrofrog/mpl-scatter-density/raw/master/images/double.png |
| 144 |
:alt: Result from the example script |
| 145 |
:align: center |
| 146 |
|
| 147 |
ScatterDensityArtist |
| 148 |
~~~~~~~~~~~~~~~~~~~~ |
| 149 |
|
| 150 |
If you are a more experienced Matplotlib user, you might want to use the |
| 151 |
``ScatterDensityArtist`` directly (this is used behind the scenes in the |
| 152 |
above example). To use this, initialize the ``ScatterDensityArtist`` with |
| 153 |
the axes as first argument, followed by any arguments you would have passed |
| 154 |
to ``scatter_density`` above (you can also take a look at the docstring for |
| 155 |
``ScatterDensityArtist``). You should then add the artist to the axes: |
| 156 |
|
| 157 |
.. code:: python |
| 158 |
|
| 159 |
from mpl_scatter_density import ScatterDensityArtist |
| 160 |
a = ScatterDensityArtist(ax, x, y) |
| 161 |
ax.add_artist(a) |
| 162 |
|
| 163 |
Advanced |
| 164 |
-------- |
| 165 |
|
| 166 |
Non-linear stretches for high dynamic range plots |
| 167 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 168 |
|
| 169 |
In some cases, your density map might have a high dynamic range, and you might |
| 170 |
therefore want to show the log of the counts rather than the counts. You can do |
| 171 |
this by passing a ``matplotlib.colors.Normalize`` object to the ``norm`` argument |
| 172 |
in the same wasy as for ``imshow``. For example, the `astropy |
| 173 |
<http://www.astropy.org>`_ package includes a `nice framework |
| 174 |
<http://docs.astropy.org/en/stable/api/astropy.visualization.LogStretch.html#astropy.visualization.LogStretch>`_ |
| 175 |
for making such a ``Normalize`` object for different functions. The following |
| 176 |
example shows how to show the density map on a log scale: |
| 177 |
|
| 178 |
.. code:: python |
| 179 |
|
| 180 |
import numpy as np |
| 181 |
import mpl_scatter_density |
| 182 |
import matplotlib.pyplot as plt |
| 183 |
|
| 184 |
# Make the norm object to define the image stretch |
| 185 |
from astropy.visualization import LogStretch |
| 186 |
from astropy.visualization.mpl_normalize import ImageNormalize |
| 187 |
norm = ImageNormalize(vmin=0., vmax=1000, stretch=LogStretch()) |
| 188 |
|
| 189 |
N = 10000000 |
| 190 |
x = np.random.normal(4, 2, N) |
| 191 |
y = np.random.normal(3, 1, N) |
| 192 |
|
| 193 |
fig = plt.figure() |
| 194 |
ax = fig.add_subplot(1, 1, 1, projection='scatter_density') |
| 195 |
ax.scatter_density(x, y, norm=norm) |
| 196 |
ax.set_xlim(-5, 10) |
| 197 |
ax.set_ylim(-5, 10) |
| 198 |
fig.savefig('gaussian_log.png') |
| 199 |
|
| 200 |
Which produces the following output: |
| 201 |
|
| 202 |
.. image:: https://github.com/astrofrog/mpl-scatter-density/raw/master/images/gaussian_log.png |
| 203 |
:alt: Result from the example script |
| 204 |
:align: center |
| 205 |
|
| 206 |
Adding a colorbar |
| 207 |
~~~~~~~~~~~~~~~~~ |
| 208 |
|
| 209 |
You can show a colorbar in the same way as you would for an image - the |
| 210 |
following example shows how to do it: |
| 211 |
|
| 212 |
.. code:: python |
| 213 |
|
| 214 |
import numpy as np |
| 215 |
import mpl_scatter_density |
| 216 |
import matplotlib.pyplot as plt |
| 217 |
|
| 218 |
N = 10000000 |
| 219 |
x = np.random.normal(4, 2, N) |
| 220 |
y = np.random.normal(3, 1, N) |
| 221 |
|
| 222 |
fig = plt.figure() |
| 223 |
ax = fig.add_subplot(1, 1, 1, projection='scatter_density') |
| 224 |
density = ax.scatter_density(x, y) |
| 225 |
ax.set_xlim(-5, 10) |
| 226 |
ax.set_ylim(-5, 10) |
| 227 |
fig.colorbar(density, label='Number of points per pixel') |
| 228 |
fig.savefig('gaussian_colorbar.png') |
| 229 |
|
| 230 |
Which produces the following output: |
| 231 |
|
| 232 |
.. image:: https://github.com/astrofrog/mpl-scatter-density/raw/master/images/gaussian_colorbar.png |
| 233 |
:alt: Result from the example script |
| 234 |
:align: center |
| 235 |
|
| 236 |
Color-coding 'markers' with individual values |
| 237 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 238 |
|
| 239 |
In the same way that a 1-D array of values can be passed to Matplotlib's |
| 240 |
``scatter`` function/method, a 1-D array of values can be passed to |
| 241 |
``scatter_density`` using the ``c=`` argument: |
| 242 |
|
| 243 |
.. code:: python |
| 244 |
|
| 245 |
import numpy as np |
| 246 |
import mpl_scatter_density |
| 247 |
import matplotlib.pyplot as plt |
| 248 |
|
| 249 |
N = 10000000 |
| 250 |
x = np.random.normal(4, 2, N) |
| 251 |
y = np.random.normal(3, 1, N) |
| 252 |
c = x - y + np.random.normal(0, 5, N) |
| 253 |
|
| 254 |
fig = plt.figure() |
| 255 |
ax = fig.add_subplot(1, 1, 1, projection='scatter_density') |
| 256 |
ax.scatter_density(x, y, c=c, vmin=-10, vmax=+10, cmap=plt.cm.RdYlBu) |
| 257 |
ax.set_xlim(-5, 13) |
| 258 |
ax.set_ylim(-5, 11) |
| 259 |
fig.savefig('gaussian_color_coded.png') |
| 260 |
|
| 261 |
Which produces the following output: |
| 262 |
|
| 263 |
.. image:: https://github.com/astrofrog/mpl-scatter-density/raw/master/images/gaussian_color_coded.png |
| 264 |
:alt: Result from the example script |
| 265 |
:align: center |
| 266 |
|
| 267 |
Note that to keep performance as good as possible, the values from the ``c`` |
| 268 |
attribute are averaged inside each pixel of the density map, then the colormap |
| 269 |
is applied. This is a little different to what ``scatter`` would converge to in |
| 270 |
the limit of many points (since in that case it would apply the color to all the |
| 271 |
markers than average the colors). |
| 272 |
|
| 273 |
Q&A |
| 274 |
--- |
| 275 |
|
| 276 |
Isn't this basically the same as datashader? |
| 277 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 278 |
|
| 279 |
This follows the same ideas as |
| 280 |
`datashader <https://github.com/bokeh/datashader>`_, but the aim of |
| 281 |
mpl-scatter-density is specifically to bring datashader-like functionality to |
| 282 |
Matplotlib users. Furthermore, mpl-scatter-density is intended to be very easy |
| 283 |
to install - for example it can be installed with pip. But if you have |
| 284 |
datashader installed and regularly use bokeh, mpl-scatter-density won't do much |
| 285 |
for you. Note that if you are interested in datashader and Matplotlib together, |
| 286 |
there is a work in progress (`pull request |
| 287 |
<https://github.com/bokeh/datashader/pull/200>`_) by **@tacaswell** to create a |
| 288 |
Matplotlib artist similar to that in this package but powered by datashader. |
| 289 |
|
| 290 |
What about vaex? |
| 291 |
~~~~~~~~~~~~~~~~ |
| 292 |
|
| 293 |
`Vaex <http://vaex.astro.rug.nl>`_ is a powerful package to |
| 294 |
visualize large datasets on N-dimensional grids, and therefore has some |
| 295 |
functionality that overlaps with what is here. However, the aim of |
| 296 |
mpl-scatter-density is just to provide a lightweight solution to make |
| 297 |
it easy for users already using Matplotlib |
| 298 |
to add scatter density maps to their plots rather than provide a complete |
| 299 |
environment for data visualization. I highly recommend that you take a look |
| 300 |
at Vaex and determine which approach is right for you! |
| 301 |
|
| 302 |
Why on earth have you defined scatter_density as a projection? |
| 303 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 304 |
|
| 305 |
If you are a Matplotlib developer: I truly am sorry for distorting the intended |
| 306 |
purpose of ``projection`` :blush:. But you have to admit that it's a pretty |
| 307 |
convenient way to have users get a custom Axes sub-class even if it has nothing |
| 308 |
to do with actual projection! |
| 309 |
|
| 310 |
Where do you see this going? |
| 311 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 312 |
|
| 313 |
There are a number of things we could add to this package, for example a way to |
| 314 |
plot density maps as contours, or a way to color code each point by a third |
| 315 |
quantity and have that reflected in the density map. If you have ideas, please |
| 316 |
open issues, and even better contribute a pull request! :smile: |
| 317 |
|
| 318 |
Can I contribute? |
| 319 |
~~~~~~~~~~~~~~~~~ |
| 320 |
|
| 321 |
I'm glad you asked - of course you are very welcome to contribute! If you have |
| 322 |
some ideas, you can open issues or create a pull request directly. Even if you |
| 323 |
don't have time to contribute actual code changes, I would love to hear from you |
| 324 |
if you are having issues using this package. |
| 325 |
|
| 326 |
[](https://dev.azure.com/thomasrobitaille/mpl-scatter-density/_build/latest?definitionId=17&branchName=master) |
| 327 |
|
| 328 |
.. |Azure Status| image:: https://dev.azure.com/thomasrobitaille/mpl-scatter-density/_apis/build/status/astrofrog.mpl-scatter-density?branchName=master |
| 329 |
:target: https://dev.azure.com/thomasrobitaille/mpl-scatter-density/_build/latest?definitionId=17&branchName=master |
| 330 |
|
| 331 |
.. |Coverage Status| image:: https://codecov.io/gh/astrofrog/mpl-scatter-density/branch/master/graph/badge.svg |
| 332 |
:target: https://codecov.io/gh/astrofrog/mpl-scatter-density |
| 333 |
|
| 334 |
Running tests |
| 335 |
------------- |
| 336 |
|
| 337 |
To run the tests, you will need `pytest <https://docs.pytest.org/en/latest/>`_ |
| 338 |
and the `pytest-mpl <https://pypi.python.org/pypi/pytest-mpl>`_ plugin. You can |
| 339 |
then run the tests with:: |
| 340 |
|
| 341 |
pytest mpl_scatter_density --mpl |