matplotlib.scale

标度定义了轴上数据值的分布，例如对数标度。

映射通过 Transform 子类实现。

以下标度是内置的

名称	类	变换	反向变换
"asinh"	AsinhScale	AsinhTransform	InvertedAsinhTransform
"function"	FuncScale	FuncTransform	FuncTransform
"functionlog"	FuncScaleLog	FuncTransform + LogTransform	InvertedLogTransform + FuncTransform
"linear"	LinearScale	IdentityTransform	IdentityTransform
"log"	LogScale	LogTransform	InvertedLogTransform
"logit"	LogitScale	LogitTransform	LogisticTransform
"symlog"	SymmetricalLogScale	SymmetricalLogTransform	InvertedSymmetricalLogTransform

用户通常只使用标度名称，例如通过 set_xscale 设置标度时： ax.set_xscale("log")。

另请参阅文档中的 标度示例。

可以通过 FuncScale，或通过创建您自己的 ScaleBase 子类和相应的变换来实现自定义标度（参见自定义标度）。第三方可以通过 register_scale 按名称注册他们的标度。

class matplotlib.scale.ScaleBase(axis)

基类: object

所有标度的基类。

标度是可分离的变换，作用于单个维度。

子类应覆盖

name

该标度的名称。

get_transform()

返回一个 Transform 的方法，该变换将数据坐标转换为标度坐标。此变换应可逆，以便例如鼠标位置可以转换回数据坐标。

set_default_locators_and_formatters()

为使用此标度的 Axis 设置默认定位器和格式器的方法。

limit_range_for_scale()

一个可选方法，将轴范围“固定”到可接受的值，例如将对数标度轴限制为正值。

构造一个新的标度。

备注

以下注释适用于标度实现者。

出于向后兼容性原因，标度将 Axis 对象作为第一个参数。然而，不应使用此参数：单个标度对象应可被多个 Axis 同时使用。

get_transform()

返回与此标度关联的 Transform 对象。

set_default_locators_and_formatters(axis)

将 axis 的定位器和格式器设置为适合此标度的实例。

limit_range_for_scale(vmin, vmax, minpos)

返回范围 vmin、vmax，（如果存在）受此标度支持的域限制。

minpos 应该是数据中的最小正值。对数标度使用此值来确定最小值。

class matplotlib.scale.LinearScale(axis)

基类： ScaleBase

默认的线性标度。

name = 'linear'

set_default_locators_and_formatters(axis)

将 axis 的定位器和格式器设置为适合此标度的实例。

get_transform()

返回线性标度的变换，即 IdentityTransform。

class matplotlib.scale.FuncTransform(forward, inverse)

基类： Transform

一个简单的变换，它接受用于正向和反向变换的任意函数。

参数:

forward可调用对象

变换的正向函数。此函数必须具有逆函数，并且为了获得最佳行为，必须是单调的。它必须具有以下签名：

def forward(values: array-like) -> array-like

inverse可调用对象

正向函数的逆函数。签名与 forward 相同。

input_dims = 1

此变换的输入维度数量。必须在子类中重写（使用整数）。

output_dims = 1

此变换的输出维度数量。必须在子类中重写（使用整数）。

transform_non_affine(values)

仅应用此变换的非仿射部分。

transform(values) 始终等价于 transform_affine(transform_non_affine(values))。

在非仿射变换中，这通常等价于 transform(values)。在仿射变换中，这始终是一个空操作。

参数:

values数组

输入值，为长度为 input_dims 或形状为 (N, input_dims) 的数组。

返回:

array

输出值，为长度为 output_dims 或形状为 (N, output_dims) 的数组，具体取决于输入。

inverted()

返回相应的逆变换。

它满足 x == self.inverted().transform(self.transform(x))。

此方法的返回值应被视为临时值。对 self 的更新不会导致其逆副本的相应更新。

has_inverse = True

如果此变换具有相应的逆变换，则为 True。

is_separable = True

如果此变换在 x 轴和 y 轴维度上是可分离的，则为 True。

class matplotlib.scale.FuncScale(axis, functions)

基类： ScaleBase

为轴提供具有用户提供函数的任意标度。

参数:

axisAxis

标度所作用的轴。

