exactcdf: distribuciones estadísticas en doble precisión, con el error declarado antes del código

Hay una escena que se repite en cualquier aula de estadística. El profesor escribe un valor z en la pizarra, alguien lo mete en una calculadora o en una hoja de cálculo, sale un valor p con ocho decimales y todo el mundo lo copia. Nadie pregunta de dónde salieron esos ocho decimales. La máquina los dijo, y la máquina no se equivoca.

Se equivoca. No siempre ni mucho, pero se equivoca, y casi nunca te avisa. Detrás de cada valor p hay una función que alguien tuvo que programar, y programar bien una función como esa es un oficio de relojero: los números grandes, los muy pequeños y las colas de la distribución se comportan cada uno a su manera, y una fórmula que funciona perfecta en el centro puede devolver basura en el extremo. La computadora es más tonta que una piedra. Hace exactamente lo que le dijeron, aunque lo que le dijeron esté mal.

exactcdf es mi respuesta a ese problema: una librería pequeña que calcula esas funciones y que, antes de calcular nada, deja por escrito cuánto se puede equivocar en cada tramo. Y luego lo comprueba.

Qué es exactcdf, en un párrafo

exactcdf es una librería de código abierto para JavaScript (Node.js) que calcula funciones de distribución acumulada —la normal, la gamma, la chi-cuadrado y la beta— y las funciones especiales en las que se apoyan (la función error y la función gamma), en doble precisión. La diseñó y la mantiene Carlos Eduardo Ravello Joo (ORCID 0009-0007-5631-7436). Está publicada en npm (se instala con npm install exactcdf) y su código está en GitHub, público desde el 5 de noviembre de 2026, bajo licencia MPL-2.0. La versión actual es la 1.0.2. No tiene dependencias, nunca devuelve NaN y cada resultado se contrasta, fila por fila, contra 31 307 valores de referencia calculados a 70 dígitos, con tolerancias por región que quedaron escritas en el repositorio antes que el código.

Instalar y usar

Necesitas Node.js 18 o posterior. Es un módulo ES ("type": "module") y no requiere compilación.

npm install exactcdf
import { pnorm, pchisq, pbeta } from "exactcdf";

pnorm(1.96);          // 0.9750021048517796
pnorm(1.96, false);   // 0.024997895148220428
pchisq(7.81, 3);      // 0.949893943649994
pbeta(0.3, 2, 5);     // 0.579825

El segundo ejemplo es el que más se usa sin saberlo: la cola superior de la normal para z = 1,96, el famoso 0,025 de cada lado que da el 95 % de confianza. En pnorm, con lowerTail en false, la librería calcula la cola de arriba directamente, sin restar de 1. Restar de 1 parece inocente, pero en las colas lejanas se come los decimales: es como pesar a un gato pesándote con él en brazos y restando tu peso. Funciona si el gato pesa bastante; si pesa poco, la balanza no se entera.

Las ocho funciones

FunciónFirmaQué devuelve
erferf(x)función error
erfcerfc(x)función error complementaria
pnormpnorm(z, lowerTail?)distribución normal estándar acumulada, Φ(z)
lgammalgamma(a)logaritmo de la función gamma, ln Γ(a)
gammagamma(a)función gamma, Γ(a)
pgammapgamma(x, a, lowerTail?)gamma incompleta inferior regularizada, P(a, x)
pchisqpchisq(x, nu, lowerTail?)chi-cuadrado acumulada con nu grados de libertad
pbetapbeta(x, a, b, lowerTail?)beta incompleta regularizada, Iₓ(a, b)

lowerTail vale true por defecto. Ninguna función devuelve NaN. Si le pasas algo fuera de dominio o de tipo equivocado —por ejemplo gamma(-1)— la librería lanza un StatsError, que hereda de RangeError y trae campos estructurados: funcion, motivo (dominio, tipo, indeterminado o pendiente), argumento, valor, dominio y region. Así quien la use puede armar su propio mensaje de error, en el idioma que quiera.

