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 を並べ替えます。edges(k) ≤ X(i) < edges(k+1) の場合、値 X(i) は k 番目のビンに含まれます。最後のビンにはビンの右端も含まれるため、edges(end-1) ≤ X(i) ≤ edges(end) の場合に X(i) が含まれます。

[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 つ以上の Name,Value のペアの引数で指定される追加のオプションを使用します。たとえば、'BinWidth' とスカラーを指定して、数値データのビンの幅を調整できます。カテゴリカル データの場合、'Normalization' と、'count'、'countdensity'、'probability'、'pdf'、'cumcount'、'cdf' のいずれかを指定できます。

例

ビンのカウント数とビンのエッジ

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

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

投票を表すカテゴリカル ベクトルを作成します。ベクトルのカテゴリは、'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
  Columns 1 through 9

     no      no      yes      yes      yes      no      no      no      no 

  Columns 10 through 16

     undecided      undecided      yes      no      no      no      yes 

  Columns 17 through 25

     no      yes      no      yes      no      no      no      yes      yes 

  Columns 26 through 27

     yes      yes 

各カテゴリに分類される要素数を求めます。

[N,Categories] = histcounts(C)

N = 1×3

    11    14     2

Categories = 1x3 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 ベクトルでなければなりません。

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

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

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

カウントに含まれるカテゴリ。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 で正規化します。

BinLimits — ビンの範囲

2 要素ベクトル

ビンの範囲。2 要素ベクトル [bmin,bmax] として指定します。このオプションは bmin 以上 bmax 以下の X の値、つまり X(X>=bmin & X<=bmax) の値のみをビンに入れます。

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

例: [N,edges] = 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) を使用します。ここで IQR は X の四分位数間範囲です。
'integers'	整数ルールは整数ごとにビンを作成するため整数データで役立ちます。幅が 1 のビンを使用し、ビンのエッジを整数の中間に設定します。誤って多すぎるビンを作成しないように、このルールを使用して作成するビンを 65536 (216) 個以下に制限できます。データの範囲が 65,536 を超える場合は、より幅の広いビンが代わりに使用されます。 メモ 'integers' は datetime データまたは duration データをサポートしません。
'sturges'	Sturges の法則は簡単なルールであるためよく用いられています。ビンの数として ceil(1 + log2(numel(X))) を選択します。
'sqrt'	平方根ルールも簡単なルールであり、他のソフトウェア パッケージで広く使用されています。ビンの数として ceil(sqrt(numel(X))) を選択します。

histcounts は、これらの式を厳密に使用してビンの数を選択するとは限りません。場合によっては、ビンのエッジが "きりのよい" 数字になるように、ビンの数がわずかに調整されることがあります。

datetime データの場合、ビン メソッドを次の時間単位のいずれかにすることができます。

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

duration データの場合、ビン メソッドを次の時間単位のいずれかにすることができます。

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

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

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

例: [N,edges] = histcounts(X,'BinMethod','integers') は整数を中心とするビンを使用します。

BinWidth — ビンの幅

スカラー

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

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

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

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

BinEdges — ビンのエッジ

数値ベクトル

ビンのエッジ。数値ベクトルとして指定します。ベクトルの最初の要素は最初のビンの左の端を指定します。最後の要素は最後のビンの右の端を指定します。ビンのエッジを指定しない場合、histcounts は自動的にビンのエッジの位置を決定します。

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

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

Normalization — 正規化のタイプ

'count' (既定値) | 'probability' | 'countdensity' | 'pdf' | 'cumcount' | 'cdf'

正規化のタイプ。次の表のいずれかの値を指定します。各ビン i に対して次のようになります。

• $$v_i$$ はビンの値です。

• $$c_i$$ はビン内の要素数です。

• $$w_i$$ はビンの幅です。

• $$N$$ は入力データ内の要素数です。データに NaN、NaT、または <undefined> 値が含まれる場合、あるいは一部のデータがビンの範囲外にある場合、この値はビン化されたデータより大きくなることがあります。

