accumarray - Accumulate vector elements - MATLAB (original) (raw)

Accumulate vector elements

Syntax

Description

[B](#bt35io5-1-A) = accumarray([ind](#bt35io5-1-subs),[data](#bt35io5-1-val)) sums groups of data by accumulating elements of a vector data according to the groups specified inind. The sum is then computed over each group. The values inind define both the group the data belongs to and the index into the output array B where each group sum is stored.

To return the group sums in order, specify ind as a vector. Then for the group with index i, accumarray returns its sum in B(i). For example, if ind = [1 1 2 2]' and data = [1 2 3 4]', then B = accumarray(ind,data) returns the column vector B = [3 7]'.

To return the group sums in another shape, specify ind as a matrix. For an _m_-by-n matrixind, each row represents the group assignment and an_n_-dimensional index into the output B. For example, if ind contains two rows of the form [3 4], then the sum of the corresponding elements indata is stored in the (3,4) element ofB.

Elements of B whose index does not appear inind are filled with 0 by default.

example

[B](#bt35io5-1-A) = accumarray([ind](#bt35io5-1-subs),[data](#bt35io5-1-val),[sz](#bt35io5-1-sz)) returns an array B padded to size sz. Specifysz as a vector of positive integers that match or exceed the dimension lengths in ind. Extra elements in the output are filled with 0. Specify sz as [] to let the indices in ind determine the size of the output.

example

[B](#bt35io5-1-A) = accumarray([ind](#bt35io5-1-subs),[data](#bt35io5-1-val),[sz](#bt35io5-1-sz),[fun](#bt35io5-1-fun)) applies the function fun to each group in data specified by ind. Specify fun using the@ symbol, such as @mean, or as[] to use the default @sum.

example

[B](#bt35io5-1-A) = accumarray([ind](#bt35io5-1-subs),[data](#bt35io5-1-val),[sz](#bt35io5-1-sz),[fun](#bt35io5-1-fun),[fillval](#bt35io5-1-fillval)) fills all elements of B that are not referred to by an index inind with the scalar value fillval. Specifyfillval as [] to use the default value0.

example

[B](#bt35io5-1-A) = accumarray([ind](#bt35io5-1-subs),[data](#bt35io5-1-val),[sz](#bt35io5-1-sz),[fun](#bt35io5-1-fun),[fillval](#bt35io5-1-fillval),[issparse](#bt35io5-1-issparse)) returns an array B that is sparse whenissparse is true or 1, and full if issparse is false or0. The output B is full by default.

example

Examples

collapse all

Sum Data by Group

Create a vector of data and a corresponding vector ind that defines groups.

Sum the values in data by the groups specified in ind.

Alternatively, use the groupsummary function, specifying 'sum' as the group computation.

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

Count Elements in Group

Create a vector of groups.

Apply scalar expansion to the number 1 to count the number of elements in each group defined in ind.

Alternatively, use the groupcounts function.

Specify Output Size

Create a vector of data and a matrix of output indices ind that defines groups of data.

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

ind = 6×2

Sum the values in data for each group in ind. The indices in ind define a 4-by-2 matrix of locations for the output.

B1 = accumarray(ind,data)

Pad the output to a 4-by-4 matrix by specifying the output size as [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

Variance by Group

Calculate group variances rather than sums.

Create a vector of data and a matrix ind that defines groups of the data.

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

Compute the variance of each group by specifying the function handle @var as the method input. This syntax applies the var function to the groups instead of sum.

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

B1 = 3×2

0.6050         0
     0    3.1250
     0    0.8450

You can specify the group computation as an anonymous function that accepts vector inputs and returns a scalar. This is useful when you want to pass additional arguments to a function. For example, use the var function with the normalization argument value 1.

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

A2 = 3×2

0.3025         0
     0    1.5625
     0    0.4225

Return Sum with Integer Type Output

Specify an additional argument to the sum function by using an anonymous function for the method input.

Create a vector of data and a matrix ind that defines groups of the data and 3-D indices into the output.

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 the data by group in their native integer class int8 by using the 'native' option for the sum function. To do this, specify an anonymous function using @(x) sum(x,'native') for the method input. The result is a 2-by-3-by-2 multidimensional array of type int8.

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

Group Values in Cell Array

Create a vector of data and a matrix ind that defines groups of the data.

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

Group the elements of data into a cell array.

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

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

Verify that the vector elements are in the same order as they appear in data.

Specify Fill Value

Create a vector of data and a matrix ind that defines groups of the data.

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

The elements of ind define a 4-by-4 matrix for the output, but only reference 4 out of the 16 elements. By default, the other 12 elements are 0 in the output. Fill in the extra output elements with NaN values instead of 0.

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

B = 4×4

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

Change Output Sparsity

Create a vector of data and a matrix ind that defines groups of the data.

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

The elements of ind define a 400-by-400 matrix for the output, but only reference 3 out of the 160,000 elements. When the output of accumarray results in a large array with a low density of nonzero elements, you can save memory by specifying the issparse option as true, creating a sparse matrix instead of a full one.

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

B = 400x400 sparse double matrix (3 nonzeros) (1,1) 125 (80,80) 118 (400,400) 152

Input Arguments

collapse all

`ind` — Output indices

vector | matrix | cell array of vectors

Output indices, specified as a vector, matrix, or cell array of vectors.

If ind is a vector, then each element specifies an index into the output and defines the groups accumulated byaccumarray. All of the elements must be positive integers and the length of ind must match the length of the data vector.
If ind is an_m_-by-n matrix, then each row specifies an _n_-dimensional index into the output. The _i_th row in ind corresponds to the _i_th value in the data and the number of rows in ind must match the length of the data vector. For example, if ind is a 3-by-2 matrix, it contains three 2-D indices. The first element of each row is the row index into the output and the second element is the column index.
If ind is a cell array of index vectors, then each vector must have the same length and they are treated as columns.

`data` — Data to be accumulated

scalar | vector

Data to be accumulated, specified as a scalar or vector.

If data is a scalar, then its value is scalar expanded.
If data is a vector, then it must have the same length as the number of rows in the index array.

`sz` — Size of output array

[] (default) | vector of positive integers

Size of the output array, specified as a vector of positive integers or as[]. For example, sz = [5 7] produces an output array that is 5-by-7. When you specify[] for the size, the values in the index array determine the size of the output. The dimension lengths insz must match or exceed the dimension lengths in the index array.

`fun` — Group computation

[] (default) | function handle

Group computation, specified as a function handle.accumarray accumulates the elements of the data vector by group, and then applies the function fun to the group elements. When you specify fun = [], the computation uses the default function sum. The specified function must accept a column vector and return a numeric,logical, or char scalar, or a scalar cell. For more information on function handles, see Create Function Handle.

Example: fun = @max

`fillval` — Fill value

[] (default) | scalar

Fill value when an element of the output does not correspond to an index provided in the index array, specified as a scalar or as [], which uses the default value 0. The data type offillval must match the data type of the computation function output.

`issparse` — Output sparsity

false or 0 (default) | true or 1

Output sparsity, specified as a numeric or logical 1 (true) or 0 (false).

When issparse is true or1, the fill value must be 0 or[], and the input data and output of the computation function must both have type double.

Output Arguments

collapse all

`B` — Output array

vector | matrix | multidimensional array

Output array, returned as a vector, matrix, or multidimensional array.B has the same data type as the values returned by the group computation function.

When the size of B is not specified, the output size depends on the index array ind.

If ind is a column vector, thenB is a column vector of lengthmax(ind,[],1).
If ind is a matrix with more than one column, then B is a multidimensional array of size max(ind,[],1).

More About

collapse all

Accumulating Elements

The following graphic illustrates the behavior ofaccumarray on a vector of temperature data taken over a 12-month period. To find the maximum temperature reading for each month,accumarray applies the max function to each group of values in temperature that have identical indices in month.

No values in month point to the 5, 6, 7, or 10 positions of the output. The elements of output maxTemp at those indices are0 by default.

Behavior of accumarray using the max function on vectors of month indices and temperature data. The output maxTemp contains the maximum temperature for each unique month

Tips

The behavior of accumarray is similar to the functionsgroupsummary and groupcounts for computing summary statistics by group and counting the number of elements in a group, respectively. For more grouping functionality in MATLAB®, see Data Preprocessing.
The behavior of accumarray is also similar to that of thehistcounts function.
- histcounts groups continuous values into a 1-D range using bin edges. accumarray groups data using_n_-dimensional indices.
- histcounts can only return bin counts and bin placement. accumarray can apply any function to the data.
  You can mimic the behavior of histcounts usingaccumarray with data = 1.
The sparse function also has accumulation behavior similar to that of accumarray.
- sparse groups data using 2-D indices, whereasaccumarray groups data using_n_-dimensional indices.
- For elements with identical indices, sparse applies the sum function (for double values) or the any function (forlogical values) and returns the scalar result in the output matrix. accumarray sums by default, but can apply any function to the data.

Extended Capabilities

C/C++ Code Generation

Generate C and C++ code using MATLAB® Coder™.

Usage notes and limitations:

Unless you provide explicit bounds on the accumarray input values, the code generator may not be able to predetermine the size of the accumarray output. Therefore, variable-size arrays and dynamic memory allocation must be enabled.
The input arguments cannot contain enumerations.
The function fun must return a full (nonsparse) scalar.
When fun returns a scalar 1-by-1 cell array:
- You must specify a value for fillval. The value you specify must be a scalar 1-by-1 cell array, and the content of the cell must have the same data type that fun returns.
- The order of accumulated values that fun receives as input may not match the order in MATLAB.
To predetermine the output type for fun, the code generator may call fun before processing the input arguments of accumarray. As a result, if the execution offun causes side effects, for instance by modifying a global or persistent variable or printing to output, then the generated code results may differ from MATLAB results.

Thread-Based Environment

Run code in the background using MATLAB® backgroundPool or accelerate code with Parallel Computing Toolbox™ ThreadPool.

This function fully supports thread-based environments. For more information, see Run MATLAB Functions in Thread-Based Environment.

GPU Arrays

Accelerate code by running on a graphics processing unit (GPU) using Parallel Computing Toolbox™.

The accumarray function supports GPU array input with these usage notes and limitations:

The value of fun must be one of @sum (default), @prod, @min,@max, @any, or@all.
data and fillval must be full (nonsparse) logical or floating-point (double or single) arrays.

For more information, see Run MATLAB Functions on a GPU (Parallel Computing Toolbox).

Version History

Introduced before R2006a

accumarray - Accumulate vector elements - MATLAB (original) (raw)

Syntax

Description

Examples

Sum Data by Group

Count Elements in Group

Specify Output Size

Variance by Group

Return Sum with Integer Type Output

Group Values in Cell Array

Specify Fill Value

Change Output Sparsity

Input Arguments

ind — Output indices

data — Data to be accumulated

sz — Size of output array

fun — Group computation

fillval — Fill value

issparse — Output sparsity

Output Arguments

B — Output array

More About

Accumulating Elements

Tips

Extended Capabilities

C/C++ Code Generation

Thread-Based Environment

GPU Arrays

Version History

`ind` — Output indices

`data` — Data to be accumulated

`sz` — Size of output array

`fun` — Group computation

`fillval` — Fill value

`issparse` — Output sparsity

`B` — Output array