functions(可调用对象, 可调用对象)

标度的正向和反向函数的二元组。正向函数必须是单调的。

两个函数都必须具有以下签名：

def forward(values: array-like) -> array-like

name = 'function'

get_transform()

返回与此标度关联的 FuncTransform 对象。

set_default_locators_and_formatters(axis)

将 axis 的定位器和格式器设置为适合此标度的实例。

class matplotlib.scale.LogTransform(base, nonpositive='clip')

基类： Transform

参数:

shorthand_namestr

表示变换“名称”的字符串。除了提高在 DEBUG=True 时 str(transform) 的可读性之外，此名称没有其他意义。

input_dims = 1

此变换的输入维度数量。必须在子类中重写（使用整数）。

output_dims = 1

此变换的输出维度数量。必须在子类中重写（使用整数）。

transform_non_affine(values)

仅应用此变换的非仿射部分。

transform(values) 始终等价于 transform_affine(transform_non_affine(values))。

在非仿射变换中，这通常等价于 transform(values)。在仿射变换中，这始终是一个空操作。

参数:

values数组

输入值，为长度为 input_dims 或形状为 (N, input_dims) 的数组。

返回:

array

输出值，为长度为 output_dims 或形状为 (N, output_dims) 的数组，具体取决于输入。

inverted()

返回相应的逆变换。

它满足 x == self.inverted().transform(self.transform(x))。

此方法的返回值应被视为临时值。对 self 的更新不会导致其逆副本的相应更新。

has_inverse = True

如果此变换具有相应的逆变换，则为 True。

is_separable = True

如果此变换在 x 轴和 y 轴维度上是可分离的，则为 True。

class matplotlib.scale.InvertedLogTransform(base)

基类： Transform

参数:

shorthand_namestr

表示变换“名称”的字符串。除了提高在 DEBUG=True 时 str(transform) 的可读性之外，此名称没有其他意义。

input_dims = 1

此变换的输入维度数量。必须在子类中重写（使用整数）。

output_dims = 1

此变换的输出维度数量。必须在子类中重写（使用整数）。

transform_non_affine(values)

仅应用此变换的非仿射部分。

transform(values) 始终等价于 transform_affine(transform_non_affine(values))。

在非仿射变换中，这通常等价于 transform(values)。在仿射变换中，这始终是一个空操作。

参数:

values数组

输入值，为长度为 input_dims 或形状为 (N, input_dims) 的数组。

返回:

array

输出值，为长度为 output_dims 或形状为 (N, output_dims) 的数组，具体取决于输入。

inverted()

返回相应的逆变换。

它满足 x == self.inverted().transform(self.transform(x))。

此方法的返回值应被视为临时值。对 self 的更新不会导致其逆副本的相应更新。

has_inverse = True

如果此变换具有相应的逆变换，则为 True。

is_separable = True

如果此变换在 x 轴和 y 轴维度上是可分离的，则为 True。

class matplotlib.scale.LogScale(axis, *, base=10, subs=None, nonpositive='clip')

基类： ScaleBase

一个标准的对数标度。注意只绘制正值。

参数:

axisAxis

标度所作用的轴。

base浮点型，默认值: 10

对数的基数。

nonpositive{'clip', 'mask'}, 默认值: 'clip'

确定非正值的行为。它们可以被遮罩为无效，或者裁剪为非常小的正数。

subs整数序列, 默认值: None

在每个主刻度线之间放置副刻度线的位置。例如，在 log10 标度中， [2, 3, 4, 5, 6, 7, 8, 9] 将在每个主刻度线之间放置 8 个对数间隔的次刻度线。

name = 'log'

property base

set_default_locators_and_formatters(axis)

将 axis 的定位器和格式器设置为适合此标度的实例。

get_transform()

返回与此标度关联的 LogTransform 对象。

limit_range_for_scale(vmin, vmax, minpos)

将域限制为正值。

class matplotlib.scale.FuncScaleLog(axis, functions, base=10)

基类： LogScale

为轴提供具有用户提供函数的任意标度，然后将其置于对数轴上。

参数:

axisAxis

标度所作用的轴。

functions(可调用对象, 可调用对象)

