def legend(self, handles, labels, loc, **kwargs):
"""
Place a legend in the figure. Labels are a sequence of
strings, handles is a sequence of line or patch instances, and
loc can be a string or an integer specifying the legend
location
USAGE:
legend( (line1, line2, line3),
('label1', 'label2', 'label3'),
'upper right')
The LOC location codes are
'best' : 0, (currently not supported, defaults to upper right)
'upper right' : 1, (default)
'upper left' : 2,
'lower left' : 3,
'lower right' : 4,
'right' : 5,
'center left' : 6,
'center right' : 7,
'lower center' : 8,
'upper center' : 9,
'center' : 10,
The legend instance is returned
"""
handles = flatten(handles)
l = Legend(self, handles, labels, loc, isaxes=False, **kwargs)
self._set_artist_props(l)
self.legends.append(l)
return l
def set_linestyle(self, linestyle):
"""
Set the linestyle of the line
'steps' is equivalent to 'steps-pre' and is maintained for
backward-compatibility.
ACCEPTS: [ '-' | '--' | '-.' | ':' | 'None' | ' ' | '' ] and
any drawstyle in combination with a linestyle, e.g. 'steps--'.
"""
# handle long drawstyle names before short ones !
for ds in flatten([k.keys() for k in (self._drawStyles_l,
self._drawStyles_s)], is_string_like):
if linestyle.startswith(ds):
self.set_drawstyle(ds)
if len(linestyle) > len(ds):
linestyle = linestyle[len(ds):]
else:
linestyle = '-'
if linestyle not in self._lineStyles:
if linestyle in ls_mapper:
linestyle = ls_mapper[linestyle]
else:
verbose.report('Unrecognized line style %s, %s' %
(linestyle, type(linestyle)))
if linestyle in [' ','']:
linestyle = 'None'
self._linestyle = linestyle
def legend(self, handles, labels, loc, **kwargs):
"""
Place a legend in the figure. Labels are a sequence of
strings, handles is a sequence of line or patch instances, and
loc can be a string or an integer specifying the legend
location
USAGE:
legend( (line1, line2, line3),
('label1', 'label2', 'label3'),
'upper right')
The LOC location codes are
'best' : 0, (currently not supported, defaults to upper right)
'upper right' : 1, (default)
'upper left' : 2,
'lower left' : 3,
'lower right' : 4,
'right' : 5,
'center left' : 6,
'center right' : 7,
'lower center' : 8,
'upper center' : 9,
'center' : 10,
The legend instance is returned
"""
handles = flatten(handles)
l = Legend(self, handles, labels, loc, isaxes=False, **kwargs)
self._set_artist_props(l)
self.legends.append(l)
return l
def legend(self, handles, labels, *args, **kwargs):
"""
Place a legend in the figure. Labels are a sequence of
strings, handles is a sequence of line or patch instances, and
loc can be a string or an integer specifying the legend
location
USAGE:
legend( (line1, line2, line3),
('label1', 'label2', 'label3'),
'upper right')
The LOC location codes are
'best' : 0, (currently not supported for figure legends)
'upper right' : 1,
'upper left' : 2,
'lower left' : 3,
'lower right' : 4,
'right' : 5,
'center left' : 6,
'center right' : 7,
'lower center' : 8,
'upper center' : 9,
'center' : 10,
loc can also be an (x,y) tuple in figure coords, which
specifies the lower left of the legend box. figure coords are
(0,0) is the left, bottom of the figure and 1,1 is the right,
top.
The legend instance is returned. The following kwargs are supported:
loc = "upper right" #
numpoints = 4 # the number of points in the legend line
prop = FontProperties(size='smaller') # the font property
pad = 0.2 # the fractional whitespace inside the legend border
markerscale = 0.6 # the relative size of legend markers vs. original
shadow # if True, draw a shadow behind legend
labelsep = 0.005 # the vertical space between the legend entries
handlelen = 0.05 # the length of the legend lines
handletextsep = 0.02 # the space between the legend line and legend text
axespad = 0.02 # the border between the axes and legend edge
"""
handles = flatten(handles)
l = Legend(self, handles, labels, *args, **kwargs)
self._set_artist_props(l)
self.legends.append(l)
return l
def legend(self, handles, labels, *args, **kwargs):
"""
Place a legend in the figure. Labels are a sequence of
strings, handles is a sequence of line or patch instances, and
loc can be a string or an integer specifying the legend
location
USAGE:
legend( (line1, line2, line3),
('label1', 'label2', 'label3'),
'upper right')
The LOC location codes are
'best' : 0, (currently not supported for figure legends)
'upper right' : 1,
'upper left' : 2,
'lower left' : 3,
'lower right' : 4,
'right' : 5,
'center left' : 6,
'center right' : 7,
'lower center' : 8,
'upper center' : 9,
'center' : 10,
loc can also be an (x,y) tuple in figure coords, which
specifies the lower left of the legend box. figure coords are
(0,0) is the left, bottom of the figure and 1,1 is the right,
top.
The legend instance is returned. The following kwargs are supported:
loc = "upper right" #
numpoints = 4 # the number of points in the legend line
prop = FontProperties(size='smaller') # the font property
pad = 0.2 # the fractional whitespace inside the legend border
markerscale = 0.6 # the relative size of legend markers vs. original
shadow # if True, draw a shadow behind legend
labelsep = 0.005 # the vertical space between the legend entries
handlelen = 0.05 # the length of the legend lines
handletextsep = 0.02 # the space between the legend line and legend text
axespad = 0.02 # the border between the axes and legend edge
"""
handles = flatten(handles)
l = Legend(self, handles, labels, *args, **kwargs)
self._set_artist_props(l)
self.legends.append(l)
return l
def set_linestyle(self, linestyle):
"""
Set the linestyle of the line (also accepts drawstyles)
================ =================
linestyle description
================ =================
'-' solid
'--' dashed
'-.' dash_dot
':' dotted
'None' draw nothing
' ' draw nothing
'' draw nothing
================ =================
'steps' is equivalent to 'steps-pre' and is maintained for
backward-compatibility.
.. seealso::
:meth:`set_drawstyle`
To set the drawing style (stepping) of the plot.
ACCEPTS: [ '-' | '--' | '-.' | ':' | 'None' | ' ' | '' ] and
any drawstyle in combination with a linestyle, e.g. 'steps--'.
"""
# handle long drawstyle names before short ones !
for ds in flatten(
[k.keys() for k in (self._drawStyles_l, self._drawStyles_s)],
is_string_like):
if linestyle.startswith(ds):
self.set_drawstyle(ds)
if len(linestyle) > len(ds):
linestyle = linestyle[len(ds):]
else:
linestyle = '-'
if linestyle not in self._lineStyles:
if linestyle in ls_mapper:
linestyle = ls_mapper[linestyle]
else:
verbose.report('Unrecognized line style %s, %s' %
(linestyle, type(linestyle)))
if linestyle in [' ', '']:
linestyle = 'None'
self._linestyle = linestyle
def set_linestyle(self, linestyle):
"""
Set the linestyle of the line (also accepts drawstyles)
================ =================
linestyle description
================ =================
'-' solid
'--' dashed
'-.' dash_dot
':' dotted
'None' draw nothing
' ' draw nothing
'' draw nothing
================ =================
'steps' is equivalent to 'steps-pre' and is maintained for
backward-compatibility.
.. seealso::
:meth:`set_drawstyle`
To set the drawing style (stepping) of the plot.
ACCEPTS: [ '-' | '--' | '-.' | ':' | 'None' | ' ' | '' ] and
any drawstyle in combination with a linestyle, e.g. 'steps--'.
"""
# handle long drawstyle names before short ones !
for ds in flatten([k.keys() for k in (self._drawStyles_l,
self._drawStyles_s)], is_string_like):
if linestyle.startswith(ds):
self.set_drawstyle(ds)
if len(linestyle) > len(ds):
linestyle = linestyle[len(ds):]
else:
linestyle = '-'
if linestyle not in self._lineStyles:
if linestyle in ls_mapper:
linestyle = ls_mapper[linestyle]
else:
verbose.report('Unrecognized line style %s, %s' %
(linestyle, type(linestyle)))
if linestyle in [' ','']:
linestyle = 'None'
self._linestyle = linestyle
def set(h, *args, **kwargs):
"""
Set handle h property in string s to value val
h can be a handle or vector of handles.
h is an instance (or vector of instances) of a class, eg a Line2D
or an Axes or Text.
args is a list of string, value pairs. if the string
is 'somename', set function calls
o.set_somename(value)
for every instance in h.
"""
if not iterable(h): h = [h]
else: h = flatten(h)
if len(args)%2:
error_msg('The set args must be string, value pairs')
funcvals = []
for i in range(0, len(args)-1, 2):
funcvals.append((args[i], args[i+1]))
funcvals.extend(kwargs.items())
ret = []
for o in h:
for s, val in funcvals:
s = s.lower()
funcName = "set_%s"%s
func = getattr(o,funcName)
try: ret.extend( [func(val)] )
except ValueError, msg:
msg = exception_to_str(msg)
error_msg(msg)
raise RuntimeError(msg)
def set(h, s, val):
"""
Set handle h property in string s to value val
h can be a handle or vector of handles.
h is an instance (or vector of instances) of a class, eg a Line2D
or an Axes or AxisText. if s is 'somename', this function calls
o.set_somename(val)
for every instance in o in h
"""
if not iterable(h): h = [h]
else: h = flatten(h)
for o in h:
try:
func = 'o.set_%s(val)' % s
eval(func, {}, {'o': o, 'val': val})
except ValueError, msg:
msg = raise_msg_to_str(msg)
error_msg(msg)
raise RuntimeError, msg
def set(h, s, val):
"""
Set handle h property in string s to value val
h can be a handle or vector of handles.
h is an instance (or vector of instances) of a class, eg a Line2D
or an Axes or AxisText. if s is 'somename', this function calls
o.set_somename(val)
for every instance in o in h
"""
if not iterable(h): h = [h]
else: h = flatten(h)
for o in h:
try:
func = 'o.set_%s(val)' % s
eval(func, {}, {'o': o, 'val' : val})
except ValueError, msg:
msg = raise_msg_to_str(msg)
error_msg(msg)
raise RuntimeError, msg
def legend(self, handles, labels, *args, **kwargs):
"""
Place a legend in the figure. Labels are a sequence of
strings, handles is a sequence of
:class:`~matplotlib.lines.Line2D` or
:class:`~matplotlib.patches.Patch` instances, and loc can be a
string or an integer specifying the legend location
USAGE::
legend( (line1, line2, line3),
('label1', 'label2', 'label3'),
'upper right')
The *loc* location codes are::
'best' : 0, (currently not supported for figure legends)
'upper right' : 1,
'upper left' : 2,
'lower left' : 3,
'lower right' : 4,
'right' : 5,
'center left' : 6,
'center right' : 7,
'lower center' : 8,
'upper center' : 9,
'center' : 10,
*loc* can also be an (x,y) tuple in figure coords, which
specifies the lower left of the legend box. figure coords are
(0,0) is the left, bottom of the figure and 1,1 is the right,
top.
Keyword arguments:
*prop*: [ None | FontProperties | dict ]
A :class:`matplotlib.font_manager.FontProperties`
instance. If *prop* is a dictionary, a new instance will be
created with *prop*. If *None*, use rc settings.
*numpoints*: integer
The number of points in the legend line, default is 4
*scatterpoints*: integer
The number of points in the legend line, default is 4
*scatteroffsets*: list of floats
a list of yoffsets for scatter symbols in legend
*markerscale*: [ None | scalar ]
The relative size of legend markers vs. original. If *None*, use rc
settings.
*fancybox*: [ None | False | True ]
if True, draw a frame with a round fancybox. If None, use rc
*shadow*: [ None | False | True ]
If *True*, draw a shadow behind legend. If *None*, use rc settings.
*ncol* : integer
number of columns. default is 1
*mode* : [ "expand" | None ]
if mode is "expand", the legend will be horizontally expanded
to fill the axes area (or *bbox_to_anchor*)
*title* : string
the legend title
Padding and spacing between various elements use following keywords
parameters. The dimensions of these values are given as a fraction
of the fontsize. Values from rcParams will be used if None.
================ ==================================================================
Keyword Description
================ ==================================================================
borderpad the fractional whitespace inside the legend border
labelspacing the vertical space between the legend entries
handlelength the length of the legend handles
handletextpad the pad between the legend handle and text
borderaxespad the pad between the axes and legend border
columnspacing the spacing between columns
================ ==================================================================
.. Note:: Not all kinds of artist are supported by the legend.
See LINK (FIXME) for details.
**Example:**
.. plot:: mpl_examples/pylab_examples/figlegend_demo.py
"""
handles = flatten(handles)
l = Legend(self, handles, labels, *args, **kwargs)
self.legends.append(l)
return l
def legend(self, handles, labels, *args, **kwargs):
"""
Place a legend in the figure. Labels are a sequence of
strings, handles is a sequence of
:class:`~matplotlib.lines.Line2D` or
:class:`~matplotlib.patches.Patch` instances, and loc can be a
string or an integer specifying the legend location
USAGE::
legend( (line1, line2, line3),
('label1', 'label2', 'label3'),
'upper right')
The *loc* location codes are::
'best' : 0, (currently not supported for figure legends)
'upper right' : 1,
'upper left' : 2,
'lower left' : 3,
'lower right' : 4,
'right' : 5,
'center left' : 6,
'center right' : 7,
'lower center' : 8,
'upper center' : 9,
'center' : 10,
*loc* can also be an (x,y) tuple in figure coords, which
specifies the lower left of the legend box. figure coords are
(0,0) is the left, bottom of the figure and 1,1 is the right,
top.
The legend instance is returned. The following kwargs are supported
*loc*
the location of the legend
*numpoints*
the number of points in the legend line
*prop*
a :class:`matplotlib.font_manager.FontProperties` instance
*pad*
the fractional whitespace inside the legend border
*markerscale*
the relative size of legend markers vs. original
*shadow*
if True, draw a shadow behind legend
*labelsep*
the vertical space between the legend entries
*handlelen*
the length of the legend lines
*handletextsep*
the space between the legend line and legend text
*axespad*
the border between the axes and legend edge
.. plot:: mpl_examples/pylab_examples/figlegend_demo.py
"""
handles = flatten(handles)
l = Legend(self, handles, labels, *args, **kwargs)
self.legends.append(l)
return l
def legend(self, handles, labels, *args, **kwargs):
"""
Place a legend in the figure. Labels are a sequence of
strings, handles is a sequence of
:class:`~matplotlib.lines.Line2D` or
:class:`~matplotlib.patches.Patch` instances, and loc can be a
string or an integer specifying the legend location
USAGE::
legend( (line1, line2, line3),
('label1', 'label2', 'label3'),
'upper right')
The *loc* location codes are::
'best' : 0, (currently not supported for figure legends)
'upper right' : 1,
'upper left' : 2,
'lower left' : 3,
'lower right' : 4,
'right' : 5,
'center left' : 6,
'center right' : 7,
'lower center' : 8,
'upper center' : 9,
'center' : 10,
*loc* can also be an (x,y) tuple in figure coords, which
specifies the lower left of the legend box. figure coords are
(0,0) is the left, bottom of the figure and 1,1 is the right,
top.
Keyword arguments:
*prop*: [ None | FontProperties | dict ]
A :class:`matplotlib.font_manager.FontProperties`
instance. If *prop* is a dictionary, a new instance will be
created with *prop*. If *None*, use rc settings.
*numpoints*: integer
The number of points in the legend line, default is 4
*scatterpoints*: integer
The number of points in the legend line, default is 4
*scatteroffsets*: list of floats
a list of yoffsets for scatter symbols in legend
*markerscale*: [ None | scalar ]
The relative size of legend markers vs. original. If *None*, use rc
settings.
*fancybox*: [ None | False | True ]
if True, draw a frame with a round fancybox. If None, use rc
*shadow*: [ None | False | True ]
If *True*, draw a shadow behind legend. If *None*, use rc settings.
*ncol* : integer
number of columns. default is 1
*mode* : [ "expand" | None ]
if mode is "expand", the legend will be horizontally expanded
to fill the axes area (or *bbox_to_anchor*)
*title* : string
the legend title
Padding and spacing between various elements use following keywords
parameters. The dimensions of these values are given as a fraction
of the fontsize. Values from rcParams will be used if None.
================ ==================================================================
Keyword Description
================ ==================================================================
borderpad the fractional whitespace inside the legend border
labelspacing the vertical space between the legend entries
handlelength the length of the legend handles
handletextpad the pad between the legend handle and text
borderaxespad the pad between the axes and legend border
columnspacing the spacing between columns
================ ==================================================================
**Example:**
.. plot:: mpl_examples/pylab_examples/figlegend_demo.py
"""
handles = flatten(handles)
l = Legend(self, handles, labels, *args, **kwargs)
self.legends.append(l)
return l
def setp(h, *args, **kwargs):
"""
matplotlib supports the use of setp ("set property") and getp to set
and get object properties, as well as to do introspection on the
object For example, to set the linestyle of a line to be dashed, you
can do
>>> line, = plot([1,2,3])
>>> setp(line, linestyle='--')
If you want to know the valid types of arguments, you can provide the
name of the property you want to set without a value
>>> setp(line, 'linestyle')
linestyle: [ '-' | '--' | '-.' | ':' | 'steps' | 'None' ]
If you want to see all the properties that can be set, and their
possible values, you can do
>>> setp(line)
... long output listing omitted'
setp operates on a single instance or a list of instances. If you
are in query mode introspecting the possible values, only the first
instance in the sequence is used. When actually setting values,
all the instances will be set. Eg, suppose you have a list of two
lines, the following will make both lines thicker and red
>>> x = arange(0,1.0,0.01)
>>> y1 = sin(2*pi*x)
>>> y2 = sin(4*pi*x)
>>> lines = plot(x, y1, x, y2)
>>> setp(lines, linewidth=2, color='r')
setp works with the matlab(TM) style string/value pairs or with
python kwargs. For example, the following are equivalent
>>> setp(lines, 'linewidth', 2, 'color', r') # matlab style
>>> setp(lines, linewidth=2, color='r') # python style
"""
insp = ArtistInspector(h)
if len(kwargs)==0 and len(args)==0:
print '\n'.join(insp.pprint_setters())
return
if len(kwargs)==0 and len(args)==1:
print insp.pprint_setters(prop=args[0])
return
if not iterable(h): h = [h]
else: h = flatten(h)
if len(args)%2:
raise ValueError('The set args must be string, value pairs')
funcvals = []
for i in range(0, len(args)-1, 2):
funcvals.append((args[i], args[i+1]))
funcvals.extend(kwargs.items())
ret = []
for o in h:
for s, val in funcvals:
s = s.lower()
funcName = "set_%s"%s
func = getattr(o,funcName)
ret.extend( [func(val)] )
return [x for x in flatten(ret)]
def setp(h, *args, **kwargs):
"""
matlab(TM) and pylab allow you to use set and get to set and get
object properties, as well as to do introspection on the object
For example, to set the linestyle of a line to be dashed, you can do
>>> line, = plot([1,2,3])
>>> set(line, linestyle='--')
If you want to know the valid types of arguments, you can provide the
name of the property you want to set without a value
>>> set(line, 'linestyle')
linestyle: [ '-' | '--' | '-.' | ':' | 'steps' | 'None' ]
If you want to see all the properties that can be set, and their
possible values, you can do
>>> set(line)
... long output listing omitted'
set operates on a single instance or a list of instances. If you are
in quey mode introspecting the possible values, only the first
instance in the sequnce is used. When actually setting values, all
the instances will be set. Eg, suppose you have a list of two lines,
the following will make both lines thicker and red
>>> x = arange(0,1.0,0.01)
>>> y1 = sin(2*pi*x)
>>> y2 = sin(4*pi*x)
>>> lines = plot(x, y1, x, y2)
>>> set(lines, linewidth=2, color='r')
Set works with the matlab(TM) style string/value pairs or with python
kwargs. For example, the following are equivalent
>>> set(lines, 'linewidth', 2, 'color', r') # matlab style
>>> set(lines, linewidth=2, color='r') # python style
"""
insp = ArtistInspector(h)
if len(kwargs) == 0 and len(args) == 0:
print '\n'.join(insp.pprint_setters())
return
if len(kwargs) == 0 and len(args) == 1:
print insp.pprint_setters(prop=args[0])
return
if not iterable(h): h = [h]
else: h = flatten(h)
if len(args) % 2:
raise ValueError('The set args must be string, value pairs')
funcvals = []
for i in range(0, len(args) - 1, 2):
funcvals.append((args[i], args[i + 1]))
funcvals.extend(kwargs.items())
ret = []
for o in h:
for s, val in funcvals:
s = s.lower()
funcName = "set_%s" % s
func = getattr(o, funcName)
ret.extend([func(val)])
return [x for x in flatten(ret)]
def legend(self, handles, labels, *args, **kwargs):
"""
Place a legend in the figure. Labels are a sequence of
strings, handles is a sequence of
:class:`~matplotlib.lines.Line2D` or
:class:`~matplotlib.patches.Patch` instances, and loc can be a
string or an integer specifying the legend location
USAGE::
legend( (line1, line2, line3),
('label1', 'label2', 'label3'),
'upper right')
The *loc* location codes are::
'best' : 0, (currently not supported for figure legends)
'upper right' : 1,
'upper left' : 2,
'lower left' : 3,
'lower right' : 4,
'right' : 5,
'center left' : 6,
'center right' : 7,
'lower center' : 8,
'upper center' : 9,
'center' : 10,
*loc* can also be an (x,y) tuple in figure coords, which
specifies the lower left of the legend box. figure coords are
(0,0) is the left, bottom of the figure and 1,1 is the right,
top.
The legend instance is returned. The following kwargs are supported
*loc*
the location of the legend
*numpoints*
the number of points in the legend line
*prop*
a :class:`matplotlib.font_manager.FontProperties` instance
*pad*
the fractional whitespace inside the legend border
*markerscale*
the relative size of legend markers vs. original
*shadow*
if True, draw a shadow behind legend
*labelsep*
the vertical space between the legend entries
*handlelen*
the length of the legend lines
*handletextsep*
the space between the legend line and legend text
*axespad*
the border between the axes and legend edge
.. plot:: ../mpl_examples/pylab_examples/figlegend_demo.py
"""
handles = flatten(handles)
l = Legend(self, handles, labels, *args, **kwargs)
self.legends.append(l)
return l
funcvals.extend(kwargs.items())
ret = []
for o in h:
for s, val in funcvals:
s = s.lower()
funcName = "set_%s"%s
func = getattr(o,funcName)
try: ret.extend( [func(val)] )
except ValueError, msg:
msg = exception_to_str(msg)
error_msg(msg)
raise RuntimeError(msg)
draw_if_interactive()
return [x for x in flatten(ret)]
def specgram(*args, **kwargs):
try: ret = gca().specgram(*args, **kwargs)
except ValueError, msg:
msg = raise_msg_to_str(msg)
error_msg(msg)
else:
Pxx, freqs, bins, im = ret
gci._current = im
draw_if_interactive()
return ret
specgram.__doc__ = Axes.specgram.__doc__
def subplot(*args, **kwargs):
"""