La decisión de no devolver nunca NaN es deliberada. Un NaN es un error que no hace ruido: se cuela en una suma, contamina el promedio y aparece tres pantallas después, cuando ya nadie sabe de dónde vino. Prefiero que la librería se queje en el momento y diga exactamente qué le molestó.

Cómo se sabe que está bien

Aquí está lo que de verdad me importa de exactcdf, y lo que la diferencia de una función copiada de un foro. La pregunta no es si da números: cualquier cosa da números. La pregunta es cuánto se aleja de la verdad, dónde, y quién lo decidió.

El orden fue este. El 13 de octubre de 2026 entraron al repositorio las referencias: miles de valores calculados con mpmath 1.3.0 a 70 dígitos, que es muchísimo más de lo que cabe en un número de doble precisión. Esas referencias no las produjo la IA. Entre el 21 y el 25 de octubre se escribieron y congelaron las tolerancias: cuánto error se le permite a cada función en cada región. El código llegó después, el 29 de octubre. El historial de git lo muestra en ese orden, y cualquiera lo puede revisar.

¿Por qué importa el orden? Porque si fijas la tolerancia después de ver los resultados, siempre vas a aprobar. Es como dibujar la diana alrededor de la flecha. Fijarla antes es aceptar que te pueden reprobar.

Las tolerancias, en error relativo, son estas: hasta 1e-15 para erf, erfc y pnorm; hasta 1e-14 para lgamma y gamma; hasta 1e-13 para pgamma, pchisq y pbeta, que son las cotas que declaran los propios algoritmos de origen. Los valores exactos y los resultados subnormales siguen reglas fijas aparte.

Y una confesión, porque sin ella el resto no vale. En las colas más difíciles —pgamma y pchisq en las ramas de Temme y de cola lejana, pbeta en las de fracción continua y asintótica— la tolerancia es provisional: entre 788 y 3 864 ulps, fijada como el doble del percentil 99 del error que comete R 4.6.1 en esas mismas filas. Está marcada «A FIJAR» en el archivo de tolerancias y se va a fijar en una versión posterior. No es un secreto: está en el repositorio, a la vista. (Un ulp es la distancia entre un número de doble precisión y el siguiente: la unidad más pequeña en que el número puede equivocarse.)

La versión actual pasa las 31 307 filas de referencia de las nueve funciones contrastadas —las ocho públicas más la interna gamma1pm1— sin un solo fallo. Este es el peor error medido por función:

FunciónFilasPeor caso (ulps)Región
erf1 5754erf_r2
erfc3 4486erfc_r3
pnorm4 8706pnorm_cola
lgamma1 54213lgamma_d
gamma1 0186gamma_fuera
pgamma7 902917pgamma_temme (74 % de su tolerancia)
pchisq2 170917pgamma_temme (74 %)
pbeta8 266121pbeta_bfrac20

Léelo así: en la normal, lo peor que se encontró en casi cinco mil casos fueron 6 ulps: unas quince cifras significativas correctas. En la gamma incompleta, en su rama más difícil, el peor caso llegó a 917 ulps, que siguen siendo unas doce o trece cifras correctas y quedan dentro de la tolerancia declarada. No digo «precisión de unos pocos ulps» en general, porque en las colas no es verdad. Digo exactamente cuánto y dónde.

Todo esto se puede reproducir. El mismo comando que corre la integración continua en Node 18, 20 y 22 en cada cambio:

npm test

O una función a la vez, con su informe por región:

node stats/harness/run.js --funcion pgamma

Las referencias viven en tests/fixtures/, los scripts que las generan en tests/gen/ y los informes de desarrollo en stats/informes/. Nada de esto pide fe. Pide un comando.

De dónde salen los algoritmos

No inventé nada en la parte matemática, y eso es bueno. Los métodos vienen de la literatura primaria, de gente que dedicó años a domar estas funciones:

  • la función error y su complementaria, del trabajo de W. J. Cody de 1969 sobre aproximaciones racionales de Chebyshev;
  • la gamma incompleta, de A. R. DiDonato y A. H. Morris (1986);
  • la beta incompleta, del Algoritmo 708 de DiDonato y Morris (1992).

