diff --git a/.appveyor.yml b/.appveyor.yml index 8d8d48ad17a1..e9d977b47f8c 100644 --- a/.appveyor.yml +++ b/.appveyor.yml @@ -4,6 +4,9 @@ # https://github.com/rmcgibbo/python-appveyor-conda-example # Backslashes in quotes need to be escaped: \ -> "\\" +branches: + except: + - /auto-backport-.*/ environment: diff --git a/.travis.yml b/.travis.yml index 8cd801b42ce3..f7c915dcdd89 100644 --- a/.travis.yml +++ b/.travis.yml @@ -3,6 +3,10 @@ language: python dist: trusty sudo: false +branches: + except: + - /^auto-backport-of-pr-\d*/ + cache: pip: true directories: diff --git a/doc/conf.py b/doc/conf.py index 987142628704..2986fac253b0 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -92,11 +92,11 @@ def _check_deps(): autodoc_default_flags = ['members', 'undoc-members'] intersphinx_mapping = { - 'python': ('https://docs.python.org/', None), - 'numpy': ('https://docs.scipy.org/doc/numpy/', None), - 'scipy': ('https://docs.scipy.org/doc/scipy/reference/', None), - 'pandas': ('http://pandas.pydata.org/pandas-docs/stable', None) - } + 'python': ('https://docs.python.org/3', None), + 'numpy': ('https://docs.scipy.org/doc/numpy/', None), + 'scipy': ('https://docs.scipy.org/doc/scipy/reference/', None), + 'pandas': ('https://pandas.pydata.org/pandas-docs/stable', None) +} explicit_order_folders = [ '../examples/api', diff --git a/doc/devel/contributing.rst b/doc/devel/contributing.rst index eb682e3bae41..d5d288af5a97 100644 --- a/doc/devel/contributing.rst +++ b/doc/devel/contributing.rst @@ -45,6 +45,8 @@ use to organize this information. Thank you for your help in keeping bug reports complete, targeted and descriptive. +.. _installing_for_devs: + Retrieving and installing the latest version of the code ======================================================== @@ -84,17 +86,28 @@ you can use ``git@`` instead of ``https://``, which works through the ssh proto and might be easier to use if you are using 2-factor authentication. -To make sure the tests run locally you must build against the correct version -of freetype. To configure the build system to fetch and build it either export -the env ``MPLLOCALFREETYPE`` as:: +Building Matplotlib for image comparison tests +---------------------------------------------- - export MPLLOCALFREETYPE=1 +Matplotlib's test suite makes heavy use of image comparison tests, +meaning the result of a plot is compared against a known good result. +Unfortunately, different versions of FreeType produce differently +formed characters, causing these image comparisons to fail. To make +them reproducible, Matplotlib can be built with a special local copy +of FreeType. This is recommended for all Matplotlib developers. -or copy :file:`setup.cfg.template` to :file:`setup.cfg` and edit it to contain -:: +Copy :file:`setup.cfg.template` to :file:`setup.cfg` and edit it to contain:: [test] local_freetype = True + tests = True + +or set the ``MPLLOCALFREETYPE`` environmental variable to any true +value. + + +Installing Matplotlib in developer mode +--------------------------------------- To install Matplotlib (and compile the c-extensions) run the following command from the top-level directory :: diff --git a/doc/devel/testing.rst b/doc/devel/testing.rst index 7b71b22d7982..d5ed965cc7d5 100644 --- a/doc/devel/testing.rst +++ b/doc/devel/testing.rst @@ -20,6 +20,10 @@ infrastructure are in :mod:`matplotlib.testing`. Requirements ------------ +Install the latest version of Matplotlib as documented in +:ref:`installing_for_devs` In particular, follow the instructions to use a +local FreeType build + The following software is required to run the tests: - pytest_, version 3.0.0 or later @@ -35,26 +39,6 @@ Optionally you can install: - pytest-xdist_ to run tests in parallel -Building matplotlib for image comparison tests ----------------------------------------------- - -matplotlib's test suite makes heavy use of image comparison tests, -meaning the result of a plot is compared against a known good result. -Unfortunately, different versions of FreeType produce differently -formed characters, causing these image comparisons to fail. To make -them reproducible, matplotlib can be built with a special local copy -of FreeType. This is recommended for all matplotlib developers. - -Add the following content to a ``setup.cfg`` file at the root of the -matplotlib source directory:: - - [test] - local_freetype = True - tests = True - -or by setting the ``MPLLOCALFREETYPE`` environmental variable to any true -value. - Running the tests ----------------- @@ -164,8 +148,7 @@ Writing an image based test is only slightly more difficult than a simple test. The main consideration is that you must specify the "baseline", or expected, images in the :func:`~matplotlib.testing.decorators.image_comparison` decorator. For -example, this test generates a single image and automatically tests -it:: +example, this test generates a single image and automatically tests it:: import numpy as np import matplotlib @@ -262,13 +245,13 @@ repository `_ -- for example, see `its Travis page `_. -If you want to enable Travis CI for your personal matplotlib GitHub +If you want to enable Travis CI for your personal Matplotlib GitHub repo, simply enable the repo to use Travis CI in either the Travis CI UI or the GitHub UI (Admin | Service Hooks). For details, see `the Travis CI Getting Started page `_. This generally isn't necessary, since any pull request submitted against -the main matplotlib repository will be tested. +the main Matplotlib repository will be tested. Once this is configured, you can see the Travis CI results at https://travis-ci.org/your_GitHub_user_name/matplotlib -- here's `an diff --git a/doc/faq/osx_framework.rst b/doc/faq/osx_framework.rst index 95585e79dd5e..ec4c6314294f 100644 --- a/doc/faq/osx_framework.rst +++ b/doc/faq/osx_framework.rst @@ -13,16 +13,14 @@ Working with Matplotlib on OSX Introduction ============ -On OSX, two different types of Python Builds exist: a regular build and a -framework build. In order to interact correctly with OSX through the native -GUI frameworks you need a framework build of Python. -At the time of writing the ``macosx`` and ``WXAgg`` backends require a -framework build to function correctly. This can result in issues for -a python installation not build as a framework and may also happen in -virtual envs and when using (Ana)Conda. -From Matplotlib 1.5 onwards the ``macosx`` backend -checks that a framework build is available and fails if a non framework -build is found. WX has a similar check build in. +On OSX, two different types of Python builds exist: a regular build and a +framework build. In order to interact correctly with OSX through the native +GUI frameworks you need a framework build of Python. At the time of writing +the ``macosx`` and ``WXAgg`` backends require a framework build to function +correctly. This can result in issues for a Python installation not build as a +framework and may also happen in virtual envs and when using (Ana)Conda. From +Matplotlib 1.5 onwards, both backends check that a framework build is available +and fail if a non framework build is found. Without this check a partially functional figure is created. Among the issues with it is that it is produced in the background and @@ -103,9 +101,9 @@ build within the virtual environment you can do ``frameworkpython -m IPython`` ``PYTHONHOME`` and Jupyter ^^^^^^^^^^^^^^^^^^^^^^^^^^ -This approach can be followed even if using `Jupyter `_ -notebooks: you just need to setup a kernel with the suitable ``PYTHONHOME`` -definition. The `jupyter-virtualenv-osx `_ +This approach can be followed even if using `Jupyter `_ +notebooks: you just need to setup a kernel with the suitable ``PYTHONHOME`` +definition. The `jupyter-virtualenv-osx `_ script automates the creation of such a kernel. @@ -139,7 +137,7 @@ With this in place you can run ``frameworkpython`` as above but will need to add to every virtualenv PythonW Compiler -^^^^^^^^^^^^^^^^ +---------------- In addition `virtualenv-pythonw-osx `_ diff --git a/doc/faq/virtualenv_faq.rst b/doc/faq/virtualenv_faq.rst index 621f261adcb8..668aa22f81e4 100644 --- a/doc/faq/virtualenv_faq.rst +++ b/doc/faq/virtualenv_faq.rst @@ -4,14 +4,6 @@ Working with Matplotlib in Virtual environments *********************************************** -.. contents:: - :backlinks: none - -.. _virtualenv_introduction: - -Introduction -============ - When running Matplotlib in a `virtual environment `_ you may discover a few issues. Matplotlib itself has no issue with virtual environments. However, some of diff --git a/doc/users/prev_whats_new/whats_new_1.5.rst b/doc/users/prev_whats_new/whats_new_1.5.rst index ec31bd887e0a..19610709498f 100644 --- a/doc/users/prev_whats_new/whats_new_1.5.rst +++ b/doc/users/prev_whats_new/whats_new_1.5.rst @@ -109,8 +109,8 @@ You can even multiply cyclers, which is like using `itertools.product()` on two or more property cycles. Remember to use parentheses if writing a multi-line `prop_cycle` parameter. -.. figure:: ../../gallery/color/images/sphx_glr_color_cycle_001.png - :target: ../../gallery/color/color_cycle.html +.. figure:: ../../tutorials/intermediate/images/sphx_glr_color_cycle_001.png + :target: ../../tutorials/intermediate/color_cycle.html :align: center :scale: 50 diff --git a/examples/animation/histogram.py b/examples/animation/histogram.py index 75adca125da5..365157172ab2 100644 --- a/examples/animation/histogram.py +++ b/examples/animation/histogram.py @@ -3,8 +3,7 @@ Animated histogram ================== -This example shows how to use a path patch to draw a bunch of -rectangles for an animated histogram. +Use a path patch to draw a bunch of rectangles for an animated histogram. """ import numpy as np @@ -14,8 +13,6 @@ import matplotlib.path as path import matplotlib.animation as animation -fig, ax = plt.subplots() - # Fixing random state for reproducibility np.random.seed(19680801) @@ -30,13 +27,23 @@ top = bottom + n nrects = len(left) -# here comes the tricky part -- we have to set up the vertex and path -# codes arrays using moveto, lineto and closepoly - -# for each rect: 1 for the MOVETO, 3 for the LINETO, 1 for the -# CLOSEPOLY; the vert for the closepoly is ignored but we still need -# it to keep the codes aligned with the vertices -nverts = nrects*(1 + 3 + 1) +############################################################################### +# Here comes the tricky part -- we have to set up the vertex and path codes +# arrays using ``plt.Path.MOVETO``, ``plt.Path.LINETO`` and +# ``plt.Path.CLOSEPOLY`` for each rect. +# +# * We need 1 ``MOVETO`` per rectangle, which sets the initial point. +# * We need 3 ``LINETO``'s, which tell Matplotlib to draw lines from +# vertex 1 to vertex 2, v2 to v3, and v3 to v4. +# * We then need one ``CLOSEPOLY`` which tells Matplotlib to draw a line from +# the v4 to our initial vertex (the ``MOVETO`` vertex), in order to close the +# polygon. +# +# .. note:: +# +# The vertex for ``CLOSEPOLY`` is ignored, but we still need a placeholder +# in the ``verts`` array to keep the codes aligned with the vertices. +nverts = nrects * (1 + 3 + 1) verts = np.zeros((nverts, 2)) codes = np.ones(nverts, int) * path.Path.LINETO codes[0::5] = path.Path.MOVETO @@ -50,13 +57,12 @@ verts[3::5, 0] = right verts[3::5, 1] = bottom -barpath = path.Path(verts, codes) -patch = patches.PathPatch( - barpath, facecolor='green', edgecolor='yellow', alpha=0.5) -ax.add_patch(patch) - -ax.set_xlim(left[0], right[-1]) -ax.set_ylim(bottom.min(), top.max()) +############################################################################### +# To animate the histogram, we need an ``animate`` function, which generates +# a random set of numbers and updates the locations of the vertices for the +# histogram (in this case, only the heights of each rectangle). ``patch`` will +# eventually be a ``Patch`` object. +patch = None def animate(i): @@ -68,5 +74,18 @@ def animate(i): verts[2::5, 1] = top return [patch, ] +############################################################################### +# And now we build the `Path` and `Patch` instances for the histogram using +# our vertices and codes. We add the patch to the `Axes` instance, and setup +# the `FuncAnimation` with our animate function. +fig, ax = plt.subplots() +barpath = path.Path(verts, codes) +patch = patches.PathPatch( + barpath, facecolor='green', edgecolor='yellow', alpha=0.5) +ax.add_patch(patch) + +ax.set_xlim(left[0], right[-1]) +ax.set_ylim(bottom.min(), top.max()) + ani = animation.FuncAnimation(fig, animate, 100, repeat=False, blit=True) plt.show() diff --git a/examples/axes_grid1/demo_axes_divider.py b/examples/axes_grid1/demo_axes_divider.py index 04028d541629..523f4a5824ae 100644 --- a/examples/axes_grid1/demo_axes_divider.py +++ b/examples/axes_grid1/demo_axes_divider.py @@ -3,6 +3,8 @@ Demo Axes Divider ================= +Axes divider to calculate location of axes and +create a divider for them using exisiting axes instances. """ import matplotlib.pyplot as plt diff --git a/examples/axes_grid1/demo_axes_grid.py b/examples/axes_grid1/demo_axes_grid.py index 1670111df01e..44a70a90c931 100644 --- a/examples/axes_grid1/demo_axes_grid.py +++ b/examples/axes_grid1/demo_axes_grid.py @@ -3,6 +3,7 @@ Demo Axes Grid ============== +Grid of 2x2 images with single or own colorbar. """ import matplotlib.pyplot as plt from mpl_toolkits.axes_grid1 import ImageGrid diff --git a/examples/axes_grid1/demo_axes_grid2.py b/examples/axes_grid1/demo_axes_grid2.py index 0c2b49f21e48..26752dd0d5a4 100644 --- a/examples/axes_grid1/demo_axes_grid2.py +++ b/examples/axes_grid1/demo_axes_grid2.py @@ -3,6 +3,7 @@ Demo Axes Grid2 =============== +Grid of images with shared xaxis and yaxis. """ import matplotlib.pyplot as plt from mpl_toolkits.axes_grid1 import ImageGrid diff --git a/examples/axes_grid1/demo_axes_hbox_divider.py b/examples/axes_grid1/demo_axes_hbox_divider.py index 544d50d6bfef..31dbfe4f1d9a 100644 --- a/examples/axes_grid1/demo_axes_hbox_divider.py +++ b/examples/axes_grid1/demo_axes_hbox_divider.py @@ -3,6 +3,7 @@ Demo Axes Hbox Divider ====================== +Hbox Divider to arrange subplots. """ import numpy as np import matplotlib.pyplot as plt diff --git a/examples/axes_grid1/demo_axes_rgb.py b/examples/axes_grid1/demo_axes_rgb.py index 9854de162410..1fcc2cee66bb 100644 --- a/examples/axes_grid1/demo_axes_rgb.py +++ b/examples/axes_grid1/demo_axes_rgb.py @@ -3,6 +3,7 @@ Demo Axes RGB ============= +RGBAxes to show RGB composite images. """ import numpy as np import matplotlib.pyplot as plt diff --git a/examples/event_handling/poly_editor.py b/examples/event_handling/poly_editor.py index 13b139d56bab..83626968f08e 100644 --- a/examples/event_handling/poly_editor.py +++ b/examples/event_handling/poly_editor.py @@ -59,7 +59,8 @@ def draw_callback(self, event): self.background = self.canvas.copy_from_bbox(self.ax.bbox) self.ax.draw_artist(self.poly) self.ax.draw_artist(self.line) - self.canvas.blit(self.ax.bbox) + # do not need to blit here, this will fire before the screen is + # updated def poly_changed(self, poly): 'this method is called whenever the polygon object is called' @@ -114,9 +115,8 @@ def key_press_callback(self, event): elif event.key == 'd': ind = self.get_ind_under_point(event) if ind is not None: - self.poly.xy = [tup - for i, tup in enumerate(self.poly.xy) - if i != ind] + self.poly.xy = np.delete(self.poly.xy, + ind, axis=0) self.line.set_data(zip(*self.poly.xy)) elif event.key == 'i': xys = self.poly.get_transform().transform(self.poly.xy) @@ -126,14 +126,14 @@ def key_press_callback(self, event): s1 = xys[i + 1] d = dist_point_to_segment(p, s0, s1) if d <= self.epsilon: - self.poly.xy = np.array( - list(self.poly.xy[:i]) + - [(event.xdata, event.ydata)] + - list(self.poly.xy[i:])) + self.poly.xy = np.insert( + self.poly.xy, i+1, + [event.xdata, event.ydata], + axis=0) self.line.set_data(zip(*self.poly.xy)) break - - self.canvas.draw() + if self.line.stale: + self.canvas.draw_idle() def motion_notify_callback(self, event): 'on mouse movement' diff --git a/examples/images_contours_and_fields/image_transparency_blend.py b/examples/images_contours_and_fields/image_transparency_blend.py new file mode 100644 index 000000000000..54a4a59c6923 --- /dev/null +++ b/examples/images_contours_and_fields/image_transparency_blend.py @@ -0,0 +1,125 @@ +""" +=========================================== +Blend transparency with color in 2-D images +=========================================== + +Blend transparency with color to highlight parts of data with imshow. + +A common use for :func:`matplotlib.pyplot.imshow` is to plot a 2-D statistical +map. While ``imshow`` makes it easy to visualize a 2-D matrix as an image, +it doesn't easily let you add transparency to the output. For example, one can +plot a statistic (such as a t-statistic) and color the transparency of +each pixel according to its p-value. This example demonstrates how you can +achieve this effect using :class:`matplotlib.colors.Normalize`. Note that it is +not possible to directly pass alpha values to :func:`matplotlib.pyplot.imshow`. + +First we will generate some data, in this case, we'll create two 2-D "blobs" +in a 2-D grid. One blob will be positive, and the other negative. +""" +# sphinx_gallery_thumbnail_number = 3 +import numpy as np +import matplotlib.pyplot as plt +from matplotlib.colors import Normalize + + +def normal_pdf(x, mean, var): + return np.exp(-(x - mean)**2 / (2*var)) + + +# Generate the space in which the blobs will live +xmin, xmax, ymin, ymax = (0, 100, 0, 100) +n_bins = 100 +xx = np.linspace(xmin, xmax, n_bins) +yy = np.linspace(ymin, ymax, n_bins) + +# Generate the blobs. The range of the values is roughly -.0002 to .0002 +means_high = [20, 50] +means_low = [50, 60] +var = [150, 200] + +gauss_x_high = normal_pdf(xx, means_high[0], var[0]) +gauss_y_high = normal_pdf(yy, means_high[1], var[0]) + +gauss_x_low = normal_pdf(xx, means_low[0], var[1]) +gauss_y_low = normal_pdf(yy, means_low[1], var[1]) + +weights_high = np.array(np.meshgrid(gauss_x_high, gauss_y_high)).prod(0) +weights_low = -1 * np.array(np.meshgrid(gauss_x_low, gauss_y_low)).prod(0) +weights = weights_high + weights_low + +# We'll also create a grey background into which the pixels will fade +greys = np.ones(weights.shape + (3,)) * 70 + +# First we'll plot these blobs using only ``imshow``. +vmax = np.abs(weights).max() +vmin = -vmax +cmap = plt.cm.RdYlBu + +fig, ax = plt.subplots() +ax.imshow(greys) +ax.imshow(weights, extent=(xmin, xmax, ymin, ymax), cmap=cmap) +ax.set_axis_off() + +############################################################################### +# Blending in transparency +# ======================== +# +# The simplest way to include transparency when plotting data with +# :func:`matplotlib.pyplot.imshow` is to convert the 2-D data array to a +# 3-D image array of rgba values. This can be done with +# :class:`matplotlib.colors.Normalize`. For example, we'll create a gradient +# moving from left to right below. + +# Create an alpha channel of linearly increasing values moving to the right. +alphas = np.ones(weights.shape) +alphas[:, 30:] = np.linspace(1, 0, 70) + +# Normalize the colors b/w 0 and 1, we'll then pass an MxNx4 array to imshow +colors = Normalize(vmin, vmax, clip=True)(weights) +colors = cmap(colors) + +# Now set the alpha channel to the one we created above +colors[..., -1] = alphas + +# Create the figure and image +# Note that the absolute values may be slightly different +fig, ax = plt.subplots() +ax.imshow(greys) +ax.imshow(colors, extent=(xmin, xmax, ymin, ymax)) +ax.set_axis_off() + +############################################################################### +# Using transparency to highlight values with high amplitude +# ========================================================== +# +# Finally, we'll recreate the same plot, but this time we'll use transparency +# to highlight the extreme values in the data. This is often used to highlight +# data points with smaller p-values. We'll also add in contour lines to +# highlight the image values. + +# Create an alpha channel based on weight values +# Any value whose absolute value is > .0001 will have zero transparency +alphas = Normalize(0, .3, clip=True)(np.abs(weights)) +alphas = np.clip(alphas, .4, 1) # alpha value clipped at the bottom at .4 + +# Normalize the colors b/w 0 and 1, we'll then pass an MxNx4 array to imshow +colors = Normalize(vmin, vmax)(weights) +colors = cmap(colors) + +# Now set the alpha channel to the one we created above +colors[..., -1] = alphas + +# Create the figure and image +# Note that the absolute values may be slightly different +fig, ax = plt.subplots() +ax.imshow(greys) +ax.imshow(colors, extent=(xmin, xmax, ymin, ymax)) + +# Add contour lines to further highlight different levels. +ax.contour(weights[::-1], levels=[-.1, .1], colors='k', linestyles='-') +ax.set_axis_off() +plt.show() + +ax.contour(weights[::-1], levels=[-.0001, .0001], colors='k', linestyles='-') +ax.set_axis_off() +plt.show() diff --git a/examples/subplots_axes_and_figures/subplot_toolbar.py b/examples/subplots_axes_and_figures/subplot_toolbar.py index dcaa6d8927fb..5d333e38b9ed 100644 --- a/examples/subplots_axes_and_figures/subplot_toolbar.py +++ b/examples/subplots_axes_and_figures/subplot_toolbar.py @@ -3,6 +3,7 @@ Subplot Toolbar =============== +Matplotlib has a toolbar available for adjusting suplot spacing. """ import matplotlib.pyplot as plt import numpy as np diff --git a/examples/subplots_axes_and_figures/subplots_adjust.py b/examples/subplots_axes_and_figures/subplots_adjust.py index e1d055b3d223..8f3f8faf0f91 100644 --- a/examples/subplots_axes_and_figures/subplots_adjust.py +++ b/examples/subplots_axes_and_figures/subplots_adjust.py @@ -3,6 +3,7 @@ Subplots Adjust =============== +Adjusting the spacing of margins and subplots using :func:~matplotlib.pyplot.subplots_adjust. """ import matplotlib.pyplot as plt import numpy as np diff --git a/examples/widgets/buttons.py b/examples/widgets/buttons.py index 6420b6022f7c..833366d33a0b 100644 --- a/examples/widgets/buttons.py +++ b/examples/widgets/buttons.py @@ -3,6 +3,10 @@ Buttons ======= +Constructing a simple button GUI to modify a sine wave. + +The ``next`` and ``previous`` button widget helps visualize the wave with +new frequencies. """ import numpy as np diff --git a/examples/widgets/check_buttons.py b/examples/widgets/check_buttons.py index 856b6b4f4a55..d9f06192dd43 100644 --- a/examples/widgets/check_buttons.py +++ b/examples/widgets/check_buttons.py @@ -3,6 +3,11 @@ Check Buttons ============= +Turning visual elements on and off with check buttons. + +This program shows the use of 'Check Buttons' which is similar to +check boxes. There are 3 different sine waves shown and we can choose which +waves are displayed with the check buttons. """ import numpy as np import matplotlib.pyplot as plt diff --git a/examples/widgets/lasso_selector_demo_sgskip.py b/examples/widgets/lasso_selector_demo_sgskip.py index 8fc8f02517d2..4b73d4b3b906 100644 --- a/examples/widgets/lasso_selector_demo_sgskip.py +++ b/examples/widgets/lasso_selector_demo_sgskip.py @@ -3,6 +3,11 @@ Lasso Selector Demo =================== +Interactively selecting data points with the lasso tool. + +This examples plots a scatter plot. You can then select a few points by drawing +a lasso loop around the points on the graph. To draw, just click +on the graph, hold, and drag it around the points you need to select. """ from __future__ import print_function diff --git a/examples/widgets/multicursor.py b/examples/widgets/multicursor.py index c49ac716fa1a..5137512065f8 100644 --- a/examples/widgets/multicursor.py +++ b/examples/widgets/multicursor.py @@ -3,6 +3,11 @@ Multicursor =========== +Showing a cursor on multiple plots simultaneously. + +This example generates two subplots and on hovering +the cursor over data in one subplot, the values of that datapoint +are shown in both respectively. """ import numpy as np import matplotlib.pyplot as plt diff --git a/examples/widgets/radio_buttons.py b/examples/widgets/radio_buttons.py index fe5d3d7b6e45..41cde39bdfb8 100644 --- a/examples/widgets/radio_buttons.py +++ b/examples/widgets/radio_buttons.py @@ -3,6 +3,11 @@ Radio Buttons ============= +Using radio buttons to choose properties of your plot. + +Radio buttons let you choose between multiple options in a visualization. +In this case, the buttons let the user choose one of the three different sine +waves to be shown in the plot. """ import numpy as np import matplotlib.pyplot as plt diff --git a/examples/widgets/slider_demo.py b/examples/widgets/slider_demo.py index 3edaaf73eb71..1e1fa44510bf 100644 --- a/examples/widgets/slider_demo.py +++ b/examples/widgets/slider_demo.py @@ -3,6 +3,11 @@ Slider Demo =========== +Using the slider widget to control visual properties of your plot. + +In this example, a slider is used to choose the frequency of a sine +wave. You can control many continuously-varying properties of your plot in +this way. """ import numpy as np import matplotlib.pyplot as plt diff --git a/examples/widgets/textbox.py b/examples/widgets/textbox.py index d05936dd6405..b3c786014b6c 100644 --- a/examples/widgets/textbox.py +++ b/examples/widgets/textbox.py @@ -3,6 +3,11 @@ Textbox ======= +Allowing text input with the Textbox widget. + +You can use the Textbox widget to let users provide any text that needs to be +displayed, including formulas. You can use a submit button to create plots +with the given input. """ import numpy as np diff --git a/lib/matplotlib/widgets.py b/lib/matplotlib/widgets.py index 8b4055643a74..af31049ce1f5 100644 --- a/lib/matplotlib/widgets.py +++ b/lib/matplotlib/widgets.py @@ -414,6 +414,13 @@ def _update(self, event): self.set_val(val) def set_val(self, val): + """ + Set slider value to *val* + + Parameters + ---------- + val : float + """ xy = self.poly.xy xy[2] = val, 1 xy[3] = val, 0 @@ -429,10 +436,19 @@ def set_val(self, val): def on_changed(self, func): """ - When the slider value is changed, call *func* with the new - slider position + When the slider value is changed call *func* with the new + slider value - A connection id is returned which can be used to disconnect + Parameters + ---------- + func : callable + Function to call when slider is changed. + The function must accept a single float as its arguments. + + Returns + ------- + cid : int + Connection id (which can be used to disconnect *func*) """ cid = self.cnt self.observers[cid] = func @@ -440,14 +456,21 @@ def on_changed(self, func): return cid def disconnect(self, cid): - """remove the observer with connection id *cid*""" + """ + Remove the observer with connection id *cid* + + Parameters + ---------- + cid : int + Connection id of the observer to be removed + """ try: del self.observers[cid] except KeyError: pass def reset(self): - """reset the slider to the initial value if needed""" + """Reset the slider to the initial value""" if (self.val != self.valinit): self.set_val(self.valinit) diff --git a/setupext.py b/setupext.py index 997b3ea5ba5b..fa685c7e172d 100644 --- a/setupext.py +++ b/setupext.py @@ -1187,7 +1187,10 @@ def do_custom_build(self): else: break else: - raise IOError("Failed to download freetype") + raise IOError("Failed to download freetype. " + "You can download the file by " + "alternative means and copy it " + " to '{0}'".format(tarball_path)) try: os.makedirs(tarball_cache_dir) except OSError: diff --git a/tutorials/advanced/transforms_tutorial.py b/tutorials/advanced/transforms_tutorial.py index 4bd41fb94de6..8a60c875551e 100644 --- a/tutorials/advanced/transforms_tutorial.py +++ b/tutorials/advanced/transforms_tutorial.py @@ -18,27 +18,31 @@ ``ax`` is a :class:`~matplotlib.axes.Axes` instance, and ``fig`` is a :class:`~matplotlib.figure.Figure` instance. -=========== ============================= ===================================== -Coordinates Transformation object Description -=========== ============================= ===================================== -"data" ``ax.transData```` The coordinate system for the data, - controlled by xlim and ylim. -"axes" ``ax.transAxes`` The coordinate system of the - `~.Axes`; (0, 0) is bottom left of - the axes, and (1, 1) is top right of - the axes. -"figure" ``fig.transFigure`` The coordinate system of the - `~.Figure`; (0, 0) is bottom left of - the figure, and (1, 1) is top right - of the figure. -"display" ``None``, or The pixel coordinate system of the - ``IdentityTransform()`` display; (0, 0) is bottom left of the - display, and (width, height) is top - right of the display in pixels. -"xaxis", ``ax.get_xaxis_transform()``, Blended coordinate systems; use data -"yaxis" ``ax.get_yaxis_transform()`` coordinates on one of the axis and - axes coordinates on the other. -=========== ============================= ===================================== ++-----------+-----------------------------+-----------------------------------+ +|Coordinates|Transformation object |Description | ++-----------+-----------------------------+-----------------------------------+ +|"data" |``ax.transData`` |The coordinate system for the data,| +| | |controlled by xlim and ylim. | ++-----------+-----------------------------+-----------------------------------+ +|"axes" |``ax.transAxes`` |The coordinate system of the | +| | |`~.Axes`; (0, 0) is bottom left of | +| | |the axes, and (1, 1) is top right | +| | |of the axes. | ++-----------+-----------------------------+-----------------------------------+ +|"figure" |``fig.transFigure`` |The coordinate system of the | +| | |`~.Figure`; (0, 0) is bottom left | +| | |of the figure, and (1, 1) is top | +| | |right of the figure. | ++-----------+-----------------------------+-----------------------------------+ +|"display" |``None``, or |The pixel coordinate system of the | +| |``IdentityTransform()`` |display; (0, 0) is bottom left of | +| | |the display, and (width, height) is| +| | |top right of the display in pixels.| ++-----------+-----------------------------+-----------------------------------+ +|"xaxis", |``ax.get_xaxis_transform()``,|Blended coordinate systems; use | +|"yaxis" |``ax.get_yaxis_transform()`` |data coordinates on one of the axis| +| | |and axes coordinates on the other. | ++-----------+-----------------------------+-----------------------------------+ All of the transformation objects in the table above take inputs in their coordinate system, and transform the input to the `display` diff --git a/tutorials/intermediate/artists.py b/tutorials/intermediate/artists.py index 657811d41424..61bc929df0ba 100644 --- a/tutorials/intermediate/artists.py +++ b/tutorials/intermediate/artists.py @@ -280,7 +280,7 @@ class in the matplotlib API, and the one you will be working with most # .. _figure-container: # # Figure container -# ================ +# ---------------- # # The top level container ``Artist`` is the # :class:`matplotlib.figure.Figure`, and it contains everything in the @@ -366,7 +366,7 @@ class in the matplotlib API, and the one you will be working with most # .. _axes-container: # # Axes container -# ============== +# -------------- # # The :class:`matplotlib.axes.Axes` is the center of the matplotlib # universe -- it contains the vast majority of all the ``Artists`` used @@ -544,7 +544,7 @@ class in the matplotlib API, and the one you will be working with most # .. _axis-container: # # Axis containers -# =============== +# --------------- # # The :class:`matplotlib.axis.Axis` instances handle the drawing of the # tick lines, the grid lines, the tick labels and the axis label. You @@ -648,7 +648,7 @@ class in the matplotlib API, and the one you will be working with most # .. _tick-container: # # Tick containers -# =============== +# --------------- # # The :class:`matplotlib.axis.Tick` is the final container object in our # descent from the :class:`~matplotlib.figure.Figure` to the diff --git a/tutorials/intermediate/color_cycle.py b/tutorials/intermediate/color_cycle.py new file mode 100644 index 000000000000..ba463ade6bf9 --- /dev/null +++ b/tutorials/intermediate/color_cycle.py @@ -0,0 +1,125 @@ +""" +=================== +Styling with cycler +=================== + +Demo of custom property-cycle settings to control colors and other style +properties for multi-line plots. + +.. note:: + + More complete documentation of the ``cycler`` API can be found + `here `_. + +This example demonstrates two different APIs: + +1. Setting the default rc parameter specifying the property cycle. + This affects all subsequent axes (but not axes already created). +2. Setting the property cycle for a single pair of axes. + +""" +from cycler import cycler +import numpy as np +import matplotlib.pyplot as plt + +############################################################################### +# First we'll generate some sample data, in this case, four offset sine +# curves. +x = np.linspace(0, 2 * np.pi, 50) +offsets = np.linspace(0, 2 * np.pi, 4, endpoint=False) +yy = np.transpose([np.sin(x + phi) for phi in offsets]) + +############################################################################### +# Now ``yy`` has shape +print(yy.shape) + +############################################################################### +# So ``yy[:, i]`` will give you the ``i``-th offset sine curve. Let's set the +# default prop_cycle using :func:`matplotlib.pyplot.rc`. We'll combine a color +# cycler and a linestyle cycler by adding (``+``) two ``cycler``'s together. +# See the bottom of this tutorial for more information about combining +# different cyclers. +default_cycler = cycler('color', ['r', 'g', 'b', 'y']) \ + + cycler('linestyle', ['-', '--', ':', '-.']) + +plt.rc('lines', linewidth=4) +plt.rc('axes', prop_cycle=default_cycler) + +############################################################################### +# Now we'll generate a figure with two axes, one on top of the other. On the +# first axis, we'll plot with the default cycler. On the second axis, we'll +# set the prop_cycler using :func:`matplotlib.axes.Axes.set_prop_cycle` +# which will only set the ``prop_cycle`` for this :mod:`matplotlib.axes.Axes` +# instance. We'll use a second ``cycler`` that combines a color cycler and a +# linewidth cycler. +custom_cycler = cycler('color', ['c', 'm', 'y', 'k']) \ + + cycler('lw', [1, 2, 3, 4]) + +fig, (ax0, ax1) = plt.subplots(nrows=2) +ax0.plot(yy) +ax0.set_title('Set default color cycle to rgby') +ax1.set_prop_cycle(custom_cycler) +ax1.plot(yy) +ax1.set_title('Set axes color cycle to cmyk') + +# Add a bit more space between the two plots. +fig.subplots_adjust(hspace=0.3) +plt.show() + +############################################################################### +# Setting ``prop_cycler`` in the ``matplotlibrc`` file or style files +# ------------------------------------------------------------------- +# +# Remember, if you want to set a custom ``prop_cycler`` in your +# ``.matplotlibrc`` file or a style file (``style.mplstyle``), you can set the +# ``axes.prop_cycle`` property: +# +# ..code-block:: python +# +# axes.prop_cycle : cycler('color', 'bgrcmyk') +# +# Cycling through multiple properties +# ----------------------------------- +# +# You can add cyclers: +# +# .. code-block:: python +# +# from cycler import cycler +# cc = (cycler(color=list('rgb')) + +# cycler(linestyle=['-', '--', '-.'])) +# for d in cc: +# print(d) +# +# Results in: +# +# .. code-block:: python +# +# {'color': 'r', 'linestyle': '-'} +# {'color': 'g', 'linestyle': '--'} +# {'color': 'b', 'linestyle': '-.'} +# +# +# You can multiply cyclers: +# +# .. code-block:: python +# +# from cycler import cycler +# cc = (cycler(color=list('rgb')) * +# cycler(linestyle=['-', '--', '-.'])) +# for d in cc: +# print(d) +# +# Results in: +# +# .. code-block:: python +# +# {'color': 'r', 'linestyle': '-'} +# {'color': 'r', 'linestyle': '--'} +# {'color': 'r', 'linestyle': '-.'} +# {'color': 'g', 'linestyle': '-'} +# {'color': 'g', 'linestyle': '--'} +# {'color': 'g', 'linestyle': '-.'} +# {'color': 'b', 'linestyle': '-'} +# {'color': 'b', 'linestyle': '--'} +# {'color': 'b', 'linestyle': '-.'} diff --git a/tutorials/introductory/sample_plots.py b/tutorials/introductory/sample_plots.py index a680678fb565..ef89dac9e165 100644 --- a/tutorials/introductory/sample_plots.py +++ b/tutorials/introductory/sample_plots.py @@ -23,11 +23,11 @@ .. _screenshots_subplot_demo: -Subplot demo -============ +Multiple subplots in one figure +=============================== Multiple axes (i.e. subplots) are created with the -:func:`~matplotlib.pyplot.subplot` command: +:func:`~matplotlib.pyplot.subplot` function: .. figure:: ../../gallery/subplots_axes_and_figures/images/sphx_glr_subplot_001.png :target: ../../gallery/subplots_axes_and_figures/subplot.html @@ -36,12 +36,46 @@ Subplot +.. _screenshots_images_demo: + +Images +====== + +Matplotlib can display images (assuming equally spaced +horizontal dimensions) using the :func:`~matplotlib.pyplot.imshow` function. + +.. figure:: ../../gallery/images_contours_and_fields/images/sphx_glr_image_demo_003.png + :target: ../../gallery/images_contours_and_fields/image_demo.html + :align: center + :scale: 50 + + Example of using :func:`~matplotlib.pyplot.imshow` to display a CT scan + +.. _screenshots_pcolormesh_demo: + + +Contouring and pseudocolor +========================== + +The :func:`~matplotlib.pyplot.pcolormesh` function can make a colored +representation of a two-dimensional array, even if the horizontal dimensions +are unevenly spaced. The +:func:`~matplotlib.pyplot.contour` function is another way to represent +the same data: + +.. figure:: ../../gallery/images_contours_and_fields/images/sphx_glr_pcolormesh_levels_001.png + :target: ../../gallery/images_contours_and_fields/pcolormesh_levels.html + :align: center + :scale: 50 + + Example comparing :func:`~matplotlib.pyplot.pcolormesh` and :func:`~matplotlib.pyplot.contour` for plotting two-dimensional data + .. _screenshots_histogram_demo: Histograms ========== -The :func:`~matplotlib.pyplot.hist` command automatically generates +The :func:`~matplotlib.pyplot.hist` function automatically generates histograms and returns the bin counts or probabilities: .. figure:: ../../gallery/statistics/images/sphx_glr_histogram_features_001.png @@ -54,8 +88,8 @@ .. _screenshots_path_demo: -Path demo -========= +Paths +===== You can add arbitrary paths in Matplotlib using the :mod:`matplotlib.path` module: @@ -69,8 +103,8 @@ .. _screenshots_mplot3d_surface: -mplot3d -========= +Three-dimensional plotting +========================== The mplot3d toolkit (see :ref:`toolkit_mplot3d-tutorial` and :ref:`mplot3d-examples-index`) has support for simple 3d graphs @@ -103,7 +137,7 @@ :align: center :scale: 50 - Plot Streamplot + Streamplot with various plotting options. This feature complements the :meth:`~matplotlib.pyplot.quiver` function for plotting vector fields. Thanks to Tom Flannaghan and Tony Yu for adding the @@ -132,7 +166,7 @@ Bar charts ========== -Use the :func:`~matplotlib.pyplot.bar` command to make bar charts, which +Use the :func:`~matplotlib.pyplot.bar` function to make bar charts, which includes customizations such as error bars: .. figure:: ../../gallery/statistics/images/sphx_glr_barchart_demo_001.png @@ -153,7 +187,7 @@ Pie charts ========== -The :func:`~matplotlib.pyplot.pie` command allows you to create pie +The :func:`~matplotlib.pyplot.pie` function allows you to create pie charts. Optional features include auto-labeling the percentage of area, exploding one or more wedges from the center of the pie, and a shadow effect. Take a close look at the attached code, which generates this figure in just @@ -168,10 +202,10 @@ .. _screenshots_table_demo: -Table demo -========== +Tables +====== -The :func:`~matplotlib.pyplot.table` command adds a text table +The :func:`~matplotlib.pyplot.table` function adds a text table to an axes. .. figure:: ../../gallery/misc/images/sphx_glr_table_demo_001.png @@ -185,10 +219,10 @@ .. _screenshots_scatter_demo: -Scatter demo -============ +Scatter plots +============= -The :func:`~matplotlib.pyplot.scatter` command makes a scatter plot +The :func:`~matplotlib.pyplot.scatter` function makes a scatter plot with (optional) size and color arguments. This example plots changes in Google's stock price, with marker sizes reflecting the trading volume and colors varying with time. Here, the @@ -204,7 +238,7 @@ .. _screenshots_slider_demo: -Slider demo +GUI widgets =========== Matplotlib has basic GUI widgets that are independent of the graphical @@ -217,15 +251,15 @@ :align: center :scale: 50 - Slider Demo + Slider and radio-button GUI. .. _screenshots_fill_demo: -Fill demo -========= +Filled curves +============= -The :func:`~matplotlib.pyplot.fill` command lets you +The :func:`~matplotlib.pyplot.fill` function lets you plot filled curves and polygons: .. figure:: ../../gallery/lines_bars_and_markers/images/sphx_glr_fill_001.png @@ -239,8 +273,8 @@ .. _screenshots_date_demo: -Date demo -========= +Date handling +============= You can plot timeseries data with major and minor ticks and custom tick formatters for both. @@ -280,7 +314,7 @@ Polar plots =========== -The :func:`~matplotlib.pyplot.polar` command generates polar plots. +The :func:`~matplotlib.pyplot.polar` function generates polar plots. .. figure:: ../../gallery/pie_and_polar_charts/images/sphx_glr_polar_demo_001.png :target: ../../gallery/pie_and_polar_charts/polar_demo.html @@ -295,9 +329,9 @@ Legends ======= -The :func:`~matplotlib.pyplot.legend` command automatically -generates figure legends, with MATLAB-compatible legend placement -commands. +The :func:`~matplotlib.pyplot.legend` function automatically +generates figure legends, with MATLAB-compatible legend-placement +functions. .. figure:: ../../gallery/api/images/sphx_glr_legend_001.png :target: ../../gallery/api/legend.html @@ -306,12 +340,12 @@ Legend -Thanks to Charles Twardy for input on the legend command. +Thanks to Charles Twardy for input on the legend function. .. _screenshots_mathtext_examples_demo: -Mathtext_examples -================= +TeX-notation for text objects +============================= Below is a sampling of the many TeX expressions now supported by Matplotlib's internal mathtext engine. The mathtext module provides TeX style mathematical @@ -349,8 +383,8 @@ .. _screenshots_eeg_demo: -EEG demo -========= +EEG GUI +======= You can embed Matplotlib into pygtk, wx, Tk, or Qt applications. Here is a screenshot of an EEG viewer called `pbrain @@ -372,7 +406,7 @@ XKCD-style sketch plots ======================= -Matplotlib supports plotting in the style of `xkcd +Just for fun, Matplotlib supports plotting in the style of `xkcd `. .. figure:: ../../gallery/showcase/images/sphx_glr_xkcd_001.png @@ -383,7 +417,13 @@ Xkcd """ -# An extra set of sample plots for the thumbnail image. +################################################################### +# Subplot example +# =============== +# +# Many plot types can be combined in one figure to create +# powerful and flexible representations of data. +# import matplotlib.pyplot as plt import numpy as np