matplotlib.cbook

A collection of utility functions and classes. Originally, many (but not all) were from the Python Cookbook -- hence the name cbook.

This module is safe to import from anywhere within Matplotlib; it imports Matplotlib only at runtime.

class matplotlib.cbook.CallbackRegistry(exception_handler=<function _exception_printer>, *, signals=None)

Bases: object

Handle registering, processing, blocking, and disconnecting for a set of signals and callbacks:

>>> def oneat(x):
...    print('eat', x)
>>> def ondrink(x):
...    print('drink', x)

>>> from matplotlib.cbook import CallbackRegistry
>>> callbacks = CallbackRegistry()

>>> id_eat = callbacks.connect('eat', oneat)
>>> id_drink = callbacks.connect('drink', ondrink)

>>> callbacks.process('drink', 123)
drink 123
>>> callbacks.process('eat', 456)
eat 456
>>> callbacks.process('be merry', 456)   # nothing will be called

>>> callbacks.disconnect(id_eat)
>>> callbacks.process('eat', 456)        # nothing will be called

>>> with callbacks.blocked(signal='drink'):
...     callbacks.process('drink', 123)  # nothing will be called
>>> callbacks.process('drink', 123)
drink 123

In practice, one should always disconnect all callbacks when they are no longer needed to avoid dangling references (and thus memory leaks). However, real code in Matplotlib rarely does so, and due to its design, it is rather difficult to place this kind of code. To get around this, and prevent this class of memory leaks, we instead store weak references to bound methods only, so when the destination object needs to die, the CallbackRegistry won't keep it alive.

Parameters:

exception_handlercallable, optional

If not None, exception_handler must be a function that takes an Exception as single parameter. It gets called with any Exception raised by the callbacks during CallbackRegistry.process, and may either re-raise the exception or handle it in another manner.

The default handler prints the exception (with traceback.print_exc) if an interactive event loop is running; it re-raises the exception if no interactive event loop is running.

signalslist, optional

If not None, signals is a list of signals that this registry handles: attempting to process or to connect to a signal not in the list throws a ValueError. The default, None, does not restrict the handled signals.

blocked(*, signal=None)

Block callback signals from being processed.

A context manager to temporarily block/disable callback signals from being processed by the registered listeners.

Parameters:

signalstr, optional

The callback signal to block. The default is to block all signals.

connect(signal, func)

Register func to be called when signal signal is generated.

disconnect(cid)

Disconnect the callback registered with callback id cid.

No error is raised if such a callback does not exist.

process(s, *args, **kwargs)

Process signal s.

All of the functions registered to receive callbacks on s will be called with *args and **kwargs.

class matplotlib.cbook.Grouper(init=())

Bases: object

A disjoint-set data structure.

Objects can be joined using join(), tested for connectedness using joined(), and all disjoint sets can be retrieved by using the object as an iterator.

The objects being joined must be hashable and weak-referenceable.

Examples

>>> from matplotlib.cbook import Grouper
>>> class Foo:
...     def __init__(self, s):
...         self.s = s
...     def __repr__(self):
...         return self.s
...
>>> a, b, c, d, e, f = [Foo(x) for x in 'abcdef']
>>> grp = Grouper()
>>> grp.join(a, b)
>>> grp.join(b, c)
>>> grp.join(d, e)
>>> list(grp)
[[a, b, c], [d, e]]
>>> grp.joined(a, b)
True
>>> grp.joined(a, c)
True
>>> grp.joined(a, d)
False

clean()

Clean dead weak references from the dictionary.

get_siblings(a)

Return all of the items joined with a, including itself.

join(a, *args)

Join given arguments into the same set. Accepts one or more arguments.

joined(a, b)

Return whether a and b are members of the same set.

remove(a)

class matplotlib.cbook.GrouperView(grouper)

Bases: object

Immutable view over a Grouper.

clean()

[Deprecated] Clean dead weak references from the dictionary.

Notes

Deprecated since version 3.6.

get_siblings(a)

Return all of the items joined with a, including itself.

join(a, *args)

[Deprecated] Join given arguments into the same set. Accepts one or more arguments.

Notes

Deprecated since version 3.6.

joined(a, b)

Return whether a and b are members of the same set.

remove(a)

[Deprecated]

Notes

Deprecated since version 3.6:

class matplotlib.cbook.Stack(default=None)

Bases: object

Stack of elements with a movable cursor.

Mimics home/back/forward in a web browser.

back()

Move the position back and return the current element.

