From ca678a49f37411b1b0e72d7d0dfa88c124b0e34b Mon Sep 17 00:00:00 2001 From: Michael Droettboom Date: Fri, 3 Aug 2012 15:06:25 -0400 Subject: [PATCH 01/12] Reinstate the manual reference counting as discovered in #1054. --- src/ft2font.cpp | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/src/ft2font.cpp b/src/ft2font.cpp index 7bfdadbe3db0..91dbb364fdd0 100644 --- a/src/ft2font.cpp +++ b/src/ft2font.cpp @@ -870,24 +870,28 @@ FT2Font::FT2Font(std::string facefile) : { std::ostringstream s; s << "Could not load facefile " << facefile << "; Unknown_File_Format" << std::endl; + ob_refcnt--; throw Py::RuntimeError(s.str()); } else if (error == FT_Err_Cannot_Open_Resource) { std::ostringstream s; s << "Could not open facefile " << facefile << "; Cannot_Open_Resource" << std::endl; + ob_refcnt--; throw Py::RuntimeError(s.str()); } else if (error == FT_Err_Invalid_File_Format) { std::ostringstream s; s << "Could not open facefile " << facefile << "; Invalid_File_Format" << std::endl; + ob_refcnt--; throw Py::RuntimeError(s.str()); } else if (error) { std::ostringstream s; s << "Could not open facefile " << facefile << "; freetype error code " << error << std::endl; + ob_refcnt--; throw Py::RuntimeError(s.str()); } @@ -904,6 +908,7 @@ FT2Font::FT2Font(std::string facefile) : { std::ostringstream s; s << "Could not set the fontsize for facefile " << facefile << std::endl; + ob_refcnt--; throw Py::RuntimeError(s.str()); } From 64e64f68caf56d04d99180024fce201d374ce429 Mon Sep 17 00:00:00 2001 From: Michael Droettboom Date: Fri, 3 Aug 2012 15:09:18 -0400 Subject: [PATCH 02/12] Fix gallery links (#1024) --- doc/sphinxext/gen_gallery.py | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/doc/sphinxext/gen_gallery.py b/doc/sphinxext/gen_gallery.py index aadc2c0e9b8c..45e2d47370d7 100644 --- a/doc/sphinxext/gen_gallery.py +++ b/doc/sphinxext/gen_gallery.py @@ -16,7 +16,7 @@ import os, glob, re, sys, warnings import matplotlib.image as image -multiimage = re.compile('(.*)_\d\d') +multiimage = re.compile('(.*?)(_\d\d){1,2}') def make_thumbnail(args): image.thumbnail(args[0], args[1], 0.3) @@ -68,11 +68,8 @@ def gen_gallery(app, doctree): thumbnails[orig_path] = thumb_path m = multiimage.match(basename) - if m is None: - pyfile = '%s.py'%basename - else: + if m is not None: basename = m.group(1) - pyfile = '%s.py'%basename data.append((subdir, basename, os.path.join(rootdir, subdir, 'thumbnails', filename))) From c9c108ebe87063edc33e5db012b97c25f69aaeaa Mon Sep 17 00:00:00 2001 From: Michael Droettboom Date: Thu, 9 Aug 2012 13:09:15 -0400 Subject: [PATCH 03/12] Fix pythonxy link --- INSTALL | 21 ++++++++++----------- 1 file changed, 10 insertions(+), 11 deletions(-) diff --git a/INSTALL b/INSTALL index 7337009b9a85..1749a4a085b0 100644 --- a/INSTALL +++ b/INSTALL @@ -6,21 +6,21 @@ Installing ********** -There are many different ways to install matplotlib, and the best -way depends on what operating system you are using, what you already -have installed, and how you want to use it. To avoid wading through -all the details (and potential complications) on this page, the -easiest thing for you to do is use one of the pre-packaged python +There are many different ways to install matplotlib, and the best way +depends on what operating system you are using, what you already have +installed, and how you want to use it. To avoid wading through all +the details (and potential complications) on this page, the easiest +thing for you to do is use one of the pre-packaged python distributions that already provide matplotlib built-in. The Enthought Python Distribution `(EPD) `_ for Windows, OS X or Redhat is an excellent choice that "just works" out of the box. Another excellent alternative for Windows users is `Python (x, y) -`_ which tends to be updated a -bit more frequently. Both of these packages include matplotlib and -pylab, and *lots* of other useful tools. matplotlib is also packaged -for almost every major Linux distribution. So if you are on Linux, -your package manager will probably provide matplotlib prebuilt. +`_ which tends to be updated a bit more +frequently. Both of these packages include matplotlib and pylab, and +*lots* of other useful tools. matplotlib is also packaged for almost +every major Linux distribution. So if you are on Linux, your package +manager will probably provide matplotlib prebuilt. Manually installing pre-built packages @@ -254,4 +254,3 @@ can get the libpng and freetype requirements (darwinports, fink, the different OSX version (e.g., 10.4 and 10.5). We recommend that you build the way we do for the OSX release: get the source from the tarball or the git repository and follow the instruction in :file:`README.osx`. - From 9745bdd279e275010fc4be65eff62b1b02284902 Mon Sep 17 00:00:00 2001 From: Michael Droettboom Date: Fri, 10 Aug 2012 12:04:51 -0400 Subject: [PATCH 04/12] Update index.html page. This allows for multiple versions of the matplotlib documentation to be made available. The scheme is that the root documentation (i.e. http://matplotlib.sf.net/) will always be the latest stable version. Other versions of the documentation will be available in subdirectories off of the root (the latest stable version is merely a symlink or redirect back to the root). This is the same convention used by "docs.python.org", as an aside. The index.html page uses some JavaScript to load a little snippet of HTML from "/versions.html" that lists the available versions. "versions.html" is not part of this repository, but is part of the matplotlib.github.com repository and is updated by hand whenever new versions are added or removed from the archive. This approach allows all versions of the documentation to point to all other versions of the documentation. This JavaScript XMLHttpRequest magic doesn't happen when the user is viewing static files on their local machine, and this is a happy coincidence. The perhaps controversial outcome of this change is that the summary list of plotting commands is removed from the front page. For one, we want to steer people toward the version of the documentation that corresponds to the version they are running. Also, this was a manually created list, and has become quite out of date over time. Better, IMHO, to link to the pyplot documentation. This freed up room to move much of the content that existed in the sidebar to the main body, where I feel it's much less buried. I plan to add a lot more external resources and links, so having the room to do this would be very helpful. Adds a "Fork me on Github" banner. --- doc/_templates/index.html | 1351 +++--------------------------- doc/_templates/indexsidebar.html | 82 -- 2 files changed, 101 insertions(+), 1332 deletions(-) diff --git a/doc/_templates/index.html b/doc/_templates/index.html index fdf1d417607d..4bfa7dc522f9 100644 --- a/doc/_templates/index.html +++ b/doc/_templates/index.html @@ -3,7 +3,42 @@ {% block body %} -

intro

+ + + + Fork me on GitHub + +

Introduction

matplotlib is a python 2D plotting library which produces publication quality figures in a variety of hardcopy formats and @@ -17,21 +52,15 @@

intro

web application servers, and six graphical user interface toolkits.

- - - - +

screenshots

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 sampling, see the screenshots, thumbnail gallery, and -examples directory

- -

screenshots

- + examples directory

For example, using "ipython -pylab" to provide an interactive environment, to generate 10,000 gaussian random numbers and plot a @@ -44,1266 +73,88 @@

intro

For the power user, you have full control of line styles, font properties, axes properties, etc, via an object oriented interface - or via a set of functions familiar to MATLAB users. - The pylab mode provides all of the pyplot plotting - functions listed below, as well as non-plotting functions from - numpy and - matplotlib.mlab.

- -

plotting commands


- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +

Download

- + Matplotlib 1.1.1 is available for +download. - - - + This is the documentation for matplotlib version {{ version }}. - +

+ - - - +

Other learning resources

