Cumulate

Cumulate(X, I)

Returns an array with each element being the sum of all of the elements of «X» along dimension «I» up to, and including, the corresponding element of «X».

Syntax:

Cumulate(X: Array[I]; I: Index, passNull: optional Boolean, reset: optional Array)

Library

Array Functions

Examples

I :=

[1, 2, 3, 4, 5, 6]

X :=

[8, 2, 0, 5, -3, 7]

Cumulate(X, I) →

[8, 10, 10, 15, 12, 19]

Optional Parameters

PassNull

«PassNull» is an optional boolean parameter that defaults to False. When it is omitted or explicitly set to False, Cumulate ignores Null values. In that case they have essentially the same effect as a zero, unless they happen to be the first value in «X», in which case they are passed since no numeric values are yet obtained.

When «passNull» is set to True, then Null values are passed through as Null in the result.

For example:

X :=

[«null», «null», 4, 1, «null», «null», 1, 9, 3, 2, «null»]

Cumulate(X, I) →

[«null», «null», 4, 5, 5, 5, 6, 15, 18, 20, 20]

Cumulate(X, I, passNull: false) →

[«null», «null», 4, 5, 5, 5, 6, 15, 18, 20, 20]

Cumulate(X, I, passNull: true) →

[«null», «null», 4, 5, «null», «null», 6, 15, 18, 20, «null»]

Reset

The optional «reset» parameter accepts an array of boolean values indexed by «I» At the positions where «reset» is true, Cumulate starts over. This sets the sum of all previous values to zero, so that the value at that position will be the same as the value in «X».

For example:

I :=

[1, 2, 3, 4, 5, 6, 7]

X :=

[8, 2, 0, 5, -3, 7, 5]

R :=

[0, 0, 1, 0, 0, 1, 0]

Cumulate(X, I, reset: R) →

[8, 10, 0, 5, 2, 7, 12]

«Reset» can be used to restart the cumulation each time some state change occurs. In such a scenario, the «reset» parameter is set to True at the first instant (along «I») that the system is in the new state.

Suppose State is a state designator, indexed by I. The following would compute how long the system has been in the same state for:

Cumulate(1, I, reset: State[@I = @I - 1] <> State)

Details

Recumulate

In Analytica 4.2 and earlier, the functionality of the «reset» parameter can be obtained using the Recumulate library function, which resets the total to zero at selected points. This usage is:

Recumulate(x, b, I)

where b is an array of booleans indexed by I, having 1 at each point where the cumulation is to be reset to zero. Recumulate is implemented as a User-Defined Function in the example Recumulate example.ana. A clever usage of this function computes the number of time steps that the system has been in the same state (see the example).

Use in Dynamic Functions

If objects X and Y belong to the same dynamic loop, then the definition of Y should never perform an operation over the Time index on the value of X. When you write such an expression, you presumably intend to operate over the entire Time-indexed array for X, which would thus implicitly refer to future points in time that have not yet been computed, and would therefore be disallowed. However, in reality, the use of X in Y's definition refers to the value of X at the current time point, so that an expression such as Cumulate(X, Time) would actually be cumulating a constant value over time. While that is not disallowed, it is probably not what is intended, and Analytica will issue a warning in this case. You can usually expression operations over Time directly using Dynamic], for example, instead of Cumulate(X, Time) you would define CumX as

Dynamic(X, Self[Time-1] + X)

For more information on dynamic functions, see Dynamic.

See Also

• Uncumulate
• Sum
• CumProduct
• Recumulate example.ana