bubble(o)

Raise all references of o to the top of the stack, and return it.

Raises:

ValueError

If o is not in the stack.

clear()

Empty the stack.

empty()

Return whether the stack is empty.

forward()

Move the position forward and return the current element.

home()

Push the first element onto the top of the stack.

The first element is returned.

push(o)

Push o to the stack at current position. Discard all later elements.

o is returned.

remove(o)

Remove o from the stack.

Raises:

ValueError

If o is not in the stack.

matplotlib.cbook.boxplot_stats(X, whis=1.5, bootstrap=None, labels=None, autorange=False)

Return a list of dictionaries of statistics used to draw a series of box and whisker plots using bxp.

Parameters:

Xarray-like

Data that will be represented in the boxplots. Should have 2 or fewer dimensions.

whisfloat or (float, float), default: 1.5

The position of the whiskers.

If a float, the lower whisker is at the lowest datum above Q1 - whis*(Q3-Q1), and the upper whisker at the highest datum below Q3 + whis*(Q3-Q1), where Q1 and Q3 are the first and third quartiles. The default value of whis = 1.5 corresponds to Tukey's original definition of boxplots.

If a pair of floats, they indicate the percentiles at which to draw the whiskers (e.g., (5, 95)). In particular, setting this to (0, 100) results in whiskers covering the whole range of the data.

In the edge case where Q1 == Q3, whis is automatically set to (0, 100) (cover the whole range of the data) if autorange is True.

Beyond the whiskers, data are considered outliers and are plotted as individual points.

bootstrapint, optional

Number of times the confidence intervals around the median should be bootstrapped (percentile method).

labelsarray-like, optional

Labels for each dataset. Length must be compatible with dimensions of X.

autorangebool, optional (False)

When True and the data are distributed such that the 25th and 75th percentiles are equal, whis is set to (0, 100) such that the whisker ends are at the minimum and maximum of the data.

Returns:

list of dict

A list of dictionaries containing the results for each column of data. Keys of each dictionary are the following:

Key	Value Description
label	tick label for the boxplot
mean	arithmetic mean value
med	50th percentile
q1	first quartile (25th percentile)
q3	third quartile (75th percentile)
iqr	interquartile range
cilo	lower notch around the median
cihi	upper notch around the median
whislo	end of the lower whisker
whishi	end of the upper whisker
fliers	outliers

Notes

Non-bootstrapping approach to confidence interval uses Gaussian-based asymptotic approximation:

\[\mathrm{med} \pm 1.57 \times \frac{\mathrm{iqr}}{\sqrt{N}}\]

General approach from: McGill, R., Tukey, J.W., and Larsen, W.A. (1978) "Variations of Boxplots", The American Statistician, 32:12-16.

matplotlib.cbook.contiguous_regions(mask)

Return a list of (ind0, ind1) such that mask[ind0:ind1].all() is True and we cover all such regions.

matplotlib.cbook.delete_masked_points(*args)

Find all masked and/or non-finite points in a set of arguments, and return the arguments with only the unmasked points remaining.

Arguments can be in any of 5 categories:

1. 1-D masked arrays

2. 1-D ndarrays

3. ndarrays with more than one dimension

4. other non-string iterables

5. anything else

The first argument must be in one of the first four categories; any argument with a length differing from that of the first argument (and hence anything in category 5) then will be passed through unchanged.

Masks are obtained from all arguments of the correct length in categories 1, 2, and 4; a point is bad if masked in a masked array or if it is a nan or inf. No attempt is made to extract a mask from categories 2, 3, and 4 if numpy.isfinite does not yield a Boolean array.

All input arguments that are not passed unchanged are returned as ndarrays after removing the points or rows corresponding to masks in any of the arguments.

A vastly simpler version of this function was originally written as a helper for Axes.scatter().

matplotlib.cbook.file_requires_unicode(x)

Return whether the given writable file-like object requires Unicode to be written to it.

matplotlib.cbook.flatten(seq, scalarp=<function is_scalar_or_string>)

Return a generator of flattened nested containers.

For example:

>>> from matplotlib.cbook import flatten
>>> l = (('John', ['Hunter']), (1, 23), [[([42, (5, 23)], )]])
>>> print(list(flatten(l)))
['John', 'Hunter', 1, 23, 42, 5, 23]

By: Composite of Holger Krekel and Luther Blissett From: https://code.activestate.com/recipes/121294/ and Recipe 1.12 in cookbook

