histcounts

直方图 bin 计数

全页折叠

语法

[N,edges] = histcounts(X)

[N,edges] = histcounts(X,nbins)

[N,edges] = histcounts(X,edges)

[N,edges,bin] = histcounts(___)

N = histcounts(C)

N = histcounts(C,Categories)

[N,Categories] = histcounts(___)

[___] = histcounts(___,Name,Value)

说明

示例

[N,edges] = histcounts(X) 将 X 的值划分为多个 bin，并返回每个 bin 中的计数以及 bin 边界。histcounts 函数使用自动分 bin 算法，返回均匀宽度的 bin，这些 bin 可涵盖 X 中的元素范围并显示基本分布的形状。

示例

[N,edges] = histcounts(X,nbins) 使用标量 nbins 指定的 bin 数量。

示例

[N,edges] = histcounts(X,edges) 将 X 划分为由向量 edges 来指定 bin 边界的 bin。如果 edges(k) ≤ X(i) < edges(k+1)，值 X(i) 位于第 k 个 bin 中。最后一个 bin 也包含 bin 的右边界，这样如果 edges(end-1) ≤ X(i) ≤ edges(end)，它包含 X(i)。

示例

[N,edges,bin] = histcounts(___) 支持任何上述语法，且可返回索引数组 bin。bin 是大小与 X 相同的数组，其元素是 X 中的对应元素的 bin 索引。第 k 个 bin 中的元素数量是 nnz(bin==k)，与 N(k) 相同。

示例

N = histcounts(C)（其中 C 是分类数组）返回向量 N，该向量指示 C 中其值等于 C 的各类别的元素的数量。C 中的每个类别在 N 中都有一个对应元素。

N = histcounts(C,Categories) 仅对 C 中其值等于由 Categories 指定的类别子集的元素进行计数。

示例

[N,Categories] = histcounts(___) 还使用分类数组的任一上述语法，返回对应于 N 中每个计数的类别。

示例

[___] = histcounts(___,Name,Value) 使用一个或多个 Name,Value 对组指定的其他选项，这些选项使用上述语法中的任意输入或输出参数组合。例如，您可以指定 'BinWidth' 和一个标量来调整数值数据的 bin 的宽度。对于分类数据，您可以指定 'Normalization' 和下列项之一：'count'、'countdensity'、'probability'、'pdf'、'cumcount' 或 'cdf'。

示例

全部折叠

bin 计数和 bin 边界

打开实时脚本

将 100 个随机值分布到多个 bin 内。histcounts 自动选择合适的 bin 宽度以显示数据的基本分布。

X = randn(100,1);
[N,edges] = histcounts(X)

N = 1×7

     2    17    28    32    16     3     2

edges = 1×8

    -3    -2    -1     0     1     2     3     4

指定 bin 数

打开实时脚本

将 10 个随机数分布到 6 个等间距 bin 内。

X = [2 3 5 7 11 13 17 19 23 29];
[N,edges] = histcounts(X,6)

N = 1×6

     2     2     2     2     1     1

edges = 1×7

         0    4.9000    9.8000   14.7000   19.6000   24.5000   29.4000

指定 bin 边界

打开实时脚本

将 1,000 个随机数分布到多个 bin 内。通过向量定义 bin 边界，其中第一个元素是第一个 bin 的左边界，而最后一个元素是最后一个 bin 的右边界。

X = randn(1000,1);
edges = [-5 -4 -2 -1 -0.5 0 0.5 1 2 4 5];
N = histcounts(X,edges)

N = 1×10

     0    24   149   142   195   200   154   111    25     0

归一化的 bin 计数

打开实时脚本

将小于 100 的所有质数分布到多个 bin 内。将 'Normalization' 指定为 'probability' 以对 bin 计数进行归一化，从而 sum(N) 为 1。即，每个 bin 计数代表观测值属于该 bin 的可能性。

X = primes(100);
[N,edges] = histcounts(X, 'Normalization', 'probability')

N = 1×4

    0.4000    0.2800    0.2800    0.0400

edges = 1×5

     0    30    60    90   120

确定 bin 放置

打开实时脚本

