Debian Codegraph @

mpl_scatter_density.egg-info/PKG-INFO

raw
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 [![Build Status](https://dev.azure.com/thomasrobitaille/mpl-scatter-density/_apis/build/status/astrofrog.mpl-scatter-density?branchName=master)](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