matplotlib.cbook.get_sample_data(fname, asfileobj=True, *, np_load=False)

Return a sample data file. fname is a path relative to the mpl-data/sample_data directory. If asfileobj is True return a file object, otherwise just a file path.

Sample data files are stored in the 'mpl-data/sample_data' directory within the Matplotlib package.

If the filename ends in .gz, the file is implicitly ungzipped. If the filename ends with .npy or .npz, asfileobj is True, and np_load is True, the file is loaded with numpy.load. np_load currently defaults to False but will default to True in a future release.

matplotlib.cbook.index_of(y)

A helper function to create reasonable x values for the given y.

This is used for plotting (x, y) if x values are not explicitly given.

First try y.index (assuming y is a pandas.Series), if that fails, use range(len(y)).

This will be extended in the future to deal with more types of labeled data.

Parameters:

yfloat or array-like

Returns:

x, yndarray

The x and y values to plot.

matplotlib.cbook.is_math_text(s)

Return whether the string s contains math expressions.

This is done by checking whether s contains an even number of non-escaped dollar signs.

matplotlib.cbook.is_scalar_or_string(val)

Return whether the given object is a scalar or string like.

matplotlib.cbook.is_writable_file_like(obj)

Return whether obj looks like a file object with a write method.

matplotlib.cbook.ls_mapper = {'-': 'solid', '--': 'dashed', '-.': 'dashdot', ':': 'dotted'}

Maps short codes for line style to their full name used by backends.

matplotlib.cbook.ls_mapper_r = {'dashdot': '-.', 'dashed': '--', 'dotted': ':', 'solid': '-'}

Maps full names for line styles used by backends to their short codes.

class matplotlib.cbook.maxdict(maxsize)

Bases: dict

[Deprecated] A dictionary with a maximum size.

Notes

This doesn't override all the relevant methods to constrain the size, just __setitem__, so use with caution.

Deprecated since version 3.6: Use functools.lru_cache instead.

matplotlib.cbook.normalize_kwargs(kw, alias_mapping=None)

Helper function to normalize kwarg inputs.

Parameters:

kwdict or None

A dict of keyword arguments. None is explicitly supported and treated as an empty dict, to support functions with an optional parameter of the form props=None.

alias_mappingdict or Artist subclass or Artist instance, optional

A mapping between a canonical name to a list of aliases, in order of precedence from lowest to highest.

If the canonical value is not in the list it is assumed to have the highest priority.

If an Artist subclass or instance is passed, use its properties alias mapping.

Raises:

TypeError

To match what Python raises if invalid arguments/keyword arguments are passed to a callable.

matplotlib.cbook.open_file_cm(path_or_file, mode='r', encoding=None)

Pass through file objects and context-manage path-likes.

matplotlib.cbook.print_cycles(objects, outstream=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>, show_progress=False)

Print loops of cyclic references in the given objects.

It is often useful to pass in gc.garbage to find the cycles that are preventing some objects from being garbage collected.

Parameters:

objects

A list of objects to find cycles in.

outstream

The stream for output.

show_progressbool

If True, print the number of objects reached as they are found.

matplotlib.cbook.pts_to_midstep(x, *args)

Convert continuous line to mid-steps.

Given a set of N points convert to 2N points which when connected linearly give a step function which changes values at the middle of the intervals.

Parameters:

xarray

The x location of the steps. May be empty.

y1, ..., yparray

y arrays to be turned into steps; all must be the same length as x.

Returns:

array

The x and y values converted to steps in the same order as the input; can be unpacked as x_out, y1_out, ..., yp_out. If the input is length N, each of these arrays will be length 2N.

Examples

>>> x_s, y1_s, y2_s = pts_to_midstep(x, y1, y2)

matplotlib.cbook.pts_to_poststep(x, *args)

Convert continuous line to post-steps.

Given a set of N points convert to 2N + 1 points, which when connected linearly give a step function which changes values at the end of the intervals.

Parameters:

xarray

The x location of the steps. May be empty.

y1, ..., yparray

y arrays to be turned into steps; all must be the same length as x.

Returns:

array

The x and y values converted to steps in the same order as the input; can be unpacked as x_out, y1_out, ..., yp_out. If the input is length N, each of these arrays will be length 2N + 1. For N=0, the length will be 0.

Examples

>>> x_s, y1_s, y2_s = pts_to_poststep(x, y1, y2)

matplotlib.cbook.pts_to_prestep(x, *args)

Convert continuous line to pre-steps.

