matplotlib.scale

比例尺（Scales）定义了轴上数据值的分布，例如对数缩放。

映射通过 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 对象作为第一个参数。

自 3.11 版本弃用：axis 参数现在是可选的，即 matplotlib 兼容不带 axis 参数的 ScaleBase 子类。

axis 参数正处于待弃用状态。它将在 matplotlib 3.13 中被弃用，并在 3.15 中被移除。

建议第三方比例尺现在就移除 axis 参数，如果它们能够将兼容性限制在 matplotlib >= 3.11 的话。否则，它们可以保留 axis 参数，并在 matplotlib 3.13 时移除。

get_transform()

返回与此比例尺关联的 Transform 对象。

set_default_locators_and_formatters(axis)

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

limit_range_for_scale(vmin, vmax, minpos)

返回限制在此比例尺支持的域（如果有）内的范围 vmin, vmax。

minpos 应为数据中的最小正值。这被对数比例尺用来确定最小值。

val_in_range(val)

返回该值（或多个值）是否在此比例尺的有效范围内。

接受标量或数组类型的 val。对于标量，返回 Python bool。对于数组，返回相同形状的布尔 ndarray。这是一个通用实现，子类可以为其域实现更高效的解决方案。

class matplotlib.scale.LinearScale(axis)

基类：ScaleBase

默认的线性比例尺。

name = 'linear'

set_default_locators_and_formatters(axis)

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

get_transform()

返回线性缩放的变换，即 IdentityTransform。

val_in_range(val)

返回该值（或多个值）是否在此比例尺的有效范围内。

除 +-inf 和 NaN 外，对所有值均为 True。

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

比例尺的轴。

注意

此参数未被使用，并将于近期版本中移除。由于有特殊的预处理，现在可以省略它，因此 FuncScale(functions) 是有效的。

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=None, *, base=10, subs=None, nonpositive='clip')

基类：ScaleBase

标准对数比例尺。注意仅绘制正值。

参数:

axisAxis

比例尺的轴。

注意

此参数未被使用，未来将被移除。由于有特殊的预处理，现在可以省略它，因此 LogScale(base=2) 是有效的。

base浮点型，默认值: 10

对数的底数。

nonpositive{'clip', 'mask'}, 默认：'clip'

确定对非正值的处理行为。它们可以被屏蔽为无效，或者被截断为极小的正数。

subsint 序列，默认：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)

将域限制为正值。

val_in_range(val)

返回该值（或多个值）是否在此比例尺的有效范围内。

对于 > 0 的值（除 +inf 和 NaN 外），此项为 True。

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

基类：LogScale

为轴提供一个带有用户提供的函数的任意比例尺，然后放置在对数轴上。

参数:

axisAxis

比例尺的轴。

注意

此参数未被使用，未来将被移除。由于有特殊的预处理，现在可以省略它，因此 FuncScaleLog(functions=(forward, inverse)) 是有效的。

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

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

property invlinthresh

[已弃用]

备注

自 3.11 版本弃用：请改用 .inverted().transform(linthresh)。

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=None, *, base=10, linthresh=2, subs=None, linscale=1)

基类：ScaleBase

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

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

请参阅 Symlog 比例尺 了解详细描述。

参数:

axisAxis

比例尺的轴。

注意

此参数未被使用，未来将被移除。由于有特殊的预处理，现在可以省略它，因此 SymmetricalLocSacle(base=2) 是有效的。

base浮点型，默认值: 10

对数的底数。

linthreshfloat, 默认：2

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

subsint 序列

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

linscalefloat, 可选

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

构建一个新的比例尺。

备注

以下说明适用于比例尺实现者。

出于向后兼容性的原因，比例尺将 Axis 对象作为第一个参数。

自 3.11 版本弃用：axis 参数现在是可选的，即 matplotlib 兼容不带 axis 参数的 ScaleBase 子类。

axis 参数正处于待弃用状态。它将在 matplotlib 3.13 中被弃用，并在 3.15 中被移除。

建议第三方比例尺现在就移除 axis 参数，如果它们能够将兼容性限制在 matplotlib >= 3.11 的话。否则，它们可以保留 axis 参数，并在 matplotlib 3.13 时移除。

name = 'symlog'

property base

property linthresh

property linscale

set_default_locators_and_formatters(axis)

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

get_transform()

返回与此比例尺关联的 SymmetricalLogTransform。

val_in_range(val)

返回该值（或多个值）是否在此比例尺的有效范围内。

除 +-inf 和 NaN 外，对所有值均为 True。

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=None, *, 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是临时的，未来可能会根据早期用户反馈进行修订。

参数:

axisAxis

比例尺的轴。

注意

此参数未被使用，未来将被移除。由于有特殊的预处理，现在可以省略它，因此 AsinhScale() 是有效的。

linear_widthfloat, 默认：1

缩放参数（在其他地方称为 \(a_0\)），定义了准线性区域的范围，以及超过此坐标值变换将渐近变为对数形式。

baseint, 默认：10

用于对数比例尺上刻度位置取整的数值底数。如果小于 1，则取整为 10 的幂的最近整数倍。

subsint 序列

用于副刻度的数值底数的倍数。如果设置为 '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 的定位器和格式器设置为适合此比例尺的实例。

val_in_range(val)

返回该值（或多个值）是否在此比例尺的有效范围内。

除 +-inf 和 NaN 外，对所有值均为 True。

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=None, nonpositive='mask', *, one_half='\\frac{1}{2}', use_overline=False)

基类：ScaleBase

用于 0 和 1 之间（不含两者）数据的 Logit 比例尺。

此比例尺类似于接近 0 和 1 时的对数比例尺，在 0.5 附近几乎是线性的。它将区间 ]0, 1[ 映射到 ]-infty, +infty[。

参数:

axisAxis

比例尺的轴。

注意

此参数未被使用，未来将被移除。由于有特殊的预处理，现在可以省略它，因此 LogitScale() 是有效的。

nonpositive{'mask', 'clip'}

确定对开区间 ]0, 1[ 之外值的处理行为。它们可以被屏蔽为无效，或者截断为非常接近 0 或 1 的数字。

use_overlinebool, 默认：False

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

one_halfstr, 默认：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 之间（不含两者）的值。

val_in_range(val)

返回该值（或多个值）是否在此比例尺的有效范围内。

对于 0 和 1 之间（不含两者）的值，此项为 True。

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 的子类

要注册的比例尺。