Syslab使用手册
⋮
2026a

# histogram2

二元直方图

函数库: TyPlot

二元直方图是一种数值数据条形图，它将数据分组到二维 bin 中。创建 Histogram2 对象后，可以通过更改直方图的属性值修改它的各个方面。这对快速修改 bin 属性或更改显示特别有用。

# 语法

histogram2(X,Y)
histogram2(X,Y,nbins)
histogram2(X,Y,Xedges,Yedges)

histogram2(___,Key=Value)
histogram2(ax,___)
h = histogram2(___)

# 说明

histogram2(X,Y) 创建 X 和 Y 的二元直方图。histogram2 函数使用自动 bin 划分算法，然后返回均匀面积的 bin，这些 bin 可涵盖 X 和 Y 中的元素范围并显示分布的基本形状。histogram2 将 bin 显示为三维矩形条形，这样每个条形的高度就表示 bin 中的元素数量。示例

histogram2(X,Y,nbins) 指定要在直方图的每个维度中使用的 bin 数量。示例

histogram2(X,Y,Xedges,Yedges) 使用向量 Xedges 和 Yedges 指定每个维度中 bin 的边界。示例

histogram2(___,Key=Value) 使用前面的任何语法指定具有一个或多个 Name,Value 对组参数的其他选项。例如，可以指定 "binwidth" 和一个二元素向量以调整每个维度中 bin 的宽度，或指定 "normalization" 和一个有效选项（"count"、"probability" 或 "countdensity"）以使用不同类型的归一化。示例

histogram2(ax,___) 将图形绘制到 ax 指定的坐标区中，而不是当前坐标区 (gca) 中。选项 ax 可以位于前面的语法中的任何输入参数组合之前。

h = histogram2(___) 返回 Histogram 对象。使用此语法可检查并调整二元直方图的属性。

# 示例

向量的直方图

生成 10000 个随机数对组并创建一个二元直方图。histogram2 函数自动选择合适的 bin 数量，以便涵盖 x 和 y 中的值范围并显示基本分布的形状。

using TyPlot
pkg_dir = pkgdir(TyPlot)
source_path = pkg_dir * "/examples/histogram2/data_10000.jl"
include(source_path)

h = histogram2(x, y)

xlabel("x")
ylabel("y")

指定 histogram2 函数的输出参数时，它返回一个二元直方图对象。可以使用该对象检查直方图的属性，例如 bin 数量或宽度。

计算每个维度的直方图 bin 数量。

nXnY = h.NumBins

nXnY = 
2-element Vector{Int64}:
 25
 28
指定直方图的 bin 数量

为划分入 25 个等距 bin 的 1,000 个随机数对组绘制一个二元直方图，其中每个维度使用 5 个 bin。

using TyPlot
pkg_dir = pkgdir(TyPlot)
source_path = pkg_dir * "/examples/histogram2/data_10000.jl"
include(source_path)

h = histogram2(x, y)

xlabel("x")
ylabel("y")
file_path = (pkgdir(TyPlot)) * "/examples/histogram2/data_1000.jl"
include(file_path)

nbins = 5;
h = histogram2(x, y, nbins)

求生成的 bin 计数。

counts = h.Values

counts =
5×5 Matrix{Float64}:
 0.0    2.0    3.0    1.0   0.0
 2.0   40.0  124.0   47.0   4.0
 1.0  119.0  341.0  109.0  10.0
 1.0   32.0  117.0   33.0   1.0
 0.0    4.0    8.0    1.0   0.0
调整直方图 bin 的数量

生成 1,000 个随机数对组并创建一个二元直方图。

using TyPlot
function morebins(nbins)
    return Int(ceil(nbins * 1.1))
end

function fewerbins(nbins)
    return Int(floor(nbins * 0.9))
end

file_path = (pkgdir(TyPlot)) * "/examples/histogram2/data_1000.jl"
include(file_path)

h = histogram2(x, y)

使用 morebins 函数精略调整 x 维度中的 bin 数量。

nbins_x = morebins(h.NumBins[1]);
nbins_x = morebins(nbins_x)
nbins = [nbins_x, h.NumBins[2]]
println(nbins) 

yedges = h.YBinEdges

cla()
h = histogram2(x, y, nbins, ybinedges = yedges)