Given a set of N points, convert to 2N - 1 points, which when connected linearly give a step function which changes values at the beginning of the intervals.

Parameters:

xarray

The x location of the steps. May be empty.

y1, ..., yparray

y arrays to be turned into steps; all must be the same length as x.

Returns:

array

The x and y values converted to steps in the same order as the input; can be unpacked as x_out, y1_out, ..., yp_out. If the input is length N, each of these arrays will be length 2N + 1. For N=0, the length will be 0.

Examples

>>> x_s, y1_s, y2_s = pts_to_prestep(x, y1, y2)

matplotlib.cbook.report_memory(i=0)

[Deprecated] Return the memory consumed by the process.

Notes

Deprecated since version 3.5: Use psutil.virtual_memory instead.

matplotlib.cbook.safe_first_element(obj)

Return the first element in obj.

This is an type-independent way of obtaining the first element, supporting both index access and the iterator protocol.

matplotlib.cbook.safe_masked_invalid(x, copy=False)

matplotlib.cbook.sanitize_sequence(data)

Convert dictview objects to list. Other inputs are returned unchanged.

class matplotlib.cbook.silent_list(type, seq=None)

Bases: list

A list with a short repr().

This is meant to be used for a homogeneous list of artists, so that they don't cause long, meaningless output.

Instead of

[<matplotlib.lines.Line2D object at 0x7f5749fed3c8>,
 <matplotlib.lines.Line2D object at 0x7f5749fed4e0>,
 <matplotlib.lines.Line2D object at 0x7f5758016550>]

one will get

<a list of 3 Line2D objects>

If self.type is None, the type name is obtained from the first item in the list (if any).

matplotlib.cbook.simple_linear_interpolation(a, steps)

Resample an array with steps - 1 points between original point pairs.

Along each column of a, (steps - 1) points are introduced between each original values; the values are linearly interpolated.

Parameters:

aarray, shape (n, ...)

stepsint

Returns:

array

shape ((n - 1) * steps + 1, ...)

matplotlib.cbook.strip_math(s)

Remove latex formatting from mathtext.

Only handles fully math and fully non-math strings.

matplotlib.cbook.to_filehandle(fname, flag='r', return_opened=False, encoding=None)

Convert a path to an open file handle or pass-through a file-like object.

Consider using open_file_cm instead, as it allows one to properly close newly created file objects more easily.

Parameters:

fnamestr or path-like or file-like

If str or os.PathLike, the file is opened using the flags specified by flag and encoding. If a file-like object, it is passed through.

flagstr, default: 'r'

Passed as the mode argument to open when fname is str or os.PathLike; ignored if fname is file-like.

return_openedbool, default: False

If True, return both the file object and a boolean indicating whether this was a new file (that the caller needs to close). If False, return only the new file.

encodingstr or None, default: None

Passed as the mode argument to open when fname is str or os.PathLike; ignored if fname is file-like.

Returns:

fhfile-like

openedbool

opened is only returned if return_opened is True.

matplotlib.cbook.violin_stats(X, method, points=100, quantiles=None)

Return a list of dictionaries of data which can be used to draw a series of violin plots.

See the Returns section below to view the required keys of the dictionary.

Users can skip this function and pass a user-defined set of dictionaries with the same keys to violinplot instead of using Matplotlib to do the calculations. See the Returns section below for the keys that must be present in the dictionaries.

Parameters:

Xarray-like

Sample data that will be used to produce the gaussian kernel density estimates. Must have 2 or fewer dimensions.

methodcallable

The method used to calculate the kernel density estimate for each column of data. When called via method(v, coords), it should return a vector of the values of the KDE evaluated at the values specified in coords.

pointsint, default: 100

Defines the number of points to evaluate each of the gaussian kernel density estimates at.

quantilesarray-like, default: None

Defines (if not None) a list of floats in interval [0, 1] for each column of data, which represents the quantiles that will be rendered for that column of data. Must have 2 or fewer dimensions. 1D array will be treated as a singleton list containing them.

Returns:

list of dict

A list of dictionaries containing the results for each column of data. The dictionaries contain at least the following:

• coords: A list of scalars containing the coordinates this particular kernel density estimate was evaluated at.

• vals: A list of scalars containing the values of the kernel density estimate at each of the coordinates given in coords.

• mean: The mean value for this column of data.

• median: The median value for this column of data.

• min: The minimum value for this column of data.

• max: The maximum value for this column of data.

• quantiles: The quantile values for this column of data.