Metrics

Overview

MASA metrics are designed to make it easy to record and report learning signals at different granularities: single scalars, streaming summary statistics, and approximate distributions. Keeping logging lightweight and backend-agnostic.

• Scalars are plain numeric values (e.g., reward, loss, episode length). Loggers keep a rolling window of recent scalar values and typically report a smoothed mean over that window.

• Summary statistics are handled by masa.common.metrics.Stats, which performs streaming aggregation over batches of values. It tracks running moments (mean and mean-square) and extrema (min/max/magnitude), and exposes derived quantities like standard deviation: \(\sigma = \sqrt{\max(0, \mathbb{E}[X^2] - \mathbb{E}[X]^2)}\). Calling Stats.get() returns a flat dictionary of scalars suitable for logging.

• Distributions are handled by masa.common.metrics.Dist, which maintains a fixed-size reservoir sample of a stream. This gives a compact approximation of the underlying distribution that can be plotted or logged as a histogram.

• Logging is performed by logger implementations (see the next page), which accept mixtures of scalars, Stats, and Dist objects. They aggregate values over a configurable window and can emit to stdout and/or TensorBoard with consistent key prefixing.

API Reference

Metrics Core

class masa.common.metrics.Stats(prefix: str = '')

Bases: object

Streaming scalar summary statistics for an arbitrary batch of values.

This class maintains simple running aggregates over a stream of scalar observations:

• Mean: \(\mu\)

• Mean of squares: \(\mathbb{E}[X^2]\)

• Derived standard deviation: \(\sigma = \sqrt{\max(0, \mathbb{E}[X^2] - \mu^2)}\)

• Extremes: min/max

• Magnitude: \(\max |x|\)

The update() method accepts any array-like input, flattens it to a 1D vector, and updates the aggregates. The get() method returns a dict of scalars suitable for logging; if prefix is non-empty, keys are prefixed with "{prefix}_".

Parameters:

prefix – Optional key prefix (without trailing underscore). If provided, keys returned by get() are of the form "{prefix}_{name}".

Variables:

• n – Total number of scalar samples seen so far.

• prefix – Prefix used to namespace emitted keys.

• stats – Internal aggregate state or None if no data has been observed. When populated, it contains keys mean, mean_squares, max, min, and mag.

update(values: ndarray | Iterable[float] | float)

Update aggregates with a batch of scalar values.

The input is converted to np.float32 and flattened. If the resulting array is empty, the call is a no-op.

Parameters:

values – A scalar or array-like collection of numeric values.

get() → Dict[str, float]

Return the current statistics as a flat dict of scalars.

Returns:

• mean: \(\mu\)

• std: \(\sigma = \sqrt{\max(0, \mathbb{E}[X^2] - \mu^2)}\)

• max: \(\max x\)

• min: \(\min x\)

• mag: \(\max |x|\)

If prefix is non-empty, keys are prefixed with "{prefix}_".

Return type:

A mapping containing

Raises:

RuntimeError – If called before any data has been observed.

class masa.common.metrics.Dist(prefix: str = '', reservoir_size: int = 2048, rng: int | Generator | BitGenerator | None = None)

Bases: object

Reservoir-sampled distribution summary.

This class maintains a fixed-size reservoir sample of a stream of scalar values using reservoir sampling. After processing \(n\) total samples, a reservoir of size \(k\) contains a uniform sample (without replacement) from the observed stream (in expectation).

Parameters:

• prefix – Optional logical prefix for this distribution (used by loggers).

• reservoir_size – Maximum number of samples retained in the reservoir.

• rng – Seed (or seed-like) passed to numpy.random.default_rng().

Variables:

• n – Total number of scalar samples seen so far.

• prefix – Prefix used by StatsLogger when naming histogram keys.

• reservoir_size – Maximum reservoir capacity.

• res – Current reservoir buffer of shape (<=reservoir_size,).

• rng – Numpy random generator used for reservoir sampling.

update(values: ndarray | Iterable[float] | float)

Update the reservoir with a batch of values.

Parameters:

values – A scalar or array-like collection of numeric values. The input is flattened into a 1D array.

get() → ndarray

Return a copy of the reservoir buffer.

Returns:

A copy of the internal reservoir array (dtype np.float32).

Next Steps

• Logging - Learn how logging is handled automatically in MASA.