标度的正向和反向函数的二元组。正向函数必须是单调的。

两个函数都必须具有以下签名：

def forward(values: array-like) -> array-like

base浮点型，默认值: 10

标度的对数基数。

name = 'functionlog'

property base

get_transform()

返回与此标度关联的 Transform 对象。

class matplotlib.scale.SymmetricalLogTransform(base, linthresh, linscale)

基类： Transform

参数:

shorthand_namestr

表示变换“名称”的字符串。除了提高在 DEBUG=True 时 str(transform) 的可读性之外，此名称没有其他意义。

input_dims = 1

此变换的输入维度数量。必须在子类中重写（使用整数）。

output_dims = 1

此变换的输出维度数量。必须在子类中重写（使用整数）。

transform_non_affine(values)

仅应用此变换的非仿射部分。

transform(values) 始终等价于 transform_affine(transform_non_affine(values))。

在非仿射变换中，这通常等价于 transform(values)。在仿射变换中，这始终是一个空操作。

参数:

values数组

输入值，作为一个长度为 input_dims 的数组或形状为 (N, input_dims) 的数组。

返回:

array

输出值，作为一个长度为 output_dims 的数组或形状为 (N, output_dims) 的数组，具体取决于输入。

inverted()

返回相应的逆变换。

它满足 x == self.inverted().transform(self.transform(x))。

此方法的返回值应被视为临时值。对 self 的更新不会导致其逆副本的相应更新。

has_inverse = True

如果此变换具有相应的逆变换，则为 True。

is_separable = True

如果此变换在 x 轴和 y 轴维度上是可分离的，则为 True。

class matplotlib.scale.InvertedSymmetricalLogTransform(base, linthresh, linscale)

基类： Transform

参数:

shorthand_namestr

表示变换“名称”的字符串。除了提高在 DEBUG=True 时 str(transform) 的可读性之外，此名称没有其他意义。

input_dims = 1

此变换的输入维度数量。必须在子类中重写（使用整数）。

output_dims = 1

此变换的输出维度数量。必须在子类中重写（使用整数）。

transform_non_affine(values)

仅应用此变换的非仿射部分。

transform(values) 始终等价于 transform_affine(transform_non_affine(values))。

在非仿射变换中，这通常等价于 transform(values)。在仿射变换中，这始终是一个空操作。

参数:

values数组

输入值，作为一个长度为 input_dims 的数组或形状为 (N, input_dims) 的数组。

返回:

array

输出值，作为一个长度为 output_dims 的数组或形状为 (N, output_dims) 的数组，具体取决于输入。

inverted()

返回相应的逆变换。

它满足 x == self.inverted().transform(self.transform(x))。

此方法的返回值应被视为临时值。对 self 的更新不会导致其逆副本的相应更新。

has_inverse = True

如果此变换具有相应的逆变换，则为 True。

is_separable = True

如果此变换在 x 轴和 y 轴维度上是可分离的，则为 True。

class matplotlib.scale.SymmetricalLogScale(axis, *, base=10, linthresh=2, subs=None, linscale=1)

基类： ScaleBase

对称对数刻度在原点的正负方向上都是对数的。

由于接近零的值趋向于无穷大，因此需要一个围绕零的线性范围。参数 linthresh 允许用户指定此范围的大小（-linthresh, linthresh）。

有关详细描述，请参阅Symlog 刻度。

参数:

base浮点型，默认值: 10

对数的基数。

linthresh浮点数，默认值：2

定义绘图呈线性的范围 (-x, x)。这避免了绘图在零点附近趋于无穷大。

subs整数序列

在每个主刻度之间放置副刻度的位置。例如，在 log10 刻度中：[2, 3, 4, 5, 6, 7, 8, 9] 将在每个主刻度之间放置 8 个对数间隔的副刻度。

linscale浮点数，可选

这允许线性范围 (-linthresh, linthresh) 相对于对数范围进行拉伸。其值是线性范围每一半要使用的对数十年数。例如，当 linscale == 1.0（默认值）时，线性范围的正半部分和负半部分所占用的空间将等于对数范围中的一个十年。

构造一个新的标度。

备注

以下注释适用于标度实现者。