nbins =
2-element Vector{Int64}:
 19
 15

使用 fewerbins 函数调整 y 维度中的 bin 数量。

nbins_y = fewerbins(h.NumBins[2]);
nbins_y = fewerbins(nbins_y)
nbins = [h.NumBins[1], nbins_y]
println(nbins) #[19 15]

cla()
h = histogram2(x, y, nbins)

nbins =
2-element Vector{Int64}:
 19
 11

通过显式设置 bin 数按精细粒度级别调整 bin 数量。

cla()
h = histogram2(x, y, [20, 10])
指定直方图的 bin 边界

生成 1,000 个随机数对组并创建一个二元直方图。使用两个向量指定 bin 边界，使具有无限宽的 bin 在直方图的边缘，以捕获不满足 x<2 的所有离群值。

using TyPlot
file_path = (pkgdir(TyPlot)) * "/examples/histogram2/data_1000.jl"
include(file_path)

Xedges = [-2:0.4:2...];
Yedges = [-2:0.4:2...];
h = histogram2(x, y, Xedges, Yedges, normalization = "countdensity")
归一化的直方图

生成 1000 个随机数对组并使用 "probability" 归一化创建一个二元直方图。

using TyPlot
file_path = (pkgdir(TyPlot)) * "/examples/histogram2/data_1000.jl"
include(file_path)

h = histogram2(x, y, normalization = "probability")

计算条形高度的总和。通过此归一化，每个条形的高度等于选取位于该 bin 间隔内的观测值的概率，并且所有条形的高度总和为 1。

S = sum(h.Values)

S = 1.0
保存并加载二元直方图对象

使用 savefig 函数保存二元直方图图窗。

using TyPlot
using TyBase
file_path = (pkgdir(TyPlot)) * "/examples/histogram2/data_100.jl"
include(file_path)

histogram2(x, y);
savefig("histogram2.syslabfig");

clear()
plt_close("all")

使用 openfig 重新将直方图加载到 Syslab。openfig 也返回图窗 h 的句柄。

h = openfig("histogram2.syslabfig")

# 输入参数

X,Y - 要分布到各 bin 的数据（以单独参数指定）
向量 | 矩阵 | 多维数组

要分布到各 bin 的数据，指定为向量、矩阵或多维数组的单独参数。X 和 Y 的大小必须相同。如果 X 和 Y 不是向量，则 histogram2 将其视为单列向量 X[:] 和 Y[:]，并绘制一个直方图。

X 和 Y 中的对应元素指定二维数据点 [X[k],Y[k]] 的 x 和 y 坐标。X 和 Y 的数据类型可以不同，但 histogram2 会将这些输入串联成占优数据类型的 N×2 矩阵。

数据类型： Float32 | Float64 | Int8 | Int16 | Int32 | Int64 | UInt8 | UInt16 | UInt32 | UInt64 | Bool

nbins - 每个维度中的 bin 数量
标量 | 向量

每个维度中的 bin 数量，指定为一个正整数标量或由正整数组成的二元素向量。如果不指定 nbins，则 histogram2 自动基于 X 和 Y 中的值计算要使用多少个 bin。

  • 如果 nbins 是标量，则 histogram2 在每个维度中使用该标量所指定的 bin 数；

  • 如果 nbins 是向量，则 nbins[1] 指定 x 维度的 bin 数，nbins[2] 指定 y 维度的 bin 数。

示例： histogram2(X,Y,20) 在每个维度中使用 20 个 bin。

示例： histogram2(X,Y,[10 20]) 在 x 维度使用 10 个 bin，在 y 维度使用 20 个 bin。

Xedges - x 维度中的 bin 边界
向量

x 维度中的 bin 边界，指定为向量。Xedges[1] 是 x 维度的第一个 bin 的第一个边界，Xedges[end] 是最后一个 bin 的外边界。

如果 Xedges[i] ≤ X[k] < Xedges[i+1] 且 Yedges[j] ≤ Y[k] < Yedges[j+1]，则 (X[k],Y[k]) 位于第 [i,j] 个 bin 中。每个维度中的最后 bin 还包含最后一个（外部）边界。例如，如果 Xedges[end-1] ≤ X[k] ≤ Xedges[end] 且 Yedges[i] ≤ Y[k] < Yedges[i+1]，则 (X[k],Y[k]) 属于最后一行中的第 i 个 bin。

