Implementation

This page describes the internal flow of median and the order in which validation and the final median calculation are applied. Unlike Overview, the goal here is not to repeat the function signature, but to show how the result is actually built.

The following snippets are taken from the current src/mespy/stats_utils.py implementation. The only helper involved is _as_float_vector, which defines the numeric input contract before the final delegation to NumPy.

Execution sequence

The implementation follows this sequence:

  1. Converts x into a one-dimensional, finite float64 vector with _as_float_vector("x", x).

  2. Rejects empty, multidimensional, or non-finite inputs directly in the shared validator.

  3. Passes the validated vector to np.median(...).

  4. Converts the final result to a Python float.

Validation and delegation to NumPy

def median(x: ArrayLike) -> float:
    values = _as_float_vector("x", x)
    return float(np.median(values))

median is the most straightforward function in the whole module.

  • It contains no alternative branches, optional parameters, or hand-rewritten formulas.

  • Tutta la robustezza dell’API e concentrata nella prima riga: _as_float_vector(...) impone che x sia un array numerico, monodimensionale, non vuoto e composto solo da valori finiti.

  • Una volta ottenuto values, la funzione non aggiunge altra logica statistica: delega il calcolo della mediana a np.median(values).

  • Il cast finale a float uniforma il tipo di ritorno dell’API pubblica, evitando di esporre uno scalare NumPy.

Edge cases and practical behavior

Questa funzione non implementa politiche speciali oltre alla validazione iniziale.

  • Se x e vuoto, il fallimento avviene prima di chiamare np.median(...), quindi il package evita warning o nan silenziosi.

  • Se x contiene NaN o infiniti, il rifiuto avviene sempre nel validatore comune, in modo coerente con tutte le altre funzioni di stats_utils.

  • Se x ha un numero pari di elementi, la scelta su come combinare i due valori centrali e interamente quella di NumPy, perche mespy non la ridefinisce.

  • Proprio per questa struttura minimale, il comportamento di median e facile da leggere: validazione comune all’ingresso, poi singola delega al motore numerico sottostante.