---
name: compute_column_stats
kind: function
lang: cpp
domain: core
version: "1.0.0"
purity: pure
signature: "ColStats compute_column_stats(const char* const* cells, int rows, int cols, int col, int unique_cap = 100000, const int* indices = nullptr, int n_indices = 0)"
description: "Calcula estadisticas completas para una columna: mean, p25/p50/p75, min/max, count de vacios, unicos, histograma de 24 bins y top-8 categorias por frecuencia."
tags: [tables, stats, statistics, histogram, percentile, tql, cpp-tables]
uses_functions: []
uses_types: []
returns: []
returns_optional: false
error_type: ""
imports: ["core/compute_column_stats.h"]
tested: true
tests:
  - "compute_column_stats: media correcta sobre vector numerico"
  - "compute_column_stats: p50 es mediana"
  - "compute_column_stats: p25 y p75 correctos"
  - "compute_column_stats: conteo de vacios correcto"
  - "compute_column_stats: columna texto no es numerica"
  - "compute_column_stats: unique_count correcto"
  - "compute_column_stats: top_categories ordena por frecuencia desc"
  - "compute_column_stats: indices filtra filas correctamente"
  - "compute_column_stats: histograma generado para numerica"
  - "compute_column_stats: columna vacia retorna stats en cero"
  - "compute_column_stats: col fuera de rango devuelve ColStats defecto"
test_file_path: "cpp/tests/test_compute_column_stats.cpp"
file_path: "cpp/functions/core/compute_column_stats.cpp"
params:
  - name: cells
    desc: "Matriz row-major de punteros a C-strings (rows x cols). nullptr indica celda nula."
  - name: rows
    desc: "Numero de filas de la matriz."
  - name: cols
    desc: "Numero de columnas de la matriz."
  - name: col
    desc: "Indice de la columna a analizar (0-based)."
  - name: unique_cap
    desc: "Maximo de valores unicos a trackear. Default 100000. Con 0 trackea todos."
  - name: indices
    desc: "Array opcional de indices de fila a incluir. Si nullptr se usan todas las filas."
  - name: n_indices
    desc: "Longitud del array indices. Ignorado si indices es nullptr."
output: "ColStats con total, empty_count, unique_count, numeric, numeric_count, min, max, sum, mean, p25, p50, p75, hist (HIST_BINS=24 floats) y top_categories (hasta 8 pares string+count)."
---

## Ejemplo

```cpp
#include "core/compute_column_stats.h"

// Columna: ["10", "20", "30", "40", "50"]
const char* data[] = {"10", "20", "30", "40", "50"};
data_table::ColStats s = data_table::compute_column_stats(data, 5, 1, 0);
// s.mean == 30.0, s.p50 == 30.0, s.p25 == 20.0, s.p75 == 40.0

// Con filtro de filas (solo filas 0, 2, 4 -> [10, 30, 50]):
int idx[] = {0, 2, 4};
s = data_table::compute_column_stats(data, 5, 1, 0, 100000, idx, 3);
// s.mean == 30.0, s.total == 3
```

## Cuando usarla

Cuando necesites mostrar un panel de estadisticas de columna (inspector, tooltip de header, sidebar de datos), calcular min/max para escalar un histograma, o detectar columnas con mucho missing antes de aplicar un filtro.

## Gotchas

- `numeric` es `true` solo si TODOS los valores no-vacios son numericos. Una sola celda texto hace que `numeric == false` y `hist` quede vacio.
- El histograma usa interpolacion lineal para los percentiles (igual que numpy `percentile` con `method='linear'`). Para distribuciones con un solo valor, el bin central recibe todo el count.
- `unique_capped` se activa cuando hay mas valores distintos que `unique_cap`. En ese caso `unique_count == unique_cap` y puede no reflejar la cardinalidad real.
- Las `top_categories` incluyen valores numericos si la columna no es puramente numerica (mezcla). Si la columna es puramente numerica, `top_categories` lista los valores numericos como strings.
