# Tabular2: funciones típicas y ampliación del procesamiento numérico

Decisión del autor, 2026-10-08: el procesamiento numérico general requerido por Simplot corresponde a **Tabular2**, no a un segundo motor numérico dentro del graficador. Este documento registra funciones existentes y pendientes; no anuncia una implementación nueva ni fija nombres de API que todavía no existen.

## Qué funciones son típicas de Tabular2

Tabular2 debe encargarse de leer, representar, consultar y transformar tablas numéricas, y producir resultados reutilizables sin necesitar un gráfico. Simplot decide qué series dibujar, los ejes, las leyendas, los paneles y los formatos de salida.

| Familia de funciones típicas | Operaciones | Estado verificado en las fuentes |
|---|---|---|
| Carga y consulta | Leer archivo o texto en memoria; listar tablas, columnas, unidades y bloques | Ya hay lectores y API; `create_table_from_string`, `table.h`, `view.h`; revisar compatibilidad del consumidor antes de ampliar |
| Carga de bytes desde DAT | Recibir texto o un binario decodificado con longitud y formato explícitos | `create_table_from_buffer_format(name, bytes, length, format, &nt)` acepta `auto`, `csv`, `simul` y `texto`; CSV funciona aunque el nombre lógico no termine en `.csv`. `create_table_from_buffer()` conserva la detección anterior. Probado con CSV y POS4; el decodificador base64 y el adaptador DAT aún faltan |
| Vistas de columnas | Elegir dominio y codominio por nombre o índice; reutilizar tablas cargadas | Existente; vistas e interfaces `interpolate*` |
| Interpolación y extrapolación | Valor entre nodos, lineal/spline, tratamiento de saltos y extremos | Existente; reutilizar su semántica, no duplicarla en Simplot |
| Búsqueda inversa | Encontrar abscisas correspondientes a un valor | Orden `inversa` de `interpola`; revisar/exponer contrato reutilizable para otros programas |
| Remuestreo | Generar una tabla sobre una malla de abscisas; paso fijo o malla declarada | `saltos A B P` ya genera paso fijo en `interpola`; mallas generales e interfaz reutilizable, a completar |
| Agregación sobre un intervalo | Integral, valor medio sobre la abscisa y valor eficaz | `integ`, `avg`, `rms` existen en `src/interpola.c`; usan trapecios y extremos interpolados linealmente; falta separar/exponer lo necesario como servicio reutilizable |
| Selección y ordenamiento | Filtrar filas, proyectar columnas, ordenar establemente, recortar y encadenar operaciones | Ampliación general pendiente; la selección histórica de Simplot se mantiene hasta poder delegarla |
| Álgebra de columnas | Expresiones por fila, escalado, desplazamiento, combinación y normalización | Planificar API común y evaluador restringido; no implementar otro con `eval` en Simplot |
| Operaciones entre tablas | Alineación por abscisa, unión, comparación, diferencias y remuestreo explícito | Pendiente; no mezclar corridas por posición ni interpolar silenciosamente |
| Estadística descriptiva | Recuento, suma, media aritmética, mínimo/máximo, varianza, desvío, mediana y cuantiles | Catálogo propuesto; no confundir la media de muestras con `avg`, que promedia sobre un intervalo de la abscisa |
| Agrupaciones e histogramas | Agregar por claves, intervalos/frecuencias, densidades normalizadas, distribución acumulada, resúmenes para cajas | Pendiente; Tabular2 calcula los valores, Simplot dibuja barras, cajas o curvas |
| Ventanas y acumulados | Sumas/promedios móviles, acumulación, normalización por referencia y eliminación de fondo | Pendiente; fijar ventana por muestras o por abscisa, bordes y tratamiento de huecos |
| Derivación numérica | Derivadas de una tabla, malla regular o irregular y tratamiento de extremos | Pendiente como operación general: `derivative` en `interpolate.c` prepara segundas derivadas para spline; no equivale a una API general de derivación |
| Integración ampliada | Integral acumulada, métodos/tolerancias explícitos, integración por tramos | Ampliación de `integ`, no reescritura de cero; distinguirla de resolver una ODE, tarea de Siru/Simul2 |
| Suavizado e interpolación ampliada | Ventanas, ajustes locales, políticas de interpolación y remuestreo | Reutilizar interpolación actual; no presentar spline interpolante como un filtro de ruido |
| Ajustes y regresión | Lineal y otros modelos, pesos, residuos, parámetros y diagnóstico de convergencia | Pendiente; resultados numéricos independientes de Gnuplot |
| FFT y análisis espectral | Transformación, amplitud/fase, espectros y filtrado asociado | Pendiente; definir muestreo, ventana, normalización y backend antes de elegir API |
| Incertidumbre y funciones muestreadas | Calcular estadísticos/intervalos, propagar errores cuando se defina el modelo, generar tablas a partir de funciones | Pendiente; dibujar errores ya suministrados no requiere calcularlos, y sigue siendo tarea de Simplot |

