accumulate

class iteration_utilities.accumulate(iterable, func=None, start=None)

Make an iterator that returns accumulated sums, or accumulated results of other binary functions (specified via the optional func argument). Copied and modified from [R02].

Parameters:

iterable : iterable

The iterable to accumulate.

func : callable or None, optional

The function with which to accumulate. Should be a function of two arguments. If None defaults to operator.add().

start : any type, optional

If given (even as None) this value is inserted before the iterable.

Returns:

accumulated : generator

The accumulated results as generator.

Notes

Elements of the input iterable may be any type that can be accepted as arguments to func. (For example, with the default operation of addition, elements may be any addable type including Decimal or Fraction.) If the input iterable is empty, the output iterable will also be empty.

References

[R02](1, 2) https://docs.python.org/3/library/itertools.html#itertools.accumulate
[R12](1, 2) https://en.wikipedia.org/wiki/Logistic_map

Examples

There are a number of uses for the func argument. It can be set to min() for a running minimum, max() for a running maximum, or operator.mul() for a running product. Amortization tables can be built by accumulating interest and applying payments. First-order recurrence relations can be modeled by supplying the initial value in the iterable and using only the accumulated total in func argument:

>>> from iteration_utilities import accumulate
>>> from itertools import repeat
>>> import operator

>>> data = [3, 4, 6, 2, 1, 9, 0, 7, 5, 8]
>>> list(accumulate(data))                   # running sum
[3, 7, 13, 15, 16, 25, 25, 32, 37, 45]
>>> list(accumulate(data, operator.add))     # running sum (explicit)
[3, 7, 13, 15, 16, 25, 25, 32, 37, 45]
>>> list(accumulate(data, operator.mul))     # running product
[3, 12, 72, 144, 144, 1296, 0, 0, 0, 0]
>>> list(accumulate(data, max))              # running maximum
[3, 4, 6, 6, 6, 9, 9, 9, 9, 9]

Amortize a 5% loan of 1000 (start value) with 4 annual payments of 90:

>>> cashflows = [-90, -90, -90, -90]
>>> list(accumulate(cashflows, lambda bal, pmt: bal*1.05 + pmt, 1000))
[960.0, 918.0, 873.9000000000001, 827.5950000000001]

Chaotic recurrence relation [R12]:

>>> logistic_map = lambda x, _:  r * x * (1 - x)
>>> r = 3.8
>>> x0 = 0.4
>>> inputs = repeat(x0, 36)     # only the initial value is used
>>> [format(x, '.2f') for x in accumulate(inputs, logistic_map)]
['0.40', '0.91', '0.30', '0.81', '0.60', '0.92', '0.29', '0.79', '0.63', '0.88', '0.39', '0.90', '0.33', '0.84', '0.52', '0.95', '0.18', '0.57', '0.93', '0.25', '0.71', '0.79', '0.63', '0.88', '0.39', '0.91', '0.32', '0.83', '0.54', '0.95', '0.20', '0.60', '0.91', '0.30', '0.80', '0.60']
__length_hint__()

Tries to estimate for the length of the instance (returns 0 if an estimation is not possible).

Note

Requires Python >= 3.4

current

(any type) The current accumulated total (readonly).

New in version 0.6.

func

(callable or None) The function used for accumulation (readonly).

New in version 0.6.