accumarray

ベクトル要素の累積

構文

B = accumarray(ind,data)

B = accumarray(ind,data,sz)

B = accumarray(ind,data,sz,fun)

B = accumarray(ind,data,sz,fun,fillval)

B = accumarray(ind,data,sz,fun,fillval,issparse)

説明

B = accumarray(ind,data) は、ind で指定されたグループに従ってベクトル data の要素の累積を行い、データのグループを合計します。その後、各グループについて合計が計算されます。ind の値で、データが属するグループと各グループの合計が格納される出力配列 B のインデックスの両方を定義します。

グループの合計を順番に返すには、ind をベクトルとして指定します。この場合、accumarray は、インデックスが i のグループの合計を B(i) に返します。たとえば、ind = [1 1 2 2]'、data = [1 2 3 4]' の場合、B = accumarray(ind,data) は列ベクトル B = [3 7]' を返します。

グループの合計を別の形状で返すには、ind を行列として指定します。ind が m 行 n 列の行列である場合、各行はグループの割り当てと出力 B に対する n 次元のインデックスを表します。たとえば、ind に [3 4] の形式で 2 つの行が含まれている場合、data の対応する要素の合計が B の (3,4) の要素に格納されます。

インデックスが ind に現れない B の要素は、既定では 0 で埋められます。

B = accumarray(ind,data,sz) は、サイズが sz になるようにパディングされた配列 B を返します。sz は、ind の次元の長さと一致するかそれを超える正の整数のベクトルとして指定します。出力の余分な要素は 0 で埋められます。ind のインデックスに応じて出力のサイズを決定するには、sz を [] として指定します。

B = accumarray(ind,data,sz,fun) は、ind で指定された data の各グループに関数 fun を適用します。@ 記号を使用して fun を指定するか (たとえば、@mean)、あるいは [] を指定して既定の @sum を使用します。

B = accumarray(ind,data,sz,fun,fillval) は、ind のインデックスで参照されていない B の要素をすべてスカラー値 fillval で埋めます。fillval を [] と指定すると、既定値 0 が使用されます。

B = accumarray(ind,data,sz,fun,fillval,issparse) は配列 B を返します。これは、issparse が true または 1 の場合はスパース、issparse が false または 0 の場合は非スパースになります。既定の設定では、出力 B は非スパースです。

例

グループ別のデータの合計

データのベクトル、およびグループを定義する対応するベクトル ind を作成します。

data = (1:6)'

data = 6×1

     1
     2
     3
     4
     5
     6

ind = [1 3 4 2 4 1]'

ind = 6×1

     1
     3
     4
     2
     4
     1

ind で指定されたグループ別に data の値を合計します。

B = accumarray(ind,data)

B = 4×1

     7
     4
     2
     8

あるいは、関数 groupsummary を使用し、グループの計算として 'sum' を指定します。

B = groupsummary(data,ind,'sum')

B = 4×1

     7
     4
     2
     8

グループの要素のカウント

グループのベクトルを作成します。

ind = [1 1 4 2 4 3]';

数値 1 にスカラー拡張を適用して、ind で定義された各グループの要素数をカウントします。

B = accumarray(ind,1)

B = 4×1

     2
     1
     1
     2

あるいは、関数 groupcounts を使用します。

B = groupcounts(ind)

B = 4×1

     2
     1
     1
     2

出力サイズの指定

データのベクトル、およびデータのグループを定義する出力インデックスの行列 ind を作成します。

data = 1:6

data = 1×6

     1     2     3     4     5     6

ind = [1 1; 2 2; 3 2; 1 1; 2 2; 4 1]

ind = 6×2

     1     1
     2     2
     3     2
     1     1
     2     2
     4     1

ind のグループごとに data の値を合計します。ind のインデックスにより、出力の位置の 4 行 2 列の行列が定義されます。

B1 = accumarray(ind,data)

B1 = 4×2

     5     0
     0     7
     0     3
     6     0

出力サイズを [4 4] と指定して、4 行 4 列の行列になるように出力をパディングします。

B2 = accumarray(ind,data,[4 4])

B2 = 4×4

     5     0     0     0
     0     7     0     0
     0     3     0     0
     6     0     0     0

グループ別の分散

グループの合計ではなく分散を計算します。

データのベクトル、およびデータのグループを定義する行列 ind を作成します。

data = [100.1 101.2 103.4 102.8 100.9 101.5]'

data = 6×1

  100.1000
  101.2000
  103.4000
  102.8000
  100.9000
  101.5000

ind = [1 1; 1 1; 2 2; 3 2; 2 2; 3 2]

ind = 6×2

     1     1
     1     1
     2     2
     3     2
     2     2
     3     2

関数ハンドル @var をメソッド入力として指定して各グループの分散を計算します。この構文は、sum の代わりに関数 var をグループに適用します。

B1 = accumarray(ind,data,[],@var)

B1 = 3×2

    0.6050         0
         0    3.1250
         0    0.8450

グループの計算は、ベクトル入力を受け取ってスカラーを返す無名関数として指定できます。これは追加の引数を関数に渡す場合などに便利です。たとえば、正規化の引数の値を 1 にして関数 var を使用します。