Las primeras familias ya tienen implementación en distinto grado; las posteriores son el catálogo de ampliación. No llamar a una orden de consola «API de biblioteca» si hoy su implementación es `static` dentro de `interpola.c`. Antes de añadir nombres nuevos, inventariar las funciones exportadas y extraer/reutilizar las operaciones ya disponibles.

## Reparto con Simplot

| Operación | Responsable |
|---|---|
| Obtener datos, convertir fechas/unidades y producir tablas derivadas | Tabular2, reutilizando sus dependencias actuales y ampliándolo donde falte |
| Calcular frecuencias, cuantiles, ajustes, derivadas, integrales o espectros | Tabular2 |
| Validar y ejecutar el grafo de operaciones numéricas reutilizables | Tabular2; Simplot transmite el pedido y recibe resultados/errores |
| Elegir series, agrupar dibujos por magnitud, construir paneles y leyendas | Simplot |
| Representar barras de error y bandas con cotas ya calculadas | Simplot |
| Escala logarítmica del eje, límites visibles, color y tamaño de símbolos | Simplot; transformar una columna mediante logaritmo o una fórmula general es Tabular2 |
| Dibujar una función analítica en Gnuplot | Se conserva el comportamiento actual de Simplot; materializar una tabla numérica de esa función corresponde a Tabular2 |
| Gramática DS/PARAPLOT y transporte DAT compartido | slex/Siru y adaptadores; no duplicar algoritmos numéricos en el parser |

Simplot v2 ya depende del paquete `tabular` y usa `interpola --exportar-simul` para leer tablas sin duplicar sus lectores. Esa integración no completa T0: todavía falta exponer las operaciones numéricas enumeradas abajo. No se elimina el filtro histórico v1 ni se cambian sus conversiones existentes; se migrarán cuando Tabular2 ofrezca una interfaz equivalente y las regresiones comparen resultados.

## Contrato necesario antes de incorporar operaciones

- Tablas originales inmutables; cada resultado derivado conserva nombres, unidades, bloque de corrida y procedencia.
- Separar magnitudes, unidades y coordenadas gráficas; convertir unidades una sola vez. Fechas completas en epoch; sin zona explícita, respetar máquina/TZ según el comportamiento existente.
- Diferenciar dato faltante, celda textual, NaN/error de cálculo y discontinuidad. Mantener el pendiente de texto y vecinos numéricos del README; no rellenar o unir saltos por defecto.
- Declarar política de abscisas repetidas, ordenamiento y alineación. Rechazar mezclas incompatibles entre corridas; interpolar solo si se pide expresamente.
- Distinguir media de muestras, media ponderada, media sobre el tiempo, RMS y densidad normalizada. Especificar extremos incluidos, bins vacíos y normalización.
- Conservar precisión de double en la interfaz y exportación; resultado numérico y diagnóstico legibles por máquina, no analizar mensajes humanos de la terminal.
- API con errores explícitos, sin terminar el proceso consumidor; respetar los contextos `tb_ctx` y no usar un mismo contexto simultáneamente desde varios hilos.
- Expresiones con operadores/funciones admitidos, sin ejecutar Perl, shell o comandos de Gnuplot. Reutilizar un evaluador del proyecto si su contrato sirve, sin decidir una dependencia nueva solo por este inventario.
- Definir interfaz C reutilizable y vía de consumo desde Simplot en Perl; estudiar biblioteca o comando por lotes con formato estable. No fijar SWIG, FFI ni un protocolo sin evaluar el caso real.

