---
source_url: https://docs.dolphindb.cn/zh/funcs/h/histogram2d.html
fetched_at: 2026-05-19T09:27:20Z
category: funcs
title: histogram2d
sha1: f443025e481534a5c500689114c76da98c51f2c9
---

# histogram2d

## 语法

`histogram2d(X, Y, [bins=10], [range], [density=false],
[weights])`

## 详情

计算两组数据样本的二维直方图。

与 `numpy.histogram2d` 的功能基本相同。

## 参数

**X**, **Y** 两个等长的数值向量，分别作为构造二维直方图的 x 和 y 坐标值。注意：不可包含空值。

**bins** 可选参数，数值标量，严格递增的、长度至少为 2 的数值向量，或者由前两者组成的元组（第一个元素表示 x 维度上的特性，第二个元素表示 y
维度的特性）。默认值为 10。注意：不能包含空值。以下为传入不同形式数据的含义说明：

- 标量：x 和 y 两个维度箱的数目。
- 向量：x 和 y 两个维度分箱的边界。
- 标量组成的二维元组：x 和 y 两个维度分别分箱的数目。
- 向量组成的二维元组：x 和 y 两个维度分别分箱的边界。
- 标量和向量组成的二维元组：标量代表在对应维度上按照均等分箱时箱的数目；向量表示在对应维度上按给定的边界值分箱。

**range** 可选参数，二维向量，形状须为(2, 2)，用来指定每个维度上统计图的最左边界和最右边界（如果 *bins*
参数未显式给出边界值时）。所有超出 *range* 的点将被视为异常点，不会被二维直方图统计。默认为空。

**density** 可选参数，布尔标量。以下为说明：

- 如果为 false（默认值），则表示直方图统计每个二维箱子的样本点个数。
- 如果为 true，则会返回每个箱子的概率密度函数。bin\_count（当前箱子内的点个数）/sample\_count（总样本点数）/
  bin\_area（每个箱子的面积）。

**weights** 可选参数，数值向量，长度须与 *X*/*Y* 相同，表示对应样本点（x\_i,
y\_i）的权重。默认为空。注意：传入向量时不可包含空数据。其中，

- 如果 *density* 为 true，则 weights 会被正则化到 1。
- 如果 *density* 为 false，则每个箱子在二维直方图中的值就是落入这些该箱子的所有点的权重值之和。

## 返回值

一个字典，包含以下 key：

- H：形状为（nx, ny）的矩阵，表示二维直方图的统计结果。nx 和 ny 分别为 x 轴和 y 轴的分箱个数。矩阵中每个值的含义取决于
  *density*，请参考 *density* 参数的说明。
- xedges：长度为 nx + 1 的向量，表示沿着 x 轴分箱时箱子的 x 轴边界。nx 为 x 轴的分箱个数。
- yedges：长度为 ny + 1 的向量，表示沿着 y 轴分箱时箱子的 y 轴边界。ny 为 y 轴的分箱个数。

## 例子

例 1：传入两组数据样本，设置 x 和 y 两个维度分别分箱的边界、 *density* 为
false，计算其二维直方图的统计结果。

```dolphindb
x = [0.1, 0.2, 0.5, 0.7, 0.9]
y = [0.2, 0.4, 0.6, 0.8, 1.0]
bins = [[0, 0.3, 0.6, 1.0], [0, 0.5, 1.0]]
density = false
result = histogram2d(x, y, bins, ,density)

/* Output:
H->#0 #1
-- --
2  0 
0  1 
0  2 
xedges->[0,0.3,0.6,1]
yedges->[0,0.5,1]
*/
```

例 2：传入两组数据样本，设置 x 均等分箱时箱的数目、y 分箱的边界、权重、*density* 为
true，计算其二维直方图的统计结果。

```dolphindb
x = [0.2, 0.4, 0.6, 0.8, 1.0]
y = [0.3, 0.5, 0.7, 0.9, 1.1]
bins = [2, [0.3, 0.5, 1.1]]
weights = [1, 2, 3, 4, 5]
density = true
result = histogram2d(x, y, bins, ,density, weights)

/* Output:
H->#0 #1
-- --
1  5 
0  9 
xedges->[0.2,0.6,1]
yedges->[0.3,0.5,1.1]
*/
```
