cbook
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.Bunch(**kwds)
-
Bases:
object
Often we want to just collect a bunch of stuff together, naming each item of the bunch; a dictionary?s OK for that, but a small do- nothing class is even handier, and prettier to use. Whenever you want to group a few variables:
>>> point = Bunch(datum=2, squared=4, coord=12) >>> point.datum By: Alex Martelli From: http://aspn.activestate.com/ASPN/Cookbook/Python/Recipe/52308
-
class matplotlib.cbook.CallbackRegistry
-
Bases:
object
Handle registering 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
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. The Python stdlib weakref module can not create weak references to bound methods directly, so we need to create a proxy object to handle weak references to bound methods (or regular free functions). This technique was shared by Peter Parente on his ?Mindtrove? blog.
-
connect(s, func)
-
register func to be called when a signal s is generated func will be called
-
disconnect(cid)
-
disconnect the callback registered with callback id cid
-
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.GetRealpathAndStat
-
Bases:
object
-
class matplotlib.cbook.Grouper(init=())
-
Bases:
object
This class provides a lightweight way to group arbitrary objects together into disjoint sets when a full-blown graph data structure would be overkill.
Objects can be joined using
join()
, tested for connectedness usingjoined()
, and all disjoint sets can be retreived by using the object as an iterator.The objects being joined must be hashable and weak-referenceable.
For example:
>>> from matplotlib.cbook import Grouper >>> class Foo(object): ... 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) >>> sorted(map(tuple, 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)
-
Returns 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)
-
Returns True if a and b are members of the same set.
-
remove(a)
-
-
exception matplotlib.cbook.IgnoredKeywordWarning
-
Bases:
UserWarning
A class for issuing warnings about keyword arguments that will be ignored by matplotlib
-
exception matplotlib.cbook.MatplotlibDeprecationWarning
-
Bases:
UserWarning
A class for issuing deprecation warnings for Matplotlib users.
In light of the fact that Python builtin DeprecationWarnings are ignored by default as of Python 2.7 (see link below), this class was put in to allow for the signaling of deprecation, but via UserWarnings which are not ignored by default.
http://docs.python.org/dev/whatsnew/2.7.html#the-future-for-python-2-x
-
class matplotlib.cbook.MemoryMonitor(nmax=20000)
-
Bases:
object
-
clear()
-
plot(i0=0, isub=1, fig=None)
-
report(segments=4)
-
xy(i0=0, isub=1)
-
-
class matplotlib.cbook.Null(*args, **kwargs)
-
Bases:
object
Null objects always and reliably ?do nothing.?
-
class matplotlib.cbook.RingBuffer(size_max)
-
Bases:
object
class that implements a not-yet-full buffer
-
append(x)
-
append an element at the end of the buffer
-
get()
-
Return a list of elements from the oldest to the newest.
-
-
class matplotlib.cbook.Sorter
-
Bases:
object
Sort by attribute or item
Example usage:
sort = Sorter() list = [(1, 2), (4, 8), (0, 3)] dict = [{'a': 3, 'b': 4}, {'a': 5, 'b': 2}, {'a': 0, 'b': 0}, {'a': 9, 'b': 9}] sort(list) # default sort sort(list, 1) # sort by index 1 sort(dict, 'a') # sort a list of dicts by key 'a'
-
byAttribute(data, attributename, inplace=1)
-
byItem(data, itemindex=None, inplace=1)
-
sort(data, itemindex=None, inplace=1)
-
-
class matplotlib.cbook.Stack(default=None)
-
Bases:
object
Implement a stack where elements can be pushed on and you can move back and forth. But no pop. Should mimic home / back / forward in a browser
-
back()
-
move the position back and return the current element
-
bubble(o)
-
raise o to the top of the stack and return o. o must be in the stack
-
clear()
-
empty the stack
-
empty()
-
forward()
-
move the position forward and return the current element
-
home()
-
push the first element onto the top of the stack
-
push(o)
-
push object onto stack at current position - all elements occurring later than the current position are discarded
-
remove(o)
-
remove element o from the stack
-
-
class matplotlib.cbook.Xlator
-
Bases:
dict
All-in-one multiple-string-substitution class
Example usage:
text = "Larry Wall is the creator of Perl" adict = { "Larry Wall" : "Guido van Rossum", "creator" : "Benevolent Dictator for Life", "Perl" : "Python", } print(multiple_replace(adict, text)) xlat = Xlator(adict) print(xlat.xlat(text))
-
xlat(text)
-
Translate text, returns the modified text.
-
-
matplotlib.cbook.align_iterators(func, *iterables)
-
This generator takes a bunch of iterables that are ordered by func It sends out ordered tuples:
(func(row), [rows from all iterators matching func(row)])
It is used by
matplotlib.mlab.recs_join()
to join record arrays
-
matplotlib.cbook.allequal(seq)
-
Return True if all elements of seq compare equal. If seq is 0 or 1 length, return True
-
matplotlib.cbook.allpairs(x)
-
return all possible pairs in sequence x
Condensed by Alex Martelli from this thread on c.l.python
-
matplotlib.cbook.alltrue(seq)
-
Return True if all elements of seq evaluate to True. If seq is empty, return False.
-
matplotlib.cbook.boxplot_stats(X, whis=1.5, bootstrap=None, labels=None, autorange=False)
-
Returns list of dictionaries of statistics used to draw a series of box and whisker plots. The
Returns
section enumerates the required keys of the dictionary. Users can skip this function and pass a user-defined set of dictionaries to the newaxes.bxp
method instead of relying on MPL to do the calculations.Parameters: X : array-like
Data that will be represented in the boxplots. Should have 2 or fewer dimensions.
whis : float, string, or sequence (default = 1.5)
As a float, determines the reach of the whiskers past the first and third quartiles (e.g., Q3 + whis*IQR, QR = interquartile range, Q3-Q1). Beyond the whiskers, data are considered outliers and are plotted as individual points. This can be 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 minimum and maximum of the data. In the edge case that the 25th and 75th percentiles are equivalent,whis
can be automatically set to'range'
via theautorange
option.bootstrap : int, optional
Number of times the confidence intervals around the median should be bootstrapped (percentile method).
labels : array-like, optional
Labels for each dataset. Length must be compatible with dimensions of
X
.autorange : bool, optional (False)
When
True
and the data are distributed such that the 25th and 75th percentiles are equal,whis
is set to'range'
such that the whisker ends are at the minimum and maximum of the data.Returns: bxpstats : 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 arithemetic mean value med 50th percentile q1 first quartile (25th percentile) q3 third quartile (75th percentile) 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:
General approach from: McGill, R., Tukey, J.W., and Larsen, W.A. (1978) ?Variations of Boxplots?, The American Statistician, 32:12-16.
-
class matplotlib.cbook.converter(missing='Null', missingval=None)
-
Bases:
object
Base class for handling string -> python type with support for missing values
-
is_missing(s)
-
-
matplotlib.cbook.dedent(s)
-
Remove excess indentation from docstring s.
Discards any leading blank lines, then removes up to n whitespace characters from each line, where n is the number of leading whitespace characters in the first line. It differs from textwrap.dedent in its deletion of leading blank lines and its use of the first non-blank line to determine the indentation.
It is also faster in most cases.
-
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-D masked arrays
- 1-D ndarrays
- ndarrays with more than one dimension
- other non-string iterables
- 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
np.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.deprecated(since, message='', name='', alternative='', pending=False, obj_type='function')
-
Decorator to mark a function as deprecated.
Parameters: since : str
The release at which this API became deprecated. This is required.
message : str, optional
Override the default deprecation message. The format specifier
%(func)s
may be used for the name of the function, and%(alternative)s
may be used in the deprecation message to insert the name of an alternative to the deprecated function.%(obj_type)
may be used to insert a friendly name for the type of object being deprecated.name : str, optional
The name of the deprecated function; if not provided the name is automatically determined from the passed in function, though this is useful in the case of renamed functions, where the new function is just assigned to the name of the deprecated function. For example:
def new_function(): ... oldFunction = new_function
alternative : str, optional
An alternative function that the user may use in place of the deprecated function. The deprecation warning will tell the user about this alternative if provided.
pending : bool, optional
If True, uses a PendingDeprecationWarning instead of a DeprecationWarning.
Examples
Basic example:
@deprecated('1.4.0') def the_function_to_deprecate(): pass
-
matplotlib.cbook.dict_delall(d, keys)
-
delete all of the keys from the
dict
d
-
matplotlib.cbook.exception_to_str(s=None)
-
matplotlib.cbook.file_requires_unicode(x)
-
Returns
True
if the given writable file-like object requires Unicode to be written to it.
-
matplotlib.cbook.finddir(o, match, case=False)
-
return all attributes of o which match string in match. if case is True require an exact case match.
-
matplotlib.cbook.flatten(seq, scalarp=)
-
Returns 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: http://aspn.activestate.com/ASPN/Cookbook/Python/Recipe/121294 and Recipe 1.12 in cookbook
-
matplotlib.cbook.get_label(y, default_name)
-
matplotlib.cbook.get_recursive_filelist(args)
-
Recurse all the files and dirs in args ignoring symbolic links and return the files as a list of strings
-
matplotlib.cbook.get_sample_data(fname, asfileobj=True)
-
Return a sample data file. fname is a path relative to the
mpl-data/sample_data
directory. If asfileobj isTrue
return a file object, otherwise just a file path.Set the rc parameter examples.directory to the directory where we should look, if sample_data files are stored in a location different than default (which is ?mpl-data/sample_data` at the same level of ?matplotlib` Python module files).
If the filename ends in .gz, the file is implicitly ungzipped.
-
matplotlib.cbook.get_split_ind(seq, N)
-
seq is a list of words. Return the index into seq such that:
len(' '.join(seq[:ind])<=N
.
-
matplotlib.cbook.index_of(y)
-
A helper function to get the index of an input to plot against if x values are not explicitly given.
Tries to get
y.index
(works if this is a pd.Series), if that fails, return np.arange(y.shape[0]).This will be extended in the future to deal with more types of labeled data.
Parameters: y : scalar or array-like
The proposed y-value
Returns: x, y : ndarray
The x and y values to plot.
-
matplotlib.cbook.is_hashable(obj)
-
Returns true if obj can be hashed
-
matplotlib.cbook.is_math_text(s)
-
matplotlib.cbook.is_numlike(obj)
-
return true if obj looks like a number
-
matplotlib.cbook.is_scalar(obj)
-
return true if obj is not string like and is not iterable
-
matplotlib.cbook.is_scalar_or_string(val)
-
Return whether the given object is a scalar or string like.
-
matplotlib.cbook.is_sequence_of_strings(obj)
-
Returns true if obj is iterable and contains strings
-
matplotlib.cbook.is_string_like(obj)
-
Return True if obj looks like a string
-
matplotlib.cbook.is_writable_file_like(obj)
-
return true if obj looks like a file object with a write method
-
matplotlib.cbook.issubclass_safe(x, klass)
-
return issubclass(x, klass) and return False on a TypeError
-
matplotlib.cbook.iterable(obj)
-
return true if obj is iterable
-
matplotlib.cbook.listFiles(root, patterns='*', recurse=1, return_folders=0)
-
Recursively list files
from Parmar and Martelli in the Python Cookbook
-
matplotlib.cbook.local_over_kwdict(local_var, kwargs, *keys)
-
Enforces the priority of a local variable over potentially conflicting argument(s) from a kwargs dict. The following possible output values are considered in order of priority:
local_var > kwargs[keys[0]] > ... > kwargs[keys[-1]]The first of these whose value is not None will be returned. If all are None then None will be returned. Each key in keys will be removed from the kwargs dict in place.
Parameters: local_var: any object
The local variable (highest priority)
- kwargs: dict
-
Dictionary of keyword arguments; modified in place
- keys: str(s)
-
Name(s) of keyword arguments to process, in descending order of priority
Returns: out: any object
Either local_var or one of kwargs[key] for key in keys
Raises: IgnoredKeywordWarning
For each key in keys that is removed from kwargs but not used as the output value
-
class matplotlib.cbook.maxdict(maxsize)
-
Bases:
dict
A dictionary with a maximum size; this doesn?t override all the relevant methods to contrain size, just setitem, so use with caution
-
matplotlib.cbook.mkdirs(newdir, mode=511)
-
make directory newdir recursively, and set mode. Equivalent to
> mkdir -p NEWDIR > chmod MODE NEWDIR
-
matplotlib.cbook.mplDeprecation
-
alias of
MatplotlibDeprecationWarning
-
matplotlib.cbook.normalize_kwargs(kw, alias_mapping=None, required=(), forbidden=(), allowed=None)
-
Helper function to normalize kwarg inputs
The order they are resolved are:
- aliasing
- required
- forbidden
- allowed
This order means that only the canonical names need appear in
allowed
,forbidden
,required
Parameters: alias_mapping, dict, 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.
required : iterable, optional
A tuple of fields that must be in kwargs.
forbidden : iterable, optional
A list of keys which may not be in kwargs
allowed : tuple, optional
A tuple of allowed fields. If this not None, then raise if
kw
contains any keys not in the union ofrequired
andallowed
. To allow only the required fields pass in()
forallowed
Raises: TypeError
To match what python raises if invalid args/kwargs are passed to a callable.
-
matplotlib.cbook.onetrue(seq)
-
Return True if one element of seq is True. It seq is empty, return False.
-
matplotlib.cbook.pieces(seq, num=2)
-
Break up the seq into num tuples
-
matplotlib.cbook.popall(seq)
-
empty a list
-
matplotlib.cbook.print_cycles(objects, outstream=<_io.textiowrapper name="<stdout>" mode="w" encoding="UTF-8">, show_progress=False)
-
- objects
- A list of objects to find cycles in. It is often useful to pass in gc.garbage to find the cycles that are preventing some objects from being garbage collected.
- outstream
- The stream for output.
- show_progress
- If True, print the number of objects reached as they are found.
-
matplotlib.cbook.pts_to_midstep(x, *args)
-
Covert continuous line to pre-steps
Given a set of N points convert to 2 N -1 points which when connected linearly give a step function which changes values at the begining the intervals.
Parameters: x : array
The x location of the steps
y1, y2, ... : array
Any number of y arrays to be turned into steps. All must be the same length as
x
Returns: x, y1, y2, .. : array
The x and y values converted to steps in the same order as the input. If the input is length
N
, each of these arrays will be length2N + 1
Examples
>> x_s, y1_s, y2_s = pts_to_prestep(x, y1, y2)
-
matplotlib.cbook.pts_to_poststep(x, *args)
-
Covert continuous line to pre-steps
Given a set of N points convert to 2 N -1 points which when connected linearly give a step function which changes values at the begining the intervals.
Parameters: x : array
The x location of the steps
y1, y2, ... : array
Any number of y arrays to be turned into steps. All must be the same length as
x
Returns: x, y1, y2, .. : array
The x and y values converted to steps in the same order as the input. If the input is length
N
, each of these arrays will be length2N + 1
Examples
>> x_s, y1_s, y2_s = pts_to_prestep(x, y1, y2)
-
matplotlib.cbook.pts_to_prestep(x, *args)
-
Covert continuous line to pre-steps
Given a set of N points convert to 2 N -1 points which when connected linearly give a step function which changes values at the begining the intervals.
Parameters: x : array
The x location of the steps
y1, y2, ... : array
Any number of y arrays to be turned into steps. All must be the same length as
x
Returns: x, y1, y2, .. : array
The x and y values converted to steps in the same order as the input. If the input is length
N
, each of these arrays will be length2N + 1
Examples
>> x_s, y1_s, y2_s = pts_to_prestep(x, y1, y2)
-
matplotlib.cbook.recursive_remove(path)
-
matplotlib.cbook.report_memory(i=0)
-
return the memory consumed by process
-
matplotlib.cbook.restrict_dict(d, keys)
-
Return a dictionary that contains those keys that appear in both d and keys, with values from d.
-
matplotlib.cbook.reverse_dict(d)
-
reverse the dictionary ? may lose data if values are not unique!
-
matplotlib.cbook.safe_first_element(obj)
-
matplotlib.cbook.safe_masked_invalid(x, copy=False)
-
matplotlib.cbook.safezip(*args)
-
make sure args are equal len before zipping
-
class matplotlib.cbook.silent_list(type, seq=None)
-
Bases:
list
override repr when returning a list of matplotlib artists to prevent long, meaningless output. This is meant to be used for a homogeneous list of a given type
-
matplotlib.cbook.simple_linear_interpolation(a, steps)
-
matplotlib.cbook.soundex(name, len=4)
-
soundex module conforming to Odell-Russell algorithm
-
matplotlib.cbook.strip_math(s)
-
remove latex formatting from mathtext
-
matplotlib.cbook.to_filehandle(fname, flag='rU', return_opened=False)
-
fname can be a filename or a file handle. Support for gzipped files is automatic, if the filename ends in .gz. flag is a read/write flag for
file()
-
class matplotlib.cbook.todate(fmt='%Y-%m-%d', missing='Null', missingval=None)
-
Bases:
matplotlib.cbook.converter
convert to a date or None
use a
time.strptime()
format string for conversion
-
class matplotlib.cbook.todatetime(fmt='%Y-%m-%d', missing='Null', missingval=None)
-
Bases:
matplotlib.cbook.converter
convert to a datetime or None
use a
time.strptime()
format string for conversion
-
class matplotlib.cbook.tofloat(missing='Null', missingval=None)
-
Bases:
matplotlib.cbook.converter
convert to a float or None
-
class matplotlib.cbook.toint(missing='Null', missingval=None)
-
Bases:
matplotlib.cbook.converter
convert to an int or None
-
class matplotlib.cbook.tostr(missing='Null', missingval='')
-
Bases:
matplotlib.cbook.converter
convert to string or None
-
matplotlib.cbook.unicode_safe(s)
-
matplotlib.cbook.unique(x)
-
Return a list of unique elements of x
-
matplotlib.cbook.unmasked_index_ranges(mask, compressed=True)
-
Find index ranges where mask is False.
mask will be flattened if it is not already 1-D.
Returns Nx2
numpy.ndarray
with each row the start and stop indices for slices of the compressednumpy.ndarray
corresponding to each of N uninterrupted runs of unmasked values. If optional argument compressed is False, it returns the start and stop indices into the originalnumpy.ndarray
, not the compressednumpy.ndarray
. Returns None if there are no unmasked values.Example:
y = ma.array(np.arange(5), mask = [0,0,1,0,0]) ii = unmasked_index_ranges(ma.getmaskarray(y)) # returns array [[0,2,] [2,4,]] y.compressed()[ii[1,0]:ii[1,1]] # returns array [3,4,] ii = unmasked_index_ranges(ma.getmaskarray(y), compressed=False) # returns array [[0, 2], [3, 5]] y.filled()[ii[1,0]:ii[1,1]] # returns array [3,4,]
Prior to the transforms refactoring, this was used to support masked arrays in Line2D.
-
matplotlib.cbook.violin_stats(X, method, points=100)
-
Returns 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 to theaxes.vplot
method instead of using MPL to do the calculations.Parameters: X : array-like
Sample data that will be used to produce the gaussian kernel density estimates. Must have 2 or fewer dimensions.
method : callable
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.points : scalar, default = 100
Defines the number of points to evaluate each of the gaussian kernel density estimates at.
Returns: 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.
-
matplotlib.cbook.warn_deprecated(since, message='', name='', alternative='', pending=False, obj_type='attribute')
-
Used to display deprecation warning in a standard way.
Parameters: since : str
The release at which this API became deprecated.
message : str, optional
Override the default deprecation message. The format specifier
%(func)s
may be used for the name of the function, and%(alternative)s
may be used in the deprecation message to insert the name of an alternative to the deprecated function.%(obj_type)
may be used to insert a friendly name for the type of object being deprecated.name : str, optional
The name of the deprecated function; if not provided the name is automatically determined from the passed in function, though this is useful in the case of renamed functions, where the new function is just assigned to the name of the deprecated function. For example:
def new_function(): ... oldFunction = new_function
alternative : str, optional
An alternative function that the user may use in place of the deprecated function. The deprecation warning will tell the user about this alternative if provided.
pending : bool, optional
If True, uses a PendingDeprecationWarning instead of a DeprecationWarning.
obj_type : str, optional
The object type being deprecated.
Examples
Basic example:
# To warn of the deprecation of "matplotlib.name_of_module" warn_deprecated('1.4.0', name='matplotlib.name_of_module', obj_type='module')
-
matplotlib.cbook.wrap(prefix, text, cols)
-
wrap text with prefix at length cols
Please login to continue.