---
name: stats_summary
kind: function
lang: cpp
domain: datascience
version: "1.0.0"
purity: pure
signature: "double stats_sum(const double*, size_t); double stats_mean(const double*, size_t); double stats_min(const double*, size_t); double stats_max(const double*, size_t); double stats_variance(const double*, size_t, bool sample=true); double stats_std(const double*, size_t, bool sample=true); double stats_quantile(const double*, size_t, double p); double stats_quantile_sorted(const double*, size_t, double p); double stats_percentile(const double*, size_t, double pct); void stats_sort(const double*, size_t, double* out)"
description: "Estadistica descriptiva pura sobre arrays double: sum (Kahan), mean, min, max, variance/std (Welford one-pass, sample/poblacional), quantile (R type-7) y percentile. stats_sort externalizable para evitar copias en queries multiples."
tags: [stats, mean, variance, std, quantile, percentile, welford, datascience, pendiente-usar]
uses_functions: []
uses_types: []
returns: []
returns_optional: false
error_type: ""
imports: [cstddef, cmath, algorithm, vector, cstring]
tested: false
tests: []
test_file_path: ""
file_path: "cpp/functions/datascience/stats_summary.cpp"
params:
  - name: data
    desc: "Array de doubles (no necesariamente ordenado salvo *_sorted)."
  - name: n
    desc: "Tamano del array. n=0 devuelve identidades sensatas (0 para sum/mean/min/max/var/std)."
  - name: sample
    desc: "Variance/std: true = muestral (n-1), false = poblacional (n). Default true."
  - name: p
    desc: "Quantile en [0, 1]. Valores fuera se clampean."
  - name: pct
    desc: "Percentile en [0, 100]. Internamente p = pct/100."
  - name: out
    desc: "(stats_sort) buffer destino. Si out == data, ordena in-place."
output: "Escalar (double) con la estadistica solicitada. stats_sort modifica out in-place; el resto no muta data."
---

# stats_summary

Pack de estadisticas basicas sobre arrays raw. Diseñado para post-proceso de samples MC, sesiones de simulacion, cadenas MCMC.

## Performance

- `stats_sum`: Kahan summation (O(n), ~5% mas lento que sum naive pero sin drift en sumas de millones de fp64).
- `stats_variance`: Welford one-pass (O(n), una sola pasada). No hay las cancelaciones catastroficas del E[X^2] - E[X]^2 naive.
- `stats_quantile`: O(n log n) por copia + sort. Para multiples queries del mismo dataset, llamar `stats_sort` una vez y `stats_quantile_sorted` despues — O(n log n + Q).

## Patron tipico

Resumen de un session simulator (vr_tiered_lab):

```cpp
std::vector<double> pnls(N);
// ... rellenar pnls ...

double mean   = fn::ds::stats_mean(pnls.data(), N);
double std    = fn::ds::stats_std (pnls.data(), N);

// CI 95% via percentiles 2.5 / 97.5
std::vector<double> sorted(N);
fn::ds::stats_sort(pnls.data(), N, sorted.data());
double p025 = fn::ds::stats_quantile_sorted(sorted.data(), N, 0.025);
double p975 = fn::ds::stats_quantile_sorted(sorted.data(), N, 0.975);
```

## Notas

- El convenio R type-7 para quantiles es el mismo que numpy default (`linear`) y matplotlib. Pasar tests numericos contra numpy debe matchear bit-exacto.
- `sample=true` (default) coincide con `np.var(x, ddof=1)` y `pd.DataFrame.var()`.
- Para datasets enormes que no caben en RAM, usar `gpu_reduce` (GPU) — esta libreria es CPU-side.