Las referencias completas, con su DOI, están al final de la página. Lo que hizo falta fue leer esos textos con lupa y decidir qué hacer en los puntos que dejan abiertos. Esas decisiones están escritas en el repositorio, una por una.

Para qué sirve

Si haces estadística, usas estas funciones aunque nunca las hayas llamado por su nombre. Algunos ejemplos concretos:

  • Valores p. El de una prueba z sale de pnorm; el de una prueba chi-cuadrado (independencia, bondad de ajuste) sale de pchisq.
  • Psicometría. Convertir un puntaje z en percentil es pnorm. Las calculadoras de corrección de instrumentos psicológicos necesitan estas funciones por debajo, y necesitan que sean confiables.
  • Proporciones y conteos. La beta incompleta da directamente la probabilidad acumulada de la binomial: el valor p exacto de una prueba binomial sale de pbeta. La gamma incompleta hace lo mismo con la de Poisson: la probabilidad acumulada de un conteo sale de pgamma.
  • Otras disciplinas. Fiabilidad en ingeniería, epidemiología, control de calidad, pruebas A/B en producto digital: cualquier lugar donde una decisión dependa de una probabilidad acumulada.
  • Herramientas en JavaScript. Si construyes una calculadora o un panel en Node, puedes usar exactcdf como motor y saber, por escrito, cuánto se puede equivocar.

En mi caso, exactcdf es el motor de las calculadoras para investigación que estoy construyendo, empezando por una para corregir instrumentos psicológicos, en código auditable.

Lo que todavía está en el taller

Las funciones inversas (qnorm, qgamma, qchisq, qt) y la t de Student acumulada (pt) ya tienen sus referencias en el repositorio, pero todavía no tienen implementación. Van a llegar por el mismo camino: tolerancias primero, código después.

Esta versión corre en Node.js. El paquete lee su archivo de reglas con node:fs, así que una versión para navegador es un trabajo aparte, que vendrá más adelante.

Cómo se hizo

Lo digo con las mismas palabras que el repositorio y el registro de Zenodo, para que no haya dos versiones. El código de stats/src, el arnés de pruebas (stats/harness) y los scripts que generan las referencias (tests/gen) los escribieron modelos de IA de Anthropic (de las familias Claude Opus y Sonnet, mediante Claude Code y Cowork, entre octubre y noviembre de 2026), a partir de una especificación escrita, derivada de la literatura primaria (Cody 1969; DiDonato y Morris 1986, 1992) y aprobada por el autor. Los valores de referencia no los produjo la IA: se calcularon con R 4.6.1 y mpmath 1.3.0, a 70 dígitos. El autor dirigió el proyecto, tomó cada decisión de diseño y de alcance, resolvió las ambigüedades numéricas que los textos dejan abiertas y firmó cada versión. Las tolerancias se fijaron y congelaron antes de escribir el código, y cada pieza se auditó en sesiones de IA distintas de la que la produjo.

Lo cuento así porque es lo que pasó, y porque una librería que presume de verificar no puede esconder cómo se construyó. La IA escribe rápido y con aplomo; por eso mismo el trabajo serio está en lo que no escribe ella: las referencias, las tolerancias fijadas de antemano y la decisión de qué se aprueba. La piedra no decide sola.

El expediente con DOI

El código, las referencias y las auditorías tal como quedaron al cerrar el desarrollo están depositados en Zenodo con el DOI 10.5281/zenodo.23811083, con fecha 30 de octubre de 2026. Los archivos de ese depósito son de acceso restringido, pero su manifiesto de huellas SHA-256 es público: permite comprobar en cualquier momento que un archivo es exactamente el que existía en esa fecha.

Licencia

exactcdf se publica bajo la Mozilla Public License 2.0 (MPL-2.0). En la práctica: puedes usarla dentro de software cerrado o comercial; si modificas los archivos de la propia librería, esos cambios tienen que seguir abiertos bajo la misma licencia.

