diff --git a/doc/_templates/index.html b/doc/_templates/index.html index 1660dfe07f33..18aef7c9bddb 100644 --- a/doc/_templates/index.html +++ b/doc/_templates/index.html @@ -55,18 +55,18 @@

Introduction

interface toolkits.

- +
- screenshots + screenshots
- screenshots + screenshots
- screenshots + screenshots
- screenshots + screenshots
@@ -75,8 +75,8 @@

Introduction

Matplotlib tries to make easy things easy and hard things possible. You can generate plots, histograms, power spectra, bar charts, errorcharts, scatterplots, etc., with just a few lines of code. - For a example, see the screenshots and thumbnail gallery.

+ For examples, see the sample plots and thumbnail gallery.

For simple plotting the pyplot module provides a MATLAB-like interface, particularly when combined diff --git a/doc/api/pyplot_summary.rst b/doc/api/pyplot_summary.rst index 7236fa864ccc..46ae71984367 100644 --- a/doc/api/pyplot_summary.rst +++ b/doc/api/pyplot_summary.rst @@ -1,8 +1,43 @@ -Plotting commands summary -========================= +Below we describe several common approaches to plotting with Matplotlib. + +.. contents:: + +The Pyplot API +-------------- + +The :mod:`matplotlib.pyplot` module contains functions that allow you to generate +many kinds of plots quickly. For examples that showcase the use +of the :mod:`matplotlib.pyplot` module, see the +:ref:`sphx_glr_tutorials_01_introductory_pyplot.py` +or the :ref:`pyplots_examples`. We also recommend that you look into +the object-oriented approach to plotting, described below. .. currentmodule:: matplotlib.pyplot .. autofunction:: plotting +The Object-Oriented API +----------------------- + +Most of these functions also exist as methods in the +:class:`matplotlib.axes.Axes` class. You can use them with the +"Object Oriented" approach to Matplotlib. + +While it is easy to quickly generate plots with the +:mod:`matplotlib.pyplot` module, +we recommend using the object-oriented approach for more control +and customization of your plots. See the methods in the +:meth:`matplotlib.axes.Axes` class for many of the same plotting functions. +For examples of the OO approach to Matplotlib, see the +:ref:`API Examples`. + +Colors in Matplotlib +-------------------- + +There are many colormaps you can use to map data onto color values. +Below we list several ways in which color can be utilized in Matplotlib. + +For a more in-depth look at colormaps, see the +:ref:`sphx_glr_tutorials_colors_colormaps.py` tutorial. + .. autofunction:: colormaps diff --git a/doc/contents.rst b/doc/contents.rst index 77585cd00d08..72612f7b7694 100644 --- a/doc/contents.rst +++ b/doc/contents.rst @@ -15,11 +15,11 @@ Overview :maxdepth: 2 users/index.rst - api/index.rst faq/index.rst mpl_toolkits/index.rst resources/index.rst thirdpartypackages/index.rst + api/index.rst devel/index.rst glossary/index.rst diff --git a/doc/make.py b/doc/make.py index e4fead0beeed..97504819dcc5 100755 --- a/doc/make.py +++ b/doc/make.py @@ -52,45 +52,6 @@ def linkcheck(): [sys.executable] + '-msphinx -b linkcheck -d build/doctrees . build/linkcheck'.split()) - -# For generating PNGs of the top row of index.html: -FRONTPAGE_PY_PATH = "../examples/frontpage/" # python scripts location -FRONTPAGE_PNG_PATH = "_static/" # png files location -# png files and corresponding generation scripts: -FRONTPAGE_PNGS = {"surface3d_frontpage.png": "3D.py", - "contour_frontpage.png": "contour.py", - "histogram_frontpage.png": "histogram.py", - "membrane_frontpage.png": "membrane.py"} - - -def generate_frontpage_pngs(only_if_needed=True): - """Executes the scripts for PNG generation of the top row of index.html. - - If `only_if_needed` is `True`, then the PNG file is only generated, if it - doesn't exist or if the python file is newer. - - Note that the element `div.responsive_screenshots` in the file - `_static/mpl.css` has the height and cumulative width of the used PNG files - as attributes. This ensures that the magnification of those PNGs is <= 1. - """ - for fn_png, fn_py in FRONTPAGE_PNGS.items(): - pn_png = os.path.join(FRONTPAGE_PNG_PATH, fn_png) # get full paths - pn_py = os.path.join(FRONTPAGE_PY_PATH, fn_py) - - # Read file modification times: - mtime_py = os.path.getmtime(pn_py) - mtime_png = (os.path.getmtime(pn_png) if os.path.exists(pn_png) else - mtime_py - 1) # set older time, if file doesn't exist - - if only_if_needed and mtime_py <= mtime_png: - continue # do nothing if png is newer - - # Execute python as subprocess (preferred over os.system()): - subprocess.check_call( - [sys.executable, pn_py]) # raises CalledProcessError() - os.rename(fn_png, pn_png) # move file to _static/ directory - - DEPSY_PATH = "_static/depsy_badge.svg" DEPSY_URL = "http://depsy.org/api/package/pypi/matplotlib/badge.svg" DEPSY_DEFAULT = "_static/depsy_badge_default.svg" @@ -121,7 +82,6 @@ def fetch_depsy_badge(): def html(buildername='html'): """Build Sphinx 'html' target. """ check_build() - generate_frontpage_pngs() fetch_depsy_badge() rc = '../lib/matplotlib/mpl-data/matplotlibrc' @@ -213,10 +173,6 @@ def clean(): for filename in glob.glob(pattern): if os.path.exists(filename): os.remove(filename) - for fn in FRONTPAGE_PNGS.keys(): # remove generated PNGs - pn = os.path.join(FRONTPAGE_PNG_PATH, fn) - if os.path.exists(pn): - os.remove(os.path.join(pn)) def build_all(): diff --git a/doc/users/examples_index.rst b/doc/users/examples_index.rst deleted file mode 100644 index 7350c2a328f5..000000000000 --- a/doc/users/examples_index.rst +++ /dev/null @@ -1,7 +0,0 @@ -=================== - Selected Examples -=================== - -.. toctree:: - - screenshots.rst diff --git a/doc/users/index.rst b/doc/users/index.rst index ec79d23a953e..52f82bd88295 100644 --- a/doc/users/index.rst +++ b/doc/users/index.rst @@ -15,7 +15,6 @@ User's Guide intro.rst installing.rst interactive.rst - examples_index whats_new.rst github_stats.rst license.rst diff --git a/examples/lines_bars_and_markers/categorical_variables.py b/examples/lines_bars_and_markers/categorical_variables.py new file mode 100644 index 000000000000..fce733581f3c --- /dev/null +++ b/examples/lines_bars_and_markers/categorical_variables.py @@ -0,0 +1,37 @@ +""" +============================== +Plotting categorical variables +============================== + +How to use categorical variables in Matplotlib. + +Many times you want to create a plot that uses categorical variables +in Matplotlib. Matplotlib allows you to pass categorical variables directly to +many plotting functions, which we demonstrate below. +""" +import matplotlib.pyplot as plt + +data = {'apples': 10, 'oranges': 15, 'lemons': 5, 'limes': 20} +names = list(data.keys()) +values = list(data.values()) + +fig, axs = plt.subplots(1, 3, figsize=(9, 3), sharey=True) +axs[0].bar(names, values) +axs[1].scatter(names, values) +axs[2].plot(names, values) +fig.suptitle('Categorical Plotting') + + +############################################################################### +# This works on both axes: + +cat = ["bored", "happy", "bored", "bored", "happy", "bored"] +dog = ["happy", "happy", "happy", "happy", "bored", "bored"] +activity = ["combing", "drinking", "feeding", "napping", "playing", "washing"] + +fig, ax = plt.subplots() +ax.plot(activity, dog, label="dog") +ax.plot(activity, cat, label="cat") +ax.legend() + +plt.show() diff --git a/tutorials/01_introductory/pyplot.py b/tutorials/01_introductory/pyplot.py index 36642516dfbb..a41102cd5f45 100644 --- a/tutorials/01_introductory/pyplot.py +++ b/tutorials/01_introductory/pyplot.py @@ -118,6 +118,30 @@ plt.ylabel('entry b') plt.show() +############################################################################### +# .. _plotting-with-categorical-vars: +# +# Plotting with categorical variables +# =================================== +# +# It is also possible to create a plot using categorical variables. +# Matplotlib allows you to pass categorical variables directly to +# many plotting functions. For example: + +names = ['group_a', 'group_b', 'group_c'] +values = [1, 10, 100] + +plt.figure(1, figsize=(9, 3)) + +plt.subplot(131) +plt.bar(names, values) +plt.subplot(132) +plt.scatter(names, values) +plt.subplot(133) +plt.plot(names, values) +plt.suptitle('Categorical Plotting') +plt.show() + ############################################################################### # .. _controlling-line-properties: # diff --git a/doc/users/screenshots.rst b/tutorials/01_introductory/sample_plots.py similarity index 60% rename from doc/users/screenshots.rst rename to tutorials/01_introductory/sample_plots.py index 83f7f21e4f62..f7294cd332e3 100644 --- a/doc/users/screenshots.rst +++ b/tutorials/01_introductory/sample_plots.py @@ -1,19 +1,21 @@ -.. _matplotlibscreenshots: - -********************** -Screenshots -********************** +""" +========================== +Sample plots in Matplotlib +========================== Here you'll find a host of example plots with the code that generated them. -Simple Plot -=========== +.. _matplotlibscreenshots: + +Line Plot +========= -Here's a very basic :func:`~matplotlib.pyplot.plot` with text labels: +Here's how to create a line plot with text labels using +:func:`~matplotlib.pyplot.plot`. -.. figure:: ../gallery/pylab_examples/images/sphx_glr_simple_plot_001.png - :target: ../gallery/pylab_examples/simple_plot.html +.. figure:: ../../gallery/pylab_examples/images/sphx_glr_simple_plot_001.png + :target: ../../gallery/pylab_examples/simple_plot.html :align: center :scale: 50 @@ -27,8 +29,8 @@ Multiple axes (i.e. subplots) are created with the :func:`~matplotlib.pyplot.subplot` command: -.. figure:: ../gallery/subplots_axes_and_figures/images/sphx_glr_subplot_001.png - :target: ../gallery/subplots_axes_and_figures/subplot.html +.. figure:: ../../gallery/subplots_axes_and_figures/images/sphx_glr_subplot_001.png + :target: ../../gallery/subplots_axes_and_figures/subplot.html :align: center :scale: 50 @@ -42,8 +44,8 @@ The :func:`~matplotlib.pyplot.hist` command automatically generates histograms and returns the bin counts or probabilities: -.. figure:: ../gallery/statistics/images/sphx_glr_histogram_features_001.png - :target: ../gallery/statistics/histogram_features.html +.. figure:: ../../gallery/statistics/images/sphx_glr_histogram_features_001.png + :target: ../../gallery/statistics/histogram_features.html :align: center :scale: 50 @@ -55,11 +57,11 @@ Path demo ========= -You can add arbitrary paths in matplotlib using the +You can add arbitrary paths in Matplotlib using the :mod:`matplotlib.path` module: -.. figure:: ../gallery/shapes_and_collections/images/sphx_glr_path_patch_001.png - :target: ../gallery/shapes_and_collections/path_patch.html +.. figure:: ../../gallery/shapes_and_collections/images/sphx_glr_path_patch_001.png + :target: ../../gallery/shapes_and_collections/path_patch.html :align: center :scale: 50 @@ -74,15 +76,15 @@ :ref:`mplot3d-examples-index`) has support for simple 3d graphs including surface, wireframe, scatter, and bar charts. -.. figure:: ../gallery/mplot3d/images/sphx_glr_surface3d_001.png - :target: ../gallery/mplot3d/surface3d.html +.. figure:: ../../gallery/mplot3d/images/sphx_glr_surface3d_001.png + :target: ../../gallery/mplot3d/surface3d.html :align: center :scale: 50 Surface3d Thanks to John Porter, Jonathon Taylor, Reinier Heeres, and Ben Root for -the `mplot3d` toolkit. This toolkit is included with all standard matplotlib +the `mplot3d` toolkit. This toolkit is included with all standard Matplotlib installs. .. _screenshots_ellipse_demo: @@ -96,8 +98,8 @@ to map the colors and/or line widths of streamlines to a separate parameter, such as the speed or local intensity of the vector field. -.. figure:: ../gallery/images_contours_and_fields/images/sphx_glr_plot_streamplot_001.png - :target: ../gallery/images_contours_and_fields/plot_streamplot.html +.. figure:: ../../gallery/images_contours_and_fields/images/sphx_glr_plot_streamplot_001.png + :target: ../../gallery/images_contours_and_fields/plot_streamplot.html :align: center :scale: 50 @@ -113,13 +115,13 @@ In support of the `Phoenix `_ mission to -Mars (which used matplotlib to display ground tracking of spacecraft), +Mars (which used Matplotlib to display ground tracking of spacecraft), Michael Droettboom built on work by Charlie Moad to provide an extremely accurate 8-spline approximation to elliptical arcs (see :class:`~matplotlib.patches.Arc`), which are insensitive to zoom level. -.. figure:: ../gallery/pylab_examples/images/sphx_glr_ellipse_demo_001.png - :target: ../gallery/pylab_examples/ellipse_demo.html +.. figure:: ../../gallery/pylab_examples/images/sphx_glr_ellipse_demo_001.png + :target: ../../gallery/pylab_examples/ellipse_demo.html :align: center :scale: 50 @@ -130,20 +132,20 @@ Bar charts ========== -Bar charts are simple to create using the :func:`~matplotlib.pyplot.bar` -command, which includes customizations such as error bars: +Use the :func:`~matplotlib.pyplot.bar` command to make bar charts, which +includes customizations such as error bars: -.. figure:: ../gallery/pylab_examples/images/sphx_glr_barchart_demo_001.png - :target: ../gallery/pylab_examples/barchart_demo.html +.. figure:: ../../gallery/pylab_examples/images/sphx_glr_barchart_demo_001.png + :target: ../../gallery/pylab_examples/barchart_demo.html :align: center :scale: 50 Barchart Demo -It's also simple to create stacked bars -(`bar_stacked.py <../gallery/pylab_examples/bar_stacked.html>`_), +You can also create stacked bars +(`bar_stacked.py <../../gallery/pylab_examples/bar_stacked.html>`_), or horizontal bar charts -(`barh.py <../gallery/lines_bars_and_markers/barh.html>`_). +(`barh.py <../../gallery/lines_bars_and_markers/barh.html>`_). .. _screenshots_pie_demo: @@ -151,14 +153,14 @@ Pie charts ========== -The :func:`~matplotlib.pyplot.pie` command allows you to easily create pie +The :func:`~matplotlib.pyplot.pie` command 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 a few lines of code. -.. figure:: ../gallery/pie_and_polar_charts/images/sphx_glr_pie_features_001.png - :target: ../gallery/pie_and_polar_charts/pie_features.html +.. figure:: ../../gallery/pie_and_polar_charts/images/sphx_glr_pie_features_001.png + :target: ../../gallery/pie_and_polar_charts/pie_features.html :align: center :scale: 50 @@ -172,8 +174,8 @@ The :func:`~matplotlib.pyplot.table` command adds a text table to an axes. -.. figure:: ../gallery/pylab_examples/images/sphx_glr_table_demo_001.png - :target: ../gallery/pylab_examples/table_demo.html +.. figure:: ../../gallery/pylab_examples/images/sphx_glr_table_demo_001.png + :target: ../../gallery/pylab_examples/table_demo.html :align: center :scale: 50 @@ -192,8 +194,8 @@ trading volume and colors varying with time. Here, the alpha attribute is used to make semitransparent circle markers. -.. figure:: ../gallery/pylab_examples/images/sphx_glr_scatter_demo2_001.png - :target: ../gallery/pylab_examples/scatter_demo2.html +.. figure:: ../../gallery/pylab_examples/images/sphx_glr_scatter_demo2_001.png + :target: ../../gallery/pylab_examples/scatter_demo2.html :align: center :scale: 50 @@ -208,10 +210,10 @@ Matplotlib has basic GUI widgets that are independent of the graphical user interface you are using, allowing you to write cross GUI figures and widgets. See :mod:`matplotlib.widgets` and the -`widget examples <../gallery/index.html>`_. +`widget examples <../../gallery/index.html>`_. -.. figure:: ../gallery/widgets/images/sphx_glr_slider_demo_001.png - :target: ../gallery/widgets/slider_demo.html +.. figure:: ../../gallery/widgets/images/sphx_glr_slider_demo_001.png + :target: ../../gallery/widgets/slider_demo.html :align: center :scale: 50 @@ -226,8 +228,8 @@ The :func:`~matplotlib.pyplot.fill` command lets you plot filled curves and polygons: -.. figure:: ../gallery/lines_bars_and_markers/images/sphx_glr_fill_001.png - :target: ../gallery/lines_bars_and_markers/fill.html +.. figure:: ../../gallery/lines_bars_and_markers/images/sphx_glr_fill_001.png + :target: ../../gallery/lines_bars_and_markers/fill.html :align: center :scale: 50 @@ -240,11 +242,11 @@ Date demo ========= -You can plot date data with major and minor ticks and custom tick formatters -for both. +You can plot timeseries data with major and minor ticks and custom +tick formatters for both. -.. figure:: ../gallery/api/images/sphx_glr_date_001.png - :target: ../gallery/api/date.html +.. figure:: ../../gallery/api/images/sphx_glr_date_001.png + :target: ../../gallery/api/date.html :align: center :scale: 50 @@ -263,8 +265,8 @@ :func:`~matplotlib.pyplot.loglog` functions simplify the creation of logarithmic plots. -.. figure:: ../gallery/pylab_examples/images/sphx_glr_log_demo_001.png - :target: ../gallery/pylab_examples/log_demo.html +.. figure:: ../../gallery/pylab_examples/images/sphx_glr_log_demo_001.png + :target: ../../gallery/pylab_examples/log_demo.html :align: center :scale: 50 @@ -280,8 +282,8 @@ The :func:`~matplotlib.pyplot.polar` command generates polar plots. -.. figure:: ../gallery/pylab_examples/images/sphx_glr_polar_demo_001.png - :target: ../gallery/pylab_examples/polar_demo.html +.. figure:: ../../gallery/pylab_examples/images/sphx_glr_polar_demo_001.png + :target: ../../gallery/pylab_examples/polar_demo.html :align: center :scale: 50 @@ -297,8 +299,8 @@ generates figure legends, with MATLAB-compatible legend placement commands. -.. figure:: ../gallery/api/images/sphx_glr_legend_001.png - :target: ../gallery/api/legend.html +.. figure:: ../../gallery/api/images/sphx_glr_legend_001.png + :target: ../../gallery/api/legend.html :align: center :scale: 50 @@ -311,14 +313,14 @@ Mathtext_examples ================= -Below is a sampling of the many TeX expressions now supported by matplotlib's +Below is a sampling of the many TeX expressions now supported by Matplotlib's internal mathtext engine. The mathtext module provides TeX style mathematical expressions using `FreeType `_ and the DejaVu, BaKoMa computer modern, or `STIX `_ fonts. See the :mod:`matplotlib.mathtext` module for additional details. -.. figure:: ../gallery/pylab_examples/images/sphx_glr_mathtext_examples_001.png - :target: ../gallery/pylab_examples/mathtext_examples.html +.. figure:: ../../gallery/pylab_examples/images/sphx_glr_mathtext_examples_001.png + :target: ../../gallery/pylab_examples/mathtext_examples.html :align: center :scale: 50 @@ -334,12 +336,12 @@ Native TeX rendering ==================== -Although matplotlib's internal math rendering engine is quite +Although Matplotlib's internal math rendering engine is quite powerful, sometimes you need TeX. Matplotlib supports external TeX rendering of strings with the *usetex* option. -.. figure:: ../gallery/pyplots/images/sphx_glr_tex_demo_001.png - :target: ../gallery/pyplots/tex_demo.html +.. figure:: ../../gallery/pyplots/images/sphx_glr_tex_demo_001.png + :target: ../../gallery/pyplots/tex_demo.html :align: center :scale: 50 @@ -350,16 +352,16 @@ EEG demo ========= -You can embed matplotlib into pygtk, wx, Tk, or Qt applications. +You can embed Matplotlib into pygtk, wx, Tk, or Qt applications. Here is a screenshot of an EEG viewer called `pbrain `__. -.. image:: ../_static/eeg_small.png +.. image:: ../../_static/eeg_small.png The lower axes uses :func:`~matplotlib.pyplot.specgram` to plot the spectrogram of one of the EEG channels. -For examples of how to embed matplotlib in different toolkits, see: +For examples of how to embed Matplotlib in different toolkits, see: * :ref:`sphx_glr_gallery_user_interfaces_embedding_in_gtk2_sgskip.py` * :ref:`sphx_glr_gallery_user_interfaces_embedding_in_wx2_sgskip.py` @@ -370,33 +372,28 @@ XKCD-style sketch plots ======================= -matplotlib supports plotting in the style of `xkcd +Matplotlib supports plotting in the style of `xkcd `. -.. figure:: ../gallery/showcase/images/sphx_glr_xkcd_001.png - :target: ../gallery/showcase/xkcd.html +.. figure:: ../../gallery/showcase/images/sphx_glr_xkcd_001.png + :target: ../../gallery/showcase/xkcd.html :align: center :scale: 50 Xkcd +""" +# An extra set of sample plots for the thumbnail image. +import matplotlib.pyplot as plt +import numpy as np +np.random.seed(19680801) +data = np.random.randn(2, 100) +fig, axs = plt.subplots(2, 2, figsize=(5, 5)) +axs[0, 0].hist(data[0]) +axs[1, 0].scatter(data[0], data[1]) +axs[0, 1].plot(data[0], data[1]) +axs[1, 1].hist2d(data[0], data[1]) - - - - - - - - - - - - - - - - - +plt.show()