A2 = accumarray(ind,data,[],@(x) var(x,1))

A2 = 3×2

    0.3025         0
         0    1.5625
         0    0.4225

整数型の出力で合計を返す

メソッド入力に無名関数を使用して、関数 sum に追加の引数を指定します。

データのベクトル、およびデータのグループと出力の 3 次元インデックスを定義する行列 ind を作成します。

data = int8(10:15)

data = 1x6 int8 row vector

   10   11   12   13   14   15

ind = [1 1 1; 1 1 1; 1 1 2; 1 1 2; 2 3 1; 2 3 2]

ind = 6×3

     1     1     1
     1     1     1
     1     1     2
     1     1     2
     2     3     1
     2     3     2

関数 sum の 'native' オプションを使用して、ネイティブの整数クラス int8 でグループ別にデータを合計します。これを行うには、@(x) sum(x,'native') を使用する無名関数をメソッド入力に指定します。結果は int8 型の 2×3×2 の多次元配列になります。

B = accumarray(ind,data,[],@(x) sum(x,'native'))

B = 2x3x2 int8 array
B(:,:,1) =

   21    0    0
    0    0   14


B(:,:,2) =

   25    0    0
    0    0   15

cell 配列の値のグループ化

データのベクトル、およびデータのグループを定義する行列 ind を作成します。

data = 1:10

data = 1×10

     1     2     3     4     5     6     7     8     9    10

ind = [1 1; 1 1; 1 1; 1 1; 2 1; 2 1; 2 1; 2 1; 2 1; 2 2]

ind = 10×2

     1     1
     1     1
     1     1
     1     1
     2     1
     2     1
     2     1
     2     1
     2     1
     2     2

data の要素を cell 配列にグループ化します。

B = accumarray(ind,data,[],@(x) {x})

B=2×2 cell array
    {4x1 double}    {0x0 double}
    {5x1 double}    {[      10]}

ベクトルの要素の順序が data での出現順序と同じであることを確認します。

B{2,1}

ans = 5×1

     5
     6
     7
     8
     9

埋め込み値の指定

データのベクトル、およびデータのグループを定義する行列 ind を作成します。

data = (101:106)'

data = 6×1

   101
   102
   103
   104
   105
   106

ind = [1 1; 2 2; 3 3; 1 1; 2 2; 4 4]

ind = 6×2

     1     1
     2     2
     3     3
     1     1
     2     2
     4     4

ind の要素により、出力の 4 行 4 列の行列が定義されますが、参照される要素は 16 個のうち 4 個のみです。既定で、他の 12 個の要素は出力で 0 になります。それらの余分な出力要素を 0 の代わりに NaN 値で埋めます。

B = accumarray(ind,data,[],[],NaN)

B = 4×4

   205   NaN   NaN   NaN
   NaN   207   NaN   NaN
   NaN   NaN   103   NaN
   NaN   NaN   NaN   106

出力のスパース性の変更

データのベクトル、およびデータのグループを定義する行列 ind を作成します。

data = [34 22 19 85 53 77 99 6];
ind = [1 1; 400 400; 80 80; 1 1; 400 400; 400 400; 80 80; 1 1]

ind = 8×2

     1     1
   400   400
    80    80
     1     1
   400   400
   400   400
    80    80
     1     1

ind の要素により、出力の 400 行 400 列の行列が定義されますが、参照される要素は 160,000 個のうち 3 個のみです。accumarray の出力が非ゼロ要素の密度が低い大規模配列になる場合、issparse オプションを true と指定することで、非スパース行列の代わりにスパース行列を作成してメモリを節約できます。

B = accumarray(ind,data,[],[],[],true)

B = 
   (1,1)      125
  (80,80)     118
 (400,400)    152

入力引数

ind — 出力インデックス

ベクトル | 行列 | ベクトルの cell 配列

出力インデックス。ベクトル、行列、ベクトルの cell 配列として指定します。

• ind がベクトルの場合、各要素で出力のインデックスを指定し、accumarray で累積されるグループを定義します。いずれの要素も正の整数でなければならず、ind の長さはデータ ベクトルの長さと一致しなければなりません。

• ind が m 行 n 列の行列の場合、各行で出力の n 次元のインデックスを指定します。ind の i 番目の行がデータの i 番目の値に対応し、ind の行数はデータ ベクトルの長さと一致しなければなりません。たとえば、ind が 3 行 2 列の行列である場合、これには 3 つの 2 次元のインデックスが含まれます。各行の最初の要素が出力の行インデックスで、2 番目の要素が列インデックスです。

• ind がインデックス ベクトルの cell 配列の場合、各ベクトルは同じ長さでなければなりません。それぞれのベクトルが列として扱われます。

data — 累積するデータ

スカラー | ベクトル

累積するデータ。スカラーまたはベクトルとして指定します。

• data がスカラーの場合、その値がスカラー拡張されます。

• data がベクトルの場合、インデックス配列の行数と同じ長さでなければなりません。

