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。

示例

[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) 使用一个或多个名称-值参量指定其他参数。例如，您可以将 BinWidth 指定为一个标量来调整数值数据的 bin 的宽度。

示例

全部折叠

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 = 1×27 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 = 1×3 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 的右边界。

每个 bin 都包含左边界，但不包含右边界，除了同时包含两个边界的最后一个 bin 外。

对于 datetime 和 duration 数据，edges 必须为单调递增顺序的 datetime 或 duration 向量。

`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。

`BinWidth` — bin 的宽度
正标量

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

对于 datetime 和 duration 数据，BinWidth 可以是标量持续时间或日历持续时间。
如果用 BinMethod、NumBins 或 BinEdges 指定 BinWidth，则 histcounts 仅采用最后一个参数。
此选项不适用于分类数据。

示例: histcounts(X,'BinWidth',5) 使用宽度为 5 的 bin。

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

bin 的边界，指定为数值向量。第一个元素指定第一个 bin 的左边界。最后一个元素指定最后一个 bin 的右边界。仅最后一个 bin 包含右边界。

如果不指定 bin 边界，则 histcounts 自动确定 bin 边界。

如果 BinCountsMode 是 "manual"，则 BinEdges 必须为行向量。

如果用 BinMethod、BinWidth、NumBins 或 BinLimits 指定 BinEdges，则 histcounts 只采用 BinEdges 且必须最后指定 BinEdges。
此选项不适用于分类数据。

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

bin 范围，指定为二元素向量 [bmin,bmax]。第一个元素指示第一个 bin 边界。第二个元素指示最后一个 bin 边界。

此选项仅使用在 bin 范围 X>=bmin & X<=bmax（包含这两个边界值）内的数据进行计算。

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

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

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

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

值	描述
`'auto'`	默认的 `'auto'` 算法选择一个 bin 宽度，以便涵盖数据范围并显示基础分布形状。
`'scott'`	如果数据接近正态分布，则斯科特规则最佳。该规则也适用于大多数的其他分布。它使用 bin 宽度 `3.5std(X(:))numel(X)^(-1/3)`。
`'fd'`	弗里德曼-迪亚科尼斯规则对数据中的离群值不太敏感，可能更适用于重尾分布的数据。它使用的 bin 宽度为 `2iqr(X(:))numel(X)^(-1/3)`；如果 `X` 包含极端离群值，则使用 `0.2(max(X(:))-min(X(:)))numel(X)^(-1/3)`。
`'integers'`	整数规则对整数数据有用，因为它为每个整数创建一个 bin。它使用 bin 宽度 1 并将 bin 边界放在整数的中间。为避免无意间创建太多 bin，可以使用该规则创建 65536 (2¹⁶) 个 bin 的限制。如果数据范围大于 65536，则整数规则改用更宽的 bin。 `'integers'` 不支持日期时间和持续时间数据。
`'sturges'`	斯特吉斯规则因其简单性而广受欢迎。它选择的 bin 数量为 `ceil(1 + log2(numel(X)))` 或 `1`，取两者中的较大者。
`'sqrt'`	平方根规则是广泛用于其他软件包。它选择的 bin 数量为 `ceil(sqrt(numel(X)))` 或 `1`，取两者中的较大者。

histcounts 稍微调整 bin 的数目，使 bin 边界落在“合适”的数字上，而不是机械遵循这些精确的公式。

对于 datetime 或 duration 数据，将分 bin 算法指定为下列时间单位之一。

值	描述	数据类型
`"second"`	每个 bin 是 1 秒。	`datetime` 和 `duration`
`"minute"`	每个 bin 是 1 分钟。	`datetime` 和 `duration`
`"hour"`	每个 bin 是 1 小时。	`datetime` 和 `duration`
`"day"`	每个 bin 表示 1 个日历日。此值将夏令时变化考虑在内。	`datetime` 和 `duration`
`"week"`	每个 bin 是 1 个日历周。	仅限 `datetime`
`"month"`	每个 bin 是 1 个日历月。	仅限 `datetime`
`"quarter"`	每个 bin 是 1 个日历季度。	仅限 `datetime`
`"year"`	每个 bin 表示 1 个日历年。此值将闰日考虑在内。	`datetime` 和 `duration`
`"decade"`	每个 bin 是 1 个十年（10 个日历年）。	仅限 `datetime`
`"century"`	每个 bin 是 1 个世纪（100 个日历年）。	仅限 `datetime`

如果为 datetime 或 duration 数据指定 BinMethod，则 histcounts 最多可以使用 65,536（即 2¹⁶）个 bin。如果指定的 bin 持续时间需要多个 bin，则 histcounts 使用与最大 bin 数对应的较大的 bin 宽度。
如果指定 BinLimits、NumBins、BinEdges 或 BinWidth，则 BinMethod 设置为 'manual'。
如果用 BinWidth、NumBins 或 BinEdges 指定 BinMethod，则 histcounts 仅采用最后一个参数。
此选项不适用于分类数据。

示例: histcounts(X,'BinMethod','integers') 将 bin 以整数为中心放置。

`Normalization` — 归一化类型
`'count'` (默认) | `'probability'` | `'percentage'` | `'countdensity'` | `'cumcount'` | `'pdf'` | `'cdf'`

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

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

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

示例: histcounts(X,'Normalization','pdf') 使用概率密度函数估计值对数据进行分 bin。

`NumBins` — bin 数量
正整数

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

如果用 BinMethod、BinWidth 或 BinEdges 指定 NumBins，则 histcounts 仅采用最后一个参数。
此选项不适用于分类数据。

输出参量

全部折叠

`N` — bin 计数
行向量

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

`edges` — bin 边界
向量

bin 边界，以向量形式返回。第一个元素是第一个 bin 的左边界。最后一个元素是最后一个 bin 的右边界。

`bin` — bin 索引
数组

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

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

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

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

提示

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

扩展功能

全部展开

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

histcounts 函数支持 tall 数组，但存在以下使用说明和限制：

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

有关详细信息，请参阅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) 上运行来加快代码执行。

histcounts 函数支持 GPU 数组输入，但有以下用法说明和限制：

不支持 64 位整数。

有关详细信息，请参阅在 GPU 上运行 MATLAB 函数 (Parallel Computing Toolbox)。

版本历史记录

在 R2014b 中推出

全部展开

R2023b: 使用百分比进行归一化

通过将 Normalization 名称-值参量指定为 'percentage'，可以将直方图值归一化为百分比。

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 | kde

主题

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

histcounts

语法

说明

示例

bin 计数和 bin 边界

指定 bin 数

指定 bin 边界

归一化的 bin 计数

确定 bin 放置

分类 bin 计数

输入参数

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

C — 分类数据 分类数组

nbins — bin 数量 正整数

edges — bin 边界 向量

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

名称-值参数

BinWidth — bin 的宽度 正标量

BinEdges — bin 的边界 数值向量

BinLimits — bin 范围 二元素向量

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

Normalization — 归一化类型 'count' (默认) | 'probability' | 'percentage' | 'countdensity' | 'cumcount' | 'pdf' | '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) 上运行来加快代码执行。

版本历史记录

R2023b: 使用百分比进行归一化

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

另请参阅

主题

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

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

`nbins` — bin 数量
正整数

`edges` — bin 边界
向量

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

`BinWidth` — bin 的宽度
正标量

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

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

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

`Normalization` — 归一化类型
`'count'` (默认) | `'probability'` | `'percentage'` | `'countdensity'` | `'cumcount'` | `'pdf'` | `'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) 上运行来加快代码执行。