Scales define the distribution of data values on an axis, e.g. a log scaling. They are defined as subclasses of ScaleBase.
See also axes.Axes.set_xscale and the scales examples in the documentation.
See Custom scale for a full example of defining a custom scale.
Matplotlib also supports non-separable transformations that operate on both Axis at the same time. They are known as projections, and defined in matplotlib.projections.
Bases: matplotlib.scale.ScaleBase
Provide an arbitrary scale with user-supplied function for the axis.
The axis for the scale.
two-tuple of the forward and inverse functions for the scale. The forward function must be monotonic.
Both functions must have the signature:
Return the FuncTransform associated with this scale.
Set the locators and formatters of axis to instances suitable for this scale.
Bases: matplotlib.scale.LogScale
Provide an arbitrary scale with user-supplied function for the axis and then put on a logarithmic axes.
The axis for the scale.
two-tuple of the forward and inverse functions for the scale. The forward function must be monotonic.
Both functions must have the signature:
Logarithmic base of the scale.
Return the Transform associated with this scale.
Bases: matplotlib.transforms.Transform
A simple transform that takes and arbitrary function for the forward and inverse transform.
The forward function for the transform. This function must have an inverse and, for best behavior, be monotonic. It must have the signature:
The inverse of the forward function. Signature as forward.
True if this transform has a corresponding inverse transform.
The number of input dimensions of this transform. Must be overridden (with integers) in the subclass.
Return the corresponding inverse transformation.
It holds x == self.inverted().transform(self.transform(x)).
The return value of this method should be treated as temporary. An update to self does not cause a corresponding update to its inverted copy.
True if this transform is separable in the x- and y- dimensions.
The number of output dimensions of this transform. Must be overridden (with integers) in the subclass.
Apply only the non-affine part of this transformation.
transform(values) is always equivalent to transform_affine(transform_non_affine(values)).
In non-affine transformations, this is generally equivalent to transform(values). In affine transformations, this is always a no-op.
The input values as NumPy array of length input_dims or shape (N x input_dims).
The output values as NumPy array of length input_dims or shape (N x output_dims), depending on the input.
Bases: matplotlib.transforms.Transform
A string representing the "name" of the transform. The name carries no significance other than to improve the readability of str(transform) when DEBUG=True.
True if this transform has a corresponding inverse transform.
The number of input dimensions of this transform. Must be overridden (with integers) in the subclass.
Return the corresponding inverse transformation.
It holds x == self.inverted().transform(self.transform(x)).
The return value of this method should be treated as temporary. An update to self does not cause a corresponding update to its inverted copy.
True if this transform is separable in the x- and y- dimensions.
The number of output dimensions of this transform. Must be overridden (with integers) in the subclass.
Apply only the non-affine part of this transformation.
transform(values) is always equivalent to transform_affine(transform_non_affine(values)).
In non-affine transformations, this is generally equivalent to transform(values). In affine transformations, this is always a no-op.
The input values as NumPy array of length input_dims or shape (N x input_dims).
The output values as NumPy array of length input_dims or shape (N x output_dims), depending on the input.
Bases: matplotlib.transforms.Transform
A string representing the "name" of the transform. The name carries no significance other than to improve the readability of str(transform) when DEBUG=True.
True if this transform has a corresponding inverse transform.
The number of input dimensions of this transform. Must be overridden (with integers) in the subclass.
Return the corresponding inverse transformation.
It holds x == self.inverted().transform(self.transform(x)).
The return value of this method should be treated as temporary. An update to self does not cause a corresponding update to its inverted copy.
True if this transform is separable in the x- and y- dimensions.
The number of output dimensions of this transform. Must be overridden (with integers) in the subclass.
Apply only the non-affine part of this transformation.
transform(values) is always equivalent to transform_affine(transform_non_affine(values)).
In non-affine transformations, this is generally equivalent to transform(values). In affine transformations, this is always a no-op.
The input values as NumPy array of length input_dims or shape (N x input_dims).
The output values as NumPy array of length input_dims or shape (N x output_dims), depending on the input.
Bases: matplotlib.scale.ScaleBase
The default linear scale.
Return the transform for linear scaling, which is just the IdentityTransform.
Set the locators and formatters of axis to instances suitable for this scale.
Bases: matplotlib.scale.ScaleBase
A standard logarithmic scale. Care is taken to only plot positive values.
The axis for the scale.
The base of the logarithm.
Determines the behavior for non-positive values. They can either be masked as invalid, or clipped to a very small positive number.
Where to place the subticks between each major tick. 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.
Return the LogTransform associated with this scale.
Limit the domain to positive values.
Set the locators and formatters of axis to instances suitable for this scale.
Bases: matplotlib.transforms.Transform
A string representing the "name" of the transform. The name carries no significance other than to improve the readability of str(transform) when DEBUG=True.
True if this transform has a corresponding inverse transform.
The number of input dimensions of this transform. Must be overridden (with integers) in the subclass.
Return the corresponding inverse transformation.
It holds x == self.inverted().transform(self.transform(x)).
The return value of this method should be treated as temporary. An update to self does not cause a corresponding update to its inverted copy.
True if this transform is separable in the x- and y- dimensions.
The number of output dimensions of this transform. Must be overridden (with integers) in the subclass.
Apply only the non-affine part of this transformation.
transform(values) is always equivalent to transform_affine(transform_non_affine(values)).
In non-affine transformations, this is generally equivalent to transform(values). In affine transformations, this is always a no-op.
The input values as NumPy array of length input_dims or shape (N x input_dims).
The output values as NumPy array of length input_dims or shape (N x output_dims), depending on the input.
Bases: matplotlib.transforms.Transform
A string representing the "name" of the transform. The name carries no significance other than to improve the readability of str(transform) when DEBUG=True.
True if this transform has a corresponding inverse transform.
The number of input dimensions of this transform. Must be overridden (with integers) in the subclass.
Return the corresponding inverse transformation.
It holds x == self.inverted().transform(self.transform(x)).
The return value of this method should be treated as temporary. An update to self does not cause a corresponding update to its inverted copy.
True if this transform is separable in the x- and y- dimensions.
The number of output dimensions of this transform. Must be overridden (with integers) in the subclass.
logistic transform (base 10)
Bases: matplotlib.scale.ScaleBase
Logit scale for data between zero and one, both excluded.
This scale is similar to a log scale close to zero and to one, and almost linear around 0.5. It maps the interval ]0, 1[ onto ]-infty, +infty[.
Currently unused.
Determines the behavior for values beyond the open interval ]0, 1[. They can either be masked as invalid, or clipped to a number very close to 0 or 1.
Indicate the usage of survival notation (overline{x}) in place of standard notation (1-x) for probability close to one.
The string used for ticks formatter to represent 1/2.
Return the LogitTransform associated with this scale.
Limit the domain to values between 0 and 1 (excluded).
Set the locators and formatters of axis to instances suitable for this scale.
Bases: matplotlib.transforms.Transform
A string representing the "name" of the transform. The name carries no significance other than to improve the readability of str(transform) when DEBUG=True.
True if this transform has a corresponding inverse transform.
The number of input dimensions of this transform. Must be overridden (with integers) in the subclass.
Return the corresponding inverse transformation.
It holds x == self.inverted().transform(self.transform(x)).
The return value of this method should be treated as temporary. An update to self does not cause a corresponding update to its inverted copy.
True if this transform is separable in the x- and y- dimensions.
The number of output dimensions of this transform. Must be overridden (with integers) in the subclass.
logit transform (base 10), masked or clipped
Bases: object
The base class for all scales.
Scales are separable transformations, working on a single dimension.
Subclasses should override
The scale's name.
A method returning a Transform, which converts data coordinates to scaled coordinates. This transform should be invertible, so that e.g. mouse positions can be converted back to data coordinates.
A method that sets default locators and formatters for an Axis that uses this scale.
An optional method that "fixes" the axis range to acceptable values, e.g. restricting log-scaled axes to positive values.
Construct a new scale.
The following note is for scale implementors.
For back-compatibility reasons, scales take an Axis object as first argument. However, this argument should not be used: a single scale object should be usable by multiple Axises at the same time.
Return the Transform object associated with this scale.
Return the range vmin, vmax, restricted to the domain supported by this scale (if any).
minpos should be the minimum positive value in the data. This is used by log scales to determine a minimum value.
Set the locators and formatters of axis to instances suitable for this scale.
Bases: matplotlib.scale.ScaleBase
The symmetrical logarithmic scale is logarithmic in both the positive and negative directions from the origin.
Since the values close to zero tend toward infinity, there is a need to have a range around zero that is linear. The parameter linthresh allows the user to specify the size of this range (-linthresh, linthresh).
The base of the logarithm.
Defines the range (-x, x), within which the plot is linear. This avoids having the plot go to infinity around zero.
Where to place the subticks between each major tick. 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.
This allows the linear range (-linthresh, linthresh) to be stretched relative to the logarithmic range. Its value is the number of decades to use for each half of the linear range. For example, when linscale == 1.0 (the default), the space used for the positive and negative halves of the linear range will be equal to one decade in the logarithmic range.
Construct a new scale.
The following note is for scale implementors.
For back-compatibility reasons, scales take an Axis object as first argument. However, this argument should not be used: a single scale object should be usable by multiple Axises at the same time.
Return the SymmetricalLogTransform associated with this scale.
Set the locators and formatters of axis to instances suitable for this scale.
Bases: matplotlib.transforms.Transform
A string representing the "name" of the transform. The name carries no significance other than to improve the readability of str(transform) when DEBUG=True.
True if this transform has a corresponding inverse transform.
The number of input dimensions of this transform. Must be overridden (with integers) in the subclass.
Return the corresponding inverse transformation.
It holds x == self.inverted().transform(self.transform(x)).
The return value of this method should be treated as temporary. An update to self does not cause a corresponding update to its inverted copy.
True if this transform is separable in the x- and y- dimensions.
The number of output dimensions of this transform. Must be overridden (with integers) in the subclass.
Apply only the non-affine part of this transformation.
transform(values) is always equivalent to transform_affine(transform_non_affine(values)).
In non-affine transformations, this is generally equivalent to transform(values). In affine transformations, this is always a no-op.
The input values as NumPy array of length input_dims or shape (N x input_dims).
The output values as NumPy array of length input_dims or shape (N x output_dims), depending on the input.
Return the names of the available scales.
Register a new kind of scale.
The scale to register.
Return a scale class by name.


Bases: matplotlib.scale.ScaleBase
Provide an arbitrary scale with user-supplied function for the axis.
The axis for the scale.
two-tuple of the forward and inverse functions for the scale. The forward function must be monotonic.
Both functions must have the signature:
Return the FuncTransform associated with this scale.
Set the locators and formatters of axis to instances suitable for this scale.


Return the FuncTransform associated with this scale.


Set the locators and formatters of axis to instances suitable for this scale.


Bases: matplotlib.scale.LogScale
Provide an arbitrary scale with user-supplied function for the axis and then put on a logarithmic axes.
The axis for the scale.
two-tuple of the forward and inverse functions for the scale. The forward function must be monotonic.
Both functions must have the signature:
Logarithmic base of the scale.
Return the Transform associated with this scale.


Return the Transform associated with this scale.


Bases: matplotlib.transforms.Transform
A simple transform that takes and arbitrary function for the forward and inverse transform.
The forward function for the transform. This function must have an inverse and, for best behavior, be monotonic. It must have the signature:
The inverse of the forward function. Signature as forward.
True if this transform has a corresponding inverse transform.
The number of input dimensions of this transform. Must be overridden (with integers) in the subclass.
Return the corresponding inverse transformation.
It holds x == self.inverted().transform(self.transform(x)).
The return value of this method should be treated as temporary. An update to self does not cause a corresponding update to its inverted copy.
True if this transform is separable in the x- and y- dimensions.
The number of output dimensions of this transform. Must be overridden (with integers) in the subclass.
Apply only the non-affine part of this transformation.
transform(values) is always equivalent to transform_affine(transform_non_affine(values)).
In non-affine transformations, this is generally equivalent to transform(values). In affine transformations, this is always a no-op.
The input values as NumPy array of length input_dims or shape (N x input_dims).
The output values as NumPy array of length input_dims or shape (N x output_dims), depending on the input.


True if this transform has a corresponding inverse transform.


The number of input dimensions of this transform. Must be overridden (with integers) in the subclass.


Return the corresponding inverse transformation.
It holds x == self.inverted().transform(self.transform(x)).
The return value of this method should be treated as temporary. An update to self does not cause a corresponding update to its inverted copy.


True if this transform is separable in the x- and y- dimensions.


The number of output dimensions of this transform. Must be overridden (with integers) in the subclass.


Apply only the non-affine part of this transformation.
transform(values) is always equivalent to transform_affine(transform_non_affine(values)).
In non-affine transformations, this is generally equivalent to transform(values). In affine transformations, this is always a no-op.
The input values as NumPy array of length input_dims or shape (N x input_dims).
The output values as NumPy array of length input_dims or shape (N x output_dims), depending on the input.


Return the names of the available scales.


Bases: matplotlib.transforms.Transform
A string representing the "name" of the transform. The name carries no significance other than to improve the readability of str(transform) when DEBUG=True.
True if this transform has a corresponding inverse transform.
The number of input dimensions of this transform. Must be overridden (with integers) in the subclass.
Return the corresponding inverse transformation.
It holds x == self.inverted().transform(self.transform(x)).
The return value of this method should be treated as temporary. An update to self does not cause a corresponding update to its inverted copy.
True if this transform is separable in the x- and y- dimensions.
The number of output dimensions of this transform. Must be overridden (with integers) in the subclass.
Apply only the non-affine part of this transformation.
transform(values) is always equivalent to transform_affine(transform_non_affine(values)).
In non-affine transformations, this is generally equivalent to transform(values). In affine transformations, this is always a no-op.
The input values as NumPy array of length input_dims or shape (N x input_dims).
The output values as NumPy array of length input_dims or shape (N x output_dims), depending on the input.


Bases: matplotlib.scale.ScaleBase
The default linear scale.
Return the transform for linear scaling, which is just the IdentityTransform.
Set the locators and formatters of axis to instances suitable for this scale.


Return the transform for linear scaling, which is just the IdentityTransform.


Bases: matplotlib.transforms.Transform
A string representing the "name" of the transform. The name carries no significance other than to improve the readability of str(transform) when DEBUG=True.
True if this transform has a corresponding inverse transform.
The number of input dimensions of this transform. Must be overridden (with integers) in the subclass.
Return the corresponding inverse transformation.
It holds x == self.inverted().transform(self.transform(x)).
The return value of this method should be treated as temporary. An update to self does not cause a corresponding update to its inverted copy.
True if this transform is separable in the x- and y- dimensions.
The number of output dimensions of this transform. Must be overridden (with integers) in the subclass.
logistic transform (base 10)


Bases: matplotlib.scale.ScaleBase
Logit scale for data between zero and one, both excluded.
This scale is similar to a log scale close to zero and to one, and almost linear around 0.5. It maps the interval ]0, 1[ onto ]-infty, +infty[.
Currently unused.
Determines the behavior for values beyond the open interval ]0, 1[. They can either be masked as invalid, or clipped to a number very close to 0 or 1.
Indicate the usage of survival notation (overline{x}) in place of standard notation (1-x) for probability close to one.
The string used for ticks formatter to represent 1/2.
Return the LogitTransform associated with this scale.
Limit the domain to values between 0 and 1 (excluded).
Set the locators and formatters of axis to instances suitable for this scale.


Return the LogitTransform associated with this scale.


Limit the domain to values between 0 and 1 (excluded).


Set the locators and formatters of axis to instances suitable for this scale.


Bases: matplotlib.transforms.Transform
A string representing the "name" of the transform. The name carries no significance other than to improve the readability of str(transform) when DEBUG=True.
True if this transform has a corresponding inverse transform.
The number of input dimensions of this transform. Must be overridden (with integers) in the subclass.
Return the corresponding inverse transformation.
It holds x == self.inverted().transform(self.transform(x)).
The return value of this method should be treated as temporary. An update to self does not cause a corresponding update to its inverted copy.
True if this transform is separable in the x- and y- dimensions.
The number of output dimensions of this transform. Must be overridden (with integers) in the subclass.
logit transform (base 10), masked or clipped


logit transform (base 10), masked or clipped


Bases: matplotlib.scale.ScaleBase
A standard logarithmic scale. Care is taken to only plot positive values.
The axis for the scale.
The base of the logarithm.
Determines the behavior for non-positive values. They can either be masked as invalid, or clipped to a very small positive number.
Where to place the subticks between each major tick. 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.
Return the LogTransform associated with this scale.
Limit the domain to positive values.
Set the locators and formatters of axis to instances suitable for this scale.


Return the LogTransform associated with this scale.


True if this transform has a corresponding inverse transform.


The number of input dimensions of this transform. Must be overridden (with integers) in the subclass.


Return the corresponding inverse transformation.
It holds x == self.inverted().transform(self.transform(x)).
The return value of this method should be treated as temporary. An update to self does not cause a corresponding update to its inverted copy.


True if this transform is separable in the x- and y- dimensions.


The number of output dimensions of this transform. Must be overridden (with integers) in the subclass.


Apply only the non-affine part of this transformation.
transform(values) is always equivalent to transform_affine(transform_non_affine(values)).
In non-affine transformations, this is generally equivalent to transform(values). In affine transformations, this is always a no-op.
The input values as NumPy array of length input_dims or shape (N x input_dims).
The output values as NumPy array of length input_dims or shape (N x output_dims), depending on the input.


Register a new kind of scale.
The scale to register.


Bases: object
The base class for all scales.
Scales are separable transformations, working on a single dimension.
Subclasses should override
The scale's name.
A method returning a Transform, which converts data coordinates to scaled coordinates. This transform should be invertible, so that e.g. mouse positions can be converted back to data coordinates.
A method that sets default locators and formatters for an Axis that uses this scale.
An optional method that "fixes" the axis range to acceptable values, e.g. restricting log-scaled axes to positive values.
Construct a new scale.
The following note is for scale implementors.
For back-compatibility reasons, scales take an Axis object as first argument. However, this argument should not be used: a single scale object should be usable by multiple Axises at the same time.
Return the Transform object associated with this scale.
Return the range vmin, vmax, restricted to the domain supported by this scale (if any).
minpos should be the minimum positive value in the data. This is used by log scales to determine a minimum value.
Set the locators and formatters of axis to instances suitable for this scale.


Return the Transform object associated with this scale.


Return the range vmin, vmax, restricted to the domain supported by this scale (if any).
minpos should be the minimum positive value in the data. This is used by log scales to determine a minimum value.


Bases: matplotlib.scale.ScaleBase
The symmetrical logarithmic scale is logarithmic in both the positive and negative directions from the origin.
Since the values close to zero tend toward infinity, there is a need to have a range around zero that is linear. The parameter linthresh allows the user to specify the size of this range (-linthresh, linthresh).
The base of the logarithm.
Defines the range (-x, x), within which the plot is linear. This avoids having the plot go to infinity around zero.
Where to place the subticks between each major tick. 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.
This allows the linear range (-linthresh, linthresh) to be stretched relative to the logarithmic range. Its value is the number of decades to use for each half of the linear range. For example, when linscale == 1.0 (the default), the space used for the positive and negative halves of the linear range will be equal to one decade in the logarithmic range.
Construct a new scale.
The following note is for scale implementors.
For back-compatibility reasons, scales take an Axis object as first argument. However, this argument should not be used: a single scale object should be usable by multiple Axises at the same time.
Return the SymmetricalLogTransform associated with this scale.
Set the locators and formatters of axis to instances suitable for this scale.


Return the SymmetricalLogTransform associated with this scale.


Set the locators and formatters of axis to instances suitable for this scale.


Bases: matplotlib.transforms.Transform
A string representing the "name" of the transform. The name carries no significance other than to improve the readability of str(transform) when DEBUG=True.
True if this transform has a corresponding inverse transform.
The number of input dimensions of this transform. Must be overridden (with integers) in the subclass.
Return the corresponding inverse transformation.
It holds x == self.inverted().transform(self.transform(x)).
The return value of this method should be treated as temporary. An update to self does not cause a corresponding update to its inverted copy.
True if this transform is separable in the x- and y- dimensions.
The number of output dimensions of this transform. Must be overridden (with integers) in the subclass.
Apply only the non-affine part of this transformation.
transform(values) is always equivalent to transform_affine(transform_non_affine(values)).
In non-affine transformations, this is generally equivalent to transform(values). In affine transformations, this is always a no-op.
The input values as NumPy array of length input_dims or shape (N x input_dims).
The output values as NumPy array of length input_dims or shape (N x output_dims), depending on the input.


Set Matplotlib's root logger and root logger handler level, creating the handler if it does not exist yet.
Typically, one should call set_loglevel("info") or set_loglevel("debug") to get additional debugging information.
The log level of the handler.
The first time this function is called, an additional handler is attached to Matplotlib's root handler; this handler is reused every time and this function simply manipulates the logger and handler's level.


Warning
In most cases, you will likely want to use one of Sphinx's builtin Math extensions instead of this one.
Mathtext may be included in two ways:
Inline, using the role:
which produces:
This text uses inline math: .
Standalone, using the directive:
which produces:
Here is some standalone math:
The mathmpl role and directive both support the following options:
The font set to use when displaying math. See rcParams["mathtext.fontset"] (default: 'dejavusans').
The font size, in points. Defaults to the value from the extension configuration option defined below.
The mathtext extension has the following configuration options:
Default font size, in points.
Additional image sizes to generate when embedding in HTML, to support responsive resolution images. The list should contain additional x-descriptors ('1.5x', '2x', etc.) to generate (1x is the default and always included.)
The .. mathmpl:: directive, as documented in the module's docstring.


The .. mathmpl:: directive, as documented in the module's docstring.


By default, in HTML output, plot will include a .png file with a link to a high-res .png and .pdf. In LaTeX output, it will include a .pdf.
The source code for the plot may be included in one of three ways:
A path to a source file as the argument to the directive:
When a path to a source file is given, the content of the directive may optionally contain a caption for the plot:
Additionally, one may specify the name of a function to call (with no arguments) immediately after importing the module:
Included as inline content to the directive:
Using doctest syntax:
The plot directive supports the following options:
The format of the input. If unset, the format is auto-detected.
Whether to display the source code. The default can be changed using the plot_include_source variable in conf.py (which itself defaults to False).
If this source file is in a non-UTF8 or non-ASCII encoding, the encoding must be specified using the :encoding: option. The encoding will not be inferred using the -*- coding -*- metacomment.
If provided, the code will be run in the context of all previous plot directives for which the :context: option was specified. This only applies to inline code plot directives, not those run from files. If the :context: reset option is specified, the context is reset for this and future plots, and previous figures are closed prior to running the code. :context: close-figs keeps the context but closes previous figures before running the code.
If specified, the code block will be run, but no figures will be inserted. This is usually useful with the :context: option.
If specified, the option's argument will be used as a caption for the figure. This overwrites the caption given in the content, when the plot is generated from a file.
Additionally, this directive supports all of the options of the image directive, except for target (since plot will add its own target). These include alt, height, width, scale, align and class.
The plot directive has the following configuration options:
Default value for the include-source option (default: False).
Whether to show a link to the source in HTML (default: True).
Code that should be executed before each plot. If None (the default), it will default to a string containing:
Base directory, to which plot:: file names are relative to. If None or empty (the default), file names are relative to the directory where the file containing the directive is.
File formats to generate (default: ['png', 'hires.png', 'pdf']). List of tuples or strings:
that determine the file format and the DPI. For entries whose DPI was omitted, sensible defaults are chosen. When passing from the command line through sphinx_build the list should be passed as suffix:dpi,suffix:dpi, ...
Whether to show links to the files in HTML (default: True).
A dictionary containing any non-standard rcParams that should be applied before each plot (default: {}).
By default, rcParams are applied when :context: option is not used in a plot directive. If set, this configuration option overrides this behavior and applies rcParams before each plot.
By default, the working directory will be changed to the directory of the example, so the code can get at its data files, if any. Also its path will be added to sys.path so it can import any helper modules sitting beside it. This configuration option can be used to specify a central directory (also added to sys.path) where data files and helper modules for all code are located.
Provide a customized template for preparing restructured text.
The .. plot:: directive, as documented in the module's docstring.
Run the plot directive.
To make plots referenceable, we need to move the reference from the "htmlonly" (or "latexonly") node to the actual figure node itself.
Return whether derived is out-of-date relative to original or any of the RST files included in it using the RST include directive (includes). derived and original are full paths, and includes is optionally a list of full paths which may have been included in the original.
Run a pyplot script and save the images in output_dir.
Save the images under output_dir with file names derived from output_base
[Deprecated] Import a Python module from a path, and run the function given by name, if function_name is not None.
Deprecated since version 3.5.
[Deprecated] Split code at plt.show().
Deprecated since version 3.5.
[Deprecated] Extract code from a piece of text, which contains either Python code or doctests.
Deprecated since version 3.5.


To make plots referenceable, we need to move the reference from the "htmlonly" (or "latexonly") node to the actual figure node itself.


Return whether derived is out-of-date relative to original or any of the RST files included in it using the RST include directive (includes). derived and original are full paths, and includes is optionally a list of full paths which may have been included in the original.


The .. plot:: directive, as documented in the module's docstring.
Run the plot directive.


Run a pyplot script and save the images in output_dir.
Save the images under output_dir with file names derived from output_base


[Deprecated] Import a Python module from a path, and run the function given by name, if function_name is not None.
Deprecated since version 3.5.


[Deprecated] Split code at plt.show().
Deprecated since version 3.5.


[Deprecated] Extract code from a piece of text, which contains either Python code or doctests.
Deprecated since version 3.5.


Bases: matplotlib.patches.Patch
An axis spine -- the line noting the data area boundaries.
Spines are the lines connecting the axis tick marks and noting the boundaries of the data area. They can be placed at arbitrary positions. See set_position for more information.
The default position is ('outward', 0).
Spines are subclasses of Patch, and inherit much of their behavior.
Spines draw a line, a circle, or an arc depending if set_patch_line, set_patch_circle, or set_patch_arc has been called. Line-like is the default.
The Axes instance containing the spine.
The spine type.
The Path instance used to draw the spine.
Valid keyword arguments are:
Property
Description
agg_filter
a filter function, which takes a (m, n, 3) float array and a dpi value, and returns a (m, n, 3) array
alpha
unknown
animated
bool
antialiased or aa
bool or None
capstyle
CapStyle or {'butt', 'projecting', 'round'}
clip_box
Bbox
clip_on
bool
clip_path
Patch or (Path, Transform) or None
color
color
edgecolor or ec
color or None
facecolor or fc
color or None
figure
Figure
fill
bool
gid
str
hatch
{'/', '\', '|', '-', '+', 'x', 'o', 'O', '.', '*'}
in_layout
bool
joinstyle
JoinStyle or {'miter', 'round', 'bevel'}
label
object
linestyle or ls
{'-', '--', '-.', ':', '', (offset, on-off-seq), ...}
linewidth or lw
float or None
path_effects
AbstractPathEffect
picker
None or bool or float or callable
rasterized
bool
sketch_params
(scale: float, length: float, randomness: float)
snap
bool or None
transform
Transform
url
str
visible
bool
zorder
float
Create and return an arc Spine.
Create and return a circular Spine.
[Deprecated]
Deprecated since version 3.4:
Clear the current spine.
Draw the Artist (and its children) using the given renderer.
This has no effect if the artist is not visible (Artist.get_visible returns False).
This method is overridden in the Artist subclasses.
Get the bounds of the spine.
Return the Transform instance mapping patch coordinates to data coordinates.
For example, one may define a patch of a circle which represents a radius of 5 by providing coordinates for a unit circle, and a transform which scales the coordinates (the patch coordinate) by 5.
Return the path of this patch.
Return the spine position.
Return the spine transform.
Return the window extent of the spines in display space, including padding for ticks (but not their labels)
See also
Create and return a linear Spine.
Register an axis.
An axis should be registered with its corresponding spine from the Axes instance. This allows the spine to clear any axis properties when needed.
Set multiple properties at once.
Supported properties are
Property
Description
agg_filter
a filter function, which takes a (m, n, 3) float array and a dpi value, and returns a (m, n, 3) array
alpha
scalar or None
animated
bool
antialiased or aa
bool or None
bounds
(low: float, high: float)
capstyle
CapStyle or {'butt', 'projecting', 'round'}
clip_box
Bbox
clip_on
bool
clip_path
Patch or (Path, Transform) or None
color
color
edgecolor or ec
color or None
facecolor or fc
color or None
figure
Figure
fill
bool
gid
str
hatch
{'/', '\', '|', '-', '+', 'x', 'o', 'O', '.', '*'}
in_layout
bool
joinstyle
JoinStyle or {'miter', 'round', 'bevel'}
label
object
linestyle or ls
{'-', '--', '-.', ':', '', (offset, on-off-seq), ...}
linewidth or lw
float or None
patch_arc
unknown
patch_circle
unknown
path_effects
AbstractPathEffect
picker
None or bool or float or callable
position
unknown
rasterized
bool
sketch_params
(scale: float, length: float, randomness: float)
snap
bool or None
transform
Transform
url
str
visible
bool
zorder
float
Set the spine bounds.
The lower spine bound. Passing None leaves the limit unchanged.
The bounds may also be passed as the tuple (low, high) as the first positional argument.
The higher spine bound. Passing None leaves the limit unchanged.
Set the edgecolor.
This method does not modify the facecolor (which defaults to "none"), unlike the Patch.set_color method defined in the parent class. Use Patch.set_facecolor to set the facecolor.
Set the spine to be arc-like.
Set the spine to be circular.
Set the spine to be linear.
Set the position of the spine.
Spine position is specified by a 2 tuple of (position type, amount). The position types are:
Additionally, shorthand notations define a special positions:
Bases: collections.abc.MutableMapping
The container of all Spines in an Axes.
The interface is dict-like mapping names (e.g. 'left') to Spine objects. Additionally it implements some pandas.Series-like features like accessing elements by attribute:
Multiple spines can be addressed simultaneously by passing a list:
Use an open slice to address all spines:
The latter two indexing methods will return a SpinesProxy that broadcasts all set_* calls to its members, but cannot be used for any other operation.
Bases: object
A proxy to broadcast set_* method calls to all contained Spines.
The proxy cannot be used for any other operations on its members.
The supported methods are determined dynamically based on the contained spines. If not all spines support a given method, it's executed only on the subset of spines that support it.


Bases: matplotlib.patches.Patch
An axis spine -- the line noting the data area boundaries.
Spines are the lines connecting the axis tick marks and noting the boundaries of the data area. They can be placed at arbitrary positions. See set_position for more information.
The default position is ('outward', 0).
Spines are subclasses of Patch, and inherit much of their behavior.
Spines draw a line, a circle, or an arc depending if set_patch_line, set_patch_circle, or set_patch_arc has been called. Line-like is the default.
The Axes instance containing the spine.
The spine type.
The Path instance used to draw the spine.
Valid keyword arguments are:
Property
Description
agg_filter
a filter function, which takes a (m, n, 3) float array and a dpi value, and returns a (m, n, 3) array
alpha
unknown
animated
bool
antialiased or aa
bool or None
capstyle
CapStyle or {'butt', 'projecting', 'round'}
clip_box
Bbox
clip_on
bool
clip_path
Patch or (Path, Transform) or None
color
color
edgecolor or ec
color or None
facecolor or fc
color or None
figure
Figure
fill
bool
gid
str
hatch
{'/', '\', '|', '-', '+', 'x', 'o', 'O', '.', '*'}
in_layout
bool
joinstyle
JoinStyle or {'miter', 'round', 'bevel'}
label
object
linestyle or ls
{'-', '--', '-.', ':', '', (offset, on-off-seq), ...}
linewidth or lw
float or None
path_effects
AbstractPathEffect
picker
None or bool or float or callable
rasterized
bool
sketch_params
(scale: float, length: float, randomness: float)
snap
bool or None
transform
Transform
url
str
visible
bool
zorder
float
Create and return an arc Spine.
Create and return a circular Spine.
[Deprecated]
Deprecated since version 3.4:
Clear the current spine.
Draw the Artist (and its children) using the given renderer.
This has no effect if the artist is not visible (Artist.get_visible returns False).
This method is overridden in the Artist subclasses.
Get the bounds of the spine.
Return the Transform instance mapping patch coordinates to data coordinates.
For example, one may define a patch of a circle which represents a radius of 5 by providing coordinates for a unit circle, and a transform which scales the coordinates (the patch coordinate) by 5.
Return the path of this patch.
Return the spine position.
Return the spine transform.
Return the window extent of the spines in display space, including padding for ticks (but not their labels)
See also
Create and return a linear Spine.
Register an axis.
An axis should be registered with its corresponding spine from the Axes instance. This allows the spine to clear any axis properties when needed.
Set multiple properties at once.
Supported properties are
Property
Description
agg_filter
a filter function, which takes a (m, n, 3) float array and a dpi value, and returns a (m, n, 3) array
alpha
scalar or None
animated
bool
antialiased or aa
bool or None
bounds
(low: float, high: float)
capstyle
CapStyle or {'butt', 'projecting', 'round'}
clip_box
Bbox
clip_on
bool
clip_path
Patch or (Path, Transform) or None
color
color
edgecolor or ec
color or None
facecolor or fc
color or None
figure
Figure
fill
bool
gid
str
hatch
{'/', '\', '|', '-', '+', 'x', 'o', 'O', '.', '*'}
in_layout
bool
joinstyle
JoinStyle or {'miter', 'round', 'bevel'}
label
object
linestyle or ls
{'-', '--', '-.', ':', '', (offset, on-off-seq), ...}
linewidth or lw
float or None
patch_arc
unknown
patch_circle
unknown
path_effects
AbstractPathEffect
picker
None or bool or float or callable
position
unknown
rasterized
bool
sketch_params
(scale: float, length: float, randomness: float)
snap
bool or None
transform
Transform
url
str
visible
bool
zorder
float
Set the spine bounds.
The lower spine bound. Passing None leaves the limit unchanged.
The bounds may also be passed as the tuple (low, high) as the first positional argument.
The higher spine bound. Passing None leaves the limit unchanged.
Set the edgecolor.
This method does not modify the facecolor (which defaults to "none"), unlike the Patch.set_color method defined in the parent class. Use Patch.set_facecolor to set the facecolor.
Set the spine to be arc-like.
Set the spine to be circular.
Set the spine to be linear.
Set the position of the spine.
Spine position is specified by a 2 tuple of (position type, amount). The position types are:
Additionally, shorthand notations define a special positions:


[Deprecated]
Deprecated since version 3.4:


Draw the Artist (and its children) using the given renderer.
This has no effect if the artist is not visible (Artist.get_visible returns False).
This method is overridden in the Artist subclasses.


Return the Transform instance mapping patch coordinates to data coordinates.
For example, one may define a patch of a circle which represents a radius of 5 by providing coordinates for a unit circle, and a transform which scales the coordinates (the patch coordinate) by 5.


Return the window extent of the spines in display space, including padding for ticks (but not their labels)
See also


Register an axis.
An axis should be registered with its corresponding spine from the Axes instance. This allows the spine to clear any axis properties when needed.


Set multiple properties at once.
Supported properties are
Property
Description
agg_filter
a filter function, which takes a (m, n, 3) float array and a dpi value, and returns a (m, n, 3) array
alpha
scalar or None
animated
bool
antialiased or aa
bool or None
bounds
(low: float, high: float)
capstyle
CapStyle or {'butt', 'projecting', 'round'}
clip_box
Bbox
clip_on
bool
clip_path
Patch or (Path, Transform) or None
color
color
edgecolor or ec
color or None
facecolor or fc
color or None
figure
Figure
fill
bool
gid
str
hatch
{'/', '\', '|', '-', '+', 'x', 'o', 'O', '.', '*'}
in_layout
bool
joinstyle
JoinStyle or {'miter', 'round', 'bevel'}
label
object
linestyle or ls
{'-', '--', '-.', ':', '', (offset, on-off-seq), ...}
linewidth or lw
float or None
patch_arc
unknown
patch_circle
unknown
path_effects
AbstractPathEffect
picker
None or bool or float or callable
position
unknown
rasterized
bool
sketch_params
(scale: float, length: float, randomness: float)
snap
bool or None
transform
Transform
url
str
visible
bool
zorder
float


Set the spine bounds.
The lower spine bound. Passing None leaves the limit unchanged.
The bounds may also be passed as the tuple (low, high) as the first positional argument.
The higher spine bound. Passing None leaves the limit unchanged.


Set the edgecolor.
This method does not modify the facecolor (which defaults to "none"), unlike the Patch.set_color method defined in the parent class. Use Patch.set_facecolor to set the facecolor.


Set the position of the spine.
Spine position is specified by a 2 tuple of (position type, amount). The position types are:
Additionally, shorthand notations define a special positions:


Bases: collections.abc.MutableMapping
The container of all Spines in an Axes.
The interface is dict-like mapping names (e.g. 'left') to Spine objects. Additionally it implements some pandas.Series-like features like accessing elements by attribute:
Multiple spines can be addressed simultaneously by passing a list:
Use an open slice to address all spines:
The latter two indexing methods will return a SpinesProxy that broadcasts all set_* calls to its members, but cannot be used for any other operation.


Bases: object
A proxy to broadcast set_* method calls to all contained Spines.
The proxy cannot be used for any other operations on its members.
The supported methods are determined dynamically based on the contained spines. If not all spines support a given method, it's executed only on the subset of spines that support it.


Styles are predefined sets of rcParams that define the visual appearance of a plot.
Customizing Matplotlib with style sheets and rcParams describes the mechanism and usage of styles.
The Style sheets reference gives an overview of the builtin styles.
Context manager for using style settings temporarily.
A style specification. Valid options are:
str
The name of a style or a path/URL to a style file. For a list of available style names, see style.available.
dict
Dictionary with valid key/value pairs for matplotlib.rcParams.
Path
A path-like object which is a path to a style file.
list
A list of style specifiers (str, Path or dict) applied from first to last in the list.
If True, apply style after resetting settings to their defaults; otherwise, apply style on top of the current settings.
Reload the style library.
Use Matplotlib style settings from a style specification.
The style name of 'default' is reserved for reverting back to the default style settings.
Note
This updates the rcParams with the settings from the style. rcParams not defined in the style are kept.
A style specification. Valid options are:
str
The name of a style or a path/URL to a style file. For a list of available style names, see style.available.
dict
Dictionary with valid key/value pairs for matplotlib.rcParams.
Path
A path-like object which is a path to a style file.
list
A list of style specifiers (str, Path or dict) applied from first to last in the list.
The following rcParams are not related to style and will be ignored if found in a style specification:
A dict mapping from style name to RcParams defining that style.
This is meant to be read-only. Use reload_library to update.
List of the names of the available styles.
This is meant to be read-only. Use reload_library to update.


Context manager for using style settings temporarily.
A style specification. Valid options are:
str
The name of a style or a path/URL to a style file. For a list of available style names, see style.available.
dict
Dictionary with valid key/value pairs for matplotlib.rcParams.
Path
A path-like object which is a path to a style file.
list
A list of style specifiers (str, Path or dict) applied from first to last in the list.
If True, apply style after resetting settings to their defaults; otherwise, apply style on top of the current settings.


List of the names of the available styles.
This is meant to be read-only. Use reload_library to update.


A dict mapping from style name to RcParams defining that style.
This is meant to be read-only. Use reload_library to update.


Use Matplotlib style settings from a style specification.
The style name of 'default' is reserved for reverting back to the default style settings.
Note
This updates the rcParams with the settings from the style. rcParams not defined in the style are kept.
A style specification. Valid options are:
str
The name of a style or a path/URL to a style file. For a list of available style names, see style.available.
dict
Dictionary with valid key/value pairs for matplotlib.rcParams.
Path
A path-like object which is a path to a style file.
list
A list of style specifiers (str, Path or dict) applied from first to last in the list.
The following rcParams are not related to style and will be ignored if found in a style specification:


Tables drawing.
Note
The table implementation in Matplotlib is lightly maintained. For a more featureful table implementation, you may wish to try blume.
Use the factory function table to create a ready-made table from texts. If you need more control, use the Table class and its methods.
The table consists of a grid of cells, which are indexed by (row, column). The cell (0, 0) is positioned at the top left.
Thanks to John Gill for providing the class and table.
Bases: matplotlib.patches.Rectangle
A cell is a Rectangle with some associated Text.
As a user, you'll most likely not creates cells yourself. Instead, you should use either the table factory function or Table.add_cell.
The position of the bottom left corner of the cell.
The cell width.
The cell height.
The color of the cell border.
The cell facecolor.
Whether the cell background is filled.
The cell text.
The alignment of the text within the cell.
A dict defining the font properties of the text. Supported keys and values are the keyword arguments accepted by FontProperties.
The cell edges to be drawn with a line: a substring of 'BRTL' (bottom, right, top, left), or one of 'open' (no edges drawn), 'closed' (all edges drawn), 'horizontal' (bottom and top), 'vertical' (right and left).
Padding between text and rectangle.
Shrink font size until the text fits into the cell width.
Draw the Artist (and its children) using the given renderer.
This has no effect if the artist is not visible (Artist.get_visible returns False).
This method is overridden in the Artist subclasses.
Return the cell fontsize.
Return a Path for the visible_edges.
Return the minimal required width for the cell.
Return the cell Text instance.
Return the text bounds as (x, y, width, height) in table coordinates.
Set multiple properties at once.
Supported properties are
Property
Description
agg_filter
a filter function, which takes a (m, n, 3) float array and a dpi value, and returns a (m, n, 3) array
alpha
scalar or None
angle
unknown
animated
bool
antialiased or aa
bool or None
bounds
(left, bottom, width, height)
capstyle
CapStyle or {'butt', 'projecting', 'round'}
clip_box
Bbox
clip_on
bool
clip_path
Patch or (Path, Transform) or None
color
color
edgecolor or ec
color or None
facecolor or fc
color or None
figure
unknown
fill
bool
fontsize
unknown
gid
str
hatch
{'/', '\', '|', '-', '+', 'x', 'o', 'O', '.', '*'}
height
unknown
in_layout
bool
joinstyle
JoinStyle or {'miter', 'round', 'bevel'}
label
object
linestyle or ls
{'-', '--', '-.', ':', '', (offset, on-off-seq), ...}
linewidth or lw
float or None
path_effects
AbstractPathEffect
picker
None or bool or float or callable
rasterized
bool
sketch_params
(scale: float, length: float, randomness: float)
snap
bool or None
text_props
unknown
transform
unknown
url
str
visible
bool
width
unknown
x
unknown
xy
(float, float)
y
unknown
zorder
float
Set the Figure instance the artist belongs to.
Set the text fontsize.
Update the text properties.
Valid keyword arguments are:
Property
Description
agg_filter
a filter function, which takes a (m, n, 3) float array and a dpi value, and returns a (m, n, 3) array
alpha
scalar or None
animated
bool
backgroundcolor
color
bbox
dict with properties for patches.FancyBboxPatch
clip_box
unknown
clip_on
unknown
clip_path
unknown
color or c
color
figure
Figure
fontfamily or family
{FONTNAME, 'serif', 'sans-serif', 'cursive', 'fantasy', 'monospace'}
fontproperties or font or font_properties
font_manager.FontProperties or str or pathlib.Path
fontsize or size
float or {'xx-small', 'x-small', 'small', 'medium', 'large', 'x-large', 'xx-large'}
fontstretch or stretch
{a numeric value in range 0-1000, 'ultra-condensed', 'extra-condensed', 'condensed', 'semi-condensed', 'normal', 'semi-expanded', 'expanded', 'extra-expanded', 'ultra-expanded'}
fontstyle or style
{'normal', 'italic', 'oblique'}
fontvariant or variant
{'normal', 'small-caps'}
fontweight or weight
{a numeric value in range 0-1000, 'ultralight', 'light', 'normal', 'regular', 'book', 'medium', 'roman', 'semibold', 'demibold', 'demi', 'bold', 'heavy', 'extra bold', 'black'}
gid
str
horizontalalignment or ha
{'center', 'right', 'left'}
in_layout
bool
label
object
linespacing
float (multiple of font size)
math_fontfamily
str
multialignment or ma
{'left', 'right', 'center'}
parse_math
bool
path_effects
AbstractPathEffect
picker
None or bool or float or callable
position
(float, float)
rasterized
bool
rotation
float or {'vertical', 'horizontal'}
rotation_mode
{None, 'default', 'anchor'}
sketch_params
(scale: float, length: float, randomness: float)
snap
bool or None
text
object
transform
Transform
transform_rotates_text
bool
url
str
usetex
bool or None
verticalalignment or va
{'center', 'top', 'bottom', 'baseline', 'center_baseline'}
visible
bool
wrap
bool
x
float
y
float
zorder
float
Set the artist transform.
The cell edges to be drawn with a line.
Reading this property returns a substring of 'BRTL' (bottom, right, top, left').
When setting this property, you can use a substring of 'BRTL' or one of {'open', 'closed', 'horizontal', 'vertical'}.
alias of matplotlib.table.Cell
Bases: matplotlib.artist.Artist
A table of cells.
The table consists of a grid of cells, which are indexed by (row, column).
For a simple table, you'll have a full grid of cells with indices from (0, 0) to (num_rows-1, num_cols-1), in which the cell (0, 0) is positioned at the top left. However, you can also add cells with negative indices. You don't have to add a cell to every grid position, so you can create tables that have holes.
Note: You'll usually not create an empty table from scratch. Instead use table to create a table from data.
The Axes to plot the table into.
The position of the cell with respect to ax. This must be one of the codes.
A bounding box to draw the table into. If this is not None, this overrides loc.
Artist properties.
The border between the Axes and the table edge in Axes units.
Create a cell and add it to the table.
Row index.
Column index.
All other parameters are passed on to Cell.
The created cell.
Automatically set the widths of given columns to optimal sizes.
The indices of the columns to auto-scale.
Automatically set font size.
Possible values where to place the table relative to the Axes.
Test whether the artist contains the mouse event.
Whether any values are within the radius.
An artist-specific dictionary of details of the event context, such as which points are contained in the pick radius. See the individual Artist subclasses for details.
Draw the Artist (and its children) using the given renderer.
This has no effect if the artist is not visible (Artist.get_visible returns False).
This method is overridden in the Artist subclasses.
The default value of visible_edges for newly added cells using add_cell.
This setting does currently only affect newly created cells using add_cell.
To change existing cells, you have to set their edges explicitly:
Return a dict of cells in the table mapping (row, column) to Cells.
You can also directly index into the Table object to access individual cells:
Return the Artists contained by the table.
Get the artist's bounding box in display space.
The bounding box' width and height are nonnegative.
Subclasses should override for inclusion in the bounding box "tight" calculation. Default is to return an empty bounding box at 0, 0.
Be careful when using this function, the results will not update if the artist window extent of the artist changes. The extent can change due to any changes in the transform stack, such as changing the axes limits, the figure size, or the canvas used (as is done when saving a figure). This can lead to unexpected behavior where interactive figures will look fine on the screen, but will save incorrectly.
Scale column widths by xscale and row heights by yscale.
Set multiple properties at once.
Supported properties are
Property
Description
agg_filter
a filter function, which takes a (m, n, 3) float array and a dpi value, and returns a (m, n, 3) array
alpha
scalar or None
animated
bool
clip_box
Bbox
clip_on
bool
clip_path
Patch or (Path, Transform) or None
figure
Figure
fontsize
float
gid
str
in_layout
bool
label
object
path_effects
AbstractPathEffect
picker
None or bool or float or callable
rasterized
bool
sketch_params
(scale: float, length: float, randomness: float)
snap
bool or None
transform
Transform
url
str
visible
bool
zorder
float
Set the font size, in points, of the cell text.
As long as auto font size has not been disabled, the value will be clipped such that the text fits horizontally into the cell.
You can disable this behavior using auto_set_font_size.
However, there is no automatic scaling of the row height so that the text may exceed the cell boundary.
Add a table to an Axes.
At least one of cellText or cellColours must be specified. These parameters must be 2D lists, in which the outer lists define the rows and the inner list define the column values per row. Each row must have the same number of elements.
The table can optionally have row and column headers, which are configured using rowLabels, rowColours, rowLoc and colLabels, colColours, colLoc respectively.
For finer grained control over tables, use the Table class and add it to the axes with Axes.add_table.
The texts to place into the table cells.
Note: Line breaks in the strings are currently not accounted for and will result in the text exceeding the cell boundaries.
The background colors of the cells.
The alignment of the text within the cells.
The column widths in units of the axes. If not given, all columns will have a width of 1 / ncols.
The text of the row header cells.
The colors of the row header cells.
The text alignment of the row header cells.
The text of the column header cells.
The colors of the column header cells.
The text alignment of the column header cells.
The position of the cell with respect to ax. This must be one of the codes.
A bounding box to draw the table into. If this is not None, this overrides loc.
The cell edges to be drawn with a line. See also visible_edges.
The created table.
Table properties.
Property
Description
agg_filter
a filter function, which takes a (m, n, 3) float array and a dpi value, and returns a (m, n, 3) array
alpha
scalar or None
animated
bool
clip_box
Bbox
clip_on
bool
clip_path
Patch or (Path, Transform) or None
figure
Figure
fontsize
float
gid
str
in_layout
bool
label
object
path_effects
AbstractPathEffect
picker
None or bool or float or callable
rasterized
bool
sketch_params
(scale: float, length: float, randomness: float)
snap
bool or None
transform
Transform
url
str
visible
bool
zorder
float


Bases: matplotlib.patches.Rectangle
A cell is a Rectangle with some associated Text.
As a user, you'll most likely not creates cells yourself. Instead, you should use either the table factory function or Table.add_cell.
The position of the bottom left corner of the cell.
The cell width.
The cell height.
The color of the cell border.
The cell facecolor.
Whether the cell background is filled.
The cell text.
The alignment of the text within the cell.
A dict defining the font properties of the text. Supported keys and values are the keyword arguments accepted by FontProperties.
The cell edges to be drawn with a line: a substring of 'BRTL' (bottom, right, top, left), or one of 'open' (no edges drawn), 'closed' (all edges drawn), 'horizontal' (bottom and top), 'vertical' (right and left).
Padding between text and rectangle.
Shrink font size until the text fits into the cell width.
Draw the Artist (and its children) using the given renderer.
This has no effect if the artist is not visible (Artist.get_visible returns False).
This method is overridden in the Artist subclasses.
Return the cell fontsize.
Return a Path for the visible_edges.
Return the minimal required width for the cell.
Return the cell Text instance.
Return the text bounds as (x, y, width, height) in table coordinates.
Set multiple properties at once.
Supported properties are
Property
Description
agg_filter
a filter function, which takes a (m, n, 3) float array and a dpi value, and returns a (m, n, 3) array
alpha
scalar or None
angle
unknown
animated
bool
antialiased or aa
bool or None
bounds
(left, bottom, width, height)
capstyle
CapStyle or {'butt', 'projecting', 'round'}
clip_box
Bbox
clip_on
bool
clip_path
Patch or (Path, Transform) or None
color
color
edgecolor or ec
color or None
facecolor or fc
color or None
figure
unknown
fill
bool
fontsize
unknown
gid
str
hatch
{'/', '\', '|', '-', '+', 'x', 'o', 'O', '.', '*'}
height
unknown
in_layout
bool
joinstyle
JoinStyle or {'miter', 'round', 'bevel'}
label
object
linestyle or ls
{'-', '--', '-.', ':', '', (offset, on-off-seq), ...}
linewidth or lw
float or None
path_effects
AbstractPathEffect
picker
None or bool or float or callable
rasterized
bool
sketch_params
(scale: float, length: float, randomness: float)
snap
bool or None
text_props
unknown
transform
unknown
url
str
visible
bool
width
unknown
x
unknown
xy
(float, float)
y
unknown
zorder
float
Set the Figure instance the artist belongs to.
Set the text fontsize.
Update the text properties.
Valid keyword arguments are:
Property
Description
agg_filter
a filter function, which takes a (m, n, 3) float array and a dpi value, and returns a (m, n, 3) array
alpha
scalar or None
animated
bool
backgroundcolor
color
bbox
dict with properties for patches.FancyBboxPatch
clip_box
unknown
clip_on
unknown
clip_path
unknown
color or c
color
figure
Figure
fontfamily or family
{FONTNAME, 'serif', 'sans-serif', 'cursive', 'fantasy', 'monospace'}
fontproperties or font or font_properties
font_manager.FontProperties or str or pathlib.Path
fontsize or size
float or {'xx-small', 'x-small', 'small', 'medium', 'large', 'x-large', 'xx-large'}
fontstretch or stretch
{a numeric value in range 0-1000, 'ultra-condensed', 'extra-condensed', 'condensed', 'semi-condensed', 'normal', 'semi-expanded', 'expanded', 'extra-expanded', 'ultra-expanded'}
fontstyle or style
{'normal', 'italic', 'oblique'}
fontvariant or variant
{'normal', 'small-caps'}
fontweight or weight
{a numeric value in range 0-1000, 'ultralight', 'light', 'normal', 'regular', 'book', 'medium', 'roman', 'semibold', 'demibold', 'demi', 'bold', 'heavy', 'extra bold', 'black'}
gid
str
horizontalalignment or ha
{'center', 'right', 'left'}
in_layout
bool
label
object
linespacing
float (multiple of font size)
math_fontfamily
str
multialignment or ma
{'left', 'right', 'center'}
parse_math
bool
path_effects
AbstractPathEffect
picker
None or bool or float or callable
position
(float, float)
rasterized
bool
rotation
float or {'vertical', 'horizontal'}
rotation_mode
{None, 'default', 'anchor'}
sketch_params
(scale: float, length: float, randomness: float)
snap
bool or None
text
object
transform
Transform
transform_rotates_text
bool
url
str
usetex
bool or None
verticalalignment or va
{'center', 'top', 'bottom', 'baseline', 'center_baseline'}
visible
bool
wrap
bool
x
float
y
float
zorder
float
Set the artist transform.
The cell edges to be drawn with a line.
Reading this property returns a substring of 'BRTL' (bottom, right, top, left').
When setting this property, you can use a substring of 'BRTL' or one of {'open', 'closed', 'horizontal', 'vertical'}.


Shrink font size until the text fits into the cell width.


Draw the Artist (and its children) using the given renderer.
This has no effect if the artist is not visible (Artist.get_visible returns False).
This method is overridden in the Artist subclasses.


Return the minimal required width for the cell.


Return the text bounds as (x, y, width, height) in table coordinates.


Set multiple properties at once.
Supported properties are
Property
Description
agg_filter
a filter function, which takes a (m, n, 3) float array and a dpi value, and returns a (m, n, 3) array
alpha
scalar or None
angle
unknown
animated
bool
antialiased or aa
bool or None
bounds
(left, bottom, width, height)
capstyle
CapStyle or {'butt', 'projecting', 'round'}
clip_box
Bbox
clip_on
bool
clip_path
Patch or (Path, Transform) or None
color
color
edgecolor or ec
color or None
facecolor or fc
color or None
figure
unknown
fill
bool
fontsize
unknown
gid
str
hatch
{'/', '\', '|', '-', '+', 'x', 'o', 'O', '.', '*'}
height
unknown
in_layout
bool
joinstyle
JoinStyle or {'miter', 'round', 'bevel'}
label
object
linestyle or ls
{'-', '--', '-.', ':', '', (offset, on-off-seq), ...}
linewidth or lw
float or None
path_effects
AbstractPathEffect
picker
None or bool or float or callable
rasterized
bool
sketch_params
(scale: float, length: float, randomness: float)
snap
bool or None
text_props
unknown
transform
unknown
url
str
visible
bool
width
unknown
x
unknown
xy
(float, float)
y
unknown
zorder
float


Set the Figure instance the artist belongs to.


Update the text properties.
Valid keyword arguments are:
Property
Description
agg_filter
a filter function, which takes a (m, n, 3) float array and a dpi value, and returns a (m, n, 3) array
alpha
scalar or None
animated
bool
backgroundcolor
color
bbox
dict with properties for patches.FancyBboxPatch
clip_box
unknown
clip_on
unknown
clip_path
unknown
color or c
color
figure
Figure
fontfamily or family
{FONTNAME, 'serif', 'sans-serif', 'cursive', 'fantasy', 'monospace'}
fontproperties or font or font_properties
font_manager.FontProperties or str or pathlib.Path
fontsize or size
float or {'xx-small', 'x-small', 'small', 'medium', 'large', 'x-large', 'xx-large'}
fontstretch or stretch
{a numeric value in range 0-1000, 'ultra-condensed', 'extra-condensed', 'condensed', 'semi-condensed', 'normal', 'semi-expanded', 'expanded', 'extra-expanded', 'ultra-expanded'}
fontstyle or style
{'normal', 'italic', 'oblique'}
fontvariant or variant
{'normal', 'small-caps'}
fontweight or weight
{a numeric value in range 0-1000, 'ultralight', 'light', 'normal', 'regular', 'book', 'medium', 'roman', 'semibold', 'demibold', 'demi', 'bold', 'heavy', 'extra bold', 'black'}
gid
str
horizontalalignment or ha
{'center', 'right', 'left'}
in_layout
bool
label
object
linespacing
float (multiple of font size)
math_fontfamily
str
multialignment or ma
{'left', 'right', 'center'}
parse_math
bool
path_effects
AbstractPathEffect
picker
None or bool or float or callable
position
(float, float)
rasterized
bool
rotation
float or {'vertical', 'horizontal'}
rotation_mode
{None, 'default', 'anchor'}
sketch_params
(scale: float, length: float, randomness: float)
snap
bool or None
text
object
transform
Transform
transform_rotates_text
bool
url
str
usetex
bool or None
verticalalignment or va
{'center', 'top', 'bottom', 'baseline', 'center_baseline'}
visible
bool
wrap
bool
x
float
y
float
zorder
float


Bases: matplotlib.artist.Artist
A table of cells.
The table consists of a grid of cells, which are indexed by (row, column).
For a simple table, you'll have a full grid of cells with indices from (0, 0) to (num_rows-1, num_cols-1), in which the cell (0, 0) is positioned at the top left. However, you can also add cells with negative indices. You don't have to add a cell to every grid position, so you can create tables that have holes.
Note: You'll usually not create an empty table from scratch. Instead use table to create a table from data.
The Axes to plot the table into.
The position of the cell with respect to ax. This must be one of the codes.
A bounding box to draw the table into. If this is not None, this overrides loc.
Artist properties.
The border between the Axes and the table edge in Axes units.
Create a cell and add it to the table.
Row index.
Column index.
All other parameters are passed on to Cell.
The created cell.
Automatically set the widths of given columns to optimal sizes.
The indices of the columns to auto-scale.
Automatically set font size.
Possible values where to place the table relative to the Axes.
Test whether the artist contains the mouse event.
Whether any values are within the radius.
An artist-specific dictionary of details of the event context, such as which points are contained in the pick radius. See the individual Artist subclasses for details.
Draw the Artist (and its children) using the given renderer.
This has no effect if the artist is not visible (Artist.get_visible returns False).
This method is overridden in the Artist subclasses.
The default value of visible_edges for newly added cells using add_cell.
This setting does currently only affect newly created cells using add_cell.
To change existing cells, you have to set their edges explicitly:
Return a dict of cells in the table mapping (row, column) to Cells.
You can also directly index into the Table object to access individual cells:
Return the Artists contained by the table.
Get the artist's bounding box in display space.
The bounding box' width and height are nonnegative.
Subclasses should override for inclusion in the bounding box "tight" calculation. Default is to return an empty bounding box at 0, 0.
Be careful when using this function, the results will not update if the artist window extent of the artist changes. The extent can change due to any changes in the transform stack, such as changing the axes limits, the figure size, or the canvas used (as is done when saving a figure). This can lead to unexpected behavior where interactive figures will look fine on the screen, but will save incorrectly.
Scale column widths by xscale and row heights by yscale.
Set multiple properties at once.
Supported properties are
Property
Description
agg_filter
a filter function, which takes a (m, n, 3) float array and a dpi value, and returns a (m, n, 3) array
alpha
scalar or None
animated
bool
clip_box
Bbox
clip_on
bool
clip_path
Patch or (Path, Transform) or None
figure
Figure
fontsize
float
gid
str
in_layout
bool
label
object
path_effects
AbstractPathEffect
picker
None or bool or float or callable
rasterized
bool
sketch_params
(scale: float, length: float, randomness: float)
snap
bool or None
transform
Transform
url
str
visible
bool
zorder
float
Set the font size, in points, of the cell text.
As long as auto font size has not been disabled, the value will be clipped such that the text fits horizontally into the cell.
You can disable this behavior using auto_set_font_size.
However, there is no automatic scaling of the row height so that the text may exceed the cell boundary.


Add a table to an Axes.
At least one of cellText or cellColours must be specified. These parameters must be 2D lists, in which the outer lists define the rows and the inner list define the column values per row. Each row must have the same number of elements.
The table can optionally have row and column headers, which are configured using rowLabels, rowColours, rowLoc and colLabels, colColours, colLoc respectively.
For finer grained control over tables, use the Table class and add it to the axes with Axes.add_table.
The texts to place into the table cells.
Note: Line breaks in the strings are currently not accounted for and will result in the text exceeding the cell boundaries.
The background colors of the cells.
The alignment of the text within the cells.
The column widths in units of the axes. If not given, all columns will have a width of 1 / ncols.
The text of the row header cells.
The colors of the row header cells.
The text alignment of the row header cells.
The text of the column header cells.
The colors of the column header cells.
The text alignment of the column header cells.
The position of the cell with respect to ax. This must be one of the codes.
A bounding box to draw the table into. If this is not None, this overrides loc.
The cell edges to be drawn with a line. See also visible_edges.
The created table.
Table properties.
Property
Description
agg_filter
a filter function, which takes a (m, n, 3) float array and a dpi value, and returns a (m, n, 3) array
alpha
scalar or None
animated
bool
clip_box
Bbox
clip_on
bool
clip_path
Patch or (Path, Transform) or None
figure
Figure
fontsize
float
gid
str
in_layout
bool
label
object
path_effects
AbstractPathEffect
picker
None or bool or float or callable
rasterized
bool
sketch_params
(scale: float, length: float, randomness: float)
snap
bool or None
transform
Transform
url
str
visible
bool
zorder
float


Create a cell and add it to the table.
Row index.
Column index.
All other parameters are passed on to Cell.
The created cell.


Automatically set the widths of given columns to optimal sizes.
The indices of the columns to auto-scale.


The border between the Axes and the table edge in Axes units.


Possible values where to place the table relative to the Axes.


Test whether the artist contains the mouse event.
Whether any values are within the radius.
An artist-specific dictionary of details of the event context, such as which points are contained in the pick radius. See the individual Artist subclasses for details.


Return a dict of cells in the table mapping (row, column) to Cells.
You can also directly index into the Table object to access individual cells:


Return the Artists contained by the table.


Get the artist's bounding box in display space.
The bounding box' width and height are nonnegative.
Subclasses should override for inclusion in the bounding box "tight" calculation. Default is to return an empty bounding box at 0, 0.
Be careful when using this function, the results will not update if the artist window extent of the artist changes. The extent can change due to any changes in the transform stack, such as changing the axes limits, the figure size, or the canvas used (as is done when saving a figure). This can lead to unexpected behavior where interactive figures will look fine on the screen, but will save incorrectly.


Scale column widths by xscale and row heights by yscale.


Set multiple properties at once.
Supported properties are
Property
Description
agg_filter
a filter function, which takes a (m, n, 3) float array and a dpi value, and returns a (m, n, 3) array
alpha
scalar or None
animated
bool
clip_box
Bbox
clip_on
bool
clip_path
Patch or (Path, Transform) or None
figure
Figure
fontsize
float
gid
str
in_layout
bool
label
object
path_effects
AbstractPathEffect
picker
None or bool or float or callable
rasterized
bool
sketch_params
(scale: float, length: float, randomness: float)
snap
bool or None
transform
Transform
url
str
visible
bool
zorder
float


Set the font size, in points, of the cell text.
As long as auto font size has not been disabled, the value will be clipped such that the text fits horizontally into the cell.
You can disable this behavior using auto_set_font_size.
However, there is no automatic scaling of the row height so that the text may exceed the cell boundary.


[Deprecated] Run the matplotlib test suite.
Deprecated since version 3.5.


[Deprecated] Run the matplotlib test suite.
Deprecated since version 3.5.
Helper functions for testing.
Utilities for comparing image results.
Calculate the per-pixel errors, then compute the root mean square error.
Return the list of file formats that compare_images can compare on this system.
E.g. ['png', 'pdf', 'svg', 'eps'].
Compare two "image" files checking differences within a tolerance.
The two given filenames may point to files which are convertible to PNG via the converter dictionary. The underlying RMS is calculated with the calculate_rms function.
The filename of the expected image.
The filename of the actual image.
The tolerance (a color value difference, where 255 is the maximal difference). The test fails if the average pixel difference is greater than this value.
Determines the output format. If called from image_comparison decorator, this should be True. (default=False)
Return None if the images are equal within the given tolerance.
If the images differ, the return value depends on in_decorator. If in_decorator is true, a dict with the following entries is returned:
Otherwise, a human-readable multi-line string representation of this information is returned.
Bases: unittest.case.TestCase
A wrapper for unittest.TestCase that includes cleanup operations.
Create an instance of the class that will use the named test method when executed. Raises a ValueError if the instance does not have a method with the specified name.
Hook method for setting up class fixture before running tests in the class.
Hook method for deconstructing the class fixture after running all tests in the class.
Decorator for test cases that generate and compare two figures.
The decorated function must take two keyword arguments, fig_test and fig_ref, and draw the test and reference images on them. After the function returns, the figures are saved and compared.
This decorator should be preferred over image_comparison when possible in order to keep the size of the test suite from ballooning.
The extensions to test.
The RMS threshold above which the test is considered failed.
If any new figures are created (and not subsequently closed) inside the test function.
Check that calling Axes.plot with a single argument plots it against [0, 1, 2, ...]:
A decorator to ensure that any global state is reset before running a test.
The style(s) to apply. Defaults to ["classic",
"_classic_test_patch"].
Compare images generated by the test with those specified in baseline_images, which must correspond, else an ImageComparisonFailure exception will be raised.
A list of strings specifying the names of the images generated by calls to Figure.savefig.
If None, the test function must use the baseline_images fixture, either as a parameter or with pytest.mark.usefixtures. This value is only allowed when using pytest.
The list of extensions to test, e.g. ['png', 'pdf'].
If None, defaults to all supported extensions: png, pdf, and svg.
When testing a single extension, it can be directly included in the names passed to baseline_images. In that case, extensions must not be set.
In order to keep the size of the test suite from ballooning, we only include the svg or pdf outputs if the test is explicitly exercising a feature dependent on that backend (see also the check_figures_equal decorator for that purpose).
The RMS threshold above which the test is considered failed.
Due to expected small differences in floating-point calculations, on 32-bit systems an additional 0.06 is added to this threshold.
The expected freetype version or range of versions for this test to pass.
Remove the title and tick text from the figure before comparison. This is useful to make the baseline images independent of variations in text rendering between different versions of FreeType.
This does not remove other, more deliberate, text, such as legends and annotations.
Optional arguments that are passed to the savefig method.
The optional style(s) to apply to the image test. The test itself can also apply additional styles if desired. Defaults to ["classic",
"_classic_test_patch"].
Bases: AssertionError
Raise this exception to mark a test as a comparison between two images.


Calculate the per-pixel errors, then compute the root mean square error.


Return the list of file formats that compare_images can compare on this system.
E.g. ['png', 'pdf', 'svg', 'eps'].


Compare two "image" files checking differences within a tolerance.
The two given filenames may point to files which are convertible to PNG via the converter dictionary. The underlying RMS is calculated with the calculate_rms function.
The filename of the expected image.
The filename of the actual image.
The tolerance (a color value difference, where 255 is the maximal difference). The test fails if the average pixel difference is greater than this value.
Determines the output format. If called from image_comparison decorator, this should be True. (default=False)
Return None if the images are equal within the given tolerance.
If the images differ, the return value depends on in_decorator. If in_decorator is true, a dict with the following entries is returned:
Otherwise, a human-readable multi-line string representation of this information is returned.


Decorator for test cases that generate and compare two figures.
The decorated function must take two keyword arguments, fig_test and fig_ref, and draw the test and reference images on them. After the function returns, the figures are saved and compared.
This decorator should be preferred over image_comparison when possible in order to keep the size of the test suite from ballooning.
The extensions to test.
The RMS threshold above which the test is considered failed.
If any new figures are created (and not subsequently closed) inside the test function.
Check that calling Axes.plot with a single argument plots it against [0, 1, 2, ...]:


A decorator to ensure that any global state is reset before running a test.
The style(s) to apply. Defaults to ["classic",
"_classic_test_patch"].


Bases: unittest.case.TestCase
A wrapper for unittest.TestCase that includes cleanup operations.
Create an instance of the class that will use the named test method when executed. Raises a ValueError if the instance does not have a method with the specified name.
Hook method for setting up class fixture before running tests in the class.
Hook method for deconstructing the class fixture after running all tests in the class.


Hook method for setting up class fixture before running tests in the class.


Hook method for deconstructing the class fixture after running all tests in the class.


Compare images generated by the test with those specified in baseline_images, which must correspond, else an ImageComparisonFailure exception will be raised.
A list of strings specifying the names of the images generated by calls to Figure.savefig.
If None, the test function must use the baseline_images fixture, either as a parameter or with pytest.mark.usefixtures. This value is only allowed when using pytest.
The list of extensions to test, e.g. ['png', 'pdf'].
If None, defaults to all supported extensions: png, pdf, and svg.
When testing a single extension, it can be directly included in the names passed to baseline_images. In that case, extensions must not be set.
In order to keep the size of the test suite from ballooning, we only include the svg or pdf outputs if the test is explicitly exercising a feature dependent on that backend (see also the check_figures_equal decorator for that purpose).
The RMS threshold above which the test is considered failed.
Due to expected small differences in floating-point calculations, on 32-bit systems an additional 0.06 is added to this threshold.
The expected freetype version or range of versions for this test to pass.
Remove the title and tick text from the figure before comparison. This is useful to make the baseline images independent of variations in text rendering between different versions of FreeType.
This does not remove other, more deliberate, text, such as legends and annotations.
Optional arguments that are passed to the savefig method.
The optional style(s) to apply to the image test. The test itself can also apply additional styles if desired. Defaults to ["classic",
"_classic_test_patch"].


Bases: AssertionError
Raise this exception to mark a test as a comparison between two images.


Support for embedded TeX expressions in Matplotlib.
Requirements:
To enable TeX rendering of all text in your Matplotlib figure, set rcParams["text.usetex"] (default: False) to True.
TeX and dvipng/dvips processing results are cached in ~/.matplotlib/tex.cache for reuse between sessions.
TexManager.get_rgba can also be used to directly obtain raster output as RGBA NumPy arrays.
Bases: object
Convert strings to dvi files using TeX, caching the results to a directory.
Repeated calls to this constructor always return the same instance.
Return a filename based on a hash of the string, fontsize, and dpi.
Return a string containing user additions to the tex preamble.
Return a string containing font configuration for the tex preamble.
Return the alpha channel.
Return latex's rendering of the tex string as an rgba array.
Return width, height and descent of the text.
Generate a dvi file containing latex's layout of tex string.
Return the file name.
Generate a png file containing latex's rendering of tex string.
Return the file name.
Generate a tex file to render the tex string at a specific font size.
Return the file name.


Bases: object
Convert strings to dvi files using TeX, caching the results to a directory.
Repeated calls to this constructor always return the same instance.
Return a filename based on a hash of the string, fontsize, and dpi.
Return a string containing user additions to the tex preamble.
Return a string containing font configuration for the tex preamble.
Return the alpha channel.
Return latex's rendering of the tex string as an rgba array.
Return width, height and descent of the text.
Generate a dvi file containing latex's layout of tex string.
Return the file name.
Generate a png file containing latex's rendering of tex string.
Return the file name.
Generate a tex file to render the tex string at a specific font size.
Return the file name.


Return a filename based on a hash of the string, fontsize, and dpi.


Return a string containing user additions to the tex preamble.


Return a string containing font configuration for the tex preamble.


Return latex's rendering of the tex string as an rgba array.


Return width, height and descent of the text.


Generate a dvi file containing latex's layout of tex string.
Return the file name.


Generate a png file containing latex's rendering of tex string.
Return the file name.


Generate a tex file to render the tex string at a specific font size.
Return the file name.