sz — 出力配列のサイズ

[] (既定値) | 正の整数のベクトル

出力配列のサイズ。正の整数のベクトルまたは [] として指定します。たとえば、sz = [5 7] は 5 行 7 列の出力配列を生成します。サイズに [] を指定すると、インデックス配列の値によって出力のサイズが決まります。sz の次元の長さは、インデックス配列の次元の長さと一致するかそれを超えていなければなりません。

fun — グループの計算

[] (既定値) | 関数ハンドル

グループの計算。関数ハンドルとして指定します。accumarray は、データ ベクトルの要素をグループ別に累積した後、グループの要素に関数 fun を適用します。fun = [] を指定すると、既定の関数である sum が計算に使用されます。指定する関数は、列ベクトルを受け入れ、数値、logical または char スカラー、あるいはスカラー cell を返さなければなりません。関数ハンドルについての詳細は、関数ハンドルの作成を参照してください。

例: fun = @max

fillval — 埋め込み値

[] (既定値) | スカラー

出力の要素がインデックス配列で指定されたインデックスに対応しない場合の埋め込み値。スカラーまたは [] (既定値 0 を使用) として指定します。fillval のデータ型は計算関数の出力のデータ型と一致しなければなりません。

issparse — 出力のスパース性

false または 0 (既定値) | true または 1

出力のスパース性。数値または logical 1 (true) または 0 (false) として指定します。

issparse が true または 1 の場合、埋め込み値は 0 または [] でなければならず、計算関数の入力データと出力の両方が double 型でなければなりません。

出力引数

B — 出力配列

ベクトル | 行列 | 多次元配列

出力配列。ベクトル、行列、または多次元配列として返されます。B はグループ計算関数で返される値と同じデータ型になります。

B のサイズが指定されていない場合、出力のサイズはインデックス配列 ind に依存します。

• ind が列ベクトルの場合、B は長さが max(ind,[],1) の列ベクトルになります。

• ind が複数の列をもつ行列の場合、B はサイズが max(ind,[],1) の多次元配列になります。

詳細

要素の累積

次の図は、12 か月間で測定された温度データのベクトルに対する accumarray の動作を示しています。各月の最高の測定温度値を求めるために、accumarray は、month 内に同一のインデックスをもつ temperature の値の各グループに対して関数 max を適用します。

month には、出力の 5、6、7、10 の位置を指している値はありません。既定では、それらのインデックスにおける出力 maxTemp の要素は 0 です。

ヒント

• accumarray の動作は、関数 groupsummary および groupcounts に似ています。前者はグループ別に要約統計量を計算し、後者はグループの要素数をカウントします。MATLAB^® のその他のグループ化機能については、データの前処理を参照してください。

• accumarray の動作は、関数 histcounts の動作にも似ています。

  • histcounts はビンのエッジを使用して連続値を 1 次元の範囲にグループ化します。accumarray は n 次元のインデックスを使用してデータをグループ化します。

  • histcounts はビンのカウント数とビンの配置を返すことのみが可能です。accumarray はデータに任意の関数を適用できます。

  accumarray に data = 1 を指定すると histcounts と同じ結果が得られます。

• 関数 sparse も accumarray と同様に累積を行います。

  • sparse は 2 次元のインデックスを使用してデータをグループ化するのに対し、accumarray は n 次元のインデックスを使用してデータをグループ化します。

  • 同一のインデックスをもつ要素が複数ある場合、sparse は関数 sum (double 値の場合) または関数 any (logical 値の場合) を適用して出力行列にスカラーの結果を返します。accumarray は既定では合計しますが、任意の関数をデータに適用できます。

拡張機能

C/C++ コード生成

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

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

• accumarray の入力値について明示的な範囲を指定しない場合、コード ジェネレーターで accumarray の出力サイズを事前定義できないことがあります。そのため、可変サイズの配列と動的メモリ割り当てを有効にしなければなりません。

• 入力引数に列挙値を含めることはできません。

• 関数 fun は非スパースのスカラーを返さなければなりません。

• fun がスカラーの 1 行 1 列の cell 配列を返す場合、次のようになります。

  • fillval の値を指定する必要があります。指定する値はスカラーの 1 行 1 列の cell 配列でなければならず、cell の内容は fun が返すデータ型と同じでなければなりません。

  • 入力として fun の受け取る累積値の順序が、MATLAB での順序と一致しない場合があります。

• fun の出力型を事前定義するために、コード ジェネレーターは accumarray の入力引数を処理する前に fun を呼び出す場合があります。そのため、fun の実行により、グローバル変数または永続変数の変更、出力への送出などを行って二次的影響が発生する場合、生成されたコードの結果は MATLAB での結果と異なることがあります。

スレッドベースの環境

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

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

GPU 配列

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

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

• fun の値は、@sum (既定)、@prod、@min、@max、@any、または @all のいずれかでなければなりません。

• data と fillval は、logical または浮動小数点 (double または single) の非スパース配列でなければなりません。

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

バージョン履歴

R2006a より前に導入

参考

histcounts | sparse | groupsummary | groupcounts