Cómo citarlo

Si usas exactcdf en una investigación, cita el software:

Ravello Joo, C. E. (2026). exactcdf (Version 1.0.2) [Computer software]. https://github.com/carlosravello-png/exactcdf

Y, si te sirve el expediente de desarrollo:

Ravello Joo, C. E. (2026). stats.js directa y su expediente: funciones estadísticas de alta precisión en JavaScript, con fixtures y auditorías [Direct stats.js and its dossier: high-precision statistical functions in JavaScript, with fixtures and audits] (Version 1.0.0). Zenodo. https://doi.org/10.5281/zenodo.23811083

El repositorio incluye un archivo CITATION.cff, así que GitHub te ofrece la cita lista con el botón «Cite this repository».

Preguntas frecuentes

¿Qué es exactcdf?

Una librería de JavaScript para Node.js que calcula las funciones de distribución acumulada normal, gamma, chi-cuadrado y beta, y las funciones error y gamma, en doble precisión, sin dependencias y con cada resultado contrastado contra referencias de 70 dígitos.

¿Cómo se instala?

Con npm install exactcdf. Requiere Node.js 18 o posterior y se importa como módulo ES.

¿Funciona en el navegador?

Esta versión no: corre en Node.js, porque lee su archivo de reglas con node:fs. Una versión para navegador está prevista como trabajo aparte.

¿Qué tan exacto es?

Pasa las 31 307 filas de referencia sin fallos. El peor error medido va de 4 ulps (erf) a 917 ulps (pgamma y pchisq en la rama de Temme), siempre dentro de tolerancias por región fijadas antes del código. En las colas más difíciles esas tolerancias son provisionales y están marcadas así en el repositorio.

¿Quién lo escribió?

Lo diseñó y lo mantiene Carlos Eduardo Ravello Joo. El código, el arnés y los generadores los escribieron modelos de IA de Anthropic a partir de una especificación aprobada por él; las referencias se calcularon con R y mpmath, no con IA; él tomó las decisiones de diseño y firmó cada versión.

¿Puedo usarlo en software comercial o cerrado?

Sí. La licencia MPL-2.0 lo permite; solo exige que los cambios a los archivos de la propia librería sigan abiertos.

¿En qué se diferencia de otras librerías de estadística en JavaScript?

No he medido comparaciones de velocidad ni de precisión con otras librerías, así que no las afirmo. La diferencia que sí puedo mostrar es de método: tolerancias declaradas por región antes de escribir el código, un arnés de pruebas congelado y público, y un error máximo medido y publicado para cada función.

¿Qué funciones faltan?

Las inversas (qnorm, qgamma, qchisq, qt) y la t de Student acumulada (pt). Sus referencias ya están en el repositorio; la implementación vendrá en versiones posteriores.

¿Cómo lo cito?

Ravello Joo, C. E. (2026). exactcdf (Version 1.0.2) [Computer software]. https://github.com/carlosravello-png/exactcdf. El repositorio incluye CITATION.cff.

Referencias

  1. Cody, W. J. (1969). Rational Chebyshev approximations for the error function. Mathematics of Computation, 23(107), 631–637. https://doi.org/10.1090/S0025-5718-1969-0247736-4
  2. DiDonato, A. R., & Morris, A. H. (1986). Computation of the incomplete gamma function ratios and their inverse. ACM Transactions on Mathematical Software, 12(4), 377–393. https://doi.org/10.1145/22721.23109
  3. DiDonato, A. R., & Morris, A. H. (1992). Algorithm 708: Significant digit computation of the incomplete beta function ratios. ACM Transactions on Mathematical Software, 18(3), 360–373. https://doi.org/10.1145/131766.131776

Software: npm · GitHub · licencia MPL-2.0
Expediente: DOI 10.5281/zenodo.23811083
Texto de esta página: CC BY 4.0

← Todas las herramientas
EN