- + - - +
  • Eric Jones gave + an introductory + tutorial on Numpy and matplotlib at SciPy 2012.
    • + - +

    Need help?

    - - - +

    You can file bugs, patches and feature requests on the +github +tracker, +but it is a good idea to ping us on the mailing list too.

    - +

    For details on what's new, see the detailed changelog or browse the source code. Anything that could +require changes to your existing codes is logged in the api changes file.

    - - - +

    There are several matplotlib add-on toolkits, including the projection +and mapping toolkit +basemap, 3d plotting with mplot3d, axes and axis helpers in axes_grid and more. +

    - +

    Open source

    - - - +

    The matplotlib license +is based on the Python Software Foundation +(PSF) license.

    - +

    There is an active developer community and a long list of people +who have made significant contributions.

    - -
    FunctionDescription
    - acorr - - - plot the autocorrelation function -
    - annotate - - - annotate something in the figure -
    - arrow - - - add an arrow to the axes -
    - axes - - - create a new axes -
    - axhline - - - draw a horizontal line across axes -
    - axvline - - - draw a vertical line across axes -
    - axhspan - - - draw a horizontal bar across axes -
    - axvspan - - - draw a vertical bar across axes -
    - axis - - - set or return the current axis limits -
    - barbs - - - a (wind) barb plot -
    - bar - - - make a bar chart -
    - barh - - - a horizontal bar chart -
    - broken_barh - - - a set of horizontal bars with gaps -
    - box - - - set the axes frame on/off state -
    - boxplot - - - make a box and whisker plot -
    - cla - - - clear current axes -
    - clabel - - - label a contour plot -
    - clf - - - clear a figure window -
    - clim - - - adjust the color limits of the current image -
    - close - - - close a figure window -
    - colorbar - - - add a colorbar to the current figure -
    - cohere - - - make a plot of coherence -
    - contour - - - make a contour plot -
    - contourf - - - make a filled contour plot -
    - csd - - - make a plot of cross spectral density -
    - delaxes - - - delete an axes from the current figure -
    - draw - - - Force a redraw of the current figure -
    - errorbar - - - make an errorbar graph -
    - figlegend - - - make legend on the figure rather than the axes -
    - figimage - - - make a figure image -
    - figtext - - - add text in figure coords -
    - figure - - - create or change active figure -
    - fill - - - make filled polygons -
    - fill_between - - - make filled polygons between two curves -
    - findobj - - - recursively find all objects matching some criteria -
    - gca - - - return the current axes -
    - gcf - - - return the current figure -
    - gci - - - get the current image, or None -
    - getp - - - get a graphics property -
    - grid - - - set whether gridding is on -
    - hexbin - - - make a 2D hexagonal binning plot -
    - hist - - - make a histogram -
    - hold - - - set the axes hold state -
    - ioff - - - turn interaction mode off -
    - ion - - - turn interaction mode on -
    - isinteractive - - - return True if interaction mode is on -
    - imread - - - load image file into array -
    - imsave - - - save array as an image file -
    - imshow - - - plot image data -
    - ishold - - - return the hold state of the current axes -
    - legend - - - make an axes legend -
    - locator_params - - - adjust parameters used in locating axis ticks -
    - loglog - - - a log log plot -
    - matshow - - - display a matrix in a new figure preserving aspect -
    - margins - - - set margins used in autoscaling -
    - pcolor - - - make a pseudocolor plot -
    - pcolormesh - - - make a pseudocolor plot using a quadrilateral mesh -
    - pie - - - make a pie chart -
    - plot - - - make a line plot -
    - plot_date - - - plot dates -
    - plotfile - - - plot column data from an ASCII tab/space/comma delimited file -
    - pie - - - pie charts -
    - polar - - - make a polar plot on a PolarAxes -
    - psd - - - make a plot of power spectral density -
    - quiver - - - make a direction field (arrows) plot -
    - rc - - - control the default params -
    - rgrids - - - customize the radial grids and labels for polar -
    - savefig - - - save the current figure -
    - scatter - - - make a scatter plot -
    - setp - - - set a graphics property -
    - semilogx - - - log x axis -
    - semilogy - - - log y axis -
    - show - - - show the figures -
    - specgram - - - a spectrogram plot -
    - spy - - - plot sparsity pattern using markers or image -
    - stem - - - make a stem plot -
    - subplot - - - make a subplot (numrows, numcols, axesnum) -
    - subplots - - - Create a figure with subplots -
    - subplots_adjust - - - change the params controlling the subplot positions of current figure -
    - subplot_tool - - - launch the subplot configuration tool -
    - suptitle - - - add a figure title -
    - table - - - add a table to the plot -
    - text - - - add some text at location x,y to the current axes -
    - thetagrids - - - customize the radial theta grids and labels for polar -
    - tick_params - - - control the appearance of ticks and tick labels -
    - ticklabel_format - - - control the format of tick labels -
    - title - - - add a title to the current axes -
    - tricontour - - - make a contour plot on a triangular grid -
    - tricontourf - - - make a filled contour plot on a triangular grid -
    - tripcolor - - - make a pseudocolor plot on a triangular grid -
    - triplot - - - plot a triangular grid -
    - xcorr - - - plot the autocorrelation function of x and y -
    - xlim - - - set/get the xlimits -
    - ylim - - - set/get the ylimits -
    - xticks - - - set/get the xticks -
    - yticks - - - set/get the yticks -
    - xlabel - - - add an xlabel to the current axes -
    - ylabel - - - add a ylabel to the current axes -
    - autumn - - - set the default colormap to autumn -
    - bone - - - set the default colormap to bone -
    - cool - - - set the default colormap to cool -
    - copper - - - set the default colormap to copper -
    - flag - - - set the default colormap to flag -
    - gray - - - set the default colormap to gray -
    - hot - - - set the default colormap to hot -
    - hsv - - - set the default colormap to hsv -
    - jet + or via a set of functions familiar to MATLAB users.

    -     		- set the default colormap to jet -
    - pink +

    Documentation

    -     		- set the default colormap to pink -
    - prism +

    Trying to learn how to do a particular kind of plot? Check out + the gallery, examples, + or the list of plotting + commands.

    -     		- set the default colormap to prism -
    - spring +
  • Nicolas Rougier has + a beginner + tutorial.
    • -     		- set the default colormap to spring -
    - summer +

    Check the faq, +the api docs, +mailing +list archives, and join the matplotlib +mailing lists. +The search tool searches all of +the documentation, including full text search of over 350 complete +examples which exercise almost every corner of matplotlib.

    -     		- set the default colormap to summer -
    - winter +

    Toolkits

    -     		- set the default colormap to winter -
    - spectral +

    Please donate +to support matplotlib development.

    -     		- set the default colormap to spectral -

    * diff --git a/doc/_templates/indexsidebar.html b/doc/_templates/indexsidebar.html index 6ef509120ff1..e69de29bb2d1 100644 --- a/doc/_templates/indexsidebar.html +++ b/doc/_templates/indexsidebar.html @@ -1,82 +0,0 @@ -

    News

    - - -

    Please donate -to support matplotlib development.

    - - -

    Matplotlib 1.1.1 is available for -download. -See what's new -and tips on installing. -

    - -

    Sandro Tosi has a new book - Matplotlib for python - developers - also - at amazon.

    - -

    Build websites like matplotlib's, -with Sphinx and extensions for -mpl plots, math, inheritance diagrams -- try -the sampledoc -tutorial. -

    - -

    Videos

    - -

    Watch the SciPy 2009 intro and advanced matplotlib tutorials -

    - -

    Watch -a talk about -matplotlib presented -at NIPS 08 -Workshop MLOSS and one presented -at ChiPy. -

    - - -

    Toolkits

    - -

    There are several matplotlib add-on toolkits, including the projection -and mapping toolkit -basemap, 3d plotting with mplot3d, axes and axis helpers in axes_grid and more. -

    - -

    Need help?

    - -

    Check the user guide, -the faq, the api docs, -archives, -and join the matplotlib -mailing lists. -The search tool searches all of -the documentation, including full text search of over 350 complete -examples which exercise almost every corner of matplotlib.

    - -

    You can file bugs, patches and feature requests on the -github -tracker, -but it is a good idea to ping us on the mailing list too.

    - -

    For details on what's new, see the detailed changelog or browse the source code. Anything that could -require changes to your existing codes is logged in the api changes file.

    - -

    Other stuff

    - -

    The matplotlib license -is based on the Python Software Foundation -(PSF) license.

    - -

    There is an active developer community and a long list of people -who have made significant contributions.

    - From 3a1c832790571288864a979ae13163d4688ef3d7 Mon Sep 17 00:00:00 2001 From: Michael Droettboom Date: Fri, 10 Aug 2012 15:24:18 -0400 Subject: [PATCH 05/12] Gentler donation language. --- doc/_templates/index.html | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/doc/_templates/index.html b/doc/_templates/index.html index 4bfa7dc522f9..348e658e2072 100644 --- a/doc/_templates/index.html +++ b/doc/_templates/index.html @@ -144,7 +144,8 @@

    Toolkits

    Open source

    -

    Please donate +

    Please +consider donating to support matplotlib development.

    The matplotlib license From b60f3ee33e382ec3d61df957a0de50ee7c471158 Mon Sep 17 00:00:00 2001 From: Michael Droettboom Date: Thu, 16 Aug 2012 15:09:25 -0400 Subject: [PATCH 06/12] Update credits page --- doc/users/credits.rst | 46 ++++++++++++++++++++++++++++++++++--------- 1 file changed, 37 insertions(+), 9 deletions(-) diff --git a/doc/users/credits.rst b/doc/users/credits.rst index d1a6200c19b8..3f8bdddf5c03 100644 --- a/doc/users/credits.rst +++ b/doc/users/credits.rst @@ -6,19 +6,22 @@ Credits matplotlib was written by John Hunter and is now developed and -maintained by a number of -`active `_ -developers. +maintained by a number of `active +`_ developers. +The current lead developer of matplotlib is Michael Droettboom. -Special thanks to those who have made valuable contributions -(roughly in order of first contribution by date) +Special thanks to those who have made valuable contributions (roughly +in order of first contribution by date). Any list like this is bound +to be incomplete and can't capture the thousands and thousands of +contributions over the years from these and others: Jeremy O'Donoghue wrote the wx backend -Andrew Straw provided much of the log scaling architecture, the fill - command, PIL support for imshow, and provided many examples. He - also wrote the support for dropped axis spines and the `buildbot +Andrew Straw + Provided much of the log scaling architecture, the fill command, PIL + support for imshow, and provided many examples. He also wrote the + support for dropped axis spines and the `buildbot `_ unit testing infrastructure which triggers the JPL/James Evans platform specific builds and regression test image comparisons from svn matplotlib across @@ -177,7 +180,32 @@ John Porter, Jonathon Taylor and Reinier Heeres matplotlib, and Jonathon Taylor and Reinier Heeres ported it to the refactored transform trunk. -Jae-Joon Lee implemented fancy arrows and boxes, rewrote the legend +Jae-Joon Lee + Implemented fancy arrows and boxes, rewrote the legend support to handle multiple columns and fancy text boxes, wrote the axes grid toolkit, and has made numerous contributions to the code and documentation + +Paul Ivanov + Has worked on getting matplotlib integrated better with other tools, + such as Sage and IPython, and getting the test infrastructure + faster, lighter and meaner. Listen to his podcast. + +Tony Yu + Has been involved in matplotlib since the early days, and recently + has contributed stream plotting among many other improvements. He + is the author of mpltools. + +Benjamin Root + Has significantly improved the capabilities of the 3D plotting. He + has improved matplotlib's documentation and code quality throughout, + and does invaluable triaging of pull requests and bugs. + +Phil Elson + Fixed some deep-seated bugs in the transforms framework, and has + been laser-focused on improving polish throughout matplotlib, + tackling things that have been considered to large and daunting for + a long time. + +Damon McDougall + Added triangulated 3D surfaces and stack plots to matplotlib. From 87f8df3bc020b91eb86b6c456a82c47ddac3b070 Mon Sep 17 00:00:00 2001 From: Michael Droettboom Date: Thu, 16 Aug 2012 15:12:04 -0400 Subject: [PATCH 07/12] Add an autogenerated plotting command summary. --- boilerplate.py | 11 +- doc/_templates/index.html | 4 +- doc/api/index.rst | 1 + doc/api/pyplot_api.rst | 3 +- doc/api/pyplot_summary.rst | 8 + doc/conf.py | 2 + lib/matplotlib/__init__.py | 2 +- lib/matplotlib/artist.py | 4 + lib/matplotlib/axes.py | 159 +++++++++---- lib/matplotlib/contour.py | 6 +- lib/matplotlib/figure.py | 8 +- lib/matplotlib/image.py | 8 +- lib/matplotlib/pyplot.py | 386 +++++++++++++++++++------------ lib/matplotlib/tri/tricontour.py | 4 +- lib/matplotlib/tri/tripcolor.py | 3 +- lib/matplotlib/tri/triplot.py | 3 +- 16 files changed, 404 insertions(+), 208 deletions(-) create mode 100644 doc/api/pyplot_summary.rst diff --git a/boilerplate.py b/boilerplate.py index 390d6424de55..9fb52cd622b5 100644 --- a/boilerplate.py +++ b/boilerplate.py @@ -20,7 +20,7 @@ _fmtplot = """\ # This function was autogenerated by boilerplate.py. Do not edit as # changes will be lost -@autogen_docstring(Axes.%(func)s) +@_autogen_docstring(Axes.%(func)s) def %(func)s(%(argspec)s): %(ax)s = gca() # allow callers to override the hold state by passing hold=True|False @@ -246,3 +246,12 @@ def %(name)s(): for name in cmaps: print _fmtcmap%locals() +print "# This function was autogenerated by boilerplate.py" +print "def _colormaps():" +print " return [" +for name in cmaps: + print " %r," % name +print " ]" + +print +print "_setup_pyplot_info_docstrings()" diff --git a/doc/_templates/index.html b/doc/_templates/index.html index 348e658e2072..4edb3d532c4f 100644 --- a/doc/_templates/index.html +++ b/doc/_templates/index.html @@ -62,7 +62,7 @@

    Introduction

    For a sampling, see the screenshots, thumbnail gallery, and examples directory

    -

    For example, using "ipython -pylab" to provide an interactive +

    For example, using "ipython --pylab" to provide an interactive environment, to generate 10,000 gaussian random numbers and plot a histogram with 100 bins, you simply need to type

    @@ -91,7 +91,7 @@

    Documentation

    Trying to learn how to do a particular kind of plot? Check out the gallery, examples, - or the list of plotting + or the list of plotting commands.

    Other learning resources

    diff --git a/doc/api/index.rst b/doc/api/index.rst index 194e481eddcb..f6c05695b3dd 100644 --- a/doc/api/index.rst +++ b/doc/api/index.rst @@ -12,6 +12,7 @@ .. toctree:: :maxdepth: 1 + pyplot_summary.rst api_changes.rst matplotlib_configuration_api.rst afm_api.rst diff --git a/doc/api/pyplot_api.rst b/doc/api/pyplot_api.rst index fe090eac87af..e1675de4fb22 100644 --- a/doc/api/pyplot_api.rst +++ b/doc/api/pyplot_api.rst @@ -1,7 +1,7 @@ ****** pyplot ****** - + :mod:`matplotlib.pyplot` ======================== @@ -10,3 +10,4 @@ pyplot :members: :undoc-members: :show-inheritance: + :exclude-members: plotting colormaps diff --git a/doc/api/pyplot_summary.rst b/doc/api/pyplot_summary.rst new file mode 100644 index 000000000000..7236fa864ccc --- /dev/null +++ b/doc/api/pyplot_summary.rst @@ -0,0 +1,8 @@ +Plotting commands summary +========================= + +.. currentmodule:: matplotlib.pyplot + +.. autofunction:: plotting + +.. autofunction:: colormaps diff --git a/doc/conf.py b/doc/conf.py index 4e5e3557ce5f..8f87cb4ae05b 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -74,6 +74,8 @@ # The name of the Pygments (syntax highlighting) style to use. pygments_style = 'sphinx' +default_role = 'obj' + # Plot directive configuration # ---------------------------- diff --git a/lib/matplotlib/__init__.py b/lib/matplotlib/__init__.py index a27152cd0ca9..e2dc196a2e55 100644 --- a/lib/matplotlib/__init__.py +++ b/lib/matplotlib/__init__.py @@ -871,7 +871,7 @@ def rc(group, **kwargs): def rcdefaults(): """ - Restore the default rc params - these are not the params loaded by + Restore the default rc params. These are not the params loaded by the rc file, but mpl's internal params. See rc_file_defaults for reloading the default params from the rc file """ diff --git a/lib/matplotlib/artist.py b/lib/matplotlib/artist.py index 9f026e93ebc9..b9e00e84de1b 100644 --- a/lib/matplotlib/artist.py +++ b/lib/matplotlib/artist.py @@ -730,6 +730,8 @@ def set(self, **kwargs): def findobj(self, match=None, include_self=True): """ + Find artist objects. + pyplot signature: findobj(o=gcf(), match=None, include_self=True) @@ -1135,6 +1137,8 @@ def getp(obj, property=None): def setp(obj, *args, **kwargs): """ + Set a property on an artist object. + matplotlib supports the use of :func:`setp` ("set property") and :func:`getp` to set and get object properties, as well as to do introspection on the object. For example, to set the linestyle of a diff --git a/lib/matplotlib/axes.py b/lib/matplotlib/axes.py index 340bb341bb13..1c3349eb8768 100644 --- a/lib/matplotlib/axes.py +++ b/lib/matplotlib/axes.py @@ -834,7 +834,7 @@ def _gen_axes_spines(self, locations=None, offset=0.0, units='inches'): } def cla(self): - """Clear the current axes""" + """Clear the current axes.""" # Note: this is called by Axes.__init__() self.xaxis.cla() self.yaxis.cla() @@ -1710,7 +1710,7 @@ def set_ymargin(self, m): def margins(self, *args, **kw): """ - Convenience method to set or retrieve autoscaling margins. + Set or retrieve autoscaling margins. signatures:: @@ -1780,6 +1780,8 @@ def get_rasterization_zorder(self): def autoscale(self, enable=True, axis='both', tight=None): """ + Autoscale the axis view to the data (toggle). + Convenience method for simple axis view autoscaling. It turns autoscaling on or off, and then, if autoscaling for either axis is on, it performs @@ -2064,6 +2066,8 @@ def set_axisbelow(self, b): @docstring.dedent_interpd def grid(self, b=None, which='major', axis='both', **kwargs): """ + Turn the axes grids on or off. + Call signature:: grid(self, b=None, which='major', axis='both', **kwargs) @@ -2101,8 +2105,8 @@ def grid(self, b=None, which='major', axis='both', **kwargs): def ticklabel_format(self, **kwargs): """ - Convenience method for manipulating the ScalarFormatter - used by default for linear axes. + Change the `~matplotlib.ticker.ScalarFormatter` used by + default for linear axes. Optional keyword arguments: @@ -2189,7 +2193,7 @@ def ticklabel_format(self, **kwargs): def locator_params(self, axis='both', tight=None, **kwargs): """ - Convenience method for controlling tick locators. + Control behavior of tick locators. Keyword arguments: @@ -2228,8 +2232,7 @@ def locator_params(self, axis='both', tight=None, **kwargs): def tick_params(self, axis='both', **kwargs): """ - Convenience method for changing the appearance of ticks and - tick labels. + Change the appearance of ticks and tick labels. Keyword arguments: @@ -3254,6 +3257,8 @@ def set_ylabel(self, ylabel, fontdict=None, labelpad=None, **kwargs): def text(self, x, y, s, fontdict=None, withdash=False, **kwargs): """ + Add text to the axes. + Call signature:: text(x, y, s, fontdict=None, **kwargs) @@ -3334,6 +3339,9 @@ def text(self, x, y, s, fontdict=None, @docstring.dedent_interpd def annotate(self, *args, **kwargs): """ + Create an annotation: a piece of text referring to a data + point. + Call signature:: annotate(s, xy, xytext=None, xycoords='data', @@ -3358,12 +3366,12 @@ def annotate(self, *args, **kwargs): @docstring.dedent_interpd def axhline(self, y=0, xmin=0, xmax=1, **kwargs): """ + Add a horizontal line across the axis. + Call signature:: axhline(y=0, xmin=0, xmax=1, **kwargs) - Axis Horizontal Line - Draw a horizontal line at *y* from *xmin* to *xmax*. With the default values of *xmin* = 0 and *xmax* = 1, this line will always span the horizontal extent of the axes, regardless of @@ -3423,12 +3431,12 @@ def axhline(self, y=0, xmin=0, xmax=1, **kwargs): @docstring.dedent_interpd def axvline(self, x=0, ymin=0, ymax=1, **kwargs): """ + Add a vertical line across the axes. + Call signature:: axvline(x=0, ymin=0, ymax=1, **kwargs) - Axis Vertical Line - Draw a vertical line at *x* from *ymin* to *ymax*. With the default values of *ymin* = 0 and *ymax* = 1, this line will always span the vertical extent of the axes, regardless of the @@ -3488,12 +3496,12 @@ def axvline(self, x=0, ymin=0, ymax=1, **kwargs): @docstring.dedent_interpd def axhspan(self, ymin, ymax, xmin=0, xmax=1, **kwargs): """ + Add a horizontal span (rectangle) across the axis. + Call signature:: axhspan(ymin, ymax, xmin=0, xmax=1, **kwargs) - Axis Horizontal Span. - *y* coords are in data units and *x* coords are in axes (relative 0-1) units. @@ -3545,12 +3553,12 @@ def axhspan(self, ymin, ymax, xmin=0, xmax=1, **kwargs): @docstring.dedent_interpd def axvspan(self, xmin, xmax, ymin=0, ymax=1, **kwargs): """ + Add a vertical span (rectangle) across the axes. + Call signature:: axvspan(xmin, xmax, ymin=0, ymax=1, **kwargs) - Axis Vertical Span. - *x* coords are in data units and *y* coords are in axes (relative 0-1) units. @@ -3604,6 +3612,8 @@ def axvspan(self, xmin, xmax, ymin=0, ymax=1, **kwargs): def hlines(self, y, xmin, xmax, colors='k', linestyles='solid', label='', **kwargs): """ + Plot horizontal lines. + call signature:: hlines(y, xmin, xmax, colors='k', linestyles='solid', **kwargs) @@ -3690,6 +3700,8 @@ def hlines(self, y, xmin, xmax, colors='k', linestyles='solid', def vlines(self, x, ymin, ymax, colors='k', linestyles='solid', label='', **kwargs): """ + Plot vertical lines. + Call signature:: vlines(x, ymin, ymax, color='k', linestyles='solid') @@ -3902,6 +3914,8 @@ def plot(self, *args, **kwargs): def plot_date(self, x, y, fmt='bo', tz=None, xdate=True, ydate=False, **kwargs): """ + Plot with data with dates. + Call signature:: plot_date(x, y, fmt='bo', tz=None, xdate=True, ydate=False, **kwargs) @@ -3971,12 +3985,12 @@ def plot_date(self, x, y, fmt='bo', tz=None, xdate=True, ydate=False, @docstring.dedent_interpd def loglog(self, *args, **kwargs): """ + Make a plot with log scaling on both the *x* and *y* axis. + Call signature:: loglog(*args, **kwargs) - Make a plot with log scaling on the *x* and *y* axis. - :func:`~matplotlib.pyplot.loglog` supports all the keyword arguments of :func:`~matplotlib.pyplot.plot` and :meth:`matplotlib.axes.Axes.set_xscale` / @@ -4031,12 +4045,12 @@ def loglog(self, *args, **kwargs): @docstring.dedent_interpd def semilogx(self, *args, **kwargs): """ + Make a plot with log scaling on the *x* axis. + Call signature:: semilogx(*args, **kwargs) - Make a plot with log scaling on the *x* axis. - :func:`semilogx` supports all the keyword arguments of :func:`~matplotlib.pyplot.plot` and :meth:`matplotlib.axes.Axes.set_xscale`. @@ -4082,12 +4096,12 @@ def semilogx(self, *args, **kwargs): @docstring.dedent_interpd def semilogy(self, *args, **kwargs): """ + Make a plot with log scaling on the *y* axis. + call signature:: semilogy(*args, **kwargs) - Make a plot with log scaling on the *y* axis. - :func:`semilogy` supports all the keyword arguments of :func:`~matplotlib.pylab.plot` and :meth:`matplotlib.axes.Axes.set_yscale`. @@ -4133,14 +4147,16 @@ def semilogy(self, *args, **kwargs): @docstring.dedent_interpd def acorr(self, x, **kwargs): """ + Plot the autocorrelation of *x*. + Call signature:: acorr(x, normed=True, detrend=mlab.detrend_none, usevlines=True, maxlags=10, **kwargs) - Plot the autocorrelation of *x*. If *normed* = *True*, - normalize the data by the autocorrelation at 0-th lag. *x* is - detrended by the *detrend* callable (default no normalization). + If *normed* = *True*, normalize the data by the autocorrelation at + 0-th lag. *x* is detrended by the *detrend* callable (default no + normalization). Data are plotted as ``plot(lags, c, **kwargs)`` @@ -4195,15 +4211,17 @@ def acorr(self, x, **kwargs): def xcorr(self, x, y, normed=True, detrend=mlab.detrend_none, usevlines=True, maxlags=10, **kwargs): """ + Plot the cross correlation between *x* and *y*. + Call signature:: xcorr(self, x, y, normed=True, detrend=mlab.detrend_none, usevlines=True, maxlags=10, **kwargs) - Plot the cross correlation between *x* and *y*. If *normed* = - *True*, normalize the data by the cross correlation at 0-th - lag. *x* and y are detrended by the *detrend* callable - (default no normalization). *x* and *y* must be equal length. + If *normed* = *True*, normalize the data by the cross + correlation at 0-th lag. *x* and y are detrended by the + *detrend* callable (default no normalization). *x* and *y* + must be equal length. Data are plotted as ``plot(lags, c, **kwargs)`` @@ -4325,13 +4343,15 @@ def get_legend_handles_labels(self, legend_handler_map=None): def legend(self, *args, **kwargs): """ + Place a legend on the current axes. + Call signature:: legend(*args, **kwargs) - Place a legend on the current axes at location *loc*. Labels are a - sequence of strings and *loc* can be a string or an integer specifying - the legend location. + Places legend at location *loc*. Labels are a sequence of + strings and *loc* can be a string or an integer specifying the + legend location. To make a legend with existing lines:: @@ -4523,12 +4543,14 @@ def legend(self, *args, **kwargs): def step(self, x, y, *args, **kwargs): """ + Make a step plot. + Call signature:: step(x, y, *args, **kwargs) - Make a step plot. Additional keyword args to :func:`step` are the same - as those for :func:`~matplotlib.pyplot.plot`. + Additional keyword args to :func:`step` are the same as those + for :func:`~matplotlib.pyplot.plot`. *x* and *y* must be 1-D sequences, and it is assumed, but not checked, that *x* is uniformly increasing. @@ -4556,6 +4578,8 @@ def step(self, x, y, *args, **kwargs): @docstring.dedent_interpd def bar(self, left, height, width=0.8, bottom=None, **kwargs): """ + Make a bar plot. + Call signature:: bar(left, height, width=0.8, bottom=0, **kwargs) @@ -4834,6 +4858,8 @@ def make_iterable(x): @docstring.dedent_interpd def barh(self, bottom, width, height=0.8, left=None, **kwargs): """ + Make a horizontal bar plot. + Call signature:: barh(bottom, width, height=0.8, left=0, **kwargs) @@ -4905,6 +4931,8 @@ def barh(self, bottom, width, height=0.8, left=None, **kwargs): @docstring.dedent_interpd def broken_barh(self, xranges, yrange, **kwargs): """ + Plot horizontal bars. + Call signature:: broken_barh(self, xranges, yrange, **kwargs) @@ -4948,6 +4976,8 @@ def broken_barh(self, xranges, yrange, **kwargs): def stem(self, x, y, linefmt='b-', markerfmt='bo', basefmt='r-', bottom=None, label=None): """ + Create a stem plot. + Call signature:: stem(x, y, linefmt='b-', markerfmt='bo', basefmt='r-') @@ -5000,6 +5030,8 @@ def pie(self, x, explode=None, labels=None, colors=None, autopct=None, pctdistance=0.6, shadow=False, labeldistance=1.1): r""" + Plot a pie chart. + Call signature:: pie(x, explode=None, labels=None, @@ -5153,6 +5185,8 @@ def errorbar(self, x, y, yerr=None, xerr=None, barsabove=False, lolims=False, uplims=False, xlolims=False, xuplims=False, **kwargs): """ + Plot an errorbar graph. + Call signature:: errorbar(x, y, yerr=None, xerr=None, @@ -5426,6 +5460,8 @@ def boxplot(self, x, notch=0, sym='b+', vert=1, whis=1.5, positions=None, widths=None, patch_artist=False, bootstrap=None): """ + Make a box and whisker plot. + Call signature:: boxplot(x, notch=0, sym='+', vert=1, whis=1.5, @@ -5698,6 +5734,8 @@ def scatter(self, x, y, s=20, c='b', marker='o', cmap=None, norm=None, faceted=True, verts=None, **kwargs): """ + Make a scatter plot. + Call signatures:: scatter(x, y, s=20, c='b', marker='o', cmap=None, norm=None, @@ -5886,6 +5924,8 @@ def hexbin(self, x, y, C = None, gridsize = 100, bins = None, reduce_C_function = np.mean, mincnt=None, marginals=False, **kwargs): """ + Make a hexagonal binning plot. + Call signature:: hexbin(x, y, C = None, gridsize = 100, bins = None, @@ -6321,6 +6361,8 @@ def on_changed(collection): @docstring.dedent_interpd def arrow(self, x, y, dx, dy, **kwargs): """ + Add an arrow to the axes. + Call signature:: arrow(x, y, dx, dy, **kwargs) @@ -6381,15 +6423,17 @@ def barbs(self, *args, **kw): @docstring.dedent_interpd def fill(self, *args, **kwargs): """ + Plot filled polygons. + Call signature:: fill(*args, **kwargs) - Plot filled polygons. *args* is a variable length argument, - allowing for multiple *x*, *y* pairs with an optional color - format string; see :func:`~matplotlib.pyplot.plot` for details - on the argument parsing. For example, to plot a polygon with - vertices at *x*, *y* in blue.:: + *args* is a variable length argument, allowing for multiple + *x*, *y* pairs with an optional color format string; see + :func:`~matplotlib.pyplot.plot` for details on the argument + parsing. For example, to plot a polygon with vertices at *x*, + *y* in blue.:: ax.fill(x,y, 'b' ) @@ -6430,6 +6474,8 @@ def fill(self, *args, **kwargs): def fill_between(self, x, y1, y2=0, where=None, interpolate=False, **kwargs): """ + Make filled polygons between two curves. + Call signature:: fill_between(x, y1, y2=0, where=None, **kwargs) @@ -6568,6 +6614,8 @@ def get_interp_point(ind): @docstring.dedent_interpd def fill_betweenx(self, y, x1, x2=0, where=None, **kwargs): """ + Make filled polygons between two horizontal curves. + Call signature:: fill_between(y, x1, x2=0, where=None, **kwargs) @@ -6681,6 +6729,8 @@ def imshow(self, X, cmap=None, norm=None, aspect=None, origin=None, extent=None, shape=None, filternorm=1, filterrad=4.0, imlim=None, resample=None, url=None, **kwargs): """ + Display an image on the axes. + Call signature:: imshow(X, cmap=None, norm=None, aspect=None, interpolation=None, @@ -6845,13 +6895,13 @@ def _pcolorargs(self, funcname, *args): @docstring.dedent_interpd def pcolor(self, *args, **kwargs): """ + Create a pseudocolor plot of a 2-D array. + Call signatures:: pcolor(C, **kwargs) pcolor(X, Y, C, **kwargs) - Create a pseudocolor plot of a 2-D array. - *C* is the array of color values. *X* and *Y*, if given, specify the (*x*, *y*) coordinates of @@ -7074,6 +7124,8 @@ def pcolor(self, *args, **kwargs): @docstring.dedent_interpd def pcolormesh(self, *args, **kwargs): """ + Plot a quadrilateral mesh. + Call signatures:: pcolormesh(C) @@ -7394,6 +7446,8 @@ def clabel(self, CS, *args, **kwargs): @docstring.dedent_interpd def table(self, **kwargs): """ + Add a table to the current axes. + Call signature:: table(cellText=None, cellColours=None, @@ -7402,11 +7456,10 @@ def table(self, **kwargs): colLabels=None, colColours=None, colLoc='center', loc='bottom', bbox=None): - Add a table to the current axes. Returns a - :class:`matplotlib.table.Table` instance. For finer grained - control over tables, use the :class:`~matplotlib.table.Table` - class and add it to the axes with - :meth:`~matplotlib.axes.Axes.add_table`. + Returns a :class:`matplotlib.table.Table` instance. For finer + grained control over tables, use the + :class:`~matplotlib.table.Table` class and add it to the axes + with :meth:`~matplotlib.axes.Axes.add_table`. Thanks to John Gill for providing the class and table. @@ -7483,6 +7536,8 @@ def hist(self, x, bins=10, range=None, normed=False, weights=None, color=None, label=None, **kwargs): """ + Plot a histogram. + Call signature:: hist(x, bins=10, range=None, normed=False, weights=None, @@ -7894,6 +7949,8 @@ def psd(self, x, NFFT=256, Fs=2, Fc=0, detrend=mlab.detrend_none, window=mlab.window_hanning, noverlap=0, pad_to=None, sides='default', scale_by_freq=None, **kwargs): """ + Plot the power spectral density. + Call signature:: psd(x, NFFT=256, Fs=2, Fc=0, detrend=mlab.detrend_none, @@ -7966,6 +8023,8 @@ def csd(self, x, y, NFFT=256, Fs=2, Fc=0, detrend=mlab.detrend_none, window=mlab.window_hanning, noverlap=0, pad_to=None, sides='default', scale_by_freq=None, **kwargs): """ + Plot cross-spectral density. + Call signature:: csd(x, y, NFFT=256, Fs=2, Fc=0, detrend=mlab.detrend_none, @@ -8035,14 +8094,16 @@ def cohere(self, x, y, NFFT=256, Fs=2, Fc=0, detrend=mlab.detrend_none, window=mlab.window_hanning, noverlap=0, pad_to=None, sides='default', scale_by_freq=None, **kwargs): """ + Plot the coherence between *x* and *y*. + Call signature:: cohere(x, y, NFFT=256, Fs=2, Fc=0, detrend = mlab.detrend_none, window = mlab.window_hanning, noverlap=0, pad_to=None, sides='default', scale_by_freq=None, **kwargs) - :meth:`cohere` the coherence between *x* and *y*. Coherence - is the normalized cross spectral density: + Plot the coherence between *x* and *y*. Coherence is the + normalized cross spectral density: .. math:: @@ -8093,6 +8154,8 @@ def specgram(self, x, NFFT=256, Fs=2, Fc=0, detrend=mlab.detrend_none, cmap=None, xextent=None, pad_to=None, sides='default', scale_by_freq=None, **kwargs): """ + Plot a spectrogram. + Call signature:: specgram(x, NFFT=256, Fs=2, Fc=0, detrend=mlab.detrend_none, @@ -8164,6 +8227,8 @@ def specgram(self, x, NFFT=256, Fs=2, Fc=0, detrend=mlab.detrend_none, def spy(self, Z, precision=0, marker=None, markersize=None, aspect='equal', **kwargs): """ + Plot the sparsity pattern on a 2-D array. + Call signature:: spy(Z, precision=0, marker=None, markersize=None, diff --git a/lib/matplotlib/contour.py b/lib/matplotlib/contour.py index 9f2c7afdb20d..fb3bb194dad5 100644 --- a/lib/matplotlib/contour.py +++ b/lib/matplotlib/contour.py @@ -51,11 +51,13 @@ class ContourLabeler: def clabel(self, *args, **kwargs): """ + Label a contour plot. + Call signature:: clabel(cs, **kwargs) - adds labels to line contours in *cs*, where *cs* is a + Adds labels to line contours in *cs*, where *cs* is a :class:`~matplotlib.contour.ContourSet` object returned by contour. @@ -1254,6 +1256,8 @@ def _initialize_x_y(self, z): return np.meshgrid(x,y) contour_doc = """ + Plot contours. + :func:`~matplotlib.pyplot.contour` and :func:`~matplotlib.pyplot.contourf` draw contour lines and filled contours, respectively. Except as noted, function diff --git a/lib/matplotlib/figure.py b/lib/matplotlib/figure.py index 533566cc9117..4e7c1a5dda2d 100644 --- a/lib/matplotlib/figure.py +++ b/lib/matplotlib/figure.py @@ -441,6 +441,8 @@ def figimage(self, X, origin=None, **kwargs): """ + Adds a non-resampled image to the figure. + call signatures:: figimage(X, **kwargs) @@ -1012,6 +1014,8 @@ def legend(self, handles, labels, *args, **kwargs): @docstring.dedent_interpd def text(self, x, y, s, *args, **kwargs): """ + Add text to figure. + Call signature:: text(x, y, s, fontdict=None, **kwargs) @@ -1089,14 +1093,14 @@ def add_axobserver(self, func): def savefig(self, *args, **kwargs): """ + Save the current figure. + Call signature:: savefig(fname, dpi=None, facecolor='w', edgecolor='w', orientation='portrait', papertype=None, format=None, transparent=False, bbox_inches=None, pad_inches=0.1): - Save the current figure. - The output formats available depend on the backend being used. Arguments: diff --git a/lib/matplotlib/image.py b/lib/matplotlib/image.py index a428b46780ba..0b78d5d1d30a 100644 --- a/lib/matplotlib/image.py +++ b/lib/matplotlib/image.py @@ -1141,8 +1141,9 @@ def draw(self, renderer, *args, **kwargs): def imread(fname, format=None): """ - Return image file in *fname* as :class:`numpy.array`. *fname* may - be a string path or a Python file-like object. + Read an image from a file into an array. + + *fname* may be a string path or a Python file-like object. If *format* is provided, will try to read file of that type, otherwise the format is deduced from the filename. If nothing can @@ -1198,7 +1199,8 @@ def pilread(): def imsave(fname, arr, vmin=None, vmax=None, cmap=None, format=None, origin=None, dpi=100): """ - Saves a 2D :class:`numpy.array` as an image with one pixel per element. + Save an array as in image file. + The output formats available depend on the backend being used. Arguments: diff --git a/lib/matplotlib/pyplot.py b/lib/matplotlib/pyplot.py index 5171dbe0b0e2..44200f4ffdaf 100644 --- a/lib/matplotlib/pyplot.py +++ b/lib/matplotlib/pyplot.py @@ -102,13 +102,13 @@ def findobj(o=None, match=None): def switch_backend(newbackend): """ - Switch the default backend to newbackend. This feature is - **experimental**, and is only expected to work switching to an - image backend. Eg, if you have a bunch of PostScript scripts that - you want to run from an interactive ipython session, you may want - to switch to the PS backend before running them to avoid having a - bunch of GUI windows popup. If you try to interactively switch - from one GUI backend to another, you will explode. + Switch the default backend. This feature is **experimental**, and + is only expected to work switching to an image backend. Eg, if + you have a bunch of PostScript scripts that you want to run from + an interactive ipython session, you may want to switch to the PS + backend before running them to avoid having a bunch of GUI windows + popup. If you try to interactively switch from one GUI backend to + another, you will explode. Calling this command will close all open windows. """ @@ -122,6 +122,8 @@ def switch_backend(newbackend): def show(*args, **kw): """ + Display a figure. + When running in ipython with its pylab mode, display all figures and return to the ipython prompt. @@ -141,7 +143,7 @@ def show(*args, **kw): def isinteractive(): """ - Return *True* if matplotlib is in interactive mode, *False* otherwise. + Return status of interactive mode. """ return matplotlib.is_interactive() @@ -201,25 +203,25 @@ def rcdefaults(): def gci(): """ - Get the current :class:`~matplotlib.cm.ScalarMappable` instance - (image or patch collection), or *None* if no images or patch - collections have been defined. The commands - :func:`~matplotlib.pyplot.imshow` and - :func:`~matplotlib.pyplot.figimage` create + Get the current colorable artist. Specifically, returns the + current :class:`~matplotlib.cm.ScalarMappable` instance (image or + patch collection), or *None* if no images or patch collections + have been defined. The commands :func:`~matplotlib.pyplot.imshow` + and :func:`~matplotlib.pyplot.figimage` create :class:`~matplotlib.image.Image` instances, and the commands :func:`~matplotlib.pyplot.pcolor` and :func:`~matplotlib.pyplot.scatter` create - :class:`~matplotlib.collections.Collection` instances. - The current image is an attribute of the current axes, or the - nearest earlier axes in the current figure that contains an - image. + :class:`~matplotlib.collections.Collection` instances. The + current image is an attribute of the current axes, or the nearest + earlier axes in the current figure that contains an image. """ return gcf()._gci() def sci(im): """ - Set the current image (target of colormap commands like - :func:`~matplotlib.pyplot.jet`, :func:`~matplotlib.pyplot.hot` or + Set the current image. This image will be the target of colormap + commands like :func:`~matplotlib.pyplot.jet`, + :func:`~matplotlib.pyplot.hot` or :func:`~matplotlib.pyplot.clim`). The current image is an attribute of the current axes. """ @@ -253,11 +255,12 @@ def figure(num=None, # autoincrement if None, else integer from 1-N **kwargs ): """ + Create a new figure. + call signature:: figure(num=None, figsize=(8, 6), dpi=80, facecolor='w', edgecolor='k') - Create a new figure and return a :class:`matplotlib.figure.Figure` instance. If *num* = *None*, the figure number will be incremented and a new figure will be created. The returned figure objects have a @@ -399,7 +402,7 @@ def disconnect(cid): def close(*args): """ - Close a figure window + Close a figure window. ``close()`` by itself closes the current figure @@ -438,7 +441,7 @@ def close(*args): def clf(): """ - Clear the current figure + Clear the current figure. """ gcf().clf() draw_if_interactive() @@ -585,13 +588,15 @@ def hold(b=None): def ishold(): """ - Return the hold status of the current axes + Return the hold status of the current axes. """ return gca().ishold() def over(func, *args, **kwargs): """ - over calls:: + Call a function with hold(True). + + Calls:: func(*args, **kwargs) @@ -608,7 +613,9 @@ def over(func, *args, **kwargs): def axes(*args, **kwargs): """ - Add an axes at position rect specified by: + Add an axes to the figure. + + The axes is added at position *rect* specified by: - ``axes()`` by itself creates a default full ``subplot(111)`` window axis. @@ -653,7 +660,7 @@ def axes(*args, **kwargs): def delaxes(*args): """ - ``delaxes(ax)``: remove *ax* from the current figure. If *ax* + Remove an axes from the current figure. If *ax* doesn't exist, an error will be raised. ``delaxes()``: delete the current axes @@ -668,8 +675,9 @@ def delaxes(*args): def sca(ax): """ - Set the current Axes instance to *ax*. The current Figure - is updated to the parent of *ax*. + Set the current Axes instance to *ax*. + + The current Figure is updated to the parent of *ax*. """ managers = _pylab_helpers.Gcf.get_all_fig_managers() for m in managers: @@ -705,7 +713,9 @@ def gca(**kwargs): def subplot(*args, **kwargs): """ - Create a subplot command, creating axes with:: + Create a new axes (subplot). + + Creating axes with:: subplot(numRows, numCols, plotNum) @@ -921,10 +931,9 @@ def subplots(nrows=1, ncols=1, sharex=False, sharey=False, squeeze=True, from gridspec import GridSpec def subplot2grid(shape, loc, rowspan=1, colspan=1, **kwargs): """ - - It creates a subplot in a grid of *shape*, at location of *loc*, - spanning *rowspan*, *colspan* cells in each direction. - The index for loc is 0-based. :: + Create a subplot in a grid. The grid is specified by *shape*, at + location of *loc*, spanning *rowspan*, *colspan* cells in each + direction. The index for loc is 0-based. :: subplot2grid(shape, loc, rowspan=1, colspan=1) @@ -933,8 +942,6 @@ def subplot2grid(shape, loc, rowspan=1, colspan=1, **kwargs): gridspec=GridSpec(shape[0], shape[2]) subplotspec=gridspec.new_subplotspec(loc, rowspan, colspan) subplot(subplotspec) - - """ fig = gcf() @@ -957,9 +964,10 @@ def subplot2grid(shape, loc, rowspan=1, colspan=1, **kwargs): def twinx(ax=None): """ - Make a second axes overlay *ax* (or the current axes if *ax* is - *None*) sharing the xaxis. The ticks for *ax2* will be placed on - the right, and the *ax2* instance is returned. + Make a second axes that shares the *x*-axis. The new axes will + overlay *ax* (or the current axes if *ax* is *None*). The ticks + for *ax2* will be placed on the right, and the *ax2* instance is + returned. .. seealso:: @@ -975,9 +983,10 @@ def twinx(ax=None): def twiny(ax=None): """ - Make a second axes overlay *ax* (or the current axes if *ax* is - *None*) sharing the yaxis. The ticks for *ax2* will be placed on - the top, and the *ax2* instance is returned. + Make a second axes that shares the *y*-axis. The new axis will + overlay *ax* (or the current axes if *ax* is *None*). The ticks + for *ax2* will be placed on the top, and the *ax2* instance is + returned. """ if ax is None: ax=gca() @@ -989,14 +998,14 @@ def twiny(ax=None): def subplots_adjust(*args, **kwargs): """ + Tune the subplot layout. + call signature:: subplots_adjust(left=None, bottom=None, right=None, top=None, wspace=None, hspace=None) - Tune the subplot layout via the - :class:`matplotlib.figure.SubplotParams` mechanism. The parameter - meanings (and suggested defaults) are:: + The parameter meanings (and suggested defaults) are:: left = 0.125 # the left side of the subplots of the figure right = 0.9 # the right side of the subplots of the figure @@ -1014,7 +1023,7 @@ def subplots_adjust(*args, **kwargs): def subplot_tool(targetfig=None): """ - Launch a subplot tool window for *targetfig* (default gcf). + Launch a subplot tool window for a figure. A :class:`matplotlib.widgets.SubplotTool` instance is returned. """ @@ -1040,7 +1049,7 @@ def subplot_tool(targetfig=None): def tight_layout(pad=1.2, h_pad=None, w_pad=None): """ - Adjust subplot parameters to give specified padding. + Automatically adjust subplot parameters to give specified padding. Parameters: @@ -1059,8 +1068,8 @@ def tight_layout(pad=1.2, h_pad=None, w_pad=None): def box(on=None): """ - Turn the axes box on or off according to *on*. - *on* may be a boolean or a string, 'on' or 'off'. + Turn the axes box on or off. *on* may be a boolean or a string, + 'on' or 'off'. If *on* is *None*, toggle state. """ @@ -1073,7 +1082,7 @@ def box(on=None): def title(s, *args, **kwargs): """ - Set the title of the current axis to *s*. + Set the title of the current axis. Default font override is:: @@ -1097,7 +1106,7 @@ def title(s, *args, **kwargs): def axis(*v, **kwargs): """ - Set/Get the axis properties: + Set or get the axis properties. >>> axis() @@ -1160,7 +1169,7 @@ def axis(*v, **kwargs): def xlabel(s, *args, **kwargs): """ - Set the *x* axis label of the current axis to *s* + Set the *x* axis label of the current axis. Default override is:: @@ -1181,7 +1190,7 @@ def xlabel(s, *args, **kwargs): def ylabel(s, *args, **kwargs): """ - Set the *y* axis label of the current axis to *s*. + Set the *y* axis label of the current axis. Defaults override is:: @@ -1207,7 +1216,9 @@ def ylabel(s, *args, **kwargs): def xlim(*args, **kwargs): """ - Set/Get the xlimits of the current axes:: + Get or set the *x* limits of the current axes. + + :: xmin, xmax = xlim() # return the current xlim xlim( (xmin, xmax) ) # set the xlim to xmin, xmax @@ -1234,7 +1245,9 @@ def xlim(*args, **kwargs): def ylim(*args, **kwargs): """ - Set/Get the ylimits of the current axes:: + Get or set the *y*-limits of the current axes. + + :: ymin, ymax = ylim() # return the current ylim ylim( (ymin, ymax) ) # set the ylim to ymin, ymax @@ -1261,11 +1274,13 @@ def ylim(*args, **kwargs): @docstring.dedent_interpd def xscale(*args, **kwargs): """ + Set the scaling of the *x*-axis. + call signature:: xscale(scale, **kwargs) - Set the scaling for the x-axis: %(scale)s + The available scales are: %(scale)s Different keywords may be accepted, depending on the scale: @@ -1278,11 +1293,13 @@ def xscale(*args, **kwargs): @docstring.dedent_interpd def yscale(*args, **kwargs): """ + Set the scaling of the *y*-axis. + call signature:: yscale(scale, **kwargs) - Set the scaling for the y-axis: %(scale)s + The available scales are: %(scale)s Different keywords may be accepted, depending on the scale: @@ -1294,7 +1311,9 @@ def yscale(*args, **kwargs): def xticks(*args, **kwargs): """ - Set/Get the xlimits of the current ticklocs and labels:: + Get or set the *x*-limits of the current tick locations and labels. + + :: # return locs, labels where locs is an array of tick locations and # labels is an array of tick labels. @@ -1332,7 +1351,9 @@ def xticks(*args, **kwargs): def yticks(*args, **kwargs): """ - Set/Get the ylimits of the current ticklocs and labels:: + Get or set the *y*-limits of the current tick locations and labels. + + :: # return locs, labels where locs is an array of tick locations and # labels is an array of tick labels. @@ -1390,8 +1411,7 @@ def minorticks_off(): def rgrids(*args, **kwargs): """ - Set/Get the radial locations of the gridlines and ticklabels on a - polar plot. + Get or set the radial gridlines on a polar plot. call signatures:: @@ -1435,7 +1455,7 @@ def rgrids(*args, **kwargs): def thetagrids(*args, **kwargs): """ - Set/Get the theta locations of the gridlines and ticklabels. + Get or set the theta locations of the gridlines in a polar plot. If no arguments are passed, return a tuple (*lines*, *labels*) where *lines* is an array of radial gridlines @@ -1581,17 +1601,38 @@ def plotting(): * spectral """ + # TODO: Generate this automatically pass -def get_plot_commands(): return ( 'axes', 'axis', 'bar', 'boxplot', 'cla', 'clf', - 'close', 'colorbar', 'cohere', 'csd', 'draw', 'errorbar', - 'figlegend', 'figtext', 'figimage', 'figure', 'fill', 'gca', - 'gcf', 'gci', 'get', 'gray', 'barh', 'jet', 'hist', 'hold', 'imread', 'imsave', - 'imshow', 'legend', 'loglog', 'quiver', 'rc', 'pcolor', 'pcolormesh', 'plot', 'psd', - 'savefig', 'scatter', 'set', 'semilogx', 'semilogy', 'show', - 'specgram', 'stem', 'subplot', 'table', 'text', 'title', 'xlabel', - 'ylabel', 'pie', 'polar') +def get_plot_commands(): + """ + Get a sorted list of all of the plotting commands. + """ + # This works by searching for all functions in this module and + # removing a few hard-coded exclusions, as well as all of the + # colormap-setting functions, and anything marked as private with + # a preceding underscore. + + import inspect + + exclude = set(['colormaps', 'colors', 'connect', 'disconnect', + 'get_plot_commands', 'get_current_fig_manager', + 'ginput', 'plotting', 'waitforbuttonpress']) + exclude |= set(colormaps()) + this_module = inspect.getmodule(get_plot_commands) + + commands = set() + for name, obj in globals().items(): + if name.startswith('_') or name in exclude: + continue + if inspect.isfunction(obj) and inspect.getmodule(obj) is this_module: + commands.add(name) + + commands = list(commands) + commands.sort() + return commands + def colors(): """ @@ -1645,23 +1686,9 @@ def colors(): def colormaps(): """ - matplotlib provides the following colormaps. + matplotlib provides the following colormaps: - * autumn - * bone - * cool - * copper - * flag - * gray - * hot - * hsv - * jet - * pink - * prism - * spring - * summer - * winter - * spectral + %s You can set the colormap for an image, pcolor, scatter, etc, either as a keyword argument:: @@ -1677,8 +1704,56 @@ def colormaps(): In interactive mode, this will update the colormap allowing you to see which one works best for your data. """ - pass - + return _colormaps() + + +def _setup_pyplot_info_docstrings(): + import re + + def pad(s, l): + """Pad string *s* to length *l*.""" + if l < len(s): + return s[:l] + return s + ' ' * (l - len(s)) + + commands = get_plot_commands() + + first_sentence = re.compile("(?:\s*).+?\.(?:\s+|$)", flags=re.DOTALL) + + # Collect the first sentence of the docstring for all of the + # plotting commands. + rows = [] + max_name = 0 + max_summary = 0 + for name in commands: + doc = globals()[name].__doc__ + summary = '' + if doc is not None: + match = first_sentence.match(doc) + if match is not None: + summary = match.group(0).strip().replace('\n', ' ') + name = '`%s`' % name + rows.append([name, summary]) + max_name = max(max_name, len(name)) + max_summary = max(max_summary, len(summary)) + + lines = [] + sep = '=' * max_name + ' ' + '=' * max_summary + lines.append(sep) + lines.append(' '.join([pad("Function", max_name), + pad("Description", max_summary)])) + lines.append(sep) + for name, summary in rows: + lines.append(' '.join([pad(name, max_name), + pad(summary, max_summary)])) + lines.append(sep) + + plotting.__doc__ = '\n'.join(lines) + + # Deal with the colormaps docstring + maps = colormaps() + maps = ', '.join(['`%s`' % x for x in maps]) + colormaps.__doc__ = colormaps.__doc__ % maps ## Plotting part 1: manually generated functions and wrappers ## @@ -1698,7 +1773,7 @@ def colorbar(mappable=None, cax=None, ax=None, **kw): def clim(vmin=None, vmax=None): """ - Set the color limits of the current image + Set the color limits of the current image. To apply clim to all axes images do:: @@ -1723,7 +1798,7 @@ def clim(vmin=None, vmax=None): def set_cmap(cmap): ''' - set the default colormap to *cmap* and apply to current image if any. + Set the default colormap. Applies to the current image if any. See help(colormaps) for more information. *cmap* must be a :class:`colors.Colormap` instance, or @@ -1795,12 +1870,14 @@ def matshow(A, fignum=None, **kw): def polar(*args, **kwargs): """ + Make a polar plot. + call signature:: polar(theta, r, **kwargs) - Make a polar plot. Multiple *theta*, *r* arguments are supported, - with format strings, as in :func:`~matplotlib.pyplot.plot`. + Multiple *theta*, *r* arguments are supported, with format + strings, as in :func:`~matplotlib.pyplot.plot`. An optional kwarg *resolution* sets the number of vertices to interpolate between each pair of points. The default is 1, @@ -1817,7 +1894,7 @@ def plotfile(fname, cols=(0,), plotfuncs=None, subplots=True, newfig=True, **kwargs): """ - Plot the data in *fname* + Plot the data in in a file. *cols* is a sequence of column identifiers to plot. An identifier is either an int or a string. If it is an int, it indicates the @@ -1937,7 +2014,7 @@ def getname_val(identifier): draw_if_interactive() -def autogen_docstring(base): +def _autogen_docstring(base): """Autogenerated wrappers will get their docstring from a base function with an addendum.""" msg = "\n\nAdditional kwargs: hold = [True|False] overrides default hold state" @@ -1947,7 +2024,7 @@ def autogen_docstring(base): # This function cannot be generated by boilerplate.py because it may # return an image or a line. -@autogen_docstring(Axes.spy) +@_autogen_docstring(Axes.spy) def spy(Z, precision=0, marker=None, markersize=None, aspect='equal', hold=None, **kwargs): ax = gca() # allow callers to override the hold state by passing hold=True|False @@ -1969,7 +2046,7 @@ def spy(Z, precision=0, marker=None, markersize=None, aspect='equal', hold=None, # This function was autogenerated by boilerplate.py. Do not edit as # changes will be lost -@autogen_docstring(Axes.acorr) +@_autogen_docstring(Axes.acorr) def acorr(x, hold=None, **kwargs): ax = gca() # allow callers to override the hold state by passing hold=True|False @@ -1987,7 +2064,7 @@ def acorr(x, hold=None, **kwargs): # This function was autogenerated by boilerplate.py. Do not edit as # changes will be lost -@autogen_docstring(Axes.arrow) +@_autogen_docstring(Axes.arrow) def arrow(x, y, dx, dy, hold=None, **kwargs): ax = gca() # allow callers to override the hold state by passing hold=True|False @@ -2005,7 +2082,7 @@ def arrow(x, y, dx, dy, hold=None, **kwargs): # This function was autogenerated by boilerplate.py. Do not edit as # changes will be lost -@autogen_docstring(Axes.axhline) +@_autogen_docstring(Axes.axhline) def axhline(y=0, xmin=0, xmax=1, hold=None, **kwargs): ax = gca() # allow callers to override the hold state by passing hold=True|False @@ -2023,7 +2100,7 @@ def axhline(y=0, xmin=0, xmax=1, hold=None, **kwargs): # This function was autogenerated by boilerplate.py. Do not edit as # changes will be lost -@autogen_docstring(Axes.axhspan) +@_autogen_docstring(Axes.axhspan) def axhspan(ymin, ymax, xmin=0, xmax=1, hold=None, **kwargs): ax = gca() # allow callers to override the hold state by passing hold=True|False @@ -2041,7 +2118,7 @@ def axhspan(ymin, ymax, xmin=0, xmax=1, hold=None, **kwargs): # This function was autogenerated by boilerplate.py. Do not edit as # changes will be lost -@autogen_docstring(Axes.axvline) +@_autogen_docstring(Axes.axvline) def axvline(x=0, ymin=0, ymax=1, hold=None, **kwargs): ax = gca() # allow callers to override the hold state by passing hold=True|False @@ -2059,7 +2136,7 @@ def axvline(x=0, ymin=0, ymax=1, hold=None, **kwargs): # This function was autogenerated by boilerplate.py. Do not edit as # changes will be lost -@autogen_docstring(Axes.axvspan) +@_autogen_docstring(Axes.axvspan) def axvspan(xmin, xmax, ymin=0, ymax=1, hold=None, **kwargs): ax = gca() # allow callers to override the hold state by passing hold=True|False @@ -2077,8 +2154,8 @@ def axvspan(xmin, xmax, ymin=0, ymax=1, hold=None, **kwargs): # This function was autogenerated by boilerplate.py. Do not edit as # changes will be lost -@autogen_docstring(Axes.bar) -def bar(left, height, width=0.80000000000000004, bottom=None, hold=None, **kwargs): +@_autogen_docstring(Axes.bar) +def bar(left, height, width=0.8, bottom=None, hold=None, **kwargs): ax = gca() # allow callers to override the hold state by passing hold=True|False washold = ax.ishold() @@ -2095,8 +2172,8 @@ def bar(left, height, width=0.80000000000000004, bottom=None, hold=None, **kwarg # This function was autogenerated by boilerplate.py. Do not edit as # changes will be lost -@autogen_docstring(Axes.barh) -def barh(bottom, width, height=0.80000000000000004, left=None, hold=None, **kwargs): +@_autogen_docstring(Axes.barh) +def barh(bottom, width, height=0.8, left=None, hold=None, **kwargs): ax = gca() # allow callers to override the hold state by passing hold=True|False washold = ax.ishold() @@ -2113,7 +2190,7 @@ def barh(bottom, width, height=0.80000000000000004, left=None, hold=None, **kwar # This function was autogenerated by boilerplate.py. Do not edit as # changes will be lost -@autogen_docstring(Axes.broken_barh) +@_autogen_docstring(Axes.broken_barh) def broken_barh(xranges, yrange, hold=None, **kwargs): ax = gca() # allow callers to override the hold state by passing hold=True|False @@ -2131,7 +2208,7 @@ def broken_barh(xranges, yrange, hold=None, **kwargs): # This function was autogenerated by boilerplate.py. Do not edit as # changes will be lost -@autogen_docstring(Axes.boxplot) +@_autogen_docstring(Axes.boxplot) def boxplot(x, notch=0, sym='b+', vert=1, whis=1.5, positions=None, widths=None, patch_artist=False, bootstrap=None, hold=None): ax = gca() # allow callers to override the hold state by passing hold=True|False @@ -2149,7 +2226,7 @@ def boxplot(x, notch=0, sym='b+', vert=1, whis=1.5, positions=None, widths=None, # This function was autogenerated by boilerplate.py. Do not edit as # changes will be lost -@autogen_docstring(Axes.cohere) +@_autogen_docstring(Axes.cohere) def cohere(x, y, NFFT=256, Fs=2, Fc=0, detrend=mlab.detrend_none, window=mlab.window_hanning, noverlap=0, pad_to=None, sides='default', scale_by_freq=None, hold=None, **kwargs): ax = gca() # allow callers to override the hold state by passing hold=True|False @@ -2167,7 +2244,7 @@ def cohere(x, y, NFFT=256, Fs=2, Fc=0, detrend=mlab.detrend_none, window=mlab.wi # This function was autogenerated by boilerplate.py. Do not edit as # changes will be lost -@autogen_docstring(Axes.clabel) +@_autogen_docstring(Axes.clabel) def clabel(CS, *args, **kwargs): ax = gca() # allow callers to override the hold state by passing hold=True|False @@ -2185,7 +2262,7 @@ def clabel(CS, *args, **kwargs): # This function was autogenerated by boilerplate.py. Do not edit as # changes will be lost -@autogen_docstring(Axes.contour) +@_autogen_docstring(Axes.contour) def contour(*args, **kwargs): ax = gca() # allow callers to override the hold state by passing hold=True|False @@ -2203,7 +2280,7 @@ def contour(*args, **kwargs): # This function was autogenerated by boilerplate.py. Do not edit as # changes will be lost -@autogen_docstring(Axes.contourf) +@_autogen_docstring(Axes.contourf) def contourf(*args, **kwargs): ax = gca() # allow callers to override the hold state by passing hold=True|False @@ -2221,7 +2298,7 @@ def contourf(*args, **kwargs): # This function was autogenerated by boilerplate.py. Do not edit as # changes will be lost -@autogen_docstring(Axes.csd) +@_autogen_docstring(Axes.csd) def csd(x, y, NFFT=256, Fs=2, Fc=0, detrend=mlab.detrend_none, window=mlab.window_hanning, noverlap=0, pad_to=None, sides='default', scale_by_freq=None, hold=None, **kwargs): ax = gca() # allow callers to override the hold state by passing hold=True|False @@ -2239,7 +2316,7 @@ def csd(x, y, NFFT=256, Fs=2, Fc=0, detrend=mlab.detrend_none, window=mlab.windo # This function was autogenerated by boilerplate.py. Do not edit as # changes will be lost -@autogen_docstring(Axes.errorbar) +@_autogen_docstring(Axes.errorbar) def errorbar(x, y, yerr=None, xerr=None, fmt='-', ecolor=None, elinewidth=None, capsize=3, barsabove=False, lolims=False, uplims=False, xlolims=False, xuplims=False, hold=None, **kwargs): ax = gca() # allow callers to override the hold state by passing hold=True|False @@ -2257,7 +2334,7 @@ def errorbar(x, y, yerr=None, xerr=None, fmt='-', ecolor=None, elinewidth=None, # This function was autogenerated by boilerplate.py. Do not edit as # changes will be lost -@autogen_docstring(Axes.fill) +@_autogen_docstring(Axes.fill) def fill(*args, **kwargs): ax = gca() # allow callers to override the hold state by passing hold=True|False @@ -2275,7 +2352,7 @@ def fill(*args, **kwargs): # This function was autogenerated by boilerplate.py. Do not edit as # changes will be lost -@autogen_docstring(Axes.fill_between) +@_autogen_docstring(Axes.fill_between) def fill_between(x, y1, y2=0, where=None, interpolate=False, hold=None, **kwargs): ax = gca() # allow callers to override the hold state by passing hold=True|False @@ -2293,7 +2370,7 @@ def fill_between(x, y1, y2=0, where=None, interpolate=False, hold=None, **kwargs # This function was autogenerated by boilerplate.py. Do not edit as # changes will be lost -@autogen_docstring(Axes.fill_betweenx) +@_autogen_docstring(Axes.fill_betweenx) def fill_betweenx(y, x1, x2=0, where=None, hold=None, **kwargs): ax = gca() # allow callers to override the hold state by passing hold=True|False @@ -2311,7 +2388,7 @@ def fill_betweenx(y, x1, x2=0, where=None, hold=None, **kwargs): # This function was autogenerated by boilerplate.py. Do not edit as # changes will be lost -@autogen_docstring(Axes.hexbin) +@_autogen_docstring(Axes.hexbin) def hexbin(x, y, C=None, gridsize=100, bins=None, xscale='linear', yscale='linear', extent=None, cmap=None, norm=None, vmin=None, vmax=None, alpha=None, linewidths=None, edgecolors='none', reduce_C_function=np.mean, mincnt=None, marginals=False, hold=None, **kwargs): ax = gca() # allow callers to override the hold state by passing hold=True|False @@ -2329,7 +2406,7 @@ def hexbin(x, y, C=None, gridsize=100, bins=None, xscale='linear', yscale='linea # This function was autogenerated by boilerplate.py. Do not edit as # changes will be lost -@autogen_docstring(Axes.hist) +@_autogen_docstring(Axes.hist) def hist(x, bins=10, range=None, normed=False, weights=None, cumulative=False, bottom=None, histtype='bar', align='mid', orientation='vertical', rwidth=None, log=False, color=None, label=None, hold=None, **kwargs): ax = gca() # allow callers to override the hold state by passing hold=True|False @@ -2347,7 +2424,7 @@ def hist(x, bins=10, range=None, normed=False, weights=None, cumulative=False, b # This function was autogenerated by boilerplate.py. Do not edit as # changes will be lost -@autogen_docstring(Axes.hlines) +@_autogen_docstring(Axes.hlines) def hlines(y, xmin, xmax, colors='k', linestyles='solid', label='', hold=None, **kwargs): ax = gca() # allow callers to override the hold state by passing hold=True|False @@ -2365,7 +2442,7 @@ def hlines(y, xmin, xmax, colors='k', linestyles='solid', label='', hold=None, * # This function was autogenerated by boilerplate.py. Do not edit as # changes will be lost -@autogen_docstring(Axes.imshow) +@_autogen_docstring(Axes.imshow) def imshow(X, cmap=None, norm=None, aspect=None, interpolation=None, alpha=None, vmin=None, vmax=None, origin=None, extent=None, shape=None, filternorm=1, filterrad=4.0, imlim=None, resample=None, url=None, hold=None, **kwargs): ax = gca() # allow callers to override the hold state by passing hold=True|False @@ -2383,7 +2460,7 @@ def imshow(X, cmap=None, norm=None, aspect=None, interpolation=None, alpha=None, # This function was autogenerated by boilerplate.py. Do not edit as # changes will be lost -@autogen_docstring(Axes.loglog) +@_autogen_docstring(Axes.loglog) def loglog(*args, **kwargs): ax = gca() # allow callers to override the hold state by passing hold=True|False @@ -2401,7 +2478,7 @@ def loglog(*args, **kwargs): # This function was autogenerated by boilerplate.py. Do not edit as # changes will be lost -@autogen_docstring(Axes.pcolor) +@_autogen_docstring(Axes.pcolor) def pcolor(*args, **kwargs): ax = gca() # allow callers to override the hold state by passing hold=True|False @@ -2419,7 +2496,7 @@ def pcolor(*args, **kwargs): # This function was autogenerated by boilerplate.py. Do not edit as # changes will be lost -@autogen_docstring(Axes.pcolormesh) +@_autogen_docstring(Axes.pcolormesh) def pcolormesh(*args, **kwargs): ax = gca() # allow callers to override the hold state by passing hold=True|False @@ -2437,8 +2514,8 @@ def pcolormesh(*args, **kwargs): # This function was autogenerated by boilerplate.py. Do not edit as # changes will be lost -@autogen_docstring(Axes.pie) -def pie(x, explode=None, labels=None, colors=None, autopct=None, pctdistance=0.59999999999999998, shadow=False, labeldistance=1.1000000000000001, hold=None): +@_autogen_docstring(Axes.pie) +def pie(x, explode=None, labels=None, colors=None, autopct=None, pctdistance=0.6, shadow=False, labeldistance=1.1, hold=None): ax = gca() # allow callers to override the hold state by passing hold=True|False washold = ax.ishold() @@ -2455,7 +2532,7 @@ def pie(x, explode=None, labels=None, colors=None, autopct=None, pctdistance=0.5 # This function was autogenerated by boilerplate.py. Do not edit as # changes will be lost -@autogen_docstring(Axes.plot) +@_autogen_docstring(Axes.plot) def plot(*args, **kwargs): ax = gca() # allow callers to override the hold state by passing hold=True|False @@ -2473,7 +2550,7 @@ def plot(*args, **kwargs): # This function was autogenerated by boilerplate.py. Do not edit as # changes will be lost -@autogen_docstring(Axes.plot_date) +@_autogen_docstring(Axes.plot_date) def plot_date(x, y, fmt='bo', tz=None, xdate=True, ydate=False, hold=None, **kwargs): ax = gca() # allow callers to override the hold state by passing hold=True|False @@ -2491,7 +2568,7 @@ def plot_date(x, y, fmt='bo', tz=None, xdate=True, ydate=False, hold=None, **kwa # This function was autogenerated by boilerplate.py. Do not edit as # changes will be lost -@autogen_docstring(Axes.psd) +@_autogen_docstring(Axes.psd) def psd(x, NFFT=256, Fs=2, Fc=0, detrend=mlab.detrend_none, window=mlab.window_hanning, noverlap=0, pad_to=None, sides='default', scale_by_freq=None, hold=None, **kwargs): ax = gca() # allow callers to override the hold state by passing hold=True|False @@ -2509,7 +2586,7 @@ def psd(x, NFFT=256, Fs=2, Fc=0, detrend=mlab.detrend_none, window=mlab.window_h # This function was autogenerated by boilerplate.py. Do not edit as # changes will be lost -@autogen_docstring(Axes.quiver) +@_autogen_docstring(Axes.quiver) def quiver(*args, **kw): ax = gca() # allow callers to override the hold state by passing hold=True|False @@ -2527,7 +2604,7 @@ def quiver(*args, **kw): # This function was autogenerated by boilerplate.py. Do not edit as # changes will be lost -@autogen_docstring(Axes.quiverkey) +@_autogen_docstring(Axes.quiverkey) def quiverkey(*args, **kw): ax = gca() # allow callers to override the hold state by passing hold=True|False @@ -2545,7 +2622,7 @@ def quiverkey(*args, **kw): # This function was autogenerated by boilerplate.py. Do not edit as # changes will be lost -@autogen_docstring(Axes.scatter) +@_autogen_docstring(Axes.scatter) def scatter(x, y, s=20, c='b', marker='o', cmap=None, norm=None, vmin=None, vmax=None, alpha=None, linewidths=None, faceted=True, verts=None, hold=None, **kwargs): ax = gca() # allow callers to override the hold state by passing hold=True|False @@ -2563,7 +2640,7 @@ def scatter(x, y, s=20, c='b', marker='o', cmap=None, norm=None, vmin=None, vmax # This function was autogenerated by boilerplate.py. Do not edit as # changes will be lost -@autogen_docstring(Axes.semilogx) +@_autogen_docstring(Axes.semilogx) def semilogx(*args, **kwargs): ax = gca() # allow callers to override the hold state by passing hold=True|False @@ -2581,7 +2658,7 @@ def semilogx(*args, **kwargs): # This function was autogenerated by boilerplate.py. Do not edit as # changes will be lost -@autogen_docstring(Axes.semilogy) +@_autogen_docstring(Axes.semilogy) def semilogy(*args, **kwargs): ax = gca() # allow callers to override the hold state by passing hold=True|False @@ -2599,7 +2676,7 @@ def semilogy(*args, **kwargs): # This function was autogenerated by boilerplate.py. Do not edit as # changes will be lost -@autogen_docstring(Axes.specgram) +@_autogen_docstring(Axes.specgram) def specgram(x, NFFT=256, Fs=2, Fc=0, detrend=mlab.detrend_none, window=mlab.window_hanning, noverlap=128, cmap=None, xextent=None, pad_to=None, sides='default', scale_by_freq=None, hold=None, **kwargs): ax = gca() # allow callers to override the hold state by passing hold=True|False @@ -2617,8 +2694,8 @@ def specgram(x, NFFT=256, Fs=2, Fc=0, detrend=mlab.detrend_none, window=mlab.win # This function was autogenerated by boilerplate.py. Do not edit as # changes will be lost -@autogen_docstring(Axes.stem) -def stem(x, y, linefmt='b-', markerfmt='bo', basefmt='r-', hold=None): +@_autogen_docstring(Axes.stem) +def stem(x, y, linefmt='b-', markerfmt='bo', basefmt='r-', bottom=None, label=None, hold=None): ax = gca() # allow callers to override the hold state by passing hold=True|False washold = ax.ishold() @@ -2626,7 +2703,7 @@ def stem(x, y, linefmt='b-', markerfmt='bo', basefmt='r-', hold=None): if hold is not None: ax.hold(hold) try: - ret = ax.stem(x, y, linefmt, markerfmt, basefmt) + ret = ax.stem(x, y, linefmt, markerfmt, basefmt, bottom, label) draw_if_interactive() finally: ax.hold(washold) @@ -2635,7 +2712,7 @@ def stem(x, y, linefmt='b-', markerfmt='bo', basefmt='r-', hold=None): # This function was autogenerated by boilerplate.py. Do not edit as # changes will be lost -@autogen_docstring(Axes.step) +@_autogen_docstring(Axes.step) def step(x, y, *args, **kwargs): ax = gca() # allow callers to override the hold state by passing hold=True|False @@ -2653,7 +2730,7 @@ def step(x, y, *args, **kwargs): # This function was autogenerated by boilerplate.py. Do not edit as # changes will be lost -@autogen_docstring(Axes.tricontour) +@_autogen_docstring(Axes.tricontour) def tricontour(*args, **kwargs): ax = gca() # allow callers to override the hold state by passing hold=True|False @@ -2671,7 +2748,7 @@ def tricontour(*args, **kwargs): # This function was autogenerated by boilerplate.py. Do not edit as # changes will be lost -@autogen_docstring(Axes.tricontourf) +@_autogen_docstring(Axes.tricontourf) def tricontourf(*args, **kwargs): ax = gca() # allow callers to override the hold state by passing hold=True|False @@ -2689,7 +2766,7 @@ def tricontourf(*args, **kwargs): # This function was autogenerated by boilerplate.py. Do not edit as # changes will be lost -@autogen_docstring(Axes.tripcolor) +@_autogen_docstring(Axes.tripcolor) def tripcolor(*args, **kwargs): ax = gca() # allow callers to override the hold state by passing hold=True|False @@ -2707,7 +2784,7 @@ def tripcolor(*args, **kwargs): # This function was autogenerated by boilerplate.py. Do not edit as # changes will be lost -@autogen_docstring(Axes.triplot) +@_autogen_docstring(Axes.triplot) def triplot(*args, **kwargs): ax = gca() # allow callers to override the hold state by passing hold=True|False @@ -2725,7 +2802,7 @@ def triplot(*args, **kwargs): # This function was autogenerated by boilerplate.py. Do not edit as # changes will be lost -@autogen_docstring(Axes.vlines) +@_autogen_docstring(Axes.vlines) def vlines(x, ymin, ymax, colors='k', linestyles='solid', label='', hold=None, **kwargs): ax = gca() # allow callers to override the hold state by passing hold=True|False @@ -2743,7 +2820,7 @@ def vlines(x, ymin, ymax, colors='k', linestyles='solid', label='', hold=None, * # This function was autogenerated by boilerplate.py. Do not edit as # changes will be lost -@autogen_docstring(Axes.xcorr) +@_autogen_docstring(Axes.xcorr) def xcorr(x, y, normed=True, detrend=mlab.detrend_none, usevlines=True, maxlags=10, hold=None, **kwargs): ax = gca() # allow callers to override the hold state by passing hold=True|False @@ -2761,7 +2838,7 @@ def xcorr(x, y, normed=True, detrend=mlab.detrend_none, usevlines=True, maxlags= # This function was autogenerated by boilerplate.py. Do not edit as # changes will be lost -@autogen_docstring(Axes.barbs) +@_autogen_docstring(Axes.barbs) def barbs(*args, **kw): ax = gca() # allow callers to override the hold state by passing hold=True|False @@ -3090,3 +3167,24 @@ def spectral(): draw_if_interactive() +# This function was autogenerated by boilerplate.py +def _colormaps(): + return [ + 'autumn', + 'bone', + 'cool', + 'copper', + 'flag', + 'gray', + 'hot', + 'hsv', + 'jet', + 'pink', + 'prism', + 'spring', + 'summer', + 'winter', + 'spectral', + ] + +_setup_pyplot_info_docstrings() diff --git a/lib/matplotlib/tri/tricontour.py b/lib/matplotlib/tri/tricontour.py index 1dcbe4a7af47..af4bf849b23e 100644 --- a/lib/matplotlib/tri/tricontour.py +++ b/lib/matplotlib/tri/tricontour.py @@ -91,10 +91,10 @@ def _contour_args(self, args, kwargs): return (tri, z) tricontour_doc = """ + Draw contours on an unstructured triangular grid. :func:`~matplotlib.pyplot.tricontour` and :func:`~matplotlib.pyplot.tricontourf` draw contour lines and - filled contours, respectively, on an unstructured triangular - grid. Except as noted, function + filled contours, respectively. Except as noted, function signatures and return values are the same for both versions. The triangulation can be specified in one of two ways; either:: diff --git a/lib/matplotlib/tri/tripcolor.py b/lib/matplotlib/tri/tripcolor.py index 2748cd0a4fc5..56e622b58ce4 100644 --- a/lib/matplotlib/tri/tripcolor.py +++ b/lib/matplotlib/tri/tripcolor.py @@ -5,8 +5,7 @@ def tripcolor(ax, *args, **kwargs): """ - Create a pseudocolor plot of an unstructured triangular grid to - the :class:`~matplotlib.axes.Axes`. + Create a pseudocolor plot of an unstructured triangular grid. The triangulation can be specified in one of two ways; either:: diff --git a/lib/matplotlib/tri/triplot.py b/lib/matplotlib/tri/triplot.py index cdd5cb3427df..e8a1aea3d52e 100644 --- a/lib/matplotlib/tri/triplot.py +++ b/lib/matplotlib/tri/triplot.py @@ -6,8 +6,7 @@ def triplot(ax, *args, **kwargs): """ - Draw a unstructured triangular grid as lines and/or markers to - the :class:`~matplotlib.axes.Axes`. + Draw a unstructured triangular grid as lines and/or markers. The triangulation to plot can be specified in one of two ways; either:: From cd4c33582343a08cf8d1f57ac1413be506acaa40 Mon Sep 17 00:00:00 2001 From: Michael Droettboom Date: Thu, 16 Aug 2012 17:03:23 -0400 Subject: [PATCH 08/12] Fix small typo listing members to exclude --- doc/api/pyplot_api.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/api/pyplot_api.rst b/doc/api/pyplot_api.rst index e1675de4fb22..94e3baac26f0 100644 --- a/doc/api/pyplot_api.rst +++ b/doc/api/pyplot_api.rst @@ -10,4 +10,4 @@ pyplot :members: :undoc-members: :show-inheritance: - :exclude-members: plotting colormaps + :exclude-members: plotting, colormaps From 5a2d0a6722410744918813c7eaf9a0ff68827cda Mon Sep 17 00:00:00 2001 From: Michael Droettboom Date: Fri, 17 Aug 2012 11:32:54 -0400 Subject: [PATCH 09/12] Add docstring to _setup_plot_info_docstrings --- lib/matplotlib/pyplot.py | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/lib/matplotlib/pyplot.py b/lib/matplotlib/pyplot.py index 44200f4ffdaf..82e0d0272288 100644 --- a/lib/matplotlib/pyplot.py +++ b/lib/matplotlib/pyplot.py @@ -1708,6 +1708,14 @@ def colormaps(): def _setup_pyplot_info_docstrings(): + """ + Generates the plotting and colormaps docstrings. + + These must be done after the entire module is imported, so it is + called from the end of this module, which is generated by + boilerplate.py. + """ + # Generate the plotting docstring import re def pad(s, l): From fe2e95d6052fa1d9fe4eaa7a5c6d5964ffacaf19 Mon Sep 17 00:00:00 2001 From: Michael Droettboom Date: Fri, 17 Aug 2012 11:33:06 -0400 Subject: [PATCH 10/12] Update credits --- doc/users/credits.rst | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/doc/users/credits.rst b/doc/users/credits.rst index 3f8bdddf5c03..50930f7d5e79 100644 --- a/doc/users/credits.rst +++ b/doc/users/credits.rst @@ -196,6 +196,13 @@ Tony Yu has contributed stream plotting among many other improvements. He is the author of mpltools. +Michiel de Hoon + Wrote and maintains the macosx backend. + +Ian Thomas + Contributed, among other things, the triangulation (tricolor and + tripcontour) methods. + Benjamin Root Has significantly improved the capabilities of the 3D plotting. He has improved matplotlib's documentation and code quality throughout, From a906f58e42ea1b793a0b61f608bb24cacf29b97c Mon Sep 17 00:00:00 2001 From: Michael Droettboom Date: Fri, 17 Aug 2012 13:25:57 -0400 Subject: [PATCH 11/12] Remove hard-coded docstring on plotting() --- lib/matplotlib/pyplot.py | 84 ---------------------------------------- 1 file changed, 84 deletions(-) diff --git a/lib/matplotlib/pyplot.py b/lib/matplotlib/pyplot.py index 82e0d0272288..3ac13e9b3ea1 100644 --- a/lib/matplotlib/pyplot.py +++ b/lib/matplotlib/pyplot.py @@ -1518,90 +1518,6 @@ def thetagrids(*args, **kwargs): ## Plotting Info ## def plotting(): - """ - Plotting commands - - =============== ========================================================= - Command Description - =============== ========================================================= - axes Create a new axes - axis Set or return the current axis limits - bar make a bar chart - boxplot make a box and whiskers chart - cla clear current axes - clabel label a contour plot - clf clear a figure window - close close a figure window - colorbar add a colorbar to the current figure - cohere make a plot of coherence - contour make a contour plot - contourf make a filled contour plot - csd make a plot of cross spectral density - draw force a redraw of the current figure - errorbar make an errorbar graph - figlegend add a legend to the figure - figimage add an image to the figure, w/o resampling - figtext add text in figure coords - figure create or change active figure - fill make filled polygons - fill_between make filled polygons between two sets of y-values - fill_betweenx make filled polygons between two sets of x-values - gca return the current axes - gcf return the current figure - gci get the current image, or None - getp get a graphics property - hist make a histogram - hold set the hold state on current axes - legend add a legend to the axes - loglog a log log plot - imread load image file into array - imsave save array as an image file - imshow plot image data - matshow display a matrix in a new figure preserving aspect - pcolor make a pseudocolor plot - plot make a line plot - plotfile plot data from a flat file - psd make a plot of power spectral density - quiver make a direction field (arrows) plot - rc control the default params - savefig save the current figure - scatter make a scatter plot - setp set a graphics property - semilogx log x axis - semilogy log y axis - show in non-interactive mode, display all figures and block - until they have been closed; in interactive mode, - show generally has no effect. - specgram a spectrogram plot - stem make a stem plot - subplot make a subplot (numrows, numcols, axesnum) - table add a table to the axes - text add some text at location x,y to the current axes - title add a title to the current axes - xlabel add an xlabel to the current axes - ylabel add a ylabel to the current axes - =============== ========================================================= - - The following commands will set the default colormap accordingly: - - * autumn - * bone - * cool - * copper - * flag - * gray - * hot - * hsv - * jet - * pink - * prism - * spring - * summer - * winter - * spectral - - """ - # TODO: Generate this automatically pass From f537d1e3584c41c2aae7636f6d914230a247ac59 Mon Sep 17 00:00:00 2001 From: Michael Droettboom Date: Fri, 17 Aug 2012 14:28:04 -0400 Subject: [PATCH 12/12] Fix hist2d docstring. --- lib/matplotlib/axes.py | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/lib/matplotlib/axes.py b/lib/matplotlib/axes.py index a8d952932143..6f6a76cc74a7 100644 --- a/lib/matplotlib/axes.py +++ b/lib/matplotlib/axes.py @@ -8114,9 +8114,12 @@ def hist(self, x, bins=10, range=None, normed=False, weights=None, def hist2d(self, x, y, bins = 10, range=None, normed=False, weights=None, cmin=None, cmax=None, **kwargs): """ + Make a 2D histogram plot. + Call signature:: - hist2d(x, y, bins = None, range=None, weights=None, cmin=None, cmax=None **kwargs) + hist2d(x, y, bins = None, range=None, weights=None, cmin=None, cmax=None **kwargs) + Make a 2d histogram plot of *x* versus *y*, where *x*, *y* are 1-D sequences of the same length