histcounts

R2026b

直方图箱计数

全页折叠

语法

[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 值划分为若干个箱，并返回箱计数和箱边界。histcounts 函数使用自动分箱算法，然后返回所选的均匀箱，这些箱可涵盖 X 中元素的范围并显示分布的基本形状。

示例

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

示例

[N,edges] = histcounts(X,edges) 将 X 划分为由向量 edges 来指定箱边界的箱。

示例

[N,edges,bin] = histcounts(___) 支持任何上述语法，且可返回索引数组 bin。bin 是大小与 X 相同的数组，其元素是 X 中的对应元素的箱索引。第 k 个箱中的元素数量是 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 指定为一个标量来调整数值数据的箱的宽度。

示例

全部折叠

箱计数和箱边界

打开实时脚本

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

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

指定箱数

打开实时脚本

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

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

指定箱边界

打开实时脚本

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

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

归一化的箱计数

打开实时脚本

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

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

确定箱放置

打开实时脚本

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

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

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

count = nnz(bin==3)

count = 
8

分类箱计数

打开实时脚本

创建一个表示投票的分类向量。该向量中的类别是 '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` — 要分布到各箱的数据
向量 | 矩阵 | 多维数组

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

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

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

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

数据类型: categorical

`nbins` — 箱数
正整数

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

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

`edges` — 箱边界
向量

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

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

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

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

计数中包含的类别，指定为字符串向量、字符向量的元胞向量、pattern 标量或分类向量。默认情况下，histcounts 对分类数组 C 中的每个类别使用一个箱，而使用 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 中的箱计数进行归一化，这样 sum(N) 为 1。

`BinWidth` — 箱的宽度
正标量

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

`NumBins` — 箱数
正整数

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

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

输出参量

全部折叠

`N` — 箱计数
行向量

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

`edges` — 箱边界
向量

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

`bin` — 箱索引
数组

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

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

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

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

提示

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

扩展功能

全部展开

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

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

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

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

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

用法说明和限制：

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

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

用法说明和限制：

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

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

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

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

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

不支持 64 位整数。

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

版本历史记录

在 R2014b 中推出

全部展开

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

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

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

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

例如，以下代码计算一个包含 1000 个元素的向量的直方图箱计数。该代码比上一版本大约快 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

语法

描述

示例

箱计数和箱边界

指定箱数

指定箱边界

归一化的箱计数

确定箱放置

分类箱计数

输入参数

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

C — 分类数据 分类数组

nbins — 箱数 正整数

edges — 箱边界 向量

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

名称-值参数

BinWidth — 箱的宽度 正标量

BinEdges — 箱的边界 数值向量

BinLimits — 箱范围 二元素向量

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

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

NumBins — 箱数 正整数

输出参量

N — 箱计数 行向量

edges — 箱边界 向量

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` — 要分布到各箱的数据
向量 | 矩阵 | 多维数组

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

`nbins` — 箱数
正整数

`edges` — 箱边界
向量

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

`BinWidth` — 箱的宽度
正标量

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

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

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

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

`NumBins` — 箱数
正整数

`N` — 箱计数
行向量

`edges` — 箱边界
向量

`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) 上运行来加快代码执行。