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 の値をビンに分割し、ビンのカウント数とビンのエッジを返します。関数 histcounts は、均一なビンを返す自動ビン化アルゴリズムを使用します。X の要素の範囲をカバーし、分布の基本的な形状を明らかにするビンが選択されます。

[N,edges] = histcounts(X,nbins) はスカラー nbins によって指定された数のビンを使用します。

[N,edges] = histcounts(X,edges) はベクトル edges によって指定されたエッジをもつビンに X を並べ替えます。

[N,edges,bin] = histcounts(___) は前述の任意の構文を使用し、さらにインデックス配列 bin を返します。bin は X と同じサイズの配列であり、その要素は X の対応する要素のビンのインデックスです。k 番目のビンの要素の数は nnz(bin==k) であり、これは N(k) と同じです。

N = histcounts(C) は、ベクトル N を返します。ここで、C は categorical 配列であり、ベクトル N は C の各カテゴリと等しい値をもつ C の要素の数を示します。このベクトルには、C のカテゴリごとに要素が 1 つあります。

N = histcounts(C,Categories) は、Categories で指定されたカテゴリのサブセットに等しい値をもつ C の要素のみをカウントします。

[N,Categories] = histcounts(___) は、categorical 配列に関する前述の構文のいずれかを使用して、N の各カウントに対応するカテゴリも返します。

[___] = histcounts(___,Name,Value) は、1 つ以上の名前と値の引数を使用して追加のパラメーターを指定します。たとえば、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 の 3 番目の出力を指定します。

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

ビンのインデックス ベクトル bin で番号 3 の出現数をカウントすることにより、3 番目のビンのカウント数を求めます。結果は N(3) と同じになります。

count = nnz(bin==3)

count = 
8

カテゴリカル ビンのカウント数

投票を表す categorical ベクトルを作成します。ベクトルのカテゴリは、'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 はそれを 1 つの列ベクトル X(:) として扱います。

histcounts はすべての NaN 値を無視します。同様にビンのエッジとして明示的に Inf または -Inf を指定しない限り、histcounts は Inf 値および -Inf 値を無視します。

データ型: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | logical | datetime | duration

C — categorical データ

categorical 配列

カテゴリカル データ。categorical 配列として指定します。histcounts は未定義のカテゴリカル値を無視します。

データ型: categorical

nbins — ビンの数

正の整数

ビンの数。正の整数として指定します。nbins を指定しない場合、histcounts は X の値に基づいて使用するビンの数を自動的に計算します。

例: [N,edges] = histcounts(X,15) は 15 個のビンを使用します。

edges — ビンのエッジ

ベクトル

ビンのエッジ。ベクトルとして指定します。edges(1) は最初のビンの先頭のエッジ、edges(end) は最後のビンの後方のエッジです。

それぞれのビンは先頭のエッジを含み、後方のエッジを含みませんが、例外として最後のビンは両方のエッジを含みます。

datetime データおよび duration データの場合、edges は順に単調増加する datetime ベクトルまたは duration ベクトルでなければなりません。

Categories — カウントに含まれるカテゴリ

すべてのカテゴリ (既定値) | string ベクトル | 文字ベクトルの cell ベクトル | pattern スカラー | categorical ベクトル

カウントに含まれるカテゴリ。string ベクトル、文字ベクトルの cell ベクトル、pattern スカラー、または categorical ベクトルとして指定します。既定では、histcounts は categorical 配列 C のカテゴリ 1 つにつきビンを 1 つ使用します。カテゴリの一意のサブセットを指定するには、Categories を使用します。

例: h = histcounts(C,["Large","Small"]) は、カテゴリ Large および Small の categorical データのみをカウントします。

例: h = histcounts(C,"Y" + wildcardPattern) は、名前が文字 Y で始まるすべてのカテゴリにある categorical データをカウントします。

データ型: string | cell | pattern | categorical

名前と値の引数

オプションの引数のペアを Name1=Value1,...,NameN=ValueN として指定します。ここで、Name は引数名で、Value は対応する値です。名前と値の引数は他の引数の後に指定しなければなりませんが、ペアの順序は重要ではありません。

R2021a より前では、コンマを使用して名前と値をそれぞれ区切り、Name を引用符で囲みます。

例: [N,edges] = histcounts(X,'Normalization','probability') は、sum(N) が 1 になるようにビンのカウント数を N で正規化します。

BinWidth — ビンの幅

正のスカラー

ビンの幅。正のスカラーとして指定します。BinWidth を指定する場合、histcounts は最大 65,536 (2¹⁶) 個のビンを使用できます。指定したビンの幅によってさらに多くのビンが必要となる場合、histcounts はビンの最大数に対応する、より大きいビンの幅を使用します。

• datetime データおよび duration データの場合、BinWidth をスカラー duration またはカレンダー期間にすることができます。

• BinWidth を BinMethod、NumBins、または BinEdges と一緒に指定した場合、histcounts は最後のパラメーターのみに従います。

• このオプションは、カテゴリカル データには適用されません。

例: histcounts(X,'BinWidth',5) は幅が 5 のビンを使用します。

BinEdges — ビンのエッジ

数値ベクトル

ビンのエッジ。数値ベクトルとして指定します。最初の要素は最初のビンの先頭のエッジを指定します。最後の要素は最後のビンの後方のエッジを指定します。後方のエッジは最後のビンにのみ含まれます。

ビンのエッジを指定しない場合、histcounts は自動的にビンのエッジを決定します。

BinCountsMode が "manual" の場合、BinEdges は行ベクトルでなければなりません。

• BinEdges を BinMethod、BinWidth、NumBins、または BinLimits と一緒に指定した場合、histcounts は BinEdges のみに従い、BinEdges は最後に指定する必要があります。