数据类型： Float32 | Float64 | Int8 | Int16 | Int32 | Int64 | UInt8 | UInt16 | UInt32 | UInt64 | Bool

Yedges - y 维度中的 bin 边界
向量

y 维度中的 bin 边界，指定为向量。yedges[1] 是 y 维度的第一个 bin 的第一个边界，yedges[end] 是最后一个 bin 的外边界。

如果 Xedges[i] ≤ X[k] < Xedges[i+1] 且 Yedges[j] ≤ Y[k] < Yedges[j+1]，则 (X[k],Y[k]) 位于第 [i,j] 个 bin 中。每个维度中的最后 bin 还包含最后一个（外部）边界。例如，如果 Xedges[end-1] ≤ X[k] ≤ Xedges[end] 且 Yedges[i] ≤ Y[k] < Yedges[i+1]，则 (X[k],Y[k]) 属于最后一行中的第 i 个 bin。

数据类型： Float32 | Float64 | Int8 | Int16 | Int32 | Int64 | UInt8 | UInt16 | UInt32 | UInt64 | Bool

ax - 坐标区对象
对象

坐标区对象。如果未指定坐标区，histogram2 函数将使用当前坐标区 (gca)。

# 名称-值对组参数

指定可选的、以逗号分隔的 Key=Value 对组参数。Key 为参数名称，Value 为对应的值。您可采用任意顺序指定多个名称-值对组参数，如 Key1=Value1,...,KeyN=ValueN 所示。

示例： histogram2(X,Y,binwidth = [5 10])

此处所列的属性只是一部分。

label - 图例
nothing（默认） | 字符串 | 数值

label 图例，默认 nothing，使用默认数据 data1 标记图形对象。如果设置了图例则以图例内容标记图形对象。

binmethod - bin 划分算法
"auto" （默认） | "scott" | "integers" | "fd"

bin 划分算法，指定为此表中的一个值。

值 说明
"auto" 默认的 "auto" 算法选择一个 bin 宽度，以便涵盖数据范围并显示基础分布形状。
"scott" 如果数据接近正态分布，则 Scott 规则最佳。该规则也适用于大多数的其他分布。它使用 bin 宽度 3.5*std(X[:])*numel(X)^(-1/3)。
"integers" 整数规则对整数数据有用，因为它为每个整数创建一个 bin。它使用 bin 宽度 1 并将 bin 边界放在整数的中间。为避免无意间创建太多 bin，可以使用该规则创建 65536 (216) 个 bin 的限制。如果数据范围大于 65536，则整数规则改用更宽的 bin。
"sturges" Sturges 规则因其简单性而广受欢迎。它将 bin 数量选择为 ceil(1 + log2(numel(X)))。
"sqrt" 平方根规则是广泛用于其他软件包。它将 bin 数量选择为 ceil(sqrt(numel(X)))。

histogram2 并不始终使用这些精确的公式来选择 bin 数目。有时 bin 数目会稍做调整，以便 bin 边界落在“合适”的数字上。

示例： histogram2(X,binmethod="integers") 创建一个带有以整数为中心的 bin 的直方图。

binwidth - bin 的宽度
向量

每个维度中的 bin 宽度，指定为由正整数组成的二元素向量 [xWidth yWidth]。

如果指定 binwidth，则 histogram2 可以沿每个维度使用最多 1024 (210) 个 bin。如果指定的 bin 宽度需要多个 bin，则 histogram2 使用与最大 bin 数对应的较大的 bin 宽度。

示例： histogram2(X,Y, binwidth = [5 10]) 在 x 维度使用的 bin 的大小为 5，在 y 维度使用的 bin 的大小为 10。

edgealpha - 直方图条形边的透明度
1 （默认） | 介于 0 和 1（包括二者）之间的标量值

直方图条形边的透明度，指定为介于 0 和 1（包含这两个边界值）之间的标量值。值 1 表示完全不透明，0 则表示完全透明（不可见）。

示例： histogram2(X,edgealpha=0.5) 创建一个具有半透明条形边的二元直方图。

edgecolor - 直方图的边界颜色
[0.15, 0.15, 0.15] （默认） | "none" | RGB 三元组 | 十六进制颜色代码 | 颜色名称