将介于 -5 和 5 之间的 100 个随机整数分布到多个 bin 内，并将 'BinMethod' 指定为 'integers' 以使用以整数为中心的单位宽度 bin。指定 histcounts 的第三个输出以返回代表数据 bin 索引的向量。

X = randi([-5,5],100,1);
[N,edges,bin] = histcounts(X,'BinMethod','integers');

通过计算数字 3 在 bin 索引向量 bin 中的出现次数求第三个 bin 的 bin 计数。结果与 N(3) 相同。

count = nnz(bin==3)

count = 8

分类 bin 计数

打开实时脚本

创建一个表示投票的分类向量。该向量中的类别是 'yes'、'no' 或 'undecided'。

A = [0 0 1 1 1 0 0 0 0 NaN NaN 1 0 0 0 1 0 1 0 1 0 0 0 1 1 1 1];
C = categorical(A,[1 0 NaN],{'yes','no','undecided'})

C = 1x27 categorical
     no      no      yes      yes      yes      no      no      no      no      undecided      undecided      yes      no      no      no      yes      no      yes      no      yes      no      no      no      yes      yes      yes      yes

确定每个类别中的元素数量。

[N,Categories] = histcounts(C)

N = 1×3

    11    14     2

Categories = 1x3 cell
    {'yes'}    {'no'}    {'undecided'}

输入参数

全部折叠

`X` — 要分布到各 bin 的数据
向量 | 矩阵 | 多维数组

要分布到各 bin 的数据，指定为向量、矩阵或多维数组。如果 X 不是向量，则 histcounts 将它视作单列向量 X(:)。

histcounts 忽略所有的 NaN 值。同样，histcounts 忽略 Inf 和 -Inf 值，除非 bin 边界将 Inf 或 -Inf 显式指定为 bin 边界。

`C` — 分类数据
分类数组

分类数据，指定为分类数组。histcounts 将忽略未定义的分类值。

数据类型： categorical

`nbins` — bin 数量
正整数

bin 数量，指定为正整数。如果不指定 nbins，则 histcounts 基于 X 中的值自动计算将使用多少个 bin。

示例： [N,edges] = histcounts(X,15) 使用 15 个 bin。

`edges` — bin 边界
向量

bin 边界，指定为向量。edges(1) 是第一个 bin 的左边界，edges(end) 是最后一个 bin 的右边界。

对于日期时间和持续时间数据，edges 必须是单调递增顺序的日期时间或持续时间向量。

`Categories` — 计数中包含的类别
所有类别（默认） | 字符串向量 | 字符向量元胞向量 | `pattern` 标量 | 分类向量

计数中包含的类别，指定为字符串向量、字符向量的元胞向量、pattern 标量或分类向量。默认情况下，histcounts 对分类数组 C 中的每个类别使用一个 bin，而使用 Categories 可指定类别的唯一子集。

示例： h = histcounts(C,["Large","Small"]) 只对类别 Large 和 Small 中的分类数据进行计数。

示例： h = histcounts(C,"Y" + wildcardPattern) 对名称以字母 Y 开头的所有类别中的分类数据进行计数。

数据类型： string | cell | pattern | categorical

名称-值参数

将可选的参数对组指定为 Name1=Value1,...,NameN=ValueN，其中 Name 是参数名称，Value 是对应的值。名称-值参数必须出现在其他参数之后，但参数对组的顺序无关紧要。

在 R2021a 之前，使用逗号分隔每个名称和值，并用引号将 Name 引起来。

示例： [N,edges] = histcounts(X,'Normalization','probability') 对 N 中的 bin 计数进行归一化，这样 sum(N) 为 1。

`BinLimits` — bin 范围
二元素向量

bin 范围，指定为二元素向量 [bmin,bmax]。该选项仅包括 X 中介于 bmin 和 bmax（含二者）之间的值，即 X(X>=bmin & X<=bmax)。

此选项不适用于分类数据。

示例： [N,edges] = histcounts(X,'BinLimits',[1,10]) 仅包括 X 中介于 1 与 10（含二者）之间的值。

`BinMethod` — 分 bin 算法
`'auto'` （默认） | `'scott'` | `'fd'` | `'integers'` | `'sturges'` | `'sqrt'` | ...

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

