matplotlib.scale
¶
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
.
- class matplotlib.scale.FuncScale(axis, functions)[source]¶
Bases:
matplotlib.scale.ScaleBase
Provide an arbitrary scale with user-supplied function for the axis.
- Parameters
- axis
Axis
The axis for the scale.
- functions(callable, callable)
two-tuple of the forward and inverse functions for the scale. The forward function must be monotonic.
Both functions must have the signature:
def forward(values: array-like) -> array-like
- axis
- get_transform()[source]¶
Return the
FuncTransform
associated with this scale.
- name = 'function'¶
- class matplotlib.scale.FuncScaleLog(axis, functions, base=10)[source]¶
Bases:
matplotlib.scale.LogScale
Provide an arbitrary scale with user-supplied function for the axis and then put on a logarithmic axes.
- Parameters
- axis
matplotlib.axis.Axis
The axis for the scale.
- functions(callable, callable)
two-tuple of the forward and inverse functions for the scale. The forward function must be monotonic.
Both functions must have the signature:
def forward(values: array-like) -> array-like
- basefloat, default: 10
Logarithmic base of the scale.
- axis
- property base¶
- name = 'functionlog'¶
- class matplotlib.scale.FuncTransform(forward, inverse)[source]¶
Bases:
matplotlib.transforms.Transform
A simple transform that takes and arbitrary function for the forward and inverse transform.
- Parameters
- forwardcallable
The forward function for the transform. This function must have an inverse and, for best behavior, be monotonic. It must have the signature:
def forward(values: array-like) -> array-like
- inversecallable
The inverse of the forward function. Signature as
forward
.
- has_inverse = True¶
True if this transform has a corresponding inverse transform.
- input_dims = 1¶
The number of input dimensions of this transform. Must be overridden (with integers) in the subclass.
- inverted()[source]¶
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.
- is_separable = True¶
True if this transform is separable in the x- and y- dimensions.
- output_dims = 1¶
The number of output dimensions of this transform. Must be overridden (with integers) in the subclass.
- transform_non_affine(values)[source]¶
Apply only the non-affine part of this transformation.
transform(values)
is always equivalent totransform_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.- Parameters
- valuesarray
The input values as NumPy array of length
input_dims
or shape (N xinput_dims
).
- Returns
- array
The output values as NumPy array of length
input_dims
or shape (N xoutput_dims
), depending on the input.
- class matplotlib.scale.InvertedLogTransform(base)[source]¶
Bases:
matplotlib.transforms.Transform
- Parameters
- shorthand_namestr
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.
- has_inverse = True¶
True if this transform has a corresponding inverse transform.
- input_dims = 1¶
The number of input dimensions of this transform. Must be overridden (with integers) in the subclass.
- inverted()[source]¶
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.
- is_separable = True¶
True if this transform is separable in the x- and y- dimensions.
- output_dims = 1¶
The number of output dimensions of this transform. Must be overridden (with integers) in the subclass.
- transform_non_affine(a)[source]¶
Apply only the non-affine part of this transformation.
transform(values)
is always equivalent totransform_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.- Parameters
- valuesarray
The input values as NumPy array of length
input_dims
or shape (N xinput_dims
).
- Returns
- array
The output values as NumPy array of length
input_dims
or shape (N xoutput_dims
), depending on the input.
- class matplotlib.scale.InvertedSymmetricalLogTransform(base, linthresh, linscale)[source]¶
Bases:
matplotlib.transforms.Transform
- Parameters
- shorthand_namestr
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.
- has_inverse = True¶
True if this transform has a corresponding inverse transform.
- input_dims = 1¶
The number of input dimensions of this transform. Must be overridden (with integers) in the subclass.
- inverted()[source]¶
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.
- is_separable = True¶
True if this transform is separable in the x- and y- dimensions.
- output_dims = 1¶
The number of output dimensions of this transform. Must be overridden (with integers) in the subclass.
- transform_non_affine(a)[source]¶
Apply only the non-affine part of this transformation.
transform(values)
is always equivalent totransform_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.- Parameters
- valuesarray
The input values as NumPy array of length
input_dims
or shape (N xinput_dims
).
- Returns
- array
The output values as NumPy array of length
input_dims
or shape (N xoutput_dims
), depending on the input.
- class matplotlib.scale.LinearScale(axis)[source]¶
Bases:
matplotlib.scale.ScaleBase
The default linear scale.
- get_transform()[source]¶
Return the transform for linear scaling, which is just the
IdentityTransform
.
- name = 'linear'¶
- class matplotlib.scale.LogScale(axis, *, base=10, subs=None, nonpositive='clip')[source]¶
Bases:
matplotlib.scale.ScaleBase
A standard logarithmic scale. Care is taken to only plot positive values.
- Parameters
- axis
Axis
The axis for the scale.
- basefloat, default: 10
The base of the logarithm.
- nonpositive{'clip', 'mask'}, default: 'clip'
Determines the behavior for non-positive values. They can either be masked as invalid, or clipped to a very small positive number.
- subssequence of int, default: None
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.
- axis
- property base¶
- get_transform()[source]¶
Return the
LogTransform
associated with this scale.
- name = 'log'¶
- class matplotlib.scale.LogTransform(base, nonpositive='clip')[source]¶
Bases:
matplotlib.transforms.Transform
- Parameters
- shorthand_namestr
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.
- has_inverse = True¶
True if this transform has a corresponding inverse transform.
- input_dims = 1¶
The number of input dimensions of this transform. Must be overridden (with integers) in the subclass.
- inverted()[source]¶
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.
- is_separable = True¶
True if this transform is separable in the x- and y- dimensions.
- output_dims = 1¶
The number of output dimensions of this transform. Must be overridden (with integers) in the subclass.
- transform_non_affine(a)[source]¶
Apply only the non-affine part of this transformation.
transform(values)
is always equivalent totransform_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.- Parameters
- valuesarray
The input values as NumPy array of length
input_dims
or shape (N xinput_dims
).
- Returns
- array
The output values as NumPy array of length
input_dims
or shape (N xoutput_dims
), depending on the input.
- class matplotlib.scale.LogisticTransform(nonpositive='mask')[source]¶
Bases:
matplotlib.transforms.Transform
- Parameters
- shorthand_namestr
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.
- has_inverse = True¶
True if this transform has a corresponding inverse transform.
- input_dims = 1¶
The number of input dimensions of this transform. Must be overridden (with integers) in the subclass.
- inverted()[source]¶
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.
- is_separable = True¶
True if this transform is separable in the x- and y- dimensions.
- output_dims = 1¶
The number of output dimensions of this transform. Must be overridden (with integers) in the subclass.
- class matplotlib.scale.LogitScale(axis, nonpositive='mask', *, one_half='\x0crac{1}{2}', use_overline=False)[source]¶
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[.
- Parameters
- axis
matplotlib.axis.Axis
Currently unused.
- nonpositive{'mask', 'clip'}
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.
- use_overlinebool, default: False
Indicate the usage of survival notation (overline{x}) in place of standard notation (1-x) for probability close to one.
- one_halfstr, default: r"frac{1}{2}"
The string used for ticks formatter to represent 1/2.
- axis
- get_transform()[source]¶
Return the
LogitTransform
associated with this scale.
- limit_range_for_scale(vmin, vmax, minpos)[source]¶
Limit the domain to values between 0 and 1 (excluded).
- name = 'logit'¶
- class matplotlib.scale.LogitTransform(nonpositive='mask')[source]¶
Bases:
matplotlib.transforms.Transform
- Parameters
- shorthand_namestr
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.
- has_inverse = True¶
True if this transform has a corresponding inverse transform.
- input_dims = 1¶
The number of input dimensions of this transform. Must be overridden (with integers) in the subclass.
- inverted()[source]¶
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.
- is_separable = True¶
True if this transform is separable in the x- and y- dimensions.
- output_dims = 1¶
The number of output dimensions of this transform. Must be overridden (with integers) in the subclass.
- class matplotlib.scale.ScaleBase(axis)[source]¶
Bases:
object
The base class for all scales.
Scales are separable transformations, working on a single dimension.
Subclasses should override
name
The scale's name.
get_transform()
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.set_default_locators_and_formatters()
A method that sets default locators and formatters for an
Axis
that uses this scale.limit_range_for_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.
Notes
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 multipleAxis
es at the same time.
- class matplotlib.scale.SymmetricalLogScale(axis, *, base=10, linthresh=2, subs=None, linscale=1)[source]¶
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).
- Parameters
- basefloat, default: 10
The base of the logarithm.
- linthreshfloat, default: 2
Defines the range
(-x, x)
, within which the plot is linear. This avoids having the plot go to infinity around zero.- subssequence of int
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.- linscalefloat, optional
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.
Notes
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 multipleAxis
es at the same time.- property base¶
- get_transform()[source]¶
Return the
SymmetricalLogTransform
associated with this scale.
- property linscale¶
- property linthresh¶
- name = 'symlog'¶
- class matplotlib.scale.SymmetricalLogTransform(base, linthresh, linscale)[source]¶
Bases:
matplotlib.transforms.Transform
- Parameters
- shorthand_namestr
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.
- has_inverse = True¶
True if this transform has a corresponding inverse transform.
- input_dims = 1¶
The number of input dimensions of this transform. Must be overridden (with integers) in the subclass.
- inverted()[source]¶
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.
- is_separable = True¶
True if this transform is separable in the x- and y- dimensions.
- output_dims = 1¶
The number of output dimensions of this transform. Must be overridden (with integers) in the subclass.
- transform_non_affine(a)[source]¶
Apply only the non-affine part of this transformation.
transform(values)
is always equivalent totransform_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.- Parameters
- valuesarray
The input values as NumPy array of length
input_dims
or shape (N xinput_dims
).
- Returns
- array
The output values as NumPy array of length
input_dims
or shape (N xoutput_dims
), depending on the input.
- matplotlib.scale.register_scale(scale_class)[source]¶
Register a new kind of scale.
- Parameters
- scale_classsubclass of
ScaleBase
The scale to register.
- scale_classsubclass of
- matplotlib.scale.scale_factory(scale, axis, **kwargs)[source]¶
Return a scale class by name.
- Parameters
- scale{'function', 'functionlog', 'linear', 'log', 'logit', 'symlog'}
- axis
matplotlib.axis.Axis