# histcounts

## 语法

``[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 的宽度。`

## 示例

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

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

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

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

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

`count = nnz(bin==3)`
```count = 8 ```

```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'} ```

## 输入参数

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

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

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

### 名称-值参数

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

• 对于 `datetime``duration` 数据，`BinWidth` 可以是标量持续时间或日历持续时间。

• 如果用 `BinMethod``NumBins``BinEdges` 指定 `BinWidth`，则 `histcounts` 仅采用最后一个参数。

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

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

• 如果用 `BinMethod``BinWidth``NumBins``BinLimits` 指定 `BinEdges`，则 `histcounts` 只采用 `BinEdges` 且必须最后指定 `BinEdges`

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

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

`'auto'`

`'scott'`

`'fd'`

`'integers'`

`'integers'` 不支持日期时间和持续时间数据。

`'sturges'`

`'sqrt'`

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

`"second"`

`datetime``duration`
`"minute"`

`datetime``duration`
`"hour"`

`datetime``duration`
`"day"`

`datetime``duration`
`"week"`每个 bin 是 1 个日历周。仅限 `datetime`
`"month"`每个 bin 是 1 个日历月。仅限 `datetime`
`"quarter"`每个 bin 是 1 个日历季度。仅限 `datetime`
`"year"`

`datetime``duration`
`"decade"`每个 bin 是 1 个十年（10 个日历年）。仅限 `datetime`
`"century"`每个 bin 是 1 个世纪（100 个日历年）。仅限 `datetime`

• 如果为 `datetime``duration` 数据指定 `BinMethod`，则 `histcounts` 最多可以使用 65,536（即 216）个 bin。如果指定的 bin 持续时间需要多个 bin，则 `histcounts` 使用与最大 bin 数对应的较大的 bin 宽度。

• 如果指定 `BinLimits``NumBins``BinEdges``BinWidth`，则 `BinMethod` 设置为 `'manual'`

• 如果用 `BinWidth``NumBins``BinEdges` 指定 `BinMethod`，则 `histcounts` 仅采用最后一个参数。

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

• ${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\text{\hspace{0.17em}}\text{\hspace{0.17em}}\cdot \text{\hspace{0.17em}}\text{\hspace{0.17em}}\text{\hspace{0.17em}}{w}_{i}}$`

• 概率密度函数的估计值。

• 对于分类数据，这与 `'probability'` 相同。

• `'pdf'` 不支持 `datetime``duration` 数据。

• bin 面积的总和最多为 `1`

`'cdf'`

`${v}_{i}=\sum _{j=1}^{i}\text{\hspace{0.17em}}\frac{{c}_{j}}{N}$`

• 累积分布函数估算值。

• 每个 bin 的计数等于该 bin 及前面所有 bin 中累积的相对观测值数量。

• `N(end)` 最多为 1。

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

• 如果用 `BinMethod``BinWidth``BinEdges` 指定 `NumBins`，则 `histcounts` 仅采用最后一个参数。

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

## 输出参量

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

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

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

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

## 提示

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