值	描述
`'auto'`	默认的 `'auto'` 算法选择一个 bin 宽度，以便涵盖数据范围并显示基础分布形状。
`'scott'`	如果数据接近正态分布，但还适用于大多数的其他分布，则 Scott 规则最佳。它使用 bin 宽度 `3.5std(X(:))numel(X)^(-1/3)`。
`'fd'`	Freedman-Diaconis 规则对数据中的离群值不太敏感，可能更适用于重尾分布的数据。它使用 bin 宽度 `2IQR(X(:))numel(X)^(-1/3)`，其中 `IQR` 为 `X` 的四分位差。
`'integers'`	整数规则对整数数据有用，因为它为每个整数创建一个 bin。它使用 bin 宽度 1 并将 bin 边界放在整数的中间。为避免无意间创建太多 bin，可以使用该规则创建 65536 个 bin 的限制 (2¹⁶)。如果数据范围大于 65536，则改用更宽的 bin。注意 `'integers'` 不支持日期时间和持续时间数据。
`'sturges'`	Sturges 规则是因其简单性而广受欢迎的简单规则。它将 bin 数量选择为 `ceil(1 + log2(numel(X)))`。
`'sqrt'`	平方根规则是另一个广泛用于其他软件包的简单规则。它将 bin 数量选择为 `ceil(sqrt(numel(X)))`。

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

对于日期时间数据，bin 方法可以是下列时间单位之一：

`'second'`	`'month'`
`'minute'`	`'quarter'`
`'hour'`	`'year'`
`'day'`	`'decade'`
`'week'`	`'century'`

对于持续时间数据，bin 方法可以是下列时间单位之一：

`'second'`	`'day'`
`'minute'`	`'year'`
`'hour'`

如果您使用日期时间或持续时间数据指定 BinMethod，则 histcounts 最多可以使用 65,536（即 2¹⁶）个 bin。如果指定的 bin 持续时间需要多个 bin，则 histcounts 使用与最大 bin 数对应的较大的 bin 宽度。

此选项不适用于分类数据。

示例： [N,edges] = histcounts(X,'BinMethod','integers') 使用以整数为中心的 bin。

`BinWidth` — bin 的宽度
标量

bin 宽度，指定为标量。如果指定 BinWidth，则 histcounts 最多可以使用 65,536（即 2¹⁶）个 bin。如果指定的 bin 宽度需要多个 bin，则 histcounts 使用与最大 bin 数对应的较大的 bin 宽度。

对于日期时间和持续时间数据，'BinWidth' 的值可以是标量持续时间或日历持续时间。

此选项不适用于分类数据。

示例： [N,edges] = histcounts(X,'BinWidth',5) 使用宽度为 5 的 bin。

`BinEdges` — bin 的边界
数值向量

bin 的边界，指定为数值向量。第一个向量元素指定第一个 bin 的左边界。最后一个元素指定最后一个 bin 的右边界。如果不指定 bin 边界，则 histcounts 自动确定 bin 边界的位置。

此选项不适用于分类数据。

`Normalization` — 归一化类型
`'count'` （默认） | `'probability'` | `'countdensity'` | `'pdf'` | `'cumcount'` | `'cdf'`

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

$v_{i}$ 是 bin 的值。
$c_{i}$ 是 bin 中的元素数目。
$w_{i}$ 是 bin 的宽度。
$N$ 是输入数据中的元素数目。此值可以大于分 bin 数据元素数，前提是数据中包含 NaN、NaT 或 <undefined> 值，或者某些数据位于 bin 范围外。