## Orden de trabajo y pruebas

### Primer paso: interfaz reutilizable para Simplot (T0)

Avance previo, sin completar T0: la exportación .simul conserva metadatos de columnas y acepta `--unidad`/`--unidad-origen` para convertir con libunidades/GNU units (`tempC`, `tempF`, unidades compuestas), además de `--magnitud-origen` para completar un rótulo ausente. Simplot v2 lo consume para RESULTADOS/UNIDADES y ejes de presentación; no contiene conversiones propias. Esta interfaz no expone todavía las seis operaciones generales que siguen.

Antes de incorporar operaciones nuevas, revisar y exponer las existentes —interpolación, búsqueda inversa, media, RMS, integral y remuestreo— mediante una interfaz reutilizable por Simplot. Es el primer entregable de Tabular2 para esta integración, no una tarea de implementación del graficador.

1. Identificar qué operaciones ya están exportadas por la biblioteca y cuáles permanecen dentro de `interpola.c`; documentar argumentos, resultados, unidades y errores.
2. Extraer o exponer las operaciones de consola que falten, reutilizando los algoritmos actuales y conservando su comportamiento. La consola y Simplot deben consumir la misma implementación.
3. Definir cómo Simplot en Perl accede a esa interfaz, con datos y errores legibles por máquina y precisión suficiente; no interpretar la salida humana de la terminal ni fijar todavía SWIG/FFI.
4. Verificar equivalencia entre consola e interfaz para las seis operaciones, incluidos extremos, saltos, errores y tablas originales intactas. Solo entonces dar T0 por completada.

Estado: pendiente de implementación; esta anotación no agrega funciones ni cambia la API.

| Etapa | Trabajo en Tabular2 | Pruebas mínimas |
|---|---|---|
| T0 | Inventariar y exponer lo existente: vistas, interpolación, inversa, avg/rms/integ y remuestreo | Comparar consola/API, valores en nodos, saltos, extremos y errores; preservar comportamiento actual |
| T1 | Contrato de tablas derivadas, filtros, columnas calculadas, alineación y dependencias | Filas desordenadas, filtros encadenados/ciclos, bloques de distintas longitudes, originales intactos, expresiones inválidas |
| T2 | Estadística, histogramas, agrupaciones, ventanas y acumulados | Referencias pequeñas calculadas a mano, recuentos conservados, muestra vs población, bins/bordes/huecos y unidades |
| T3 | Derivación, integral acumulada, suavizado y ajustes | Recta/parábola, malla irregular, ruido conocido, residuos y fallos de convergencia |
| T4 | FFT, espectros y ampliaciones de incertidumbre | Señales conocidas, escala de amplitud/potencia, ventana, malla no uniforme y unidades |
| Integración | Simplot consume cada capacidad disponible, sin duplicarla | Mismos resultados que API/CLI; DAT sin DS; sin Gnuplot para probar cálculos; comparar selección histórica antes de sustituirla |

Este plan concreta una necesidad nueva surgida de [la comparación de graficadores de Simplot](../../simplot/doc/PLAN-FUNCIONAL.md). Matiza la decisión de mantenimiento del 2026-10-06: se registran ampliaciones solicitadas, no se da por implementado el catálogo ni se cambian prioridades de otros proyectos. Las funciones gráficas pueden avanzar usando tablas ya calculadas mientras se desarrolla este contrato.