値	ビンの値	メモ
'count' (既定)	$$v_i=c_i$$	観測のカウント数または頻度。 ビンの値の合計は numel(X) 以下です。一部の入力データがビンに含まれていない場合にのみ、合計は numel(X) 未満になります。 カテゴリカル データの場合、ビンの値の合計は numel(X) または sum(ismember(X(:),Categories)) です。
'countdensity'	$$v_i=\frac{c_i}{w_i}$$	ビンの幅でスケーリングされたカウント数または頻度。 カテゴリカル データの場合、これは、'count' と同じです。 メモ 'countdensity' は datetime データまたは duration データをサポートしません。
'cumcount'	$$v_i={\displaystyle \sum _{j=1}^i{c}_j}$$	累積カウント数。各ビンの値は、そのビンとその前にあるすべてのビンの累積観測数です。 最後のビンの値は、numel(X) 以下です。 カテゴリカル データの場合、最後のビンの値は numel(X) 以下または sum(ismember(X(:),Categories)) 以下です。
'probability'	$$v_i=\frac{c_i}{N}$$	相対的確率。 ビンの値の合計は、1 以下です。
'pdf'	$$v_i=\frac{c_i}{N\cdot w_i}$$	確率密度関数の推定値です。 カテゴリカル データの場合、これは、'probability' と同じです。 メモ 'pdf' は datetime データまたは duration データをサポートしません。
'cdf'	$$v_i={\displaystyle \sum _{j=1}^i\frac{c_j}{N}}$$	累積密度関数の推定値です。 N(end) は 1 以下です。

例: [N,edges] = histcounts(X,'Normalization','pdf') は確率密度関数の推定値を使用してデータをビンに入れます。

NumBins — ビンの数

正の整数

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

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

出力引数

N — ビンのカウント数

行ベクトル

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

edges — ビンのエッジ

ベクトル

ビンのエッジ。ベクトルとして返されます。edges(1) は最初のビンの左の端、edges(end) は最後のビンの右の端です。

bin — ビンのインデックス

配列

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

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

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

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

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

ヒント

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

拡張機能

tall 配列

メモリの許容量を超えるような多数の行を含む配列を計算します。

使用上の注意事項および制限事項:

• 一部の入力オプションはサポートされていません。使用可能なオプションは次のとおりです。

  • 'BinWidth'

  • 'BinLimits'

  • 'Normalization'

  • 'BinMethod' — 'auto' ビン メソッドと 'scott' ビン メソッドは同じです。'fd' ビン メソッドはサポートされていません。

• 入力引数 Categories はパターン式をサポートしません。

詳細については、tall 配列を参照してください。

C/C++ コード生成

MATLAB® Coder™ を使用して C および C++ コードを生成します。

使用上の注意事項および制限事項:

• コード生成では、この関数のスパース行列入力はサポートされません。

• ビンのエッジを指定しない場合、コード生成で可変サイズ配列および動的メモリ割り当てが必要になることがあります。

• 入力引数 Categories はパターン式をサポートしません。

GPU コード生成

GPU Coder™ を使用して NVIDIA® GPU のための CUDA® コードを生成します。

使用上の注意事項および制限事項:

• コード生成では、この関数のスパース行列入力はサポートされません。

• ビンのエッジを指定しない場合、コード生成で可変サイズ配列および動的メモリ割り当てが必要になることがあります。

• 入力引数 Categories はパターン式をサポートしません。

スレッドベースの環境

MATLAB® の backgroundPool を使用してバックグラウンドでコードを実行するか、Parallel Computing Toolbox™ の ThreadPool を使用してコードを高速化します。

この関数はスレッドベースの環境を完全にサポートしています。詳細については、スレッドベースの環境での MATLAB 関数の実行を参照してください。

GPU 配列

Parallel Computing Toolbox™ を使用してグラフィックス処理装置 (GPU) 上で実行することにより、コードを高速化します。

使用上の注意事項および制限事項:

• 64 ビット整数はサポートされません。

詳細については、GPU での MATLAB 関数の実行 (Parallel Computing Toolbox)を参照してください。

バージョン履歴

R2014b で導入

参考

histogram | histogram2 | discretize | histcounts2

トピック

• 推奨されない hist および histc インスタンスの置き換え

×

例を開く

この例の変更されたバージョンがあります。編集された方の例を開きますか?

いいえ、変更されたバージョンを上書きします。 はい