值	bin 值	注释
`'count'`（默认值）	$v_{i} = c_{i}$	观测值的计数或频率。 bin 值之和小于或等于 `numel(X)`。仅当某些输入数据不在 bin 中时，bin 值之和才会小于 `numel(X)`。对于分类数据，bin 值之和为 `numel(X)` 或 `sum(ismember(X(:),Categories))`。
`'countdensity'`	$v_{i} = \frac{c_{i}}{w_{i}}$	按 bin 的宽度进行换算的计数或频率。对于分类数据，这与 `'count'` 相同。注意 `'countdensity'` 不支持日期时间和持续时间数据。
`'cumcount'`	$v_{i} = \sum_{j = 1}^{i} c_{j}$	累积计数。每个 bin 的值等于该 bin 及以前的所有 bin 中的累积观测值数量。最后一个 bin 的值小于或等于 `numel(X)`。对于分类数据，最后一个 bin 的值小于或等于 `numel(X)` 或 `sum(ismember(X(:),Categories))`。
`'probability'`	$v_{i} = \frac{c_{i}}{N}$	相对概率。 bin 值之和小于或等于 `1`。
`'pdf'`	$v_{i} = \frac{c_{i}}{N \cdot w_{i}}$	概率密度函数的估计值。对于分类数据，这与 `'probability'` 相同。注意 `'pdf'` 不支持日期时间和持续时间数据。
`'cdf'`	$v_{i} = \sum_{j = 1}^{i} \frac{c_{j}}{N}$	累积的密度函数估算值。 `N(end)` 小于或等于 `1`。

示例： [N,edges] = histcounts(X,'Normalization','pdf') 使用概率密度函数估计值对数据分 bin。

`NumBins` — bin 数量
正整数

bin 数量，指定为正整数。如果不指定 NumBins，则 histcounts 基于输入数据自动计算将使用多少个 bin。

此选项不适用于分类数据。

输出参数

全部折叠

`N` — bin 计数
行向量

bin 计数，以行向量的形式返回。

`edges` — bin 边界
向量

bin 边界，以向量的形式返回。edges(1) 是第一个 bin 的左边界，edges(end) 是最后一个 bin 的右边界。

`bin` — bin 索引
数组

bin 索引，以大小与 X 相同的数组形式返回。bin 中的每个元素说明哪些编号的 bin 包含 X 中的对应元素。

bin 中的 0 值用于指明不属于任何 bin 的元素（例如 NaN 值）。

`Categories` — 计数中包含的类别
字符向量元胞向量

计数中包含的类别，以字符向量元胞向量形式返回。Categories 包含 C 中对应于 N 中每个计数的类别。

提示

histcounts 的行为与 discretize 函数的行为类似。使用 histcounts 查找每个 bin 中的元素数量。另一方面，使用 discretize 可查找每个元素所属的 bin（不计数）。

扩展功能

tall 数组
对行数太多而无法放入内存的数组进行计算。

用法说明和限制：

不支持某些输入选项。允许使用的选项包括：
- 'BinWidth'
- 'BinLimits'
- 'Normalization'
- 'BinMethod' - 'auto' 和 'scott' 是相同的 bin 方法。不支持 'fd' bin 方法。
Categories 输入参数不支持模式表达式。

有关详细信息，请参阅 tall 数组。

C/C++ 代码生成
使用 MATLAB® Coder™ 生成 C 代码和 C++ 代码。

用法说明和限制：

代码生成不支持对此函数使用稀疏矩阵输入。
如果您不提供 bin 边界，代码生成可能需要可变大小数组和动态内存分配。
Categories 输入参数不支持模式表达式。

GPU 代码生成
使用 GPU Coder™ 为 NVIDIA® GPU 生成 CUDA® 代码。

用法说明和限制：

代码生成不支持对此函数使用稀疏矩阵输入。
如果您不提供 bin 边界，代码生成可能需要可变大小数组和动态内存分配。
Categories 输入参数不支持模式表达式。

基于线程的环境
使用 MATLAB® `backgroundPool` 在后台运行代码或使用 Parallel Computing Toolbox™ `ThreadPool` 加快代码运行速度。

此函数完全支持基于线程的环境。有关详细信息，请参阅在基于线程的环境中运行 MATLAB 函数。

GPU 数组
通过使用 Parallel Computing Toolbox™ 在图形处理单元 (GPU) 上运行来加快代码执行。

用法说明和限制：

不支持 64 位整数。

有关详细信息，请参阅Run MATLAB Functions on a GPU (Parallel Computing Toolbox)。

版本历史记录

在 R2014b 中推出

全部展开

R2023a: 改进了使用少量数值和逻辑值输入数据时的性能

由于输入解析更快，histcounts 函数在使用数值和逻辑值数据时的性能得到了改进。输入解析在计算时间中的占比越大，性能改进越显著。当要分布到各 bin 的数据的大小小于 2000 个元素时，就会出现这种情况。

