stats.moving-average

def moving_average(values: Sequence[float], window: int, kind: MovingAverageKind, decimals: int) -> List[float]

MovingAverageKind = Literal["simple", "exponential"]

from fune.stats.moving_average import moving_average  # stats.moving-average@^2

import math
from typing import List, Sequence

from .math_round_float import round_float  ← from math.round-float ^1.0.0 · built alongside by fune
from .stats_moving_average_types import MovingAverageKind


def _window_mean(values: List[float], end: int, window: int) -> float:
    # Summed afresh, left to right; math.fsum or sum() with a start value
    # would round differently from the other languages.
    total = 0.0
    for i in range(end - window + 1, end + 1):
        total = total + values[i]
    return total / window


def moving_average(values: Sequence[float], window: int, kind: MovingAverageKind, decimals: int) -> List[float]:
    """Simple or exponential moving average, one value per full window.

    The exponential average is seeded with the simple average of the first
    window and carried unrounded; only the returned values are rounded, by
    math.round-float on the exact value of each double (2.675 gives 2.67).
    """
    if isinstance(values, (str, bytes)) or not isinstance(values, (list, tuple)):
        raise TypeError("values must be a list of numbers")
    for v in values:
        if isinstance(v, bool) or not isinstance(v, (int, float)) or not math.isfinite(v):
            raise TypeError("values must be finite numbers, received %r" % (v,))
    if isinstance(window, bool) or not isinstance(window, int) or window < 1:
        raise ValueError("window must be a whole number of 1 or greater, received %r" % (window,))
    if kind not in ("simple", "exponential"):
        raise ValueError('unknown moving average kind "%s"' % (kind,))
    # Checked here as well as in round_float (same wording), so a series too
    # short to produce any output still refuses bad decimals.
    if isinstance(decimals, bool) or not isinstance(decimals, int) or decimals < 0 or decimals > 12:
        raise ValueError("decimals must be a whole number from 0 to 12, received %r" % (decimals,))

    series = [float(v) for v in values]
    out: List[float] = []
    if len(series) < window:
        return out

    if kind == "simple":
        for end in range(window - 1, len(series)):
            out.append(round_float(_window_mean(series, end, window), decimals))
        return out

    alpha = 2.0 / (window + 1)
    ema = _window_mean(series, window - 1, window)
    out.append(round_float(ema, decimals))
    for i in range(window, len(series)):
        ema = ema + alpha * (series[i] - ema)
        out.append(round_float(ema, decimals))
    return out

Install

fune build

With that line in your source, in a Python project (language python in fune.project), fune build resolves it and its 1 dependency, pins them in fune.lock, downloads only the Python package of each, and builds the code above into your project’s .fune/build, one readable file per capability with a header linking back here. Or pin a range in fune.project and build in one step:

fune add stats.moving-average

The manifest, vectors and README with only the Python implementation. Install it without the registry with fune add ./stats.moving-average-2.0.0-python.fune, or fetch it from a terminal with fune pull stats.moving-average@2.0.0:python.

The whole function, every language, is one file too: stats.moving-average-2.0.0.fune, 16,223 bytes, sha256 a3ae5d80d93991fcecfb0b38c0fdfef47b6272f0925172d288273ab4a28150a5. It installs into a project of any language.

# fune: before stats.moving-average

# fune: after stats.moving-average

# fune: replace math.round-float in stats.moving-average

# fune: step stats.moving-average after <n|label>

More from the author

**Precision.** Every output is rounded to `decimals` places (0 to 12) by `math.round-float`: half away from zero, decided on the exact value of the double, -0 returned as 0. The running exponential average is carried unrounded; only what is returned is rounded, so the rounding does not compound. "The exact value of the double" is literal: 1.005 is stored as 1.00499999999999989..., so it rounds to 1.00 at two places, and the mean of 2.67 and 2.68 is the double 2.67499999999999982..., so it rounds to 2.67. Callers who need decimal-exact averages of money should average integer minor units with `stats.weighted-average` instead.

**Why the three languages agree to the bit.** Each window is summed afresh, left to right (not by a running add-and-subtract, which accumulates error differently depending on history), and only IEEE-754 +, -, x, / and floor are used, in the same order in every language. Each of those operations is correctly rounded by the standard, so TypeScript, Python and Rust hold the same double before rounding; `math.round-float` then rounds that double the same way in all three.

## Changes in 2.0.0

2.0.0 rounds on the exact value of the double, so an average of 2.67 and 2.68 (the double 2.67499999999999982...) now gives 2.67. 1.x rounded the scaled product instead (floor of |x| x 10^decimals, compared with a half), and 2.675 x 100 is exactly 267.5 in floating point, so 1.x said 2.68. The private rounding helper is gone: this version requires `math.round-float ^1.0.0` and rounds with it, so every float capability in the registry rounds alike.

Only outputs whose double lies just below (or just above) a tie that the scaled product lands exactly on change; everything else is the same double. None of the 1.x vectors changed answers (each was recomputed from the exact value of its double). New vectors pin the difference: the mean of 2.67 and 2.68 gives 2.67 (1.x 2.68), of -2.67 and -2.68 gives -2.67 (1.x -2.68), an exponential output of 2.675 gives 2.67 (1.x 2.68), and 1.45 at one place gives 1.4 (1.x 1.5); 8.345, stored just above its tie, still gives 8.35.

`decimals` is still 0 to 12, and still refused up front with the same message ("decimals must be a whole number from 0 to 12"), so a series too short for any output refuses it as before.

Files