• このオプションは、カテゴリカル データには適用されません。

BinLimits — ビンの範囲

2 要素ベクトル

ビンの範囲。2 要素ベクトル [bmin,bmax] として指定します。最初の要素は最初のビンのエッジを示します。2 番目の要素は最後のビンのエッジを示します。

このオプションを使用すると、ビンの範囲 X>=bmin & X<=bmax に含まれるデータのみを使用して計算します。

このオプションは、カテゴリカル データには適用されません。

例: histcounts(X,'BinLimits',[1,10]) は 1 以上 10 以下の X の値のみをビンに入れます。

BinMethod — ビン化アルゴリズム

'auto' (既定値) | 'scott' | 'fd' | 'integers' | 'sturges' | 'sqrt' | ...

ビン化アルゴリズム。次の表のいずれかの値を指定します。

値	説明
'auto'	既定値の 'auto' アルゴリズムは、データの範囲をカバーするビンの幅を選択することで、基となる分布の形状を明らかにします。
'scott'	スコットの法則はデータが正規分布に近い場合に最適です。この規則は他の多くの分布にも適しています。ビンの幅として 3.5*std(X(:))*numel(X)^(-1/3) を使用します。
'fd'	Freedman-Diaconis の法則は、データの外れ値の影響を受けにくく、裾が大きい分布をもつデータにより適しています。ビンの幅として 2*iqr(X(:))*numel(X)^(-1/3) を使用します。X に極端な外れ値がある場合は 0.2*(max(X(:))-min(X(:)))*numel(X)^(-1/3) を使用します。
'integers'	整数ルールは整数ごとにビンを作成するため整数データで役立ちます。幅が 1 のビンを使用し、ビンのエッジを整数の中間に設定します。 誤って多すぎるビンを作成しないように、このルールを使用して作成するビンを 65536 (216) 個以下に制限できます。データの範囲が 65,536 よりも大きい場合、整数ルールは代わりに幅の広いビンを使用します。 'integers' は datetime データまたは duration データをサポートしません。
'sturges'	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"	各ビンは 10 年 (10 カレンダー年) です。	datetime のみ
"century"	各ビンは 1 世紀 (100 カレンダー年) です。	datetime のみ

• datetime または duration データに対して BinMethod を指定する場合、histcounts は最大 65,536 個 (2¹⁶) のビンを使用できます。指定したビンの期間にさらに多くのビンが必要となる場合、histcounts はビンの最大数に対応する、より大きいビンの幅を使用します。

• BinLimits、NumBins、BinEdges、または BinWidth を指定すると、BinMethod は 'manual' に設定されます。

• BinMethod を BinWidth、NumBins、または BinEdges と一緒に指定した場合、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)、categorical データの場合は sum(ismember(X(:),'Categories')) です。合計がこれより小さくなるのは、一部の入力データがビンに含まれていない場合のみです。
'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}$$	ビンの幅でスケーリングされたカウント数または頻度。 categorical データの場合、これは、'count' と同じです。 'countdensity' は、datetime データも duration データもサポートしません。 ビンの面積の合計は最大で numel(X) です。
'cumcount'	$$v_i={\displaystyle \sum _{j=1}^i{c}_j}$$	累積カウント数、つまり各ビンとそれ以前のすべてのビンの観測数です。 N(end) は最大で numel(X)、categorical データの場合は sum(ismember(X(:),'Categories')) です。
'pdf'	$$v_i=\frac{c_i}{N\cdot w_i}$$	確率密度関数の推定値です。 カテゴリカル データの場合、これは、'probability' と同じです。 'pdf' は、datetime データも duration データもサポートしません。 ビンの面積の合計は最大で 1 です。
'cdf'	$$v_i={\displaystyle \sum _{j=1}^i\frac{c_j}{N}}$$	累積分布関数の推定値です。 それぞれのビンのカウント数は、そのビンとそれ以前のすべてのビンの相対的な観測数の累積と等しくなります。 N(end) は最大で 1 です。

例: histcounts(X,'Normalization','pdf') は、確率密度関数の推定値を使用してデータをビン化します。

NumBins — ビンの数

正の整数

ビンの数。正の整数として指定します。NumBins を指定しない場合、histcounts は使用するビンの数を入力データに基づいて自動的に計算します。

• NumBins を BinMethod、BinWidth、または BinEdges と一緒に指定した場合、histcounts は最後のパラメーターのみに従います。

• このオプションは、カテゴリカル データには適用されません。

出力引数

N — ビンのカウント数

行ベクトル

ビンのカウント数。行ベクトルとして返されます。

edges — ビンのエッジ

ベクトル

ビン エッジ。ベクトルとして返されます。最初の要素は最初のビンの先頭のエッジです。最後の要素は最後のビンの後方のエッジです。

bin — ビンのインデックス

配列

ビンのインデックス。X と同じサイズの配列として返されます。bin の各要素は、対応する X の要素を格納するビンの番号を記述します。

bin の 0 の値はその要素がどのビンにも属していないことを示します(たとえば NaN 値)。

Categories — カウントに含まれるカテゴリ

文字ベクトルの cell ベクトル

カウントに含まれるカテゴリ。文字ベクトルの cell ベクトルとして返されます。Categories には、N の各カウントに対応する C のカテゴリが含まれます。

ヒント

• histcounts の動作は、関数 discretize の動作と似ています。各ビンの要素数を調べるには、histcounts を使用します。一方、各要素が属するビンを調べる (要素数のカウントはしない) には、discretize を使用します。

拡張機能

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: 小さい数値および logical 入力データでのパフォーマンスの向上

より高速な入力解析により、数値および logical データでの関数 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 インスタンスの置き換え