Menu
▾
▴
SF.net SVN: matplotlib:[7282] trunk/matplotlib
|
From: <jo...@us...> - 2009-07-22 13:08:44
|
Revision: 7282
http://matplotlib.svn.sourceforge.net/matplotlib/?rev=7282&view=rev
Author: jouni
Date: 2009-07-22 13:08:41 +0000 (Wed, 22 Jul 2009)
Log Message:
-----------
Improved boilerplate.py so that it generates the correct signatures for pyplot functions.
Modified Paths:
--------------
trunk/matplotlib/CHANGELOG
trunk/matplotlib/boilerplate.py
trunk/matplotlib/lib/matplotlib/pyplot.py
Modified: trunk/matplotlib/CHANGELOG
===================================================================
--- trunk/matplotlib/CHANGELOG 2009-07-22 10:54:35 UTC (rev 7281)
+++ trunk/matplotlib/CHANGELOG 2009-07-22 13:08:41 UTC (rev 7282)
@@ -1,3 +1,6 @@
+2009-07-22 Improved boilerplate.py so that it generates the correct
+ signatures for pyplot functions. - JKS
+
2009-07-19 Fixed the docstring of Axes.step to reflect the correct
meaning of the kwargs "pre" and "post" - See SF bug
https://sourceforge.net/tracker/index.php?func=detail&aid=2823304&group_id=80706&atid=560720
Modified: trunk/matplotlib/boilerplate.py
===================================================================
--- trunk/matplotlib/boilerplate.py 2009-07-22 10:54:35 UTC (rev 7281)
+++ trunk/matplotlib/boilerplate.py 2009-07-22 13:08:41 UTC (rev 7282)
@@ -1,47 +1,50 @@
-# wrap the plot commands defined in axes. The code generated by this
+# Wrap the plot commands defined in axes. The code generated by this
# file is pasted into pylab.py. We did try to do this the smart way,
# with callable functions and new.function, but could never get the
# docstrings right for python2.2. See
# http://groups.google.com/group/comp.lang.python/browse_frm/thread/dcd63ec13096a0f6/1b14640f3a4ad3dc?#1b14640f3a4ad3dc
+# For some later history, see
+# http://thread.gmane.org/gmane.comp.python.matplotlib.devel/7068
+import inspect
+import random
+import re
+import sys
+import types
-# note we check for __doc__ is not None since py2exe optimize removes
-# the docstrings
+# import the local copy of matplotlib, not the installed one
+sys.path.insert(0, './lib')
+from matplotlib.axes import Axes
+from matplotlib.cbook import dedent
_fmtplot = """\
# This function was autogenerated by boilerplate.py. Do not edit as
# changes will be lost
-def %(func)s(*args, **kwargs):
+def %(func)s(%(argspec)s):
+ %(docstring)s
+ %(ax)s = gca()
# allow callers to override the hold state by passing hold=True|False
- b = ishold()
- h = kwargs.pop('hold', None)
- if h is not None:
- hold(h)
+ %(washold)s = %(ax)s.ishold()
+ %(sethold)s
+ if hold is not None:
+ %(ax)s.hold(hold)
try:
- ret = gca().%(func)s(*args, **kwargs)
+ %(ret)s = %(ax)s.%(func)s(%(call)s)
draw_if_interactive()
- except:
- hold(b)
- raise
+ finally:
+ %(ax)s.hold(%(washold)s)
%(mappable)s
- hold(b)
- return ret
-if Axes.%(func)s.__doc__ is not None:
- %(func)s.__doc__ = dedent(Axes.%(func)s.__doc__) + \"\"\"
-
-Additional kwargs: hold = [True|False] overrides default hold state\"\"\"
+ return %(ret)s
"""
_fmtmisc = """\
# This function was autogenerated by boilerplate.py. Do not edit as
# changes will be lost
-def %(func)s(*args, **kwargs):
-
- ret = gca().%(func)s(*args, **kwargs)
+def %(func)s(%(argspec)s):
+ %(docstring)s
+ %(ret)s = gca().%(func)s(%(call)s)
draw_if_interactive()
- return ret
-if Axes.%(func)s.__doc__ is not None:
- %(func)s.__doc__ = dedent(Axes.%(func)s.__doc__)
+ return %(ret)s
"""
# these methods are all simple wrappers of Axes methods by the same
@@ -101,33 +104,113 @@
)
cmappable = {
- 'contour' : 'if ret._A is not None: gci._current = ret',
- 'contourf': 'if ret._A is not None: gci._current = ret',
- 'hexbin' : 'gci._current = ret[0]',
- 'scatter' : 'gci._current = ret',
- 'pcolor' : 'gci._current = ret',
- 'pcolormesh' : 'gci._current = ret',
- 'imshow' : 'gci._current = ret',
- 'spy' : 'gci._current = ret',
- 'quiver' : 'gci._current = ret',
- 'specgram' : 'gci._current = ret[-1]',
+ 'contour' : 'if %(ret)s._A is not None: gci._current = %(ret)s',
+ 'contourf': 'if %(ret)s._A is not None: gci._current = %(ret)s',
+ 'hexbin' : 'gci._current = %(ret)s',
+ 'scatter' : 'gci._current = %(ret)s',
+ 'pcolor' : 'gci._current = %(ret)s',
+ 'pcolormesh' : 'gci._current = %(ret)s',
+ 'imshow' : 'gci._current = %(ret)s',
+ 'spy' : 'gci._current = %(ret)s',
+ 'quiver' : 'gci._current = %(ret)s',
+ 'specgram' : 'gci._current = %(ret)s[-1]',
}
+def format_value(value):
+ """
+ Format function default values as needed for inspect.formatargspec.
+ The interesting part is a hard-coded list of functions used
+ as defaults in pyplot methods.
+ """
+ if isinstance(value, types.FunctionType):
+ if value.func_name in ('detrend_none', 'window_hanning'):
+ return '=mlab.' + value.func_name
+ if value.func_name == 'mean':
+ return '=np.' + value.func_name
+ raise ValueError, ('default value %s unknown to boilerplate.formatvalue'
+ % value)
+ return '='+repr(value)
-for func in _plotcommands:
- if func in cmappable:
- mappable = cmappable[func]
- else:
- mappable = ''
- print _fmtplot%locals()
+def remove_final_whitespace(string):
+ """
+ Return a copy of *string* with final whitespace removed from each line.
+ """
+ return '\n'.join(x.rstrip() for x in string.split('\n'))
+def make_docstring(cmd, mention_hold):
+ func = getattr(Axes, cmd)
+ docstring = inspect.getdoc(func)
+ if docstring is None:
+ return ""
+ escaped = re.sub(r'\\', r'\\\\', docstring)
+ if mention_hold:
+ escaped += '''
-for func in _misccommands:
- print _fmtmisc%locals()
+Additional kwargs: hold = [True|False] overrides default hold state
+'''
+ return '"""'+escaped+'"""'
+for fmt,cmdlist in (_fmtplot,_plotcommands),(_fmtmisc,_misccommands):
+ for func in cmdlist:
+ # For some commands, an additional line is needed to set the
+ # color map
+ if func in cmappable:
+ mappable = cmappable[func] % locals()
+ else:
+ mappable = ''
+ # Format docstring
+ docstring = make_docstring(func, fmt is _fmtplot)
+ # Get argspec of wrapped function
+ args, varargs, varkw, defaults = inspect.getargspec(getattr(Axes, func))
+ args.pop(0) # remove 'self' argument
+ if defaults is None:
+ defaults = ()
+
+ # How to call the wrapped function
+ call = map(str, args)
+ if varargs is not None:
+ call.append('*'+varargs)
+ if varkw is not None:
+ call.append('**'+varkw)
+ call = ', '.join(call)
+
+ # Add a hold keyword argument if needed (fmt is _fmtplot) and
+ # possible (if *args is used, we can't just add a hold
+ # argument in front of it since it would gobble one of the
+ # arguments the user means to pass via *args)
+ if varargs:
+ sethold = "hold = %(varkw)s.pop('hold', None)" % locals()
+ elif fmt is _fmtplot:
+ args.append('hold')
+ defaults = defaults + (None,)
+ sethold = ''
+
+ # Now we can build the argspec for defining the wrapper
+ argspec = inspect.formatargspec(args, varargs, varkw, defaults,
+ formatvalue=format_value)
+ argspec = argspec[1:-1] # remove parens
+
+ # A gensym-like facility in case some function takes an
+ # argument named washold, ax, or ret
+ washold,ret,ax = 'washold', 'ret', 'ax'
+ bad = set(args) | set((varargs, varkw))
+ while washold in bad or ret in bad or ax in bad:
+ washold = 'washold' + str(random.randrange(10**12))
+ ret = 'ret' + str(random.randrange(10**12))
+ ax = 'ax' + str(random.randrange(10**12))
+
+ # Since we can't avoid using some function names,
+ # bail out if they are used as argument names
+ for reserved in ('gca', 'gci', 'draw_if_interactive'):
+ if reserved in bad:
+ raise ValueError, \
+ 'Axes method %s has kwarg named %s' % (func, reserved)
+
+ print remove_final_whitespace(fmt%locals())
+
# define the colormap functions
_fmtcmap = """\
# This function was autogenerated by boilerplate.py. Do not edit as
Modified: trunk/matplotlib/lib/matplotlib/pyplot.py
===================================================================
--- trunk/matplotlib/lib/matplotlib/pyplot.py 2009-07-22 10:54:35 UTC (rev 7281)
+++ trunk/matplotlib/lib/matplotlib/pyplot.py 2009-07-22 13:08:41 UTC (rev 7282)
@@ -13,12 +13,14 @@
from matplotlib.artist import setp as _setp
from matplotlib.axes import Axes
from matplotlib.projections import PolarAxes
-from matplotlib import mlab # for csv2rec in plotfile
+from matplotlib import mlab # for csv2rec, detrend_none, window_hanning
from matplotlib.scale import get_scale_docs, get_scale_names
from matplotlib import cm
from matplotlib.cm import get_cmap
+import numpy as np
+
# We may not need the following imports here:
from matplotlib.colors import Normalize, normalize # latter for backwards compat.
from matplotlib.lines import Line2D
@@ -1593,987 +1595,5048 @@
# This function was autogenerated by boilerplate.py. Do not edit as
# changes will be lost
-def acorr(*args, **kwargs):
+def acorr(x, hold=None, **kwargs):
+ """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).
+
+Data are plotted as ``plot(lags, c, **kwargs)``
+
+Return value is a tuple (*lags*, *c*, *line*) where:
+
+ - *lags* are a length 2*maxlags+1 lag vector
+
+ - *c* is the 2*maxlags+1 auto correlation vector
+
+ - *line* is a :class:`~matplotlib.lines.Line2D` instance
+ returned by :meth:`plot`
+
+The default *linestyle* is None and the default *marker* is
+``'o'``, though these can be overridden with keyword args.
+The cross correlation is performed with
+:func:`numpy.correlate` with *mode* = 2.
+
+If *usevlines* is *True*, :meth:`~matplotlib.axes.Axes.vlines`
+rather than :meth:`~matplotlib.axes.Axes.plot` is used to draw
+vertical lines from the origin to the acorr. Otherwise, the
+plot style is determined by the kwargs, which are
+:class:`~matplotlib.lines.Line2D` properties.
+
+*maxlags* is a positive integer detailing the number of lags
+to show. The default value of *None* will return all
+:math:`2 \\mathrm{len}(x) - 1` lags.
+
+The return value is a tuple (*lags*, *c*, *linecol*, *b*)
+where
+
+- *linecol* is the
+ :class:`~matplotlib.collections.LineCollection`
+
+- *b* is the *x*-axis.
+
+.. seealso::
+
+ :meth:`~matplotlib.axes.Axes.plot` or
+ :meth:`~matplotlib.axes.Axes.vlines`
+ For documentation on valid kwargs.
+
+**Example:**
+
+:func:`~matplotlib.pyplot.xcorr` above, and
+:func:`~matplotlib.pyplot.acorr` below.
+
+**Example:**
+
+.. plot:: mpl_examples/pylab_examples/xcorr_demo.py
+
+Additional kwargs: hold = [True|False] overrides default hold state
+"""
+ ax = gca()
# allow callers to override the hold state by passing hold=True|False
- b = ishold()
- h = kwargs.pop('hold', None)
- if h is not None:
- hold(h)
+ washold = ax.ishold()
+
+ if hold is not None:
+ ax.hold(hold)
try:
- ret = gca().acorr(*args, **kwargs)
+ ret = ax.acorr(x, **kwargs)
draw_if_interactive()
- except:
- hold(b)
- raise
+ finally:
+ ax.hold(washold)
- hold(b)
return ret
-if Axes.acorr.__doc__ is not None:
- acorr.__doc__ = dedent(Axes.acorr.__doc__) + """
-Additional kwargs: hold = [True|False] overrides default hold state"""
-
# This function was autogenerated by boilerplate.py. Do not edit as
# changes will be lost
-def arrow(*args, **kwargs):
+def arrow(x, y, dx, dy, hold=None, **kwargs):
+ """call signature::
+
+ arrow(x, y, dx, dy, **kwargs)
+
+Draws arrow on specified axis from (*x*, *y*) to (*x* + *dx*,
+*y* + *dy*).
+
+Optional kwargs control the arrow properties:
+ alpha: float (0.0 transparent through 1.0 opaque)
+ animated: [True | False]
+ antialiased or aa: [True | False] or None for default
+ axes: an :class:`~matplotlib.axes.Axes` instance
+ clip_box: a :class:`matplotlib.transforms.Bbox` instance
+ clip_on: [True | False]
+ clip_path: [ (:class:`~matplotlib.path.Path`, :class:`~matplotlib.transforms.Transform`) | :class:`~matplotlib.patches.Patch` | None ]
+ color: matplotlib color arg or sequence of rgba tuples
+ contains: a callable function
+ edgecolor or ec: mpl color spec, or None for default, or 'none' for no color
+ facecolor or fc: mpl color spec, or None for default, or 'none' for no color
+ figure: a :class:`matplotlib.figure.Figure` instance
+ fill: [True | False]
+ gid: an id string
+ hatch: [ '/' | '\\\\' | '|' | '-' | '+' | 'x' | 'o' | 'O' | '.' | '*' ]
+ label: any string
+ linestyle or ls: ['solid' | 'dashed' | 'dashdot' | 'dotted']
+ linewidth or lw: float or None for default
+ lod: [True | False]
+ picker: [None|float|boolean|callable]
+ rasterized: [True | False | None]
+ snap: unknown
+ transform: :class:`~matplotlib.transforms.Transform` instance
+ url: a url string
+ visible: [True | False]
+ zorder: any number
+
+**Example:**
+
+.. plot:: mpl_examples/pylab_examples/arrow_demo.py
+
+Additional kwargs: hold = [True|False] overrides default hold state
+"""
+ ax = gca()
# allow callers to override the hold state by passing hold=True|False
- b = ishold()
- h = kwargs.pop('hold', None)
- if h is not None:
- hold(h)
+ washold = ax.ishold()
+
+ if hold is not None:
+ ax.hold(hold)
try:
- ret = gca().arrow(*args, **kwargs)
+ ret = ax.arrow(x, y, dx, dy, **kwargs)
draw_if_interactive()
- except:
- hold(b)
- raise
+ finally:
+ ax.hold(washold)
- hold(b)
return ret
-if Axes.arrow.__doc__ is not None:
- arrow.__doc__ = dedent(Axes.arrow.__doc__) + """
-Additional kwargs: hold = [True|False] overrides default hold state"""
-
# This function was autogenerated by boilerplate.py. Do not edit as
# changes will be lost
-def axhline(*args, **kwargs):
+def axhline(y=0, xmin=0, xmax=1, hold=None, **kwargs):
+ """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
+the xlim settings, even if you change them, eg. with the
+:meth:`set_xlim` command. That is, the horizontal extent is
+in axes coords: 0=left, 0.5=middle, 1.0=right but the *y*
+location is in data coordinates.
+
+Return value is the :class:`~matplotlib.lines.Line2D`
+instance. kwargs are the same as kwargs to plot, and can be
+used to control the line properties. Eg.,
+
+* draw a thick red hline at *y* = 0 that spans the xrange
+
+ >>> axhline(linewidth=4, color='r')
+
+* draw a default hline at *y* = 1 that spans the xrange
+
+ >>> axhline(y=1)
+
+* draw a default hline at *y* = .5 that spans the the middle half of
+ the xrange
+
+ >>> axhline(y=.5, xmin=0.25, xmax=0.75)
+
+Valid kwargs are :class:`~matplotlib.lines.Line2D` properties:
+
+ alpha: float (0.0 transparent through 1.0 opaque)
+ animated: [True | False]
+ antialiased or aa: [True | False]
+ axes: an :class:`~matplotlib.axes.Axes` instance
+ clip_box: a :class:`matplotlib.transforms.Bbox` instance
+ clip_on: [True | False]
+ clip_path: [ (:class:`~matplotlib.path.Path`, :class:`~matplotlib.transforms.Transform`) | :class:`~matplotlib.patches.Patch` | None ]
+ color or c: any matplotlib color
+ contains: a callable function
+ dash_capstyle: ['butt' | 'round' | 'projecting']
+ dash_joinstyle: ['miter' | 'round' | 'bevel']
+ dashes: sequence of on/off ink in points
+ data: 2D array
+ drawstyle: [ 'default' | 'steps' | 'steps-pre' | 'steps-mid' | 'steps-post' ]
+ figure: a :class:`matplotlib.figure.Figure` instance
+ fillstyle: ['full' | 'left' | 'right' | 'bottom' | 'top']
+ gid: an id string
+ label: any string
+ linestyle or ls: [ '-' | '--' | '-.' | ':' | 'None' | ' ' | '' ] and any drawstyle in combination with a linestyle, e.g. 'steps--'.
+ linewidth or lw: float value in points
+ lod: [True | False]
+ marker: [ '+' | '*' | ',' | '.' | '1' | '2' | '3' | '4' | '<' | '>' | 'D' | 'H' | '^' | '_' | 'd' | 'h' | 'o' | 'p' | 's' | 'v' | 'x' | '|' | TICKUP | TICKDOWN | TICKLEFT | TICKRIGHT | 'None' | ' ' | '' ]
+ markeredgecolor or mec: any matplotlib color
+ markeredgewidth or mew: float value in points
+ markerfacecolor or mfc: any matplotlib color
+ markersize or ms: float
+ markevery: None | integer | (startind, stride)
+ picker: float distance in points or callable pick function ``fn(artist, event)``
+ pickradius: float distance in points
+ rasterized: [True | False | None]
+ snap: unknown
+ solid_capstyle: ['butt' | 'round' | 'projecting']
+ solid_joinstyle: ['miter' | 'round' | 'bevel']
+ transform: a :class:`matplotlib.transforms.Transform` instance
+ url: a url string
+ visible: [True | False]
+ xdata: 1D array
+ ydata: 1D array
+ zorder: any number
+
+.. seealso::
+
+ :meth:`axhspan`
+ for example plot and source code
+
+Additional kwargs: hold = [True|False] overrides default hold state
+"""
+ ax = gca()
# allow callers to override the hold state by passing hold=True|False
- b = ishold()
- h = kwargs.pop('hold', None)
- if h is not None:
- hold(h)
+ washold = ax.ishold()
+
+ if hold is not None:
+ ax.hold(hold)
try:
- ret = gca().axhline(*args, **kwargs)
+ ret = ax.axhline(y, xmin, xmax, **kwargs)
draw_if_interactive()
- except:
- hold(b)
- raise
+ finally:
+ ax.hold(washold)
- hold(b)
return ret
-if Axes.axhline.__doc__ is not None:
- axhline.__doc__ = dedent(Axes.axhline.__doc__) + """
-Additional kwargs: hold = [True|False] overrides default hold state"""
-
# This function was autogenerated by boilerplate.py. Do not edit as
# changes will be lost
-def axhspan(*args, **kwargs):
+def axhspan(ymin, ymax, xmin=0, xmax=1, hold=None, **kwargs):
+ """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.
+
+Draw a horizontal span (rectangle) from *ymin* to *ymax*.
+With the default values of *xmin* = 0 and *xmax* = 1, this
+always spans the xrange, regardless of the xlim settings, even
+if you change them, eg. with the :meth:`set_xlim` command.
+That is, the horizontal extent is in axes coords: 0=left,
+0.5=middle, 1.0=right but the *y* location is in data
+coordinates.
+
+Return value is a :class:`matplotlib.patches.Polygon`
+instance.
+
+Examples:
+
+* draw a gray rectangle from *y* = 0.25-0.75 that spans the
+ horizontal extent of the axes
+
+ >>> axhspan(0.25, 0.75, facecolor='0.5', alpha=0.5)
+
+Valid kwargs are :class:`~matplotlib.patches.Polygon` properties:
+
+ alpha: float (0.0 transparent through 1.0 opaque)
+ animated: [True | False]
+ antialiased or aa: [True | False] or None for default
+ axes: an :class:`~matplotlib.axes.Axes` instance
+ clip_box: a :class:`matplotlib.transforms.Bbox` instance
+ clip_on: [True | False]
+ clip_path: [ (:class:`~matplotlib.path.Path`, :class:`~matplotlib.transforms.Transform`) | :class:`~matplotlib.patches.Patch` | None ]
+ color: matplotlib color arg or sequence of rgba tuples
+ contains: a callable function
+ edgecolor or ec: mpl color spec, or None for default, or 'none' for no color
+ facecolor or fc: mpl color spec, or None for default, or 'none' for no color
+ figure: a :class:`matplotlib.figure.Figure` instance
+ fill: [True | False]
+ gid: an id string
+ hatch: [ '/' | '\\\\' | '|' | '-' | '+' | 'x' | 'o' | 'O' | '.' | '*' ]
+ label: any string
+ linestyle or ls: ['solid' | 'dashed' | 'dashdot' | 'dotted']
+ linewidth or lw: float or None for default
+ lod: [True | False]
+ picker: [None|float|boolean|callable]
+ rasterized: [True | False | None]
+ snap: unknown
+ transform: :class:`~matplotlib.transforms.Transform` instance
+ url: a url string
+ visible: [True | False]
+ zorder: any number
+
+**Example:**
+
+.. plot:: mpl_examples/pylab_examples/axhspan_demo.py
+
+Additional kwargs: hold = [True|False] overrides default hold state
+"""
+ ax = gca()
# allow callers to override the hold state by passing hold=True|False
- b = ishold()
- h = kwargs.pop('hold', None)
- if h is not None:
- hold(h)
+ washold = ax.ishold()
+
+ if hold is not None:
+ ax.hold(hold)
try:
- ret = gca().axhspan(*args, **kwargs)
+ ret = ax.axhspan(ymin, ymax, xmin, xmax, **kwargs)
draw_if_interactive()
- except:
- hold(b)
- raise
+ finally:
+ ax.hold(washold)
- hold(b)
return ret
-if Axes.axhspan.__doc__ is not None:
- axhspan.__doc__ = dedent(Axes.axhspan.__doc__) + """
-Additional kwargs: hold = [True|False] overrides default hold state"""
-
# This function was autogenerated by boilerplate.py. Do not edit as
# changes will be lost
-def axvline(*args, **kwargs):
+def axvline(x=0, ymin=0, ymax=1, hold=None, **kwargs):
+ """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
+ylim settings, even if you change them, eg. with the
+:meth:`set_ylim` command. That is, the vertical extent is in
+axes coords: 0=bottom, 0.5=middle, 1.0=top but the *x* location
+is in data coordinates.
+
+Return value is the :class:`~matplotlib.lines.Line2D`
+instance. kwargs are the same as kwargs to plot, and can be
+used to control the line properties. Eg.,
+
+* draw a thick red vline at *x* = 0 that spans the yrange
+
+ >>> axvline(linewidth=4, color='r')
+
+* draw a default vline at *x* = 1 that spans the yrange
+
+ >>> axvline(x=1)
+
+* draw a default vline at *x* = .5 that spans the the middle half of
+ the yrange
+
+ >>> axvline(x=.5, ymin=0.25, ymax=0.75)
+
+Valid kwargs are :class:`~matplotlib.lines.Line2D` properties:
+
+ alpha: float (0.0 transparent through 1.0 opaque)
+ animated: [True | False]
+ antialiased or aa: [True | False]
+ axes: an :class:`~matplotlib.axes.Axes` instance
+ clip_box: a :class:`matplotlib.transforms.Bbox` instance
+ clip_on: [True | False]
+ clip_path: [ (:class:`~matplotlib.path.Path`, :class:`~matplotlib.transforms.Transform`) | :class:`~matplotlib.patches.Patch` | None ]
+ color or c: any matplotlib color
+ contains: a callable function
+ dash_capstyle: ['butt' | 'round' | 'projecting']
+ dash_joinstyle: ['miter' | 'round' | 'bevel']
+ dashes: sequence of on/off ink in points
+ data: 2D array
+ drawstyle: [ 'default' | 'steps' | 'steps-pre' | 'steps-mid' | 'steps-post' ]
+ figure: a :class:`matplotlib.figure.Figure` instance
+ fillstyle: ['full' | 'left' | 'right' | 'bottom' | 'top']
+ gid: an id string
+ label: any string
+ linestyle or ls: [ '-' | '--' | '-.' | ':' | 'None' | ' ' | '' ] and any drawstyle in combination with a linestyle, e.g. 'steps--'.
+ linewidth or lw: float value in points
+ lod: [True | False]
+ marker: [ '+' | '*' | ',' | '.' | '1' | '2' | '3' | '4' | '<' | '>' | 'D' | 'H' | '^' | '_' | 'd' | 'h' | 'o' | 'p' | 's' | 'v' | 'x' | '|' | TICKUP | TICKDOWN | TICKLEFT | TICKRIGHT | 'None' | ' ' | '' ]
+ markeredgecolor or mec: any matplotlib color
+ markeredgewidth or mew: float value in points
+ markerfacecolor or mfc: any matplotlib color
+ markersize or ms: float
+ markevery: None | integer | (startind, stride)
+ picker: float distance in points or callable pick function ``fn(artist, event)``
+ pickradius: float distance in points
+ rasterized: [True | False | None]
+ snap: unknown
+ solid_capstyle: ['butt' | 'round' | 'projecting']
+ solid_joinstyle: ['miter' | 'round' | 'bevel']
+ transform: a :class:`matplotlib.transforms.Transform` instance
+ url: a url string
+ visible: [True | False]
+ xdata: 1D array
+ ydata: 1D array
+ zorder: any number
+
+.. seealso::
+
+ :meth:`axhspan`
+ for example plot and source code
+
+Additional kwargs: hold = [True|False] overrides default hold state
+"""
+ ax = gca()
# allow callers to override the hold state by passing hold=True|False
- b = ishold()
- h = kwargs.pop('hold', None)
- if h is not None:
- hold(h)
+ washold = ax.ishold()
+
+ if hold is not None:
+ ax.hold(hold)
try:
- ret = gca().axvline(*args, **kwargs)
+ ret = ax.axvline(x, ymin, ymax, **kwargs)
draw_if_interactive()
- except:
- hold(b)
- raise
+ finally:
+ ax.hold(washold)
- hold(b)
return ret
-if Axes.axvline.__doc__ is not None:
- axvline.__doc__ = dedent(Axes.axvline.__doc__) + """
-Additional kwargs: hold = [True|False] overrides default hold state"""
-
# This function was autogenerated by boilerplate.py. Do not edit as
# changes will be lost
-def axvspan(*args, **kwargs):
+def axvspan(xmin, xmax, ymin=0, ymax=1, hold=None, **kwargs):
+ """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.
+
+Draw a vertical span (rectangle) from *xmin* to *xmax*. With
+the default values of *ymin* = 0 and *ymax* = 1, this always
+spans the yrange, regardless of the ylim settings, even if you
+change them, eg. with the :meth:`set_ylim` command. That is,
+the vertical extent is in axes coords: 0=bottom, 0.5=middle,
+1.0=top but the *y* location is in data coordinates.
+
+Return value is the :class:`matplotlib.patches.Polygon`
+instance.
+
+Examples:
+
+* draw a vertical green translucent rectangle from x=1.25 to 1.55 that
+ spans the yrange of the axes
+
+ >>> axvspan(1.25, 1.55, facecolor='g', alpha=0.5)
+
+Valid kwargs are :class:`~matplotlib.patches.Polygon`
+properties:
+
+ alpha: float (0.0 transparent through 1.0 opaque)
+ animated: [True | False]
+ antialiased or aa: [True | False] or None for default
+ axes: an :class:`~matplotlib.axes.Axes` instance
+ clip_box: a :class:`matplotlib.transforms.Bbox` instance
+ clip_on: [True | False]
+ clip_path: [ (:class:`~matplotlib.path.Path`, :class:`~matplotlib.transforms.Transform`) | :class:`~matplotlib.patches.Patch` | None ]
+ color: matplotlib color arg or sequence of rgba tuples
+ contains: a callable function
+ edgecolor or ec: mpl color spec, or None for default, or 'none' for no color
+ facecolor or fc: mpl color spec, or None for default, or 'none' for no color
+ figure: a :class:`matplotlib.figure.Figure` instance
+ fill: [True | False]
+ gid: an id string
+ hatch: [ '/' | '\\\\' | '|' | '-' | '+' | 'x' | 'o' | 'O' | '.' | '*' ]
+ label: any string
+ linestyle or ls: ['solid' | 'dashed' | 'dashdot' | 'dotted']
+ linewidth or lw: float or None for default
+ lod: [True | False]
+ picker: [None|float|boolean|callable]
+ rasterized: [True | False | None]
+ snap: unknown
+ transform: :class:`~matplotlib.transforms.Transform` instance
+ url: a url string
+ visible: [True | False]
+ zorder: any number
+
+.. seealso::
+
+ :meth:`axhspan`
+ for example plot and source code
+
+Additional kwargs: hold = [True|False] overrides default hold state
+"""
+ ax = gca()
# allow callers to override the hold state by passing hold=True|False
- b = ishold()
- h = kwargs.pop('hold', None)
- if h is not None:
- hold(h)
+ washold = ax.ishold()
+
+ if hold is not None:
+ ax.hold(hold)
try:
- ret = gca().axvspan(*args, **kwargs)
+ ret = ax.axvspan(xmin, xmax, ymin, ymax, **kwargs)
draw_if_interactive()
- except:
- hold(b)
- raise
+ finally:
+ ax.hold(washold)
- hold(b)
return ret
-if Axes.axvspan.__doc__ is not None:
- axvspan.__doc__ = dedent(Axes.axvspan.__doc__) + """
-Additional kwargs: hold = [True|False] overrides default hold state"""
-
# This function was autogenerated by boilerplate.py. Do not edit as
# changes will be lost
-def bar(*args, **kwargs):
+def bar(left, height, width=0.80000000000000004, bottom=None, color=None, edgecolor=None, linewidth=None, yerr=None, xerr=None, ecolor=None, capsize=3, align='edge', orientation='vertical', log=False, hold=None, **kwargs):
+ """call signature::
+
+ bar(left, height, width=0.8, bottom=0,
+ color=None, edgecolor=None, linewidth=None,
+ yerr=None, xerr=None, ecolor=None, capsize=3,
+ align='edge', orientation='vertical', log=False)
+
+Make a bar plot with rectangles bounded by:
+
+ *left*, *left* + *width*, *bottom*, *bottom* + *height*
+ (left, right, bottom and top edges)
+
+*left*, *height*, *width*, and *bottom* can be either scalars
+or sequences
+
+Return value is a list of
+:class:`matplotlib.patches.Rectangle` instances.
+
+Required arguments:
+
+ ======== ===============================================
+ Argument Description
+ ======== ===============================================
+ *left* the x coordinates of the left sides of the bars
+ *height* the heights of the bars
+ ======== ===============================================
+
+Optional keyword arguments:
+
+ =============== ==========================================
+ Keyword Description
+ =============== ==========================================
+ *width* the widths of the bars
+ *bottom* the y coordinates of the bottom edges of
+ the bars
+ *color* the colors of the bars
+ *edgecolor* the colors of the bar edges
+ *linewidth* width of bar edges; None means use default
+ linewidth; 0 means don't draw edges.
+ *xerr* if not None, will be used to generate
+ errorbars on the bar chart
+ *yerr* if not None, will be used to generate
+ errorbars on the bar chart
+ *ecolor* specifies the color of any errorbar
+ *capsize* (default 3) determines the length in
+ points of the error bar caps
+ *align* 'edge' (default) | 'center'
+ *orientation* 'vertical' | 'horizontal'
+ *log* [False|True] False (default) leaves the
+ orientation axis as-is; True sets it to
+ log scale
+ =============== ==========================================
+
+For vertical bars, *align* = 'edge' aligns bars by their left
+edges in left, while *align* = 'center' interprets these
+values as the *x* coordinates of the bar centers. For
+horizontal bars, *align* = 'edge' aligns bars by their bottom
+edges in bottom, while *align* = 'center' interprets these
+values as the *y* coordinates of the bar centers.
+
+The optional arguments *color*, *edgecolor*, *linewidth*,
+*xerr*, and *yerr* can be either scalars or sequences of
+length equal to the number of bars. This enables you to use
+bar as the basis for stacked bar charts, or candlestick plots.
+
+Other optional kwargs:
+
+ alpha: float (0.0 transparent through 1.0 opaque)
+ animated: [True | False]
+ antialiased or aa: [True | False] or None for default
+ axes: an :class:`~matplotlib.axes.Axes` instance
+ clip_box: a :class:`matplotlib.transforms.Bbox` instance
+ clip_on: [True | False]
+ clip_path: [ (:class:`~matplotlib.path.Path`, :class:`~matplotlib.transforms.Transform`) | :class:`~matplotlib.patches.Patch` | None ]
+ color: matplotlib color arg or sequence of rgba tuples
+ contains: a callable function
+ edgecolor or ec: mpl color spec, or None for default, or 'none' for no color
+ facecolor or fc: mpl color spec, or None for default, or 'none' for no color
+ figure: a :class:`matplotlib.figure.Figure` instance
+ fill: [True | False]
+ gid: an id string
+ hatch: [ '/' | '\\\\' | '|' | '-' | '+' | 'x' | 'o' | 'O' | '.' | '*' ]
+ label: any string
+ linestyle or ls: ['solid' | 'dashed' | 'dashdot' | 'dotted']
+ linewidth or lw: float or None for default
+ lod: [True | False]
+ picker: [None|float|boolean|callable]
+ rasterized: [True | False | None]
+ snap: unknown
+ transform: :class:`~matplotlib.transforms.Transform` instance
+ url: a url string
+ visible: [True | False]
+ zorder: any number
+
+**Example:** A stacked bar chart.
+
+.. plot:: mpl_examples/pylab_examples/bar_stacked.py
+
+Additional kwargs: hold = [True|False] overrides default hold state
+"""
+ ax = gca()
# allow callers to override the hold state by passing hold=True|False
- b = ishold()
- h = kwargs.pop('hold', None)
- if h is not None:
- hold(h)
+ washold = ax.ishold()
+
+ if hold is not None:
+ ax.hold(hold)
try:
- ret = gca().bar(*args, **kwargs)
+ ret = ax.bar(left, height, width, bottom, color, edgecolor, linewidth, yerr, xerr, ecolor, capsize, align, orientation, log, **kwargs)
draw_if_interactive()
- except:
- hold(b)
- raise
+ finally:
+ ax.hold(washold)
- hold(b)
return ret
-if Axes.bar.__doc__ is not None:
- bar.__doc__ = dedent(Axes.bar.__doc__) + """
-Additional kwargs: hold = [True|False] overrides default hold state"""
-
# This function was autogenerated by boilerplate.py. Do not edit as
# changes will be lost
-def barh(*args, **kwargs):
+def barh(bottom, width, height=0.80000000000000004, left=None, hold=None, **kwargs):
+ """call signature::
+
+ barh(bottom, width, height=0.8, left=0, **kwargs)
+
+Make a horizontal bar plot with rectangles bounded by:
+
+ *left*, *left* + *width*, *bottom*, *bottom* + *height*
+ (left, right, bottom and top edges)
+
+*bottom*, *width*, *height*, and *left* can be either scalars
+or sequences
+
+Return value is a list of
+:class:`matplotlib.patches.Rectangle` instances.
+
+Required arguments:
+
+ ======== ======================================================
+ Argument Description
+ ======== ======================================================
+ *bottom* the vertical positions of the bottom edges of the bars
+ *width* the lengths of the bars
+ ======== ======================================================
+
+Optional keyword arguments:
+
+ =============== ==========================================
+ Keyword Description
+ =============== ==========================================
+ *height* the heights (thicknesses) of the bars
+ *left* the x coordinates of the left edges of the
+ bars
+ *color* the colors of the bars
+ *edgecolor* the colors of the bar edges
+ *linewidth* width of bar edges; None means use default
+ linewidth; 0 means don't draw edges.
+ *xerr* if not None, will be used to generate
+ errorbars on the bar chart
+ *yerr* if not None, will be used to generate
+ errorbars on the bar chart
+ *ecolor* specifies the color of any errorbar
+ *capsize* (default 3) determines the length in
+ points of the error bar caps
+ *align* 'edge' (default) | 'center'
+ *log* [False|True] False (default) leaves the
+ horizontal axis as-is; True sets it to log
+ scale
+ =============== ==========================================
+
+Setting *align* = 'edge' aligns bars by their bottom edges in
+bottom, while *align* = 'center' interprets these values as
+the *y* coordinates of the bar centers.
+
+The optional arguments *color*, *edgecolor*, *linewidth*,
+*xerr*, and *yerr* can be either scalars or sequences of
+length equal to the number of bars. This enables you to use
+barh as the basis for stacked bar charts, or candlestick
+plots.
+
+other optional kwargs:
+
+ alpha: float (0.0 transparent through 1.0 opaque)
+ animated: [True | False]
+ antialiased or aa: [True | False] or None for default
+ axes: an :class:`~matplotlib.axes.Axes` instance
+ clip_box: a :class:`matplotlib.transforms.Bbox` instance
+ clip_on: [True | False]
+ clip_path: [ (:class:`~matplotlib.path.Path`, :class:`~matplotlib.transforms.Transform`) | :class:`~matplotlib.patches.Patch` | None ]
+ color: matplotlib color arg or sequence of rgba tuples
+ contains: a callable function
+ edgecolor or ec: mpl color spec, or None for default, or 'none' for no color
+ facecolor or fc: mpl color spec, or None for default, or 'none' for no color
+ figure: a :class:`matplotlib.figure.Figure` instance
+ fill: [True | False]
+ gid: an id string
+ hatch: [ '/' | '\\\\' | '|' | '-' | '+' | 'x' | 'o' | 'O' | '.' | '*' ]
+ label: any string
+ linestyle or ls: ['solid' | 'dashed' | 'dashdot' | 'dotted']
+ linewidth or lw: float or None for default
+ lod: [True | False]
+ picker: [None|float|boolean|callable]
+ rasterized: [True | False | None]
+ snap: unknown
+ transform: :class:`~matplotlib.transforms.Transform` instance
+ url: a url string
+ visible: [True | False]
+ zorder: any number
+
+Additional kwargs: hold = [True|False] overrides default hold state
+"""
+ ax = gca()
# allow callers to override the hold state by passing hold=True|False
- b = ishold()
- h = kwargs.pop('hold', None)
- if h is not None:
- hold(h)
+ washold = ax.ishold()
+
+ if hold is not None:
+ ax.hold(hold)
try:
- ret = gca().barh(*args, **kwargs)
+ ret = ax.barh(bottom, width, height, left, **kwargs)
draw_if_interactive()
- except:
- hold(b)
- raise
+ finally:
+ ax.hold(washold)
- hold(b)
return ret
-if Axes.barh.__doc__ is not None:
- barh.__doc__ = dedent(Axes.barh.__doc__) + """
-Additional kwargs: hold = [True|False] overrides default hold state"""
-
# This function was autogenerated by boilerplate.py. Do not edit as
# changes will be lost
-def broken_barh(*args, **kwargs):
+def broken_barh(xranges, yrange, hold=None, **kwargs):
+ """call signature::
+
+ broken_barh(self, xranges, yrange, **kwargs)
+
+A collection of horizontal bars spanning *yrange* with a sequence of
+*xranges*.
+
+Required arguments:
+
+ ========= ==============================
+ Argument Description
+ ========= ==============================
+ *xranges* sequence of (*xmin*, *xwidth*)
+ *yrange* sequence of (*ymin*, *ywidth*)
+ ========= ==============================
+
+kwargs are
+:class:`matplotlib.collections.BrokenBarHCollection`
+properties:
+
+ alpha: float
+ animated: [True | False]
+ antialiased or antialiaseds: Boolean or sequence of booleans
+ array: unknown
+ axes: an :class:`~matplotlib.axes.Axes` instance
+ clim: a length 2 sequence of floats
+ clip_box: a :class:`matplotlib.transforms.Bbox` instance
+ clip_on: [True | False]
+ clip_path: [ (:class:`~matplotlib.path.Path`, :class:`~matplotlib.transforms.Transform`) | :class:`~matplotlib.patches.Patch` | None ]
+ cmap: a colormap
+ color: matplotlib color arg or sequence of rgba tuples
+ colorbar: unknown
+ contains: a callable function
+ edgecolor or edgecolors: matplotlib color arg or sequence of rgba tuples
+ facecolor or facecolors: matplotlib color arg or sequence of rgba tuples
+ figure: a :class:`matplotlib.figure.Figure` instance
+ gid: an id string
+ label: any string
+ linestyle or linestyles or dashes: ['solid' | 'dashed', 'dashdot', 'dotted' | (offset, on-off-dash-seq) ]
+ linewidth or lw or linewidths: float or sequence of floats
+ lod: [True | False]
+ norm: unknown
+ offsets: float or sequence of floats
+ picker: [None|float|boolean|callable]
+ pickradius: unknown
+ rasterized: [True | False | None]
+ snap: unknown
+ transform: :class:`~matplotlib.transforms.Transform` instance
+ url: a url string
+ urls: unknown
+ visible: [True | False]
+ zorder: any number
+
+these can either be a single argument, ie::
+
+ facecolors = 'black'
+
+or a sequence of arguments for the various bars, ie::
+
+ facecolors = ('black', 'red', 'green')
+
+**Example:**
+
+.. plot:: mpl_examples/pylab_examples/broken_barh.py
+
+Additional kwargs: hold = [True|False] overrides default hold state
+"""
+ ax = gca()
# allow callers to override the hold state by passing hold=True|False
- b = ishold()
- h = kwargs.pop('hold', None)
- if h is not None:
- hold(h)
+ washold = ax.ishold()
+
+ if hold is not None:
+ ax.hold(hold)
try:
- ret = gca().broken_barh(*args, **kwargs)
+ ret = ax.broken_barh(xranges, yrange, **kwargs)
draw_if_interactive()
- except:
- hold(b)
- raise
+ finally:
+ ax.hold(washold)
- hold(b)
return ret
-if Axes.broken_barh.__doc__ is not None:
- broken_barh.__doc__ = dedent(Axes.broken_barh.__doc__) + """
-Additional kwargs: hold = [True|False] overrides default hold state"""
-
# This function was autogenerated by boilerplate.py. Do not edit as
# changes will be lost
-def boxplot(*args, **kwargs):
+def boxplot(x, notch=0, sym='b+', vert=1, whis=1.5, positions=None, widths=None, hold=None):
+ """call signature::
+
+ boxplot(x, notch=0, sym='+', vert=1, whis=1.5,
+ positions=None, widths=None)
+
+Make a box and whisker plot for each column of *x* or each
+vector in sequence *x*. The box extends from the lower to
+upper quartile values of the data, with a line at the median.
+The whiskers extend from the box to show the range of the
+data. Flier points are those past the end of the whiskers.
+
+- *notch* = 0 (default) produces a rectangular box plot.
+- *notch* = 1 will produce a notched box plot
+
+*sym* (default 'b+') is the default symbol for flier points.
+Enter an empty string ('') if you don't want to show fliers.
+
+- *vert* = 1 (default) makes the boxes vertical.
+- *vert* = 0 makes horizontal boxes. This seems goofy, but
+ that's how Matlab did it.
+
+*whis* (default 1.5) defines the length of the whiskers as
+a function of the inner quartile range. They extend to the
+most extreme data point within ( ``whis*(75%-25%)`` ) data range.
+
+*positions* (default 1,2,...,n) sets the horizontal positions of
+the boxes. The ticks and limits are automatically set to match
+the positions.
+
+*widths* is either a scalar or a vector and sets the width of
+each box. The default is 0.5, or ``0.15*(distance between extreme
+positions)`` if that is smaller.
+
+*x* is an array or a sequence of vectors.
+
+Returns a dictionary mapping each component of the boxplot
+to a list of the :class:`matplotlib.lines.Line2D`
+instances created.
+
+**Example:**
+
+.. plot:: pyplots/boxplot_demo.py
+
+Additional kwargs: hold = [True|False] overrides default hold state
+"""
+ ax = gca()
# allow callers to override the hold state by passing hold=True|False
- b = ishold()
- h = kwargs.pop('hold', None)
- if h is not None:
- hold(h)
+ washold = ax.ishold()
+
+ if hold is not None:
+ ax.hold(hold)
try:
- ret = gca().boxplot(*args, **kwargs)
+ ret = ax.boxplot(x, notch, sym, vert, whis, positions, widths)
draw_if_interactive()
- except:
- hold(b)
- raise
+ finally:
+ ax.hold(washold)
- hold(b)
return ret
-if Axes.boxplot.__doc__ is not None:
- boxplot.__doc__ = dedent(Axes.boxplot.__doc__) + """
-Additional kwargs: hold = [True|False] overrides default hold state"""
-
# This function was autogenerated by boilerplate.py. Do not edit as
# changes will be lost
-def cohere(*args, **kwargs):
+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):
+ """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)
+
+cohere the coherence between *x* and *y*. Coherence is the normalized
+cross spectral density:
+
+.. math::
+
+ C_{xy} = \\frac{|P_{xy}|^2}{P_{xx}P_{yy}}
+
+Keyword arguments:
+
+ *NFFT*: integer
+ The number of data points used in each block for the FFT.
+ Must be even; a power 2 is most efficient. The default value is 256.
+
+ *Fs*: scalar
+ The sampling frequency (samples per time unit). It is used
+ to calculate the Fourier frequencies, freqs, in cycles per time
+ unit. The default value is 2.
+
+ *detrend*: callable
+ The function applied to each segment before fft-ing,
+ designed to remove the mean or linear trend. Unlike in
+ matlab, where the *detrend* parameter is a vector, in
+ matplotlib is it a function. The :mod:`~matplotlib.pylab`
+ module defines :func:`~matplotlib.pylab.detrend_none`,
+ :func:`~matplotlib.pylab.detrend_mean`, and
+ :func:`~matplotlib.pylab.detrend_linear`, but you can use
+ a custom function as well.
+
+ *window*: callable or ndarray
+ A function or a vector of length *NFFT*. To create window
+ vectors see :func:`window_hanning`, :func:`window_none`,
+ :func:`numpy.blackman`, :func:`numpy.hamming`,
+ :func:`numpy.bartlett`, :func:`scipy.signal`,
+ :func:`scipy.signal.get_window`, etc. The default is
+ :func:`window_hanning`. If a function is passed as the
+ argument, it must take a data segment as an argument and
+ return the windowed version of the segment.
+
+ *noverlap*: integer
+ The number of points of overlap between blocks. The default value
+ is 0 (no overlap).
+
+ *pad_to*: integer
+ The number of points to which the data segment is padded when
+ performing the FFT. This can be different from *NFFT*, which
+ specifies the number of data points used. While not increasing
+ the actual resolution of the psd (the minimum distance between
+ resolvable peaks), this can give more points in the plot,
+ allowing for more detail. This corresponds to the *n* parameter
+ in the call to fft(). The default is None, which sets *pad_to*
+ equal to *NFFT*
+
+ *sides*: [ 'default' | 'onesided' | 'twosided' ]
+ Specifies which sides of the PSD to return. Default gives the
+ default behavior, which returns one-sided for real data and both
+ for complex data. 'onesided' forces the return of a one-sided PSD,
+ while 'twosided' forces two-sided.
+
+ *scale_by_freq*: boolean
+ Specifies whether the resulting density values should be scaled
+ by the scaling frequency, which gives density in units of Hz^-1.
+ This allows for integration over the returned frequency values.
+ The default is True for MatLab compatibility.
+
+ *Fc*: integer
+ The center frequency of *x* (defaults to 0), which offsets
+ the x extents of the plot to reflect the frequency range used
+ when a signal is acquired and then filtered and downsampled to
+ baseband.
+
+The return value is a tuple (*Cxy*, *f*), where *f* are the
+frequencies of the coherence vector.
+
+kwargs are applied to the lines.
+
+References:
+
+ * Bendat & Piersol -- Random Data: Analysis and Measurement
+ Procedures, John Wiley & Sons (1986)
+
+kwargs control the :class:`~matplotlib.lines.Line2D`
+properties of the coherence plot:
+
+ alpha: float (0.0 transparent through 1.0 opaque)
+ animated: [True | False]
+ antialiased or aa: [True | False]
+ axes: an :class:`~matplotlib.axes.Axes` instance
+ clip_box: a :class:`matplotlib.transforms.Bbox` instance
+ clip_on: [True | False]
+ clip_path: [ (:class:`~matplotlib.path.Path`, :class:`~matplotlib.transforms.Transform`) | :class:`~matplotlib.patches.Patch` | None ]
+ color or c: any matplotlib color
+ contains: a callable function
+ dash_capstyle: ['butt' | 'round' | 'projecting']
+ dash_joinstyle: ['miter' | 'round' | 'bevel']
+ dashes: sequence of on/off ink in points
+ data: 2D array
+ drawstyle: [ 'default' | 'steps' | 'steps-pre' | 'steps-mid' | 'steps-post' ]
+ figure: a :class:`matplotlib.figure.Figure` instance
+ fillstyle: ['full' | 'left' | 'right' | 'bottom' | 'top']
+ gid: an id string
+ label: any string
+ linestyle or ls: [ '-' | '--' | '-.' | ':' | 'None' | ' ' | '' ] and any drawstyle in combination with a linestyle, e.g. 'steps--'.
+ linewidth or lw: float value in points
+ lod: [True | False]
+ marker: [ '+' | '*' | ',' | '.' | '1' | '2' | '3' | '4' | '<' | '>' | 'D' | 'H' | '^' | '_' | 'd' | 'h' | 'o' | 'p' | 's' | 'v' | 'x' | '|' | TICKUP | TICKDOWN | TICKLEFT | TICKRIGHT | 'None' | ' ' | '' ]
+ markeredgecolor or mec: any matplotlib color
+ markeredgewidth or mew: float value in points
+ markerfacecolor or mfc: any matplotlib color
+ markersize or ms: float
+ markevery: None | integer | (startind, stride)
+ picker: float distance in points or callable pick function ``fn(artist, event)``
+ pickradius: float distance in points
+ rasterized: [True | False | None]
+ snap: unknown
+ solid_capstyle: ['butt' | 'round' | 'projecting']
+ solid_joinstyle: ['miter' | 'round' | 'bevel']
+ transform: a :class:`matplotlib.transforms.Transform` instance
+ url: a url string
+ visible: [True | False]
+ xdata: 1D array
+ ydata: 1D array
+ zorder: any number
+
+**Example:**
+
+.. plot:: mpl_examples/pylab_examples/cohere_demo.py
+
+Additional kwargs: hold = [True|False] overrides default hold state
+"""
+ ax = gca()
# allow callers to override the hold state by passing hold=True|False
- b = ishold()
- h = kwargs.pop('hold', None)
- if h is not None:
- hold(h)
+ washold = ax.ishold()
+
+ if hold is not None:
+ ax.hold(hold)
try:
- ret = gca().cohere(*args, **kwargs)
+ ret = ax.cohere(x, y, NFFT, Fs, Fc, detrend, window, noverlap, pad_to, sides, scale_by_freq, **kwargs)
draw_if_interactive()
- except:
- hold(b)
- raise
+ finally:
+ ax.hold(washold)
- hold(b)
return ret
-if Axes.cohere.__doc__ is not None:
- cohere.__doc__ = dedent(Axes.cohere.__doc__) + """
-Additional kwargs: hold = [True|False] overrides default hold state"""
-
# This function was autogenerated by boilerplate.py. Do not edit as
# changes will be lost
-def clabel(*args, **kwargs):
+def clabel(CS, *args, **kwargs):
+ """call signature::
+
+ clabel(cs, **kwargs)
+
+adds labels to line contours in *cs*, where *cs* is a
+:class:`~matplotlib.contour.ContourSet` object returned by
+contour.
+
+::
+
+ clabel(cs, v, **kwargs)
+
+only labels contours listed in *v*.
+
+Optional keyword arguments:
+
+ *fontsize*:
+ See http://matplotlib.sf.net/fonts.html
+
+ *colors*:
+ - if *None*, the color of each label matches the color of
+ the corresponding contour
+
+ - if one string color, e.g. *colors* = 'r' or *colors* =
+ 'red', all labels will be plotted in this color
+
+ - if a tuple of matplotlib color args (string, float, rgb, etc),
+ different labels will be plotted in different colors in the order
+ specified
+
+ *inline*:
+ controls whether the underlying contour is removed or
+ not. Default is *True*.
+
+ *inline_spacing*:
+ space in pixels to leave on each side of label when
+ placing inline. Defaults to 5. This spacing will be
+ exact for labels at locations where the contour is
+ straight, less so for labels on curved contours.
+
+ *fmt*:
+ a format string for the label. Default is '%1.3f'
+ Alternatively, this can be a dictionary matching contour
+ levels with arbitrary strings to use for each contour level
+ (i.e., fmt[level]=string)
+
+ *manual*:
+ if *True*, contour labels will be placed manually using
+ mouse clicks. Click the first button near a contour to
+ add a label, click the second button (or potentially both
+ mouse buttons at once) to finish adding labels. The third
+ button can be used to remove the last label added, but
+ only if labels are not inline. Alternatively, the keyboard
+ can be used to select label locations (enter to end label
+ placement, delete or backspace act like the third mouse button,
+ and any other key will select a label location).
+
+ *rightside_up*:
+ if *True* (default), label rotations will always be plus
+ or minus 90 degrees from level.
+
+.. plot:: mpl_examples/pylab_examples/contour_demo.py
+
+Additional kwargs: hold = [True|False] overrides default hold state
+"""
+ ax = gca()
# allow callers to override the hold state by passing hold=True|False
- b = ishold()
- h = kwargs.pop('hold', None)
- if h is not None:
- hold(h)
+ washold = ax.ishold()
+ hold = kwargs.pop('hold', None)
+ if hold is not None:
+ ax.hold(hold)
try:
- ret = gca().clabel(*args, **kwargs)
+ ret = ax.clabel(CS, *args, **kwargs)
draw_if_interactive()
- except:
- hold(b)
- raise
+ finally:
+ ax.hold(washold)
- hold(b)
return ret
-if Axes.clabel.__doc__ is not None:
- clabel.__doc__ = dedent(Axes.clabel.__doc__) + """
-Additional kwargs: hold = [True|False] overrides default hold state"""
-
# This function was autogenerated by boilerplate.py. Do not edit as
# changes will be lost
def contour(*args, **kwargs):
+ """:func:`~matplotlib.pyplot.contour` and
+:func:`~matplotlib.pyplot.contourf` draw contour lines and
+filled contours, respectively. Except as noted, function
+signatures and return values are the same for both versions.
+
+:func:`~matplotlib.pyplot.contourf` differs from the Matlab
+(TM) version in that it does not draw the polygon edges,
+because the contouring engine yields simply connected regions
+with branch cuts. To draw the edges, add line contours with
+calls to :func:`~matplotlib.pyplot.contour`.
+
+
+call signatures::
+
+ contour(Z)
+
+make a contour plot of an array *Z*. The level values are chosen
+automatically.
+
+::
+
+ contour(X,Y,Z)
+
+*X*, *Y* specify the (*x*, *y*) coordinates of the surface
+
+::
+
+ contour(Z,N)
+ contour(X,Y,Z,N)
+
+contour *N* automatically-chosen levels.
+
+::
+
+ contour(Z,V)
+ contour(X,Y,Z,V)
+
+draw contour lines at the values specified in sequence *V*
+
+::
+
+ contourf(..., V)
+
+fill the (len(*V*)-1) regions between the values in *V*
+
+::
+
+ contour(Z, **kwargs)
+
+Use keyword args to control colors, linewidth, origin, cmap ... see
+below for more details.
+
+*X*, *Y*, and *Z* must be arrays with the same dimensions.
+
+*Z* may be a masked array, but filled contouring may not
+handle internal masked regions correctly.
+
+``C = contour(...)`` returns a
+:class:`~matplotlib.contour.ContourSet` object.
+
+Optional keyword arguments:
+
+ *colors*: [ None | string | (mpl_colors) ]
+ If *None*, the colormap specified by cmap will be used.
+
+ If a string, like 'r' or 'red', all levels will be plotted in this
+ color.
+
+ If a tuple of matplotlib color args (string, float, rgb, etc),
+ different levels will be plotted in different colors in the order
+ specified.
+
+ *alpha*: float
+ The alpha blending value
+
+ *cmap*: [ None | Colormap ]
+ A cm :class:`~matplotlib.cm.Colormap` instance or
+ *None*. If *cmap* is *None* and *colors* is *None*, a
+ default Colormap is used.
+
+ *norm*: [ None | Normalize ]
+ A :class:`matplotlib.colors.Normalize` instance for
+ scaling data values to colors. If *norm* is *None* and
+ *colors* is *None*, the default linear scaling is used.
+
+ *origin*: [ None | 'upper' | 'lower' | 'image' ]
+ If *None*, the first value of *Z* will correspond to the
+ lower left corner, location (0,0). If 'image', the rc
+ value for ``image.origin`` will be used.
+
+ This keyword is not active if *X* and *Y* are specified in
+ the call to contour.
+
+ *extent*: [ None | (x0,x1,y0,y1) ]
+
+ If *origin* is not *None*, then *extent* is interpreted as
+ in :func:`matplotlib.pyplot.imshow`: it gives the outer
+ pixel boundaries. In this case, the position of Z[0,0]
+ is the center of the pixel, not a corner. If *origin* is
+ *None*, then (*x0*, *y0*) is the position of Z[0,0], and
+ (*x1*, *y1*) is the position of Z[-1,-1].
+
+ This keyword is not active if *X* and *Y* are specified in
+ the call to contour.
+
+ *locator*: [ None | ticker.Locator subclass ]
+ If *locator* is None, the default
+ :class:`~matplotlib.ticker.MaxNLocator` is used. The
+ locator is used to determine the contour levels if they
+ are not given explicitly via the *V* argument.
+
+ *extend*: [ 'neither' | 'both' | 'min' | 'max' ]
+ Unless this is 'neither', contour levels are automatically
+ added to one or both ends of the range so that all data
+ are included. These added ranges are then mapped to the
+ special colormap values which default to the ends of the
+ colormap range, but can be set via
+ :meth:`matplotlib.cm.Colormap.set_under` and
+ :meth:`matplotlib.cm.Colormap.set_over` methods.
+
+contour-only keyword arguments:
+
+ *linewidths*: [ None | number | tuple of numbers ]
+ If *linewidths* is *None*, the default width in
+ ``lines.linewidth`` in ``matplotlibrc`` is used.
+
+ If a number, all levels will be plotted with this linewidth.
+
+ If a tuple, different levels will be plotted with different
+ linewidths in the order specified
+
+ *linestyles*: [None | 'solid' | 'dashed' | 'dashdot' | 'dotted' ]
+ If *linestyles* is *None*, the 'solid' is used.
+
+ *linestyles* can also be an iterable of the above strings
+ specifying a set of linestyles to be used. If this
+ iterable is shorter than the number of contour levels
+ it will be repeated as necessary.
+
+ If contour is using a monochrome colormap and the contour
+ level is less than 0, then the linestyle specified
+ in ``contour.negative_linestyle`` in ``matplotlibrc``
+ will be used.
+
+contourf-only keyword arguments:
+
+ *antialiased*: [ True | False ]
+ enable antialiasing
+
+ *nchunk*: [ 0 | integer ]
+ If 0, no subdivision of the domain. Specify a positive integer to
+ divide the domain into subdomains of roughly *nchunk* by *nchunk*
+ points. This may never actually be advantageous, so this option may
+ be removed. Chunking introduces artifacts at the chunk boundaries
+ unless *antialiased* is *False*.
+
+**Example:**
+
+.. plot:: mpl_examples/pylab_examples/contour_demo.py
+
+Additional kwargs: hold = [True|False] overrides default hold state
+"""
+ ax = gca()
# allow callers to override the hold state by passing hold=True|False
- b = ishold()
- h = kwargs.pop('hold', None)
- if h is not None:
- hold(h)
+ washold = ax.ishold()
+ hold = kwargs.pop('hold', None)
+ if hold is not None:
+ ax.hold(hold)
try:
- ret = gca().contour(*args, **kwargs)
+ ret = ax.contour(*args, **kwargs)
draw_if_interactive()
- except:
- hold(b)
- raise
+ finally:
+ ax.hold(washold)
if ret._A is not None: gci._current = ret
- hold(b)
return ret
-if Axes.contour.__doc__ is not None:
- contour.__doc__ = dedent(Axes.contour.__doc__) + """
-Additional kwargs: hold = [True|False] overrides default hold state"""
-
# This function was autogenerated by boilerplate.py. Do not edit as
# changes will b...
[truncated message content] |