出于向后兼容性原因，标度将 Axis 对象作为第一个参数。然而，不应使用此参数：单个标度对象应可被多个 Axis 同时使用。

name = 'symlog'

property base

property linthresh

property linscale

set_default_locators_and_formatters(axis)

将 axis 的定位器和格式器设置为适合此标度的实例。

get_transform()

返回与此刻度关联的 SymmetricalLogTransform。

class matplotlib.scale.AsinhTransform(linear_width)

基类： Transform

由 AsinhScale 使用的反双曲正弦变换

参数:

shorthand_namestr

表示变换“名称”的字符串。除了提高在 DEBUG=True 时 str(transform) 的可读性之外，此名称没有其他意义。

input_dims = 1

此变换的输入维度数量。必须在子类中重写（使用整数）。

output_dims = 1

此变换的输出维度数量。必须在子类中重写（使用整数）。

transform_non_affine(values)

仅应用此变换的非仿射部分。

transform(values) 始终等价于 transform_affine(transform_non_affine(values))。

在非仿射变换中，这通常等价于 transform(values)。在仿射变换中，这始终是一个空操作。

参数:

values数组

输入值，作为一个长度为 input_dims 的数组或形状为 (N, input_dims) 的数组。

返回:

array

输出值，作为一个长度为 output_dims 的数组或形状为 (N, output_dims) 的数组，具体取决于输入。

inverted()

返回相应的逆变换。

它满足 x == self.inverted().transform(self.transform(x))。

此方法的返回值应被视为临时值。对 self 的更新不会导致其逆副本的相应更新。

has_inverse = True

如果此变换具有相应的逆变换，则为 True。

is_separable = True

如果此变换在 x 轴和 y 轴维度上是可分离的，则为 True。

class matplotlib.scale.InvertedAsinhTransform(linear_width)

基类： Transform

由 AsinhScale 使用的双曲正弦变换

参数:

shorthand_namestr

表示变换“名称”的字符串。除了提高在 DEBUG=True 时 str(transform) 的可读性之外，此名称没有其他意义。

input_dims = 1

此变换的输入维度数量。必须在子类中重写（使用整数）。

output_dims = 1

此变换的输出维度数量。必须在子类中重写（使用整数）。

transform_non_affine(values)

仅应用此变换的非仿射部分。

transform(values) 始终等价于 transform_affine(transform_non_affine(values))。

在非仿射变换中，这通常等价于 transform(values)。在仿射变换中，这始终是一个空操作。

参数:

values数组

输入值，作为一个长度为 input_dims 的数组或形状为 (N, input_dims) 的数组。

返回:

array

输出值，作为一个长度为 output_dims 的数组或形状为 (N, output_dims) 的数组，具体取决于输入。

inverted()

返回相应的逆变换。

它满足 x == self.inverted().transform(self.transform(x))。

此方法的返回值应被视为临时值。对 self 的更新不会导致其逆副本的相应更新。

has_inverse = True

如果此变换具有相应的逆变换，则为 True。

is_separable = True

如果此变换在 x 轴和 y 轴维度上是可分离的，则为 True。

class matplotlib.scale.AsinhScale(axis, *, linear_width=1.0, base=10, subs='auto', **kwargs)

基类： ScaleBase

基于反双曲正弦（asinh）的准对数刻度

对于接近零的值，这本质上是一个线性刻度；但对于大绝对值（正或负），它渐近地呈对数关系。线性与对数区域之间的过渡是平滑的，与 SymmetricalLogScale（“symlog”）刻度相比，函数梯度没有不连续性。

具体来说，轴坐标 \(a\) 的变换为 \(a \rightarrow a_0 \sinh^{-1} (a / a_0)\)，其中 \(a_0\) 是变换线性区域的有效宽度。在该区域中，变换为 \(a \rightarrow a + \mathcal{O}(a^3)\)。对于较大的 \(a\) 值，变换表现为 \(a \rightarrow a_0 \, \mathrm{sgn}(a) \ln |a| + \mathcal{O}(1)\)。

注意

此API是临时的，未来可能会根据早期用户反馈进行修订。

参数:

linear_width浮点数，默认值：1

刻度参数（在其他地方也称为 \(a_0\)），定义了准线性区域的范围，以及变换渐近变为对数关系的坐标值。