直方图的边界颜色，指定为下列值之一：

  • "none" - 不绘制边；
  • RGB 三元组、十六进制颜色代码或颜色名称 - 边使用指定的颜色。 RGB 三元组和十六进制颜色代码对于指定自定义颜色非常有用。
    • RGB 三元组是包含三个元素的行向量，其元素分别指定颜色中红、绿、蓝分量的强度。强度值必须位于 [0,1] 范围内，例如 [0.4 0.6 0.7]；
    • 十六进制颜色代码是字符向量或字符串标量，以井号 (#) 开头，后跟三个或六个十六进制数字，范围可以是 0 到 F。这些值不区分大小写。因此，颜色代码 "#FF8800" 与 "#ff8800"、"#F80" 与 "#f80" 是等效的。

此外，还可以按名称指定一些常见的颜色。下表列出了命名颜色选项、等效 RGB 三元组和十六进制颜色代码。

颜色名称 短名称 RGB 三元组 十六进制颜色代码 外观
"red" "r" [1, 0, 0] "#FF0000"
"green" 不适用 [0, 0.5019607843137255, 0] "#008000"
不适用 "g" [0, 0.5, 0] "#007F00"
不适用 不适用 [0, 1, 0] "#00FF00"
"blue" "b" [0, 0, 1] "#0000FF"
"cyan" 不适用 [0, 1, 1] "#00FFFF"
不适用 "c" [0, 0.75, 0.75] "#00BFBF"
"magenta" 不适用 [1, 0, 1] "#FF00FF"
不适用 "m" [0.75, 0, 0.75] "#BF00BF"
"yellow" 不适用 [1, 1, 0] "#FFFF00"
不适用 "y" [0.75, 0.75, 0] "#BFBF00"
"black" "k" [0, 0, 0] "#000000"
"white" "w" [1, 1, 1] "#FFFFFF"
"none" 不适用 不适用 不适用 无颜色

以下是 Syslab 在许多类型的绘图中使用的默认颜色的 RGB 三元组和十六进制颜色代码。

RGB 三元组 十六进制颜色代码 外观
[0, 0.4470, 0.7410] "#0072BD"
[0.8500, 0.3250, 0.0980] "#D95319"
[0.9290, 0.6940, 0.1250] "#EDB120"
[0.4940, 0.1840, 0.5560] "#7E2F8E"
[0.4660, 0.6740, 0.1880] "#77AC30"
[0.3010, 0.7450, 0.9330] "#4DBEEE"
[0.6350, 0.0780, 0.1840] "#A2142F"

示例： histogram2(X,edgecolor="r") 创建一个带红色条形边界的直方图。

facealpha - 直方图条形的透明度
1 （默认） | 介于 0 和 1（包括二者）之间的标量值

直方图条形的透明度，指定为介于 0 和 1（包括二者）之间的标量值。histogram 对所有的直方图条形使用相同的透明度。值 1 表示完全不透明，0 则表示完全透明（不可见）。

示例： histogram2(X,Y,facealpha = 0.5) 创建一个具有半透明条形的二元直方图。

facecolor - 直方图的条形颜色
"auto" （默认） | "none" | RGB 三元组 | 十六进制颜色代码 | 颜色名称

直方图的条形颜色，指定为下列值之一：

  • "none" - 条形未填充；
  • "auto" - 直方图条形颜色是自动选择的（默认）；
  • RGB 三元组、十六进制颜色代码或颜色名称 - 用指定的颜色填充条形。 RGB 三元组和十六进制颜色代码对于指定自定义颜色非常有用。
    • RGB 三元组是包含三个元素的行向量，其元素分别指定颜色中红、绿、蓝分量的强度。强度值必须位于 [0,1] 范围内，例如 [0.4 0.6 0.7]；
    • 十六进制颜色代码是字符向量或字符串标量，以井号 (#) 开头，后跟三个或六个十六进制数字，范围可以是 0 到 F。这些值不区分大小写。因此，颜色代码 "#FF8800" 与 "#ff8800"、"#F80" 与 "#f80" 是等效的。

此外，还可以按名称指定一些常见的颜色。下表列出了命名颜色选项、等效 RGB 三元组和十六进制颜色代码。

颜色名称 短名称 RGB 三元组 十六进制颜色代码 外观
"red" "r" [1, 0, 0] "#FF0000"
"green" 不适用 [0, 0.5019607843137255, 0] "#008000"
不适用 "g" [0, 0.5, 0] "#007F00"
不适用 不适用 [0, 1, 0] "#00FF00"
"blue" "b" [0, 0, 1] "#0000FF"
"cyan" 不适用 [0, 1, 1] "#00FFFF"
不适用 "c" [0, 0.75, 0.75] "#00BFBF"
"magenta" 不适用 [1, 0, 1] "#FF00FF"
不适用 "m" [0.75, 0, 0.75] "#BF00BF"
"yellow" 不适用 [1, 1, 0] "#FFFF00"
不适用 "y" [0.75, 0.75, 0] "#BFBF00"
"black" "k" [0, 0, 0] "#000000"
"white" "w" [1, 1, 1] "#FFFFFF"
"none" 不适用 不适用 不适用 无颜色

以下是 Syslab 在许多类型的绘图中使用的默认颜色的 RGB 三元组和十六进制颜色代码。

RGB 三元组 十六进制颜色代码 外观
[0, 0.4470, 0.7410] "#0072BD"
[0.8500, 0.3250, 0.0980] "#D95319"
[0.9290, 0.6940, 0.1250] "#EDB120"
[0.4940, 0.1840, 0.5560] "#7E2F8E"
[0.4660, 0.6740, 0.1880] "#77AC30"
[0.3010, 0.7450, 0.9330] "#4DBEEE"
[0.6350, 0.0780, 0.1840] "#A2142F"

示例： histogram2(X,Y,facecolor = "g") 创建一个具有绿色条形的三维直方图。

linestyle - 线型
"-" （默认） | "--" | ":" | "-." | "none"

线型，指定为下表中列出的选项之一。

线型 说明 表示的线条
"-" 实线
"--" 虚线
":" 点线
"-." 点划线
"none" 无线条 无线条
linewidth - 条形轮廓的宽度
0.5 （默认） | 正值

条形轮廓的宽度，指定为以磅为单位的正值。一磅等于 1/72 英寸。

示例： 1.5

数据类型： Int16 | Int32 | Int64 | Float16 | Float32 | Float64

normalization - 归一化类型
"count" （默认） | "countdensity" | "probability" | "pdf"

归一化类型，指定为此表中的一个值。对于每个 bin i：

  • vi 是 bin 的值；
  • ci 是 bin 中的元素数目；
  • Ai=Wxi*Wyi 是每个 bin 的面积，使用 bin 宽度 x 和 y 计算得出；
  • N 是输入数据中的元素数目。此值可以大于分 bin 数据元素数，前提是数据中包含 NaN 值，或者某些数据位于 bin 范围外。
值 bin值 注释
"count" (默认值)
  • 观测值的计数或频率；
  • bin 值之和小于或等于 numel(X)。仅当某些输入数据不在 bin 中时，bin 值之和才会小于 numel(X)。
"countdensity"
  • 按 bin 的面积进行换算的计数或频率；
  • 每个条形的体积（高 * 面积）是 bin 中的观测值数量。条形体积之和小于或等于 numel(X) 和 numel(y)。
"probability"
  • 相对概率;
  • 条形高度之和小于或等于 1。
"pdf"
  • 概率密度函数的估计值；
  • 每个条形的体积是相对观测值数量。条形体积之和小于或等于 1。

示例： histogram2(X,Y,normalization = "probability") 。

xbinlimits - x 维度的 bin 范围
向量

x 维度的 bin 范围，指定为二元素向量 [xbmin,xbmax]。该向量表示 x 维度中的第一个和最后一个 bin 边界。

histogram2 只绘制在 bin 范围 Data(Data(:,1)>=xbmin & Data(:,1)<=xbmax)（包含这两个边界值）内的数据。

ybinlimits - y 维度的 bin 范围
向量

y 维度的 bin 范围，指定为二元素向量 [ybmin,ybmax]。该向量表示 y 维度中的第一个和最后一个 bin 边界。

histogram2 只绘制在 bin 范围 Data(Data(:,2)>=ybmin & Data(:,2)<=ybmax)（包含这两个边界值）内的数据。

# 输出参数

h - 二元直方图
对象

直方图，以对象的形式返回。

# 另请参阅

histcounts