diff --git a/boilerplate.py b/boilerplate.py index b1a430a0f98f..1572158c30d1 100644 --- a/boilerplate.py +++ b/boilerplate.py @@ -42,7 +42,7 @@ PLOT_TEMPLATE = AUTOGEN_MSG + """ -@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 @@ -216,7 +216,7 @@ def format_value(value): call.append('%s' % arg) else: call.append('%s=%s' % (arg, arg)) - + if varargs is not None: call.append('*'+varargs) if varkw is not None: @@ -286,6 +286,8 @@ def format_value(value): for name in cmaps: yield CMAP_TEMPLATE.format(name=name) + yield '' + yield '_setup_pyplot_info_docstrings()' def build_pyplot(): pyplot_path = os.path.join(os.path.dirname(__file__), 'lib', diff --git a/doc/_templates/index.html b/doc/_templates/index.html index fdf1d417607d..4edb3d532c4f 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,23 +52,17 @@

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 +

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

@@ -44,1266 +73,89 @@

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 +consider donating +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.

    - 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..94e3baac26f0 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/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))) diff --git a/doc/users/credits.rst b/doc/users/credits.rst index d1a6200c19b8..50930f7d5e79 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,39 @@ 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. + +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, + 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. diff --git a/lib/matplotlib/__init__.py b/lib/matplotlib/__init__.py index 2737c5237939..4ef3eb512e84 100644 --- a/lib/matplotlib/__init__.py +++ b/lib/matplotlib/__init__.py @@ -892,7 +892,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 072b44bf5136..6ce12b083748 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 5c3ddf2f9554..a8d952932143 100644 --- a/lib/matplotlib/axes.py +++ b/lib/matplotlib/axes.py @@ -835,7 +835,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() @@ -1711,7 +1711,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:: @@ -1781,6 +1781,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 @@ -2065,6 +2067,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) @@ -2102,8 +2106,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: @@ -2190,7 +2194,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: @@ -2229,8 +2233,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: @@ -3255,6 +3258,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) @@ -3335,6 +3340,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', @@ -3359,12 +3367,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 @@ -3424,12 +3432,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 @@ -3489,12 +3497,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. @@ -3546,12 +3554,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. @@ -3605,6 +3613,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) @@ -3692,6 +3702,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') @@ -3905,6 +3917,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) @@ -3974,12 +3988,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` / @@ -4034,12 +4048,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`. @@ -4085,12 +4099,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`. @@ -4136,14 +4150,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)`` @@ -4198,15 +4214,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)`` @@ -4328,13 +4346,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:: @@ -4532,12 +4552,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. @@ -4565,6 +4587,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) @@ -4843,6 +4867,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) @@ -4914,6 +4940,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) @@ -4957,6 +4985,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-') @@ -5009,6 +5039,8 @@ def pie(self, x, explode=None, labels=None, colors=None, autopct=None, pctdistance=0.6, shadow=False, labeldistance=1.1, startangle=None, radius=None): r""" + Plot a pie chart. + Call signature:: pie(x, explode=None, labels=None, @@ -5182,6 +5214,8 @@ def errorbar(self, x, y, yerr=None, xerr=None, xlolims=False, xuplims=False, errorevery=1, capthick=None, **kwargs): """ + Plot an errorbar graph. + Call signature:: errorbar(x, y, yerr=None, xerr=None, @@ -5492,6 +5526,8 @@ def boxplot(self, x, notch=False, sym='b+', vert=True, whis=1.5, positions=None, widths=None, patch_artist=False, bootstrap=None, usermedians=None, conf_intervals=None): """ + Make a box and whisker plot. + Call signature:: boxplot(x, notch=False, sym='+', vert=True, whis=1.5, @@ -5837,6 +5873,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, @@ -6025,6 +6063,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, @@ -6461,6 +6501,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) @@ -6541,15 +6583,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' ) @@ -6590,6 +6634,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) @@ -6728,6 +6774,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) @@ -6841,6 +6889,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, @@ -7005,13 +7055,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 @@ -7234,6 +7284,8 @@ def pcolor(self, *args, **kwargs): @docstring.dedent_interpd def pcolormesh(self, *args, **kwargs): """ + Plot a quadrilateral mesh. + Call signatures:: pcolormesh(C) @@ -7555,6 +7607,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, @@ -7563,11 +7617,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. @@ -7644,6 +7697,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, @@ -8123,6 +8178,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, @@ -8195,6 +8252,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, @@ -8264,14 +8323,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:: @@ -8322,6 +8383,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, @@ -8393,6 +8456,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 4b9c5ec3db4e..7abcbb91f7e6 100644 --- a/lib/matplotlib/contour.py +++ b/lib/matplotlib/contour.py @@ -52,11 +52,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. @@ -1409,6 +1411,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 a9c0b3300f69..ce8a11f6945d 100644 --- a/lib/matplotlib/figure.py +++ b/lib/matplotlib/figure.py @@ -464,6 +464,8 @@ def figimage(self, X, origin=None, **kwargs): """ + Adds a non-resampled image to the figure. + call signatures:: figimage(X, **kwargs) @@ -1041,6 +1043,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) @@ -1134,14 +1138,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 4719667f3a9a..0c50fa460d54 100644 --- a/lib/matplotlib/image.py +++ b/lib/matplotlib/image.py @@ -1042,7 +1042,7 @@ def __init__(self, bbox, interp_at_native is a flag that determines whether or not interpolation should still be applied when the image is displayed at its native resolution. A common - use case for this is when displaying an image for annotational purposes; it is + use case for this is when displaying an image for annotational purposes; it is treated similarly to Photoshop (interpolation is only used when displaying the image at non-native resolutions). @@ -1167,9 +1167,10 @@ 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. If using a file - object, it must be opened in binary mode. + Read an image from a file into an array. + + *fname* may be a string path or a Python file-like object. If + using a file object, it must be opened in binary mode. If *format* is provided, will try to read file of that type, otherwise the format is deduced from the filename. If nothing can @@ -1234,7 +1235,8 @@ def pilread(fname): 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 9ad92c4d034d..15a309307dab 100644 --- a/lib/matplotlib/pyplot.py +++ b/lib/matplotlib/pyplot.py @@ -104,13 +104,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. """ @@ -123,6 +123,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. @@ -142,7 +144,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() @@ -202,25 +204,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. """ @@ -254,11 +256,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 @@ -400,7 +403,7 @@ def disconnect(cid): def close(*args): """ - Close a figure window + Close a figure window. ``close()`` by itself closes the current figure @@ -439,7 +442,7 @@ def close(*args): def clf(): """ - Clear the current figure + Clear the current figure. """ gcf().clf() draw_if_interactive() @@ -586,13 +589,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) @@ -609,7 +614,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. @@ -654,7 +661,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 @@ -669,8 +676,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: @@ -706,7 +714,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) @@ -997,10 +1007,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) @@ -1009,8 +1018,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() @@ -1033,9 +1040,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:: @@ -1051,9 +1059,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() @@ -1065,14 +1074,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 @@ -1090,7 +1099,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. """ @@ -1116,7 +1125,7 @@ def subplot_tool(targetfig=None): def tight_layout(pad=1.08, h_pad=None, w_pad=None, rect=None): """ - Adjust subplot parameters to give specified padding. + Automatically adjust subplot parameters to give specified padding. Parameters: @@ -1139,8 +1148,8 @@ def tight_layout(pad=1.08, h_pad=None, w_pad=None, rect=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. """ @@ -1153,7 +1162,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:: @@ -1177,7 +1186,7 @@ def title(s, *args, **kwargs): def axis(*v, **kwargs): """ - Set/Get the axis properties: + Set or get the axis properties. >>> axis() @@ -1240,7 +1249,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:: @@ -1261,7 +1270,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:: @@ -1287,7 +1296,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 @@ -1314,7 +1325,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 @@ -1341,11 +1354,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: @@ -1358,11 +1373,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: @@ -1374,7 +1391,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. @@ -1412,7 +1431,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. @@ -1470,8 +1491,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:: @@ -1515,7 +1535,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 @@ -1578,102 +1598,36 @@ 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 - hist2d make a 2d 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 - stackplot make a stacked 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 + pass + +def get_plot_commands(): """ - pass + 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) -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', 'hist2d', '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') + 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(): """ @@ -1955,6 +1909,57 @@ def colormaps(): return sorted(cm.cmap_d.keys()) +def _setup_pyplot_info_docstrings(): + """ + Generates the plotting and docstring. + + 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): + """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) + ## Plotting part 1: manually generated functions and wrappers ## import matplotlib.colorbar @@ -1976,7 +1981,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:: @@ -2001,7 +2006,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 @@ -2073,12 +2078,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, @@ -2095,7 +2102,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 @@ -2214,7 +2221,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" @@ -2223,8 +2230,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 @@ -2247,12 +2253,12 @@ 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 washold = ax.ishold() - + if hold is not None: ax.hold(hold) try: @@ -2260,17 +2266,17 @@ def acorr(x, hold=None, **kwargs): draw_if_interactive() finally: ax.hold(washold) - + return ret # 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 washold = ax.ishold() - + if hold is not None: ax.hold(hold) try: @@ -2278,17 +2284,17 @@ def arrow(x, y, dx, dy, hold=None, **kwargs): draw_if_interactive() finally: ax.hold(washold) - + return ret # 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 washold = ax.ishold() - + if hold is not None: ax.hold(hold) try: @@ -2296,17 +2302,17 @@ def axhline(y=0, xmin=0, xmax=1, hold=None, **kwargs): draw_if_interactive() finally: ax.hold(washold) - + return ret # 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 washold = ax.ishold() - + if hold is not None: ax.hold(hold) try: @@ -2314,17 +2320,17 @@ def axhspan(ymin, ymax, xmin=0, xmax=1, hold=None, **kwargs): draw_if_interactive() finally: ax.hold(washold) - + return ret # 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 washold = ax.ishold() - + if hold is not None: ax.hold(hold) try: @@ -2332,17 +2338,17 @@ def axvline(x=0, ymin=0, ymax=1, hold=None, **kwargs): draw_if_interactive() finally: ax.hold(washold) - + return ret # 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 washold = ax.ishold() - + if hold is not None: ax.hold(hold) try: @@ -2350,17 +2356,17 @@ def axvspan(xmin, xmax, ymin=0, ymax=1, hold=None, **kwargs): draw_if_interactive() finally: ax.hold(washold) - + return ret # This function was autogenerated by boilerplate.py. Do not edit as # changes will be lost -@autogen_docstring(Axes.bar) +@_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() - + if hold is not None: ax.hold(hold) try: @@ -2368,17 +2374,17 @@ def bar(left, height, width=0.8, bottom=None, hold=None, **kwargs): draw_if_interactive() finally: ax.hold(washold) - + return ret # This function was autogenerated by boilerplate.py. Do not edit as # changes will be lost -@autogen_docstring(Axes.barh) +@_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() - + if hold is not None: ax.hold(hold) try: @@ -2386,17 +2392,17 @@ def barh(bottom, width, height=0.8, left=None, hold=None, **kwargs): draw_if_interactive() finally: ax.hold(washold) - + return ret # 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 washold = ax.ishold() - + if hold is not None: ax.hold(hold) try: @@ -2404,19 +2410,19 @@ def broken_barh(xranges, yrange, hold=None, **kwargs): draw_if_interactive() finally: ax.hold(washold) - + return ret # 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=False, sym='b+', vert=True, whis=1.5, positions=None, widths=None, patch_artist=False, bootstrap=None, usermedians=None, conf_intervals=None, hold=None): ax = gca() # allow callers to override the hold state by passing hold=True|False washold = ax.ishold() - + if hold is not None: ax.hold(hold) try: @@ -2427,19 +2433,19 @@ def boxplot(x, notch=False, sym='b+', vert=True, whis=1.5, positions=None, draw_if_interactive() finally: ax.hold(washold) - + return ret # 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 washold = ax.ishold() - + if hold is not None: ax.hold(hold) try: @@ -2449,12 +2455,12 @@ def cohere(x, y, NFFT=256, Fs=2, Fc=0, detrend=mlab.detrend_none, draw_if_interactive() finally: ax.hold(washold) - + return ret # 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 @@ -2467,12 +2473,12 @@ def clabel(CS, *args, **kwargs): draw_if_interactive() finally: ax.hold(washold) - + return ret # 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 @@ -2490,7 +2496,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 @@ -2508,14 +2514,14 @@ 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 washold = ax.ishold() - + if hold is not None: ax.hold(hold) try: @@ -2525,12 +2531,12 @@ def csd(x, y, NFFT=256, Fs=2, Fc=0, detrend=mlab.detrend_none, draw_if_interactive() finally: ax.hold(washold) - + return ret # 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, errorevery=1, capthick=None, @@ -2538,7 +2544,7 @@ def errorbar(x, y, yerr=None, xerr=None, fmt='-', ecolor=None, elinewidth=None, ax = gca() # allow callers to override the hold state by passing hold=True|False washold = ax.ishold() - + if hold is not None: ax.hold(hold) try: @@ -2550,12 +2556,12 @@ def errorbar(x, y, yerr=None, xerr=None, fmt='-', ecolor=None, elinewidth=None, draw_if_interactive() finally: ax.hold(washold) - + return ret # 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 @@ -2568,17 +2574,17 @@ def fill(*args, **kwargs): draw_if_interactive() finally: ax.hold(washold) - + return ret # 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 washold = ax.ishold() - + if hold is not None: ax.hold(hold) try: @@ -2587,17 +2593,17 @@ def fill_between(x, y1, y2=0, where=None, interpolate=False, hold=None, **kwargs draw_if_interactive() finally: ax.hold(washold) - + return ret # 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 washold = ax.ishold() - + if hold is not None: ax.hold(hold) try: @@ -2605,12 +2611,12 @@ def fill_betweenx(y, x1, x2=0, where=None, hold=None, **kwargs): draw_if_interactive() finally: ax.hold(washold) - + return ret # 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', @@ -2619,7 +2625,7 @@ def hexbin(x, y, C=None, gridsize=100, bins=None, xscale='linear', ax = gca() # allow callers to override the hold state by passing hold=True|False washold = ax.ishold() - + if hold is not None: ax.hold(hold) try: @@ -2637,14 +2643,14 @@ def hexbin(x, y, C=None, gridsize=100, bins=None, xscale='linear', # 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 washold = ax.ishold() - + if hold is not None: ax.hold(hold) try: @@ -2656,18 +2662,18 @@ def hist(x, bins=10, range=None, normed=False, weights=None, cumulative=False, draw_if_interactive() finally: ax.hold(washold) - + return ret # This function was autogenerated by boilerplate.py. Do not edit as # changes will be lost -@autogen_docstring(Axes.hist2d) +@_autogen_docstring(Axes.hist2d) def hist2d(x, y, bins=10, range=None, normed=False, weights=None, cmin=None, cmax=None, hold=None, **kwargs): ax = gca() # allow callers to override the hold state by passing hold=True|False washold = ax.ishold() - + if hold is not None: ax.hold(hold) try: @@ -2681,13 +2687,13 @@ def hist2d(x, y, bins=10, range=None, normed=False, weights=None, cmin=None, # 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 washold = ax.ishold() - + if hold is not None: ax.hold(hold) try: @@ -2696,12 +2702,12 @@ def hlines(y, xmin, xmax, colors='k', linestyles='solid', label='', hold=None, draw_if_interactive() finally: ax.hold(washold) - + return ret # 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, @@ -2709,7 +2715,7 @@ def imshow(X, cmap=None, norm=None, aspect=None, interpolation=None, alpha=None, ax = gca() # allow callers to override the hold state by passing hold=True|False washold = ax.ishold() - + if hold is not None: ax.hold(hold) try: @@ -2726,7 +2732,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 @@ -2739,12 +2745,12 @@ def loglog(*args, **kwargs): draw_if_interactive() finally: ax.hold(washold) - + return ret # 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 @@ -2762,7 +2768,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 @@ -2780,14 +2786,14 @@ def pcolormesh(*args, **kwargs): # This function was autogenerated by boilerplate.py. Do not edit as # changes will be lost -@autogen_docstring(Axes.pie) +@_autogen_docstring(Axes.pie) def pie(x, explode=None, labels=None, colors=None, autopct=None, pctdistance=0.6, shadow=False, labeldistance=1.1, startangle=None, radius=None, hold=None): ax = gca() # allow callers to override the hold state by passing hold=True|False washold = ax.ishold() - + if hold is not None: ax.hold(hold) try: @@ -2798,12 +2804,12 @@ def pie(x, explode=None, labels=None, colors=None, autopct=None, draw_if_interactive() finally: ax.hold(washold) - + return ret # 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 @@ -2816,18 +2822,18 @@ def plot(*args, **kwargs): draw_if_interactive() finally: ax.hold(washold) - + return ret # 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 washold = ax.ishold() - + if hold is not None: ax.hold(hold) try: @@ -2836,19 +2842,19 @@ def plot_date(x, y, fmt='bo', tz=None, xdate=True, ydate=False, hold=None, draw_if_interactive() finally: ax.hold(washold) - + return ret # 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 washold = ax.ishold() - + if hold is not None: ax.hold(hold) try: @@ -2858,12 +2864,12 @@ def psd(x, NFFT=256, Fs=2, Fc=0, detrend=mlab.detrend_none, draw_if_interactive() finally: ax.hold(washold) - + return ret # 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 @@ -2881,7 +2887,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 @@ -2894,19 +2900,19 @@ def quiverkey(*args, **kw): draw_if_interactive() finally: ax.hold(washold) - + return ret # 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 washold = ax.ishold() - + if hold is not None: ax.hold(hold) try: @@ -2922,7 +2928,7 @@ def scatter(x, y, s=20, c='b', marker='o', cmap=None, norm=None, vmin=None, # 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 @@ -2935,12 +2941,12 @@ def semilogx(*args, **kwargs): draw_if_interactive() finally: ax.hold(washold) - + return ret # 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 @@ -2953,12 +2959,12 @@ def semilogy(*args, **kwargs): draw_if_interactive() finally: ax.hold(washold) - + return ret # 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, @@ -2966,7 +2972,7 @@ def specgram(x, NFFT=256, Fs=2, Fc=0, detrend=mlab.detrend_none, ax = gca() # allow callers to override the hold state by passing hold=True|False washold = ax.ishold() - + if hold is not None: ax.hold(hold) try: @@ -2982,7 +2988,7 @@ def specgram(x, NFFT=256, Fs=2, Fc=0, detrend=mlab.detrend_none, # This function was autogenerated by boilerplate.py. Do not edit as # changes will be lost -@autogen_docstring(Axes.stackplot) +@_autogen_docstring(Axes.stackplot) def stackplot(x, *args, **kwargs): ax = gca() # allow callers to override the hold state by passing hold=True|False @@ -3000,13 +3006,13 @@ def stackplot(x, *args, **kwargs): # This function was autogenerated by boilerplate.py. Do not edit as # changes will be lost -@autogen_docstring(Axes.stem) +@_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() - + if hold is not None: ax.hold(hold) try: @@ -3015,12 +3021,12 @@ def stem(x, y, linefmt='b-', markerfmt='bo', basefmt='r-', bottom=None, draw_if_interactive() finally: ax.hold(washold) - + return ret # 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 @@ -3033,19 +3039,19 @@ def step(x, y, *args, **kwargs): draw_if_interactive() finally: ax.hold(washold) - + return ret # This function was autogenerated by boilerplate.py. Do not edit as # changes will be lost -@autogen_docstring(Axes.streamplot) +@_autogen_docstring(Axes.streamplot) def streamplot(x, y, u, v, density=1, linewidth=None, color=None, cmap=None, norm=None, arrowsize=1, arrowstyle='-|>', minlength=0.1, hold=None): ax = gca() # allow callers to override the hold state by passing hold=True|False washold = ax.ishold() - + if hold is not None: ax.hold(hold) try: @@ -3061,7 +3067,7 @@ def streamplot(x, y, u, v, density=1, linewidth=None, color=None, cmap=None, # 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 @@ -3079,7 +3085,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 @@ -3097,7 +3103,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 @@ -3115,7 +3121,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 @@ -3128,18 +3134,18 @@ def triplot(*args, **kwargs): draw_if_interactive() finally: ax.hold(washold) - + return ret # 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 washold = ax.ishold() - + if hold is not None: ax.hold(hold) try: @@ -3148,18 +3154,18 @@ def vlines(x, ymin, ymax, colors='k', linestyles='solid', label='', hold=None, draw_if_interactive() finally: ax.hold(washold) - + return ret # 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 washold = ax.ishold() - + if hold is not None: ax.hold(hold) try: @@ -3168,12 +3174,12 @@ def xcorr(x, y, normed=True, detrend=mlab.detrend_none, usevlines=True, draw_if_interactive() finally: ax.hold(washold) - + return ret # 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 @@ -3186,7 +3192,7 @@ def barbs(*args, **kw): draw_if_interactive() finally: ax.hold(washold) - + return ret # This function was autogenerated by boilerplate.py. Do not edit as @@ -3501,3 +3507,4 @@ def spectral(): im.set_cmap(cm.spectral) draw_if_interactive() +_setup_pyplot_info_docstrings() diff --git a/lib/matplotlib/tri/tricontour.py b/lib/matplotlib/tri/tricontour.py index 3de074053376..8e4f4117ef87 100644 --- a/lib/matplotlib/tri/tricontour.py +++ b/lib/matplotlib/tri/tricontour.py @@ -92,10 +92,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 b65290bcaa6a..575a5fbc1e79 100644 --- a/lib/matplotlib/tri/tripcolor.py +++ b/lib/matplotlib/tri/tripcolor.py @@ -6,8 +6,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 3a852aa96074..cb2418a2f338 100644 --- a/lib/matplotlib/tri/triplot.py +++ b/lib/matplotlib/tri/triplot.py @@ -7,8 +7,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::