例如，以下代码计算一个包含 1000 个元素的向量的直方图 bin 计数。该代码比上一版本大约快 3 倍。

function timingHistcounts
X = rand(1,1000);
for k = 1:3e3
    histcounts(X,"BinMethod","auto");
end
end

大致的执行时间是：

R2022b：0.62 秒

R2023a：0.21 秒

代码是在运行 Windows^® 10 的 Intel^® Xeon^® CPU E5-1650 v4 @ 3.60 GHz 测试系统上使用 timeit 函数进行计时的。

timeit(@timingHistcounts)

另请参阅

histogram | histogram2 | discretize | histcounts2

主题

替换不建议使用的 hist 和 histc 实例

histcounts

语法

说明

示例

bin 计数和 bin 边界

指定 bin 数

指定 bin 边界

归一化的 bin 计数

确定 bin 放置

分类 bin 计数

输入参数

X — 要分布到各 bin 的数据 向量 | 矩阵 | 多维数组

C — 分类数据 分类数组

nbins — bin 数量 正整数

edges — bin 边界 向量

Categories — 计数中包含的类别 所有类别 （默认） | 字符串向量 | 字符向量元胞向量 | pattern 标量 | 分类向量

名称-值参数

BinLimits — bin 范围 二元素向量

BinMethod — 分 bin 算法 'auto' （默认） | 'scott' | 'fd' | 'integers' | 'sturges' | 'sqrt' | ...

BinWidth — bin 的宽度 标量

BinEdges — bin 的边界 数值向量

Normalization — 归一化类型 'count' （默认） | 'probability' | 'countdensity' | 'pdf' | 'cumcount' | 'cdf'

NumBins — bin 数量 正整数

输出参数

N — bin 计数 行向量

edges — bin 边界 向量

bin — bin 索引 数组

Categories — 计数中包含的类别 字符向量元胞向量

提示

扩展功能

tall 数组 对行数太多而无法放入内存的数组进行计算。

C/C++ 代码生成 使用 MATLAB® Coder™ 生成 C 代码和 C++ 代码。

GPU 代码生成 使用 GPU Coder™ 为 NVIDIA® GPU 生成 CUDA® 代码。

基于线程的环境 使用 MATLAB® backgroundPool 在后台运行代码或使用 Parallel Computing Toolbox™ ThreadPool 加快代码运行速度。

GPU 数组 通过使用 Parallel Computing Toolbox™ 在图形处理单元 (GPU) 上运行来加快代码执行。

版本历史记录

R2023a: 改进了使用少量数值和逻辑值输入数据时的性能

另请参阅

主题

WeChat

`X` — 要分布到各 bin 的数据
向量 | 矩阵 | 多维数组

`C` — 分类数据
分类数组

`nbins` — bin 数量
正整数

`edges` — bin 边界
向量

`Categories` — 计数中包含的类别
所有类别（默认） | 字符串向量 | 字符向量元胞向量 | `pattern` 标量 | 分类向量

`BinLimits` — bin 范围
二元素向量

`BinMethod` — 分 bin 算法
`'auto'` （默认） | `'scott'` | `'fd'` | `'integers'` | `'sturges'` | `'sqrt'` | ...

`BinWidth` — bin 的宽度
标量

`BinEdges` — bin 的边界
数值向量

`Normalization` — 归一化类型
`'count'` （默认） | `'probability'` | `'countdensity'` | `'pdf'` | `'cumcount'` | `'cdf'`

`NumBins` — bin 数量
正整数

`N` — bin 计数
行向量

`edges` — bin 边界
向量

`bin` — bin 索引
数组

`Categories` — 计数中包含的类别
字符向量元胞向量

tall 数组
对行数太多而无法放入内存的数组进行计算。

C/C++ 代码生成
使用 MATLAB® Coder™ 生成 C 代码和 C++ 代码。

GPU 代码生成
使用 GPU Coder™ 为 NVIDIA® GPU 生成 CUDA® 代码。

基于线程的环境
使用 MATLAB® `backgroundPool` 在后台运行代码或使用 Parallel Computing Toolbox™ `ThreadPool` 加快代码运行速度。

GPU 数组
通过使用 Parallel Computing Toolbox™ 在图形处理单元 (GPU) 上运行来加快代码执行。