"""
.. module:: CPlot
:synopsis: A standard plot.
.. moduleauthor:: Marco Melis <marco.melis@unica.it>
.. moduleauthor:: Ambra Demontis <ambra.demontis@unica.it>
"""
import inspect
import sys
from matplotlib.axes import Axes
from secml.core import CCreator
from secml.array import CArray
from secml.array.array_utils import tuple_sequence_tondarray
[docs]class CPlot(CCreator):
"""Interface for standard plots.
This class provides an interface and few other methods useful
for standard plot creation.
To be never explicitly instanced. Will be created by `CFigure`.
Parameters
----------
sp : Axes
Subplot to use for plotting. Instance of `matplotlib.axes.Axes`.
default_params : dict
Dictionary with default parameters.
See Also
--------
.CFigure : creates and handle figures.
"""
def __init__(self, sp, default_params):
if not isinstance(sp, Axes):
raise TypeError("`matplotlib.axes.Axes` instance is requested.")
# Target subplot reference
self._sp = sp
# Store default parameters
self._params = default_params
# Collect methods from subclasses
self._collect_spmethods()
# Callback parameter for showing the legend after
# applying custom plot parameters
self.show_legend = None
# Placeholders for plot parameters
self._ylabel = None
self._xlabel = None
self._yticks = None
self._yticklabels = None
self._xticks = None
self._xticklabels = None
self._xlim = None
self._ylim = None
def _collect_spmethods(self):
"""Collects methods from CPlot subclasses and attach them to self."""
c_list = CPlot.get_subclasses() # Retrieve all CPlot subclasses
methods_list = []
for c_info in c_list: # For each CPlot subclass (name, class)
if c_info[0] == CPlot.__name__:
# Avoid adding methods of CPlot to CPlot
continue
# Get methods of each CPlot subclasses,
# use isfunction for Py3, ismethod for Py2 # TODO: REMOVE Python 2
pred = inspect.isfunction # unbound methods or functions
if sys.version_info < (3, 0): # Py2 this covers unbound methods
pred = inspect.ismethod
c_methods = inspect.getmembers(c_info[1], pred)
for method in c_methods: # For each method (name, unbound method)
# Skip special methods and already added methods
if not method[0].startswith('__') and \
method[0] not in methods_list and \
not hasattr(self, method[0]):
methods_list.append(method)
# Add methods to CPlot. Use __get__ to bound method to CPlot instance
for method in methods_list:
setattr(self, method[0], method[1].__get__(self))
@property
def n_lines(self):
"""Returns the number of lines inside current subplot."""
return len(self.get_lines())
def _set_lines_params(self, kwargs):
"""Add lines-related parameters to input dictionary."""
# Parameters are updated/added only if not yet specified
if 'linewidth' not in kwargs:
kwargs['linewidth'] = self._params['lines.linewidth']
if 'markersize' not in kwargs:
kwargs['markersize'] = self._params['lines.markersize']
return kwargs
[docs] def set(self, param_name, param_value, copy=False):
raise NotImplementedError
[docs] def get_params(self):
raise NotImplementedError
[docs] def get_state(self):
raise NotImplementedError
[docs] def set_state(self, state_dict, copy=False):
raise NotImplementedError
[docs] def load_state(self, path):
raise NotImplementedError
[docs] def save_state(self, path):
raise NotImplementedError
[docs] def get_lines(self):
"""Return a list of lines contained by the subplot."""
return self._sp.get_lines()
[docs] def get_legend_handles_labels(self):
"""Return handles and labels for legend contained by the subplot."""
return self._sp.get_legend_handles_labels()
[docs] def get_xticks_idx(self, xticks):
"""Returns the position of markers to plot.
Parameters
----------
xticks : CArray
Ticks of x-axis where marker should be plotted.
Returns
-------
ticks_idx : list
List with the position of each xtick.
Notes
-----
If a given xtick is not exactly available,
the closest value's position will be returned.
"""
return xticks.binary_search(self._sp.get_xticks()).tolist()
[docs] def set_axisbelow(self, axisbelow=True):
"""Set axis ticks and gridlines below most artists."""
self._sp.set_axisbelow(axisbelow)
[docs] def merge(self, sp):
"""Merge input subplot to active subplot.
Parameters
----------
sp : CPlot
Subplot to be merged.
"""
for line in sp.get_lines():
self._sp.add_line(line)
if self.get_legend() is not None:
h, l = sp.get_legend_handles_labels()
self.legend(h, l)
[docs] def plot(self, x, y=None, *args, **kwargs):
"""Plot a line.
If only one array is given it is supposed to be the
y axis data. x axis values are set as index array 0..N-1 .
Parameters
----------
x : list or CArray
x axis values
y : list or CArray
y axis values
color : str
.. list-table::
:header-rows: 1
* - Character
- Color
* - 'b'
- blue
* - 'g'
- green
* - 'r'
- red
* - 'c'
- cyan
* - 'm'
- magenta
* - 'y'
- yellow
* - 'k'
- black
* - 'w'
- white
alpha : float, default 1.0
0.0 for transparent through 1.0 opaque
linestyle : character, default '-'
Can be one into this list : ['-' | '--' | '-.' | ':' | 'None' | ' ' | '']
linewidth : float
0.0 to 1.0
marker : str
.. list-table::
:header-rows: 1
* - Character
- Marker
* - '.'
- point marker
* - ','
- pixel marker
* - 'o'
- circle marker
* - 'v'
- triangle_down marker
* - '^'
- triangle_up marker
* - '<'
- triangle_left marker
* - '>'
- triangle_right marker
* - '1'
- tri_down marker
* - '2'
- tri_up marker
* - '3'
- tri_left marker
* - '4'
- tri_right marker
* - 's'
- square marker
* - 'p'
- pentagon marker
* - '*'
- star marker
* - 'h'
- hexagon1 marker
* - 'H'
- hexagon2 marker
* - '+'
- plus marker
* - 'x'
- x marker
* - 'D'
- diamond marker
* - 'd'
- thin_diamond marker
* - '|'
- vline marker
* - '_'
- hline marker
Examples
--------
.. plot:: pyplots/plot.py
:include-source:
"""
# Set lines-related parameters
kwargs = self._set_lines_params(kwargs)
# Convert sequences inside tuple to ndarray
x, y = tuple_sequence_tondarray((x, y))
if y is None:
self._sp.plot(x, *args, **kwargs)
else:
self._sp.plot(x, y, *args, **kwargs)
[docs] def semilogx(self, x, y=None, *args, **kwargs):
"""Plot with log scaling on the x axis.
If only one array is given it is supposed to be the
y axis data. x axis values are set as index array 0..N-1 .
Parameters
----------
x : list or CArray
x axis values
y : list or CArray
y axis values
basex : scalar > 1, default is 10
Base of the x logarithm
subsx : [ None | sequence ]
Where to place the subticks between each major tick.
Sequence of integers. For example, in a log10 scale:
[2, 3, 4, 5, 6, 7, 8, 9] will place 8 logarithmically
spaced minor ticks between each major tick.
nonposx : [ 'mask' | 'clip' ], default 'mask'
Non-positive values in x can be masked as invalid, or
clipped to a very small positive number
See Also
--------
.plot : Plot with standard axis.
Examples
--------
.. plot:: pyplots/semilogx.py
:include-source:
"""
if 'subsx' in kwargs and isinstance(kwargs['subsx'], CArray):
kwargs['subsx'] = kwargs['subsx'].tondarray()
# Set other lines-related parameters
kwargs = self._set_lines_params(kwargs)
# Convert sequences inside tuple to ndarray
x, y = tuple_sequence_tondarray((x, y))
if y is None:
self._sp.semilogx(x, *args, **kwargs)
else:
self._sp.semilogx(x, y, *args, **kwargs)
[docs] def semilogy(self, x, y=None, *args, **kwargs):
"""Plot with log scaling on the y axis.
If only one array is given it is supposed to be the
y axis data. x axis values are set as index array 0..N-1 .
Parameters
----------
x : list or CArray
x axis values.
y : list or CArray
y axis values.
basey : scalar > 1, default is 10
Base of the y logarithm
subsy : [ None | sequence ], default None
Where to place the subticks between each major tick.
Should be a sequence of integers.
For example, in a log10 scale: [2, 3, 4, 5, 6, 7, 8, 9]
will place 8 logarithmically spaced minor ticks between
each major tick.
nonposy : [ 'mask' | 'clip' ], default 'mask'
Non-positive values in x can be masked as invalid, or
clipped to a very small positive number.
See Also
--------
.plot : Plot with standard axis.
Examples
--------
.. plot:: pyplots/semilogy.py
:include-source:
"""
if 'subsy' in kwargs and isinstance(kwargs['subsy'], CArray):
kwargs['subsy'] = kwargs['subsy'].tondarray()
# Set other lines-related parameters
kwargs = self._set_lines_params(kwargs)
# Convert sequences inside tuple to ndarray
x, y = tuple_sequence_tondarray((x, y))
if y is None:
self._sp.semilogy(x, *args, **kwargs)
else:
self._sp.semilogy(x, y, *args, **kwargs)
[docs] def loglog(self, x, y=None, *args, **kwargs):
"""Plot with log scaling on both the x and y axis.
If only one array is given it is supposed to be the
y axis data. x axis values are set as index array 0..N-1 .
Parameters
----------
x : list or CArray
x axis values.
y : list or CArray
y axis values.
basex, basey : scalar > 1, default is 10
Base of the x/y logarithm.
subsx, subsy : [ None | sequence ]
Where to place the subticks between each major tick.
Should be a sequence of integers. For example, in a
log10 scale: [2, 3, 4, 5, 6, 7, 8, 9] will place 8
logarithmically spaced minor ticks between each major tick.
nonposx, nonposy : ['mask' | 'clip' ], default 'mask'.
Non-positive values in x or y can be masked as invalid, or
clipped to a very small positive number.
See Also
--------
.plot : Plot with standard axis.
"""
if 'subsx' in kwargs and isinstance(kwargs['subsx'], CArray):
kwargs['subsx'] = kwargs['subsx'].tondarray()
if 'subsy' in kwargs and isinstance(kwargs['subsy'], CArray):
kwargs['subsy'] = kwargs['subsy'].tondarray()
# Set other lines-related parameters
kwargs = self._set_lines_params(kwargs)
# Convert sequences inside tuple to ndarray
x, y = tuple_sequence_tondarray((x, y))
if y is None:
self._sp.loglog(x, *args, **kwargs)
else:
self._sp.loglog(x, y, *args, **kwargs)
[docs] def scatter(self, x, y, s=20, c='b', *args, **kwargs):
"""Scatter plot of x vs y.
Parameters
----------
x, y : list or CArray
Input data. Both object must have the same size.
s : scalar or shape (n, ), optional, default: 20
size in points^2.
c : color or sequence of color, optional, default 'b'
c can be a single color format string, or a sequence
of color specifications of length N, or a sequence of
numbers with the same shape of x,y to be mapped to
colors using the cmap and norm specified via kwargs
(see below). Note that c should not be a single
numeric RGB or RGBA sequence because that is
indistinguishable from an array of values to be
colormapped. c can be a 2-D array in which the rows
are RGB or RGBA, however.
marker : MarkerStyle, optional, default: 'o'
See markers for more information on the different
styles of markers scatter supports.
cmap : Colormap, optional, default: None
A Colormap instance or registered name. cmap is only
used if c is an array of floats. If None, default
parameter image.cmap is used.
norm : Normalize, optional, default: None
A Normalize instance is used to scale luminance data
to 0, 1. norm is only used if c is an array of floats.
vmin, vmax : scalar, optional, default: None
vmin and vmax are used in conjunction with norm to
normalize luminance data. If either are None, the min
and max of the color array is used. Note if you pass a
norm instance, your settings for vmin and vmax will
be ignored.
alpha : scalar, optional, default: None
The alpha blending value, between 0 (transparent) and 1 (opaque)
linewidths : scalar or array_like, optional, default: None
If None, defaults to (lines.linewidth,). Note that this
is a tuple, and if you set the linewidths argument you
must set it as a sequence of float.
Examples
--------
.. plot:: pyplots/scatter.py
:include-source:
"""
if 'linewidths' not in kwargs:
kwargs['linewidths'] = self._params['lines.linewidth']
# Convert sequences inside tuple to ndarray
if not isinstance(c, str):
x, y, c = tuple_sequence_tondarray((x, y, c))
else:
x, y = tuple_sequence_tondarray((x, y))
self._sp.scatter(x, y, s, c, *args, **kwargs)
[docs] def contour(self, x, y, z, *args, **kwargs):
"""Draw contour lines of a function.
Parameters
----------
x, y : CArray or list
specify the (x, y) coordinates of the surface.
X and Y must both be 2-D with the same shape
as Z, or they must both be 1-D such that len(X)
is the number of columns in Z and len(Y) is the
number of rows in Z.
z : CArray or list
value into (x, y) surface's position
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 Colormap instance or None. If cmap is None and
colors is None, a default Colormap is used.
vmin, vmax : [ None | scalar ]
If not None, either or both of these values will be
supplied to the matplotlib.colors.
Normalize instance, overriding the default color
scaling based on levels.
levels : [level0, level1, ..., leveln]
A list of floating point numbers indicating the level
curves to draw; e.g., to draw just the zero contour
pass levels=[0]
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
default parameter 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 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.
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.
antialiased : [ True | False ]
enable antialiasing, overriding the defaults.
For filled contours, the default is True. For line
contours, it is taken from default_parameters ['lines.antialiased'].
linewidths : [ None | number | tuple of numbers ]
If linewidths is None, the default width in lines.linewidth
default_parameters 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 default is 'solid' unless the
lines are monochrome. In that case, negative contours will
take their linestyle from the matplotlibrc `contour.negative_`
linestyle setting.
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.
Examples
--------
.. plot:: pyplots/contour.py
:include-source:
"""
if 'linewidths' not in kwargs:
kwargs['linewidths'] = self._params['lines.linewidth']
# Convert sequences inside tuple to ndarray
x, y, z = tuple_sequence_tondarray((x, y, z))
return self._sp.contour(x, y, z, *args, **kwargs)
[docs] def contourf(self, x, y, z, *args, **kwargs):
"""Draw filled contour of a function.
Parameters
----------
x, y : CArray or list
specify the (x, y) coordinates of the surface.
X and Y must both be 2-D with the same shape as Z,
or they must both be 1-D such that len(X) is the
number of columns in Z and len(Y) is the number of
rows in Z.
z : CArray or list
value into (x, y) surface's position
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 Colormap instance or None. If cmap is None and
colors is None, a default Colormap is used.
vmin, vmax : [ None | scalar ]
If not None, either or both of these values will be
supplied to the matplotlib.colors.
Normalize instance, overriding the default color
scaling based on levels.
levels : [level0, level1, ..., leveln]
A list of floating point numbers indicating the level
curves to draw; e.g., to draw just the zero contour
pass levels=[0]
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
default parameter 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 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.
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.
antialiased : [ True | False ]
enable antialiasing, overriding the defaults.
For filled contours, the default is True. For line contours,
it is taken from default_parameters ['lines.antialiased'].
Examples
--------
.. plot:: pyplots/contourf.py
:include-source:
"""
# Convert sequences inside tuple to ndarray
x, y, z = tuple_sequence_tondarray((x, y, z))
return self._sp.contourf(x, y, z, *args, **kwargs)
[docs] def clabel(self, contour, *args, **kwargs):
"""Label a contour plot.
Parameters
----------
contour : contour object
returned from contour function
fontsize : int
size in points or relative size e.g., 'smaller', 'x-large'
colors : str
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 : bool
controls whether the underlying contour is removed
or not. Default is True.
inline_spacing : int
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 : str
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), or it can be any callable,
such as a Formatter instance, that returns a string when
called with a numeric contour level.
manual : bool
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).
manual can be an iterable object of x,y tuples. Contour
labels will be created as if mouse is clicked at each
x,y positions.
rightside_up : bool
if True (default), label rotations will always be plus
or minus 90 degrees from level.
Examples
--------
.. plot:: pyplots/clabel.py
:include-source:
"""
if 'fontsize' not in kwargs:
kwargs['fontsize'] = self._params['font.size']
return self._sp.clabel(contour, *args, **kwargs)
[docs] def colorbar(self, mappable, ticks=None, *args, **kwargs):
"""Add colorbar to plot.
Parameters
----------
mappable : object
Image, ContourSet, or other to which the colorbar applies
use_gridspec : boolean, default False
if True colorbar is created as an instance of Subplot using the grid_spec module.
Additional keyword arguments are of two kinds:
Axes properties:
.. list-table::
:header-rows: 1
* - Property
- Description
* - orientation
- vertical or horizontal
* - fraction, default 0.15
- fraction of original axes to use for colorbar
* - pad, default 0.05 if vertical, 0.15 if horizontal
- fraction of original axes between colorbar and new image axes
* - shrink, default 1.0
- fraction by which to shrink the colorbar
* - aspect, default 20
- ratio of long to short dimensions
* - anchor, default (0.0, 0.5) if vertical; (0.5, 1.0) if horizontal
- the anchor point of the colorbar axes
* - panchor, default (1.0, 0.5) if vertical; (0.5, 0.0) if horizontal;
- the anchor point of the colorbar parent axes. If False, the
parent axes' anchor will be unchanged
Colorbar properties:
.. list-table::
:header-rows: 1
* - Property
- Description
* - extend
- [ 'neither' | 'both' | 'min' | 'max' ] If not 'neither', make
pointed end(s) for out-of- range values. These are set for a
given colormap using the colormap set_under and set_over methods.
* - extendfrac
- [ None | 'auto' | length | lengths ] If set to None, both the
minimum and maximum triangular colorbar extensions with have a
length of 5% of the interior colorbar length (this is the default
setting). If set to 'auto', makes the triangular colorbar
extensions the same lengths as the interior boxes (when spacing
is set to 'uniform') or the same lengths as the respective adjacent
interior boxes (when spacing is set to 'proportional'). If a scalar,
indicates the length of both the minimum and maximum triangular colorbar
extensions as a fraction of the interior colorbar length. A two-element
sequence of fractions may also be given, indicating the lengths of the
minimum and maximum colorbar extensions respectively as a fraction of
the interior colorbar length.
* - extendrect
- [ False | True ] If False the minimum and maximum colorbar extensions
will be triangular (the default). If True the extensions will be rectangular.
* - spacing
- [ 'uniform' | 'proportional' ] Uniform spacing gives each discrete color
the same space; proportional makes the space proportional to the data interval.
* - ticks
- [ None | list of ticks | Locator object ] If None, ticks are determined
automatically from the input.
* - format
- [ None | format string | Formatter object ] If None, the ScalarFormatter
is used. If a format string is given, e.g., '%.3f', that is used. An
alternative Formatter object may be given instead.
* - drawedges
- [ False | True ] If true, draw lines at color boundaries.
Notes
-----
If mappable is a ContourSet, its extend kwarg is included automatically.
Note that the shrink kwarg provides a simple way to keep a vertical colorbar.
If the colorbar is too tall (or a horizontal colorbar is too wide) use a
smaller value of shrink.
Examples
--------
.. plot:: pyplots/colorbar.py
:include-source:
"""
ticks = ticks.tolist() if isinstance(ticks, CArray) else ticks
from matplotlib.pyplot import colorbar
cbar = colorbar(mappable, ticks=ticks, *args, **kwargs)
if 'fontsize' not in kwargs:
kwargs['fontsize'] = self._params['font.size']
cbar.ax.tick_params(labelsize=kwargs['fontsize'])
return cbar
[docs] def errorbar(self, x, y, xerr=None, yerr=None, *args, **kwargs):
"""Plot with error deltas in yerr and xerr.
Vertical errorbars are plotted if yerr is not None. Horizontal
errorbars are plotted if xerr is not None. x, y, xerr, and yerr
can all be scalars, which plots a single error bar at x, y.
Parameters
----------
x : list or CArray
x axis values.
y : list or CArray
y axis values.
xerr, yerr : [ scalar | N, Nx1, or 2xN array-like ], default None
If a scalar number, len(N) array-like object, or an
Nx1 array-like object, errorbars are drawn at +/-value
relative to the data.
If a sequence of shape 2xN, errorbars are drawn at -row1
and +row2 relative to the data.
fmt : [ '' | 'none' | plot format string ], default ''
The plot format symbol. If fmt is 'none' (case-insensitive),
only the errorbars are plotted.
This is used for adding errorbars to a bar plot, for example.
Default is '', an empty plot format string; properties are
then identical to the defaults for plot().
ecolor : [ None | mpl color ], default None
A matplotlib color arg which gives the color the errorbar
lines; if None, use the color of the line connecting the markers.
elinewidth : scalar, default None
The linewidth of the errorbar lines. If None, use the linewidth.
capsize : scalar, default 3
The length of the error bar caps in points.
capthick : scalar, default None
An alias kwarg to markeredgewidth (a.k.a. - mew). This setting
is a more sensible name for the property that controls the
thickness of the error bar cap in points. For backwards
compatibility, if mew or markeredgewidth are given, then they
will over-ride capthick. This may change in future releases.
barsabove : [ True | False ]
if True, will plot the errorbars above the plot
symbols. Default is below.
lolims, uplims, xlolims, xuplims : [ False | True ], default False
These arguments can be used to indicate that a value
gives only upper/lower limits. In that case a caret symbol
is used to indicate this. lims-arguments may be of the same
type as xerr and yerr. To use limits with inverted axes,
set_xlim() or set_ylim() must be called before errorbar().
errorevery : positive integer, default 1
subsamples the errorbars. e.g., if everyerror=5, errorbars
for every 5-th datapoint will be plotted. The data plot
itself still shows all data points.
Examples
--------
.. plot:: pyplots/errorbar.py
:include-source:
"""
# Set lines-related parameters
kwargs = self._set_lines_params(kwargs)
# Convert sequences inside tuple to ndarray
x, y, xerr, yerr = tuple_sequence_tondarray((x, y, xerr, yerr))
self._sp.errorbar(x, y, xerr=xerr, yerr=yerr, *args, **kwargs)
[docs] def bar(self, left, height, width=0.8, bottom=None, *args, **kwargs):
"""Bar plot.
Parameters
----------
left : sequence of scalars
x coordinates of the left sides of the bars.
height : sequence of scalars
height(s) of the bars.
width : scalar or array-like, optional, default: 0.8
width(s) of the bars.
bottom : scalar or array-like, optional, default: None
y coordinate(s) of the bars.
color : scalar or array-like, optional
Colors of the bar faces.
edgecolor : scalar or array-like, optional
Colors of the bar edges.
linewidth : scalar or array-like, optional, default: None
Width of bar edge(s). If None, use default linewidth;
If 0, don't draw edges.
xerr : scalar or array-like, optional, default: None
If not None, will be used to generate errorbar(s)
on the bar chart.
yerr : scalar or array-like, optional, default: None
If not None, will be used to generate errorbar(s)
on the bar chart.
ecolor : scalar or array-like, optional, default: None
Specifies the color of errorbar(s)
capsize : integer, optional, default: 3
Determines the length in points of the error bar caps.
error_kw : dict
dictionary of kwargs to be passed to errorbar method.
ecolor and capsize may be specified here rather than
independent kwargs.
align : ['edge' | 'center'], optional, default: 'edge'
If edge, aligns bars by their left edges (for vertical
bars) and by their bottom edges (for horizontal bars).
If center, interpret the left argument as the coordinates
of the centers of the bars.
orientation : 'vertical' | 'horizontal', optional, default: 'vertical'
The orientation of the bars.
log : boolean, optional, default: False
If true, sets the axis to be log scale.
Returns
-------
bar_list : list of bar type objects
Examples
--------
.. plot:: pyplots/bar.py
:include-source:
"""
if 'linewidth' not in kwargs:
kwargs['linewidth'] = self._params['lines.linewidth']
# Convert sequences inside tuple to ndarray
left, height, width, bottom = tuple_sequence_tondarray(
(left, height, width, bottom))
return self._sp.bar(left, height, width, bottom, *args, **kwargs)
[docs] def barh(self, bottom, width, height=0.8, left=None, *args, **kwargs):
"""Horizontal bar plot.
Parameters
----------
bottom : sequence of scalars
y coordinates of the bars.
width : sequence of scalars
width(s) of the bars.
height : scalar or array-like, optional, default: 0.8
height(s) of the bars.
left : scalar or array-like, optional, default: None
x coordinate(s) of the bars.
color : scalar or array-like, optional
Colors of the bar faces.
edgecolor : scalar or array-like, optional
Colors of the bar edges.
linewidth : scalar or array-like, optional, default: None
Width of bar edge(s). If None, use default linewidth;
If 0, don't draw edges.
xerr : scalar or array-like, optional, default: None
If not None, will be used to generate errorbar(s)
on the bar chart.
yerr : scalar or array-like, optional, default: None
If not None, will be used to generate errorbar(s)
on the bar chart.
ecolor : scalar or array-like, optional, default: None
Specifies the color of errorbar(s)
capsize : integer, optional, default: 3
Determines the length in points of the error bar caps.
error_kw : dict
dictionary of kwargs to be passed to errorbar method.
ecolor and capsize may be specified here rather than
independent kwargs.
align : ['edge' | 'center'], optional, default: 'edge'
If edge, aligns bars by their left edges (for vertical
bars) and by their bottom edges (for horizontal bars).
If center, interpret the left argument as the coordinates
of the centers of the bars.
orientation : 'vertical' | 'horizontal', optional, default: 'vertical'
The orientation of the bars.
log : boolean, optional, default: False
If true, sets the axis to be log scale.
Returns
-------
bar_list : list of bar type objects
"""
if 'linewidth' not in kwargs:
kwargs['linewidth'] = self._params['lines.linewidth']
# Convert sequences inside tuple to ndarray
bottom, width, height, left = tuple_sequence_tondarray(
(bottom, width, height, left))
return self._sp.barh(bottom, width, height, left, *args, **kwargs)
[docs] def hist(self, x, *args, **kwargs):
"""Plot a histogram.
Compute and draw the histogram of x.
The return value is a tuple (n, bins, patches) or
([n0, n1, ...], bins, [patches0, patches1,...]) if
the input contains multiple data.
Multiple data can be provided via x as a list of
datasets of potentially different length ([x0, x1, ...]),
or as a 2-D ndarray in which each column is a dataset.
Parameters
----------
x : (n,) array or sequence of (n,) arrays
Input values, this takes either a single array or a
sequency of arrays which are not required to be of
the same length
bins : integer or array_like, optional, default is 10
If an integer is given, bins + 1 bin edges are returned.
Unequally spaced bins are supported if bins is a sequence.
range : tuple or None, optional
The lower and upper range of the bins. Lower and upper
outliers are ignored.
If not provided, range is (x.min(), x.max()). Range has
no effect if bins is a sequence.
If bins is a sequence or range is specified, autoscaling
is based on the specified bin range instead of the range of x.
density : boolean, optional
If True, the first element of the return tuple will be
the counts normalized to form a probability density,
i.e., n/(len(x)`dbin), i.e., the integral of the histogram
will sum to 1. If stacked is also True, the sum of the
histograms is normalized to 1.
weights : (n, ) array_like or None, optional
An array of weights, of the same shape as x. Each value
in x only contributes its associated weight towards the
bin count (instead of 1). If density is True, the weights
are normalized, so that the integral of the density over
the range remains 1.
cumulative : boolean, optional
Dafault False. If True, then a histogram is computed
where each bin gives the counts in that bin plus all bins
for smaller values.
The last bin gives the total number of datapoints.
If density is also True then the histogram is normalized
such that the last bin equals 1.
If cumulative evaluates to less than 0 (e.g., -1), the
direction of accumulation is reversed. In this case, if density
is also True, then the histogram is normalized such that
the first bin equals 1.
bottom : array_like, scalar, or None
Location of the bottom baseline of each bin. If a scalar,
the base line for each bin is shifted by the same amount.
If an array, each bin is shifted independently and the
length of bottom must match the number of bins.
If None, defaults to 0.
histtype : {'bar', 'barstacked', 'step', 'stepfilled'}, optional
- 'bar' (default) is a traditional bar-type histogram.
If multiple data are given the bars are aranged side by side.
- 'barstacked' is a bar-type histogram where multiple data are
stacked on top of each other.
- 'step' generates a lineplot that is by default unfilled.
- 'stepfilled' generates a lineplot that is by default filled.
align : {'left', 'mid', 'right'}, optional
- 'left': bars are centered on the left bin edges.
- 'mid': default, bars are centered between the bin edges.
- 'right': bars are centered on the right bin edges.
orientation : {'horizontal', 'vertical'}, optional
If 'horizontal', barh will be used for bar-type histograms
and the bottom kwarg will be the left edges.
rwidth : scalar or None, optional
The relative width of the bars as a fraction of the bin width.
If None, automatically compute the width. Ignored if histtype
is 'step' or 'stepfilled'.
log : boolean, optional
Default False. If True, the histogram axis will be set to a
log scale. If log is True and x is a 1D array, empty bins
will be filtered out and only the non-empty (n, bins, patches)
will be returned.
color : color or array_like of colors or None, optional
Color spec or sequence of color specs, one per dataset.
Default (None) uses the standard line color sequence.
label : string or None, optional
String, or sequence of strings to match multiple datasets.
Bar charts yield multiple patches per dataset, but only the
first gets the label, so that the legend command will work
as expected.
stacked : boolean, optional
If True, multiple data are stacked on top of each other.
If False (default) multiple data are aranged side by side
if histtype is 'bar' or on top of each other if histtype
is 'step'.
Returns
-------
n : CArray or list of arrays
The values of the histogram bins. See density and weights
for a description of the possible semantics.
If input x is an array, then this is an array of length nbins.
If input is a sequence arrays [data1, data2,..], then this is
a list of arrays with the values of the histograms for each of
the arrays in the same order.
bins : CArray
The edges of the bins. Length nbins + 1 (nbins left edges and
right edge of last bin).
Always a single array even when multiple data sets are passed in.
patches : list or list of lists
Silent list of individual patches used to create the histogram or
list of such list if multiple input datasets.
Examples
--------
.. plot:: pyplots/hist.py
:include-source:
"""
if 'linewidth' not in kwargs:
kwargs['linewidth'] = self._params['lines.linewidth']
x = list(xi.tondarray() if isinstance(xi, CArray) else xi for xi in x)
n, bins, patches = self._sp.hist(x, *args, **kwargs)
if isinstance(n, list):
n = list(CArray(ni) for ni in n)
return n, CArray(bins), patches
[docs] def boxplot(self, x, notch=False, sym=None, vert=True, whis=1.5,
positions=None, widths=None, patch_artist=False,
bootstrap=None, usermedians=None, conf_intervals=None,
meanline=False, showmeans=False, showcaps=True,
showbox=True, showfliers=True, boxprops=None, labels=None,
flierprops=None, medianprops=None, meanprops=None,
capprops=None, whiskerprops=None, manage_xticks=True):
"""Make a box and whisker plot.
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.
Parameters
----------
x : Array or a sequence of vectors.
The input data.
notch : bool, default = False
If False, produces a rectangular box plot.
If True, will produce a notched box plot
sym : str or None, default = None
The default symbol for flier points.
Enter an empty string ('') if you don't want to show fliers.
If `None`, then the fliers default to 'b+' If you want more
control use the flierprops kwarg.
vert : bool, default = True
If True (default), makes the boxes vertical.
If False, makes horizontal boxes.
whis : float, sequence (default = 1.5) or string
As a float, determines the reach of the whiskers past the first
and third quartiles (e.g., Q3 + whis*IQR, IQR = interquartile
range, Q3-Q1). Beyond the whiskers, data are considered outliers
and are plotted as individual points. Set this to an unreasonably
high value to force the whiskers to show the min and max values.
Alternatively, set this to an ascending sequence of percentile
(e.g., [5, 95]) to set the whiskers at specific percentiles of
the data. Finally, *whis* can be the string 'range' to force the
whiskers to the min and max of the data. In the edge case that
the 25th and 75th percentiles are equivalent, *whis* will be
automatically set to 'range'.
bootstrap : None (default) or integer
Specifies whether to bootstrap the confidence intervals
around the median for notched boxplots. If bootstrap==None,
no bootstrapping is performed, and notches are calculated
using a Gaussian-based asymptotic approximation (see McGill, R.,
Tukey, J.W., and Larsen, W.A., 1978, and Kendall and Stuart,
1967). Otherwise, bootstrap specifies the number of times to
bootstrap the median to determine it's 95% confidence intervals.
Values between 1000 and 10000 are recommended.
usermedians : array-like or None (default)
An array or sequence whose first dimension (or length) is
compatible with *x*. This overrides the medians computed by
matplotlib for each element of *usermedians* that is not None.
When an element of *usermedians* == None, the median will be
computed by matplotlib as normal.
conf_intervals : array-like or None (default)
Array or sequence whose first dimension (or length) is compatible
with *x* and whose second dimension is 2. When the current element
of *conf_intervals* is not None, the notch locations computed by
matplotlib are overridden (assuming notch is True). When an
element of *conf_intervals* is None, boxplot compute notches the
method specified by the other kwargs (e.g., *bootstrap*).
positions : array-like, default = [1, 2, ..., n]
Sets the positions of the boxes. The ticks and limits
are automatically set to match the positions.
widths : array-like, default = 0.5
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.
labels : sequence or None (default)
Labels for each dataset. Length must be compatible with
dimensions of *x*
patch_artist : bool, default = False
If False produces boxes with the Line2D artist
If True produces boxes with the Patch artist
showmeans : bool, default = False
If True, will toggle one the rendering of the means
showcaps : bool, default = True
If True, will toggle one the rendering of the caps
showbox : bool, default = True
If True, will toggle one the rendering of box
showfliers : bool, default = True
If True, will toggle one the rendering of the fliers
boxprops : dict or None (default)
If provided, will set the plotting style of the boxes
whiskerprops : dict or None (default)
If provided, will set the plotting style of the whiskers
capprops : dict or None (default)
If provided, will set the plotting style of the caps
flierprops : dict or None (default)
If provided, will set the plotting style of the fliers
medianprops : dict or None (default)
If provided, will set the plotting style of the medians
meanprops : dict or None (default)
If provided, will set the plotting style of the means
meanline : bool, default = False
If True (and *showmeans* is True), will try to render the mean
as a line spanning the full width of the box according to
*meanprops*. Not recommended if *shownotches* is also True.
Otherwise, means will be shown as points.
Returns
-------
result : dict
A dictionary mapping each component of the boxplot
to a list of the :class:`matplotlib.lines.Line2D`
instances created. That dictionary has the following keys
(assuming vertical boxplots):
- boxes: the main body of the boxplot showing the quartiles
and the median's confidence intervals if enabled.
- medians: horizonal lines at the median of each box.
- whiskers: the vertical lines extending to the most extreme,
n-outlier data points.
- caps: the horizontal lines at the ends of the whiskers.
- fliers: points representing data that extend beyond the
whiskers (outliers).
- means: points or lines representing the means.
"""
if isinstance(x, CArray):
x = (x, )
x = tuple_sequence_tondarray(tuple(x))
if usermedians is not None:
if isinstance(usermedians, CArray):
usermedians = (usermedians, )
usermedians = tuple_sequence_tondarray(tuple(usermedians))
if conf_intervals is not None:
if isinstance(conf_intervals, CArray):
conf_intervals = (conf_intervals, )
conf_intervals = tuple_sequence_tondarray(tuple(conf_intervals))
if isinstance(positions, CArray):
positions = positions.tondarray()
self._sp.boxplot(x, notch, sym, vert, whis,
positions, widths, patch_artist,
bootstrap, usermedians, conf_intervals,
meanline, showmeans, showcaps,
showbox, showfliers, boxprops,
labels, flierprops, medianprops,
meanprops, capprops, whiskerprops,
manage_xticks)
[docs] def fill_between(self, x, y1, y2=0, where=None,
interpolate=False, step=None, **kwargs):
"""Fill the area between two horizontal curves.
The curves are defined by the points (x, y1) and (x, y2).
This creates one or multiple polygons describing the filled area.
You may exclude some horizontal sections from filling using where.
By default, the edges connect the given points directly.
Use step if the filling should be a step function,
i.e. constant in between x.
Parameters
----------
x : CArray (length N)
The x coordinates of the nodes defining the curves.
y1 : CArray (length N) or scalar
The y coordinates of the nodes defining the first curve.
y2 : CArray (length N) or scalar, optional, default: 0
The y coordinates of the nodes defining the second curve.
where : CArray of bool (length N), optional, default: None
Define where to exclude some horizontal regions from being filled.
The filled regions are defined by the coordinates x[where].
More precisely, fill between x[i] and x[i+1] if where[i] and
where[i+1]. Note that this definition implies that an isolated
True value between two False values in where will not result
in filling. Both sides of the True position remain unfilled due
to the adjacent False values.
interpolate : bool, optional
This option is only relvant if where is used and the two curves
are crossing each other.
Semantically, where is often used for y1 > y2 or similar.
By default, the nodes of the polygon defining the filled region
will only be placed at the positions in the x array.
Such a polygon cannot describe the above semantics close to
the intersection. The x-sections containing the intersecion
are simply clipped.
Setting interpolate to True will calculate the actual
intersection point and extend the filled region up to this point.
step : {'pre', 'post', 'mid'}, optional
Define step if the filling should be a step function,
i.e. constant in between x.
The value determines where the step will occur:
- 'pre': The y value is continued constantly to the left from
every x position, i.e. the interval (x[i-1], x[i]] has the
value y[i].
- 'post': The y value is continued constantly to the right from
every x position, i.e. the interval [x[i], x[i+1]) has the
value y[i].
- 'mid': Steps occur half-way between the x positions.
"""
x, y1, y2, where = tuple_sequence_tondarray((x, y1, y2, where))
self._sp.fill_between(x, y1, y2=y2, where=where,
interpolate=interpolate, step=step, **kwargs)
[docs] def xlim(self, bottom=None, top=None):
"""Set axes x limits.
Parameters
----------
bottom : scalar
Starting value for the x axis.
top : scalar
Ending value for the x axis.
Examples
--------
.. plot:: pyplots/xlim.py
:include-source:
"""
self._xlim = (bottom, top)
self._sp.set_xlim(bottom, top)
[docs] def ylim(self, bottom=None, top=None):
"""Set axes y limits.
Parameters
----------
bottom : scalar
Starting value for the y axis.
top : scalar
Ending value for the y axis.
See Also
--------
.xlim : Set x axis limits.
"""
self._ylim = (bottom, top)
self._sp.set_ylim(bottom, top)
[docs] def xscale(self, scale_type, nonposx='mask', basex=10, **kwargs):
"""Set scale for x axis.
Parameters
----------
scale_type : {'linear', 'log', 'symlog', 'logit'}
Scale for x axis. Default 'linear'.
nonposx: [ 'mask' | 'clip' ], default 'mask'
Non-positive values in x can be masked as invalid,
or clipped to a very small positive number.
basex : int
The base of the logarithm, must be higger than 1.
"""
self._sp.set_xscale(scale_type, nonposx=nonposx, basex=basex, **kwargs)
[docs] def yscale(self, scale_type, nonposy='mask', basey=10, **kwargs):
"""Set scale for y axis.
Parameters
----------
scale_type : {'linear', 'log', 'symlog', 'logit'}
Scale for y axis. Default 'linear'.
nonposy: [ 'mask' | 'clip' ], default 'mask'
Non-positive values in y can be masked as invalid,
or clipped to a very small positive number.
basey : int
The base of the logarithm, must be higger than 1.
"""
self._sp.set_yscale(scale_type, nonposy=nonposy, basey=basey, **kwargs)
[docs] def xlabel(self, label, *args, **kwargs):
"""Set a label for the x axis.
Parameters
----------
label : string
Label's text.
*args, **kwargs
Same as :meth:`.text` method.
Examples
--------
.. plot:: pyplots/xlabel.py
:include-source:
"""
if 'fontsize' not in kwargs:
kwargs['fontsize'] = self._params['font.size']
self._xlabel = label
self._sp.set_xlabel(label, *args, **kwargs)
[docs] def ylabel(self, label, *args, **kwargs):
"""Set a label for the y axis
Parameters
----------
label : string
Label's text.
*args, **kwargs
Same as :meth:`.text` method.
See Also
--------
.xlabel : Set a label for the x axis.
"""
if 'fontsize' not in kwargs:
kwargs['fontsize'] = self._params['font.size']
self._ylabel = label
self._sp.set_ylabel(label, *args, **kwargs)
[docs] def xticks(self, location_array, *args, **kwargs):
"""Set the x-tick locations and labels.
Parameters
----------
location_array : CArray or list
Contain ticks location.
*args, **kwargs
Same as :meth:`.text` method.
Examples
--------
.. plot:: pyplots/xticks.py
:include-source:
"""
if isinstance(location_array, CArray):
location_array = location_array.tondarray()
self._xticks = location_array
self._sp.set_xticks(location_array, *args, **kwargs)
[docs] def yticks(self, location_array, *args, **kwargs):
"""Set the y-tick locations and labels.
Parameters
----------
location_array : CArray or list
Contain ticks location.
*args, **kwargs
Same as :meth:`.text` method.
See Also
--------
.xticks : Set the x-tick locations and labels.
"""
if isinstance(location_array, CArray):
location_array = location_array.tondarray()
self._yticks = location_array
self._sp.set_yticks(location_array, *args, **kwargs)
[docs] def xticklabels(self, labels, *args, **kwargs):
"""Set the xtick labels.
Parameters
----------
labels : list or CArray of string
Xtick labels.
*args, **kwargs
Same as :meth:`.text` method.
Examples
--------
.. plot:: pyplots/xticklabels.py
:include-source:
"""
labels = labels.tolist() if isinstance(labels, CArray) else labels
self._xticklabels = labels
self._sp.set_xticklabels(labels, *args, **kwargs)
[docs] def yticklabels(self, labels, *args, **kwargs):
"""Set the ytick labels.
Parameters
----------
labels : list or CArray of string
Xtick labels.
*args, **kwargs
Same as :meth:`.text` method.
See Also
--------
.xticklabels : Set the xtick labels.
"""
labels = labels.tolist() if isinstance(labels, CArray) else labels
self._yticklabels = labels
self._sp.set_yticklabels(labels, *args, **kwargs)
[docs] def tick_params(self, *args, **kwargs):
"""Change the appearance of ticks and tick labels.
Parameters
----------
axis : ['x' | 'y' | 'both']
Axis on which to operate; default is 'both'.
reset : [True | False]
Default False. If True, set all parameters to defaults
before processing other keyword arguments.
which : ['major' | 'minor' | 'both']
Default is 'major'; apply arguments to which ticks.
direction : ['in' | 'out' | 'inout']
Puts ticks inside the axes, outside the axes, or both.
length : int
Tick length in points.
width : int
Tick width in points.
color : str
Tick color; accepts any mpl color spec.
pad : int
Distance in points between tick and label.
labelsize : int, str
Tick label font size in points or as a string (e.g., 'large').
labelcolor : str
Tick label color; mpl color spec.
colors : str
Changes the tick color and the label color to the same
value: mpl color spec.
bottom, top, left, right : bool, optional
Controls whether to draw the respective ticks.
labelbottom, labeltop, labelleft, labelright : bool, optional
Controls whether to draw the respective tick labels.
Examples
--------
.. plot:: pyplots/tick_params.py
:include-source:
"""
self._sp.tick_params(*args, **kwargs)
[docs] def grid(self, grid_on=True, axis='both', **kwargs):
"""Draw grid for current plot.
Parameters
----------
grid_on : boolean, default True
if True show grid, elsewhere hide grid.
axis : string, default 'both'
can be 'both' (default), 'x', or 'y' to
control which set of gridlines are drawn.
kwargs : any
Other keyword arguments for grid.
Examples
--------
.. plot:: pyplots/grid.py
:include-source:
"""
self._sp.grid(grid_on, axis=axis, **kwargs)
[docs] def text(self, *args, **kwargs):
"""Create a Text instance at x, y with string text.
Parameters
----------
Any of the following keyword arguments is supported.
Text properties:
.. list-table::
:header-rows: 1
* - Property
- Description
* - alpha
- float (0.0 transparent through 1.0 opaque)
* - animated
- [True | False]
* - backgroundcolor
- one of possible color
* - bbox
- rectangle prop dict
* - color
- one of possible color
* - family or fontfamily or fontname or name
- [FONTNAME | 'serif' | 'sans-serif' | 'cursive' | 'fantasy' | 'monospace' ]
* - horizontalalignment or ha
- [ 'center' | 'right' | 'left' ]
* - label
- string or anything printable with '%s' conversion.
* - linespacing
- float (multiple of font size)
* - position
- (x,y)
* - rasterized
- [True | False | None]
* - rotation
- [ angle in degrees | 'vertical' | 'horizontal' ]
* - size or fontsize
- [size in points | 'xx-small' | 'x-small' | 'small' | 'medium' |
'large' | 'x-large' | 'xx-large' ]
* - stretch or fontstretch
- [a numeric value in range 0-1000 | 'ultra-condensed' | 'extra-condensed'
| 'condensed' | 'semi-condensed' | 'normal' | 'semi-expanded' | 'expanded'
| 'extra-expanded' | 'ultra-expanded' ]
* - style or fontstyle
- [ 'normal' | 'italic' | 'oblique']
* - text
- string or anything printable with '%s' conversion.
* - verticalalignment or va or ma
- [ 'center' | 'top' | 'bottom' | 'baseline' ]
* - visible
- [True | False]
* - weight or fontweight
- [a numeric value in range 0-1000 | 'ultralight' | 'light' | 'normal'
| 'regular' | 'book' | 'medium' | 'roman' | 'semibold' | 'demibold'
| 'demi' | 'bold' | 'heavy' | 'extra bold' | 'black' ]
* - x
- float, x position of the text.
* - y
- float. y position of the text.
* - zorder
- any number, objects with lower zorder values are drawn first.
Font properties:
.. list-table::
:header-rows: 1
* - Property
- Description
* - family
- (font name or font family) es: 'serif', 'sans-serif', 'cursive',
'fantasy', or 'monospace'
* - style
- either between 'normal', 'italic' or 'oblique'
* - variant
- 'normal' or 'small-caps'
* - stretch
- A numeric value in the range 0-1000 or one of 'ultra-condensed',
'extra-condensed', 'condensed', 'semi-condensed', 'normal', 'semi-expanded',
'expanded', 'extra-expanded' or 'ultra-expanded'
* - weight
- A numeric value in the range 0-1000 or one of 'ultralight', 'light',
'normal', 'regular', 'book', 'medium', 'roman', 'semibold', 'demibold',
'demi', 'bold', 'heavy', 'extra bold', 'black'
* - size
- Either an relative value of 'xx-small', 'x-small', 'small', 'medium',
'large', 'x-large', 'xx-large' or an absolute font size, e.g., 12
"""
if 'fontsize' not in kwargs:
kwargs['fontsize'] = self._params['font.size']
return self._sp.text(*args, **kwargs)
[docs] def legend(self, *args, **kwargs):
"""Create legend for plot.
Parameters
----------
loc: integer or string or pair of floats, default: 0
.. list-table::
:header-rows: 1
* - Integer
- Location
* - 0
- 'best'
* - 1
- 'upper right'
* - 2
- 'upper left'
* - 3
- 'lower left'
* - 4
- 'lower right'
* - 5
- 'right'
* - 6
- 'center left'
* - 7
- 'center right'
* - 8
- 'lower center'
* - 9
- 'upper center'
* - 10
- 'center'
bbox_to_anchor : tuple of floats
Specify any arbitrary location for the legend in bbox_transform
coordinates (default Axes coordinates). For example, to put the
legend's upper right hand corner in the center of the axes the
following keywords can be used: loc='upper right',
bbox_to_anchor=(0.5, 0.5).
ncol : integer
The number of columns that the legend has. Default is 1.
prop : None or dict
The font properties of the legend. If None (default), the current
default parameters will be used.
fontsize : int or float or {'xx-small', 'x-small', 'small', 'medium', 'large', 'x-large', 'xx-large'}
Controls the font size of the legend. If the value is numeric
the size will be the absolute font size in points.
String values are relative to the current default font size.
This argument is only used if prop is not specified.
numpoints : None or int
The number of marker points in the legend when creating a
legend entry for a line. Default is None which will take the
value from the legend.numpoints default parameter.
scatterpoints : None or int
The number of marker points in the legend when creating a
legend entry for a scatter plot. Default is None which will
take the value from the legend.scatterpoints default parameter.
scatteryoffsets : iterable of floats
The vertical offset (relative to the font size) for the markers
created for a scatter plot legend entry. 0.0 is at the base the
legend text, and 1.0 is at the top. To draw all markers at the
same height, set to [0.5]. Default [0.375, 0.5, 0.3125].
markerscale : None or int or float
The relative size of legend markers compared with the originally
drawn ones. Default is None which will take the value from the
legend.markerscale default parameter.
frameon : None or bool
Control whether a frame should be drawn around the legend.
Default is None which will take the value from the legend.frameon
default parameter.
fancybox : None or bool
Control whether round edges should be enabled around the
FancyBboxPatch which makes up the legend's background.
Default is None which will take the value from the
legend.fancybox default parameter.
shadow : None or bool
Control whether to draw a shadow behind the legend.
Default is None which will take the value from the
legend.shadow default parameter.
framealpha : None or float
Control the alpha transparency of the legend's frame.
Default is None which will take the value from the
legend.framealpha default parameter.
mode : either between {"expand", None}
If mode is set to "expand" the legend will be horizontally
expanded to fill the axes area (or bbox_to_anchor if
defines the legend's size).
bbox_transform : None or matplotlib.transforms.Transform
The transform for the bounding box (bbox_to_anchor).
For a value of None (default) the Axes' transAxes transform
will be used.
title : str or None
The legend's title. Default is no title (None).
borderpad : float or None
The fractional whitespace inside the legend border.
Measured in font-size units. Default is None which will take
the value from the legend.borderpad default parameter.
labelspacing : float or None
The vertical space between the legend entries. Measured in
font-size units. Default is None which will take the value
from the legend.labelspacing default parameter.
handlelength : float or None
The length of the legend handles. Measured in
font-size units. Default is None which will take the
value from the legend.handlelength default parameter.
handletextpad : float or None
The pad between the legend handle and text. Measured in
font-size units. Default is None which will take the value
from the legend.handletextpad default parameter.
borderaxespad : float or None
The pad between the axes and legend border. Measured in
font-size units. Default is None which will take the value
from the legend.borderaxespad default parameter.
columnspacing : float or None
The spacing between columns. Measured in font-size units.
Default is None which will take the value from the
legend.columnspacing default parameter.
*args, **kwargs
Same as :meth:`.text`.
Examples
--------
.. plot:: pyplots/legend.py
:include-source:
"""
if 'fontsize' not in kwargs:
kwargs['fontsize'] = self._params['font.size']
self.show_legend = True
return self._sp.legend(*args, **kwargs)
[docs] def get_legend(self):
"""Returns the handler of current subplot legend."""
return self._sp.get_legend()
[docs] def title(self, text, *args, **kwargs):
"""Set a title for subplot."""
if 'fontsize' not in kwargs:
kwargs['fontsize'] = self._params['font.size']
return self._sp.set_title(text, *args, **kwargs)
[docs] def plot_path(self, path, path_style='-', path_width=1.5, path_color='k',
straight=False, start_style='h', start_facecolor='r',
start_edgecolor='k', start_edgewidth=1,
final_style='*', final_facecolor='g',
final_edgecolor='k', final_edgewidth=1):
"""Plot a path traversed by a point.
By default, path is drawn in solid black, start point
is drawn with a red star and the end point is drawn
with a green asterisk.
Parameters
----------
path : CArray
Every row contain one point coordinate.
path_style : str
Style for the path line. Default solid (-).
path_width : int
Width of path line. Default 1.5.
path_color : str
Color for the path line. Default black (k).
straight : bool, default False
If True, path will be plotted straight between start and end point.
start_style : str
Style for the start point. Default an hexagon (h).
start_facecolor : str
Color for the start point. Default red (r).
start_edgecolor : str
Color for the edge of the start point marker. Default black (k).
start_edgewidth : scalar
Width of the edge for the start point. Default 1.
final_style : str
Style for the end point. Default a star (*).
final_facecolor : str
Color for the end point. Default red (g).
final_edgecolor : str
Color for the edge of the final point marker. Default black (k).
final_edgewidth : scalar
Width of the edge for the end point. Default 1.
Examples
--------
.. plot:: pyplots/plot_path.py
:include-source:
"""
path_2d = CArray(path).atleast_2d()
if path_2d.shape[1] != 2:
raise ValueError("cannot plot a {:}-Dimensional path."
"".format(path_2d.shape[1]))
# Plotting full path, then the start and the end points
if straight is False:
self.plot(path_2d[:, 0], path_2d[:, 1],
linestyle=path_style,
color=path_color,
linewidth=path_width)
else:
self.plot(path_2d[[0, -1], 0], path_2d[[0, -1], 1],
linestyle=path_style, color=path_color)
self.plot(path_2d[0, 0], path_2d[0, 1], marker=start_style,
markerfacecolor=start_facecolor,
markeredgecolor=start_edgecolor,
markeredgewidth=start_edgewidth)
self.plot(path_2d[-1, 0], path_2d[-1, 1], marker=final_style,
markerfacecolor=final_facecolor,
markeredgecolor=final_edgecolor,
markeredgewidth=final_edgewidth)
[docs] def imshow(self, img, *args, **kwargs):
"""Plot image.
Parameters
----------
img : CArray or PIL.Image.Image
Image to plot.
"""
if isinstance(img, CArray):
img = img.tondarray()
return self._sp.imshow(img, *args, **kwargs)
[docs] def matshow(self, array, *args, **kwargs):
"""Plot an array as a matrix.
Parameters
----------
array : CArray
Array that we want plot as a matrix.
"""
return self._sp.matshow(array.tondarray(), *args, **kwargs)
[docs] def quiver(self, U, V, X=None, Y=None,
color='k', linestyle='-', linewidth=1.0, alpha=1.0):
"""A quiver plot displays velocity vectors as arrows
with components (u,v) at the points (x,y).
For example, the first vector is defined by components
u(1), v(1) and is displayed at the point x(1), y(1).
quiver(x,y,u,v) plots vectors as arrows at the coordinates
specified in each corresponding pair of elements in x and y.
quiver(u,v) draws vectors specified by u and v at equally
spaced points in the x-y plane.
Parameters
----------
U, V: scalar or CArray
Give the x and y components of the arrow vectors.
X, Y: scalar or CArray, optional
The x and y coordinates of the arrow locations
(default is tail of arrow; see pivot kwarg)
color :
Color of the gradient directions.
linestyle : str
['solid' | 'dashed', 'dashdot', 'dotted' |
(offset, on-off-dash-seq) | '-' | '--' | '-.' | ':' |
'None' | ' ' | '']
linewidth : float
Width of the line.
alpha : float
Transparency factor of the directions.
"""
if X is None:
self._sp.quiver(U.tondarray(), V.tondarray(),
color=color, linestyle=linestyle,
linewidth=linewidth, alpha=alpha)
else:
self._sp.quiver(X.tondarray(), Y.tondarray(),
U.tondarray(), V.tondarray(),
color=color, linestyle=linestyle,
linewidth=linewidth, alpha=alpha)