base整数，默认值：10

用于对数刻度上刻度位置进行舍入的底数。如果小于 1，则舍入到最接近的 10 的幂的整数倍。

subs整数序列

用于次刻度的底数的倍数。如果设置为 'auto'，将使用内置默认值，例如 base=10 时为 (2, 5)。

name = 'asinh'

auto_tick_multipliers = {3: (2,), 4: (2,), 5: (2,), 8: (2, 4), 10: (2, 5), 16: (2, 4, 8), 64: (4, 16), 1024: (256, 512)}

property linear_width

get_transform()

返回与此标度关联的 Transform 对象。

set_default_locators_and_formatters(axis)

将 axis 的定位器和格式器设置为适合此标度的实例。

class matplotlib.scale.LogitTransform(nonpositive='mask')

基类： Transform

参数:

shorthand_namestr

表示变换“名称”的字符串。除了提高在 DEBUG=True 时 str(transform) 的可读性之外，此名称没有其他意义。

input_dims = 1

此变换的输入维度数量。必须在子类中重写（使用整数）。

output_dims = 1

此变换的输出维度数量。必须在子类中重写（使用整数）。

transform_non_affine(values)

logit 变换（以 10 为底），已遮罩或裁剪

inverted()

返回相应的逆变换。

它满足 x == self.inverted().transform(self.transform(x))。

此方法的返回值应被视为临时值。对 self 的更新不会导致其逆副本的相应更新。

has_inverse = True

如果此变换具有相应的逆变换，则为 True。

is_separable = True

如果此变换在 x 轴和 y 轴维度上是可分离的，则为 True。

class matplotlib.scale.LogisticTransform(nonpositive='mask')

基类： Transform

参数:

shorthand_namestr

表示变换“名称”的字符串。除了提高在 DEBUG=True 时 str(transform) 的可读性之外，此名称没有其他意义。

input_dims = 1

此变换的输入维度数量。必须在子类中重写（使用整数）。

output_dims = 1

此变换的输出维度数量。必须在子类中重写（使用整数）。

transform_non_affine(values)

logistic 变换（以 10 为底）

inverted()

返回相应的逆变换。

它满足 x == self.inverted().transform(self.transform(x))。

此方法的返回值应被视为临时值。对 self 的更新不会导致其逆副本的相应更新。

has_inverse = True

如果此变换具有相应的逆变换，则为 True。

is_separable = True

如果此变换在 x 轴和 y 轴维度上是可分离的，则为 True。

class matplotlib.scale.LogitScale(axis, nonpositive='mask', *, one_half='\\frac{1}{2}', use_overline=False)

基类： ScaleBase

用于零和一之间（不包括零和一）数据的 Logit 刻度。

此刻度在接近零和一时类似于对数刻度，在 0.5 附近几乎是线性的。它将区间 ]0, 1[ 映射到 ]-∞, +∞[。

参数:

axisAxis

目前未使用。

nonpositive{'mask', 'clip'}

决定超出开区间 ]0, 1[ 的值的行为。它们可以被遮罩为无效，或裁剪到非常接近 0 或 1 的值。

use_overline布尔值，默认值：False

指示在概率接近 1 时，使用生存符号（overline{x}）代替标准符号（1-x）。

one_half字符串，默认值：r"frac{1}{2}"

用于刻度格式化程序以表示 1/2 的字符串。

name = 'logit'

get_transform()

返回与此刻度关联的 LogitTransform。

set_default_locators_and_formatters(axis)

将 axis 的定位器和格式器设置为适合此标度的实例。

limit_range_for_scale(vmin, vmax, minpos)

将域限制在 0 到 1 之间（不包括 0 和 1）的值。

matplotlib.scale.get_scale_names()

返回可用刻度的名称。

matplotlib.scale.scale_factory(scale, axis, **kwargs)

按名称返回一个刻度类。

参数:

scale{'asinh', 'function', 'functionlog', 'linear', 'log', 'logit', 'symlog'}

axisAxis

matplotlib.scale.register_scale(scale_class)

注册一种新的刻度。

参数:

scale_classScaleBase 的子类

要注册的刻度。