The cumulate operator produces a result array containing a running aggregate along a dimension of the input array.

Synopsis

cumulate(array, aggregate[,aggregate2,...] [, dimension]])

Summary

The cumulate operator calculates a running aggregate along a single dimension of the input array. The calculation happens along one particular dimension of the array. The aggregate call requires one of the SciDB or P4 aggregates, or a user-defined aggregate function. If you do not specify the dimension, cumulate uses the first declared dimension of the array.

Limitation

The cumulate operator cannot handle input arrays containing non-zero chunk overlaps.

Examples

Cumulative Sum Along the Second Dimension

To calculate the cumulative sum along the second dimension of a 2-dimensional, 1 -attribute array, do the following:

Create a matrix and store values into it:
AFL% store(build(<val:double>[row=0:2; col=0:3],row*4+col+1),A);

The output is:
[ [(1),(2),(3),(4)], [(5),(6),(7),(8)], [(9),(10),(11),(12)] ]
Calculate the cumulative sum along the first dimension:
AFL% cumulate(A,sum(val),row);

The output is:
[ [(1),(2),(3),(4)], [(6),(8),(10),(12)], [(15),(18),(21),(24)] ]
Calculate the cumulative product along the first dimension:
AFL% cumulate(A,prod(val),row);

The output is:
[ [(1),(2),(3),(4)], [(5),(12),(21),(32)], [(45),(120),(231),(384)] ]
Calculate the cumulative average along the second dimension:
AFL% cumulate(A,avg(val),col);

The output is:
[ [(1),(1.5),(2),(2.5)], [(5),(5.5),(6),(6.5)], [(9),(9.5),(10),(10.5)] ]
Calculate the the average, min, and max values along the first dimension:
AFL% cumulate(A,avg(val),min(val),max(val),row);

The output is:
[ [(1,1,1),(2,2,2),(3,3,3),(4,4,4)], [(3,1,5),(4,2,6),(5,3,7),(6,4,8)], [(5,1,9),(6,2,10),(7,3,11),(8,4,12)] ]

Array Containing Empty Cells and Null Values

To calculate an array that contains empty cells and null values, do the following:

Assume the following array, B, with dimensions i and j.
AFL% scan(B)

The output is:
[ [(1.25,null),(),(-7,-7)], [(),(),(4.2,1)], [(4.5,null),(11,9),(2.6,null)], [(),(1.7,6.5),(6.2,null)] ]
Calculate the cumulative average along the second dimension, for both attributes.
AFL% cumulate(B,avg(val1),avg(val2),j);

The output is:
[ [(1.25,null),(),(-2.875,-7)], [(),(),(4.2,1)], [(4.5,null),(7.75,9),(6.03333,9)], [(),(1.7,6.5),(3.95,6.5)] ]
Calculate the variance for the first attribute, along the first dimension.
AFL% cumulate(B,var(val1));

The output is:
[ [(null),(),(null)], [(),(),(62.72)], [(5.28125),(null),(36.6933)], [(),(43.245),(34.28)] ]