1. #  N-Metrics: The Exact Thermodynamics of Consensus
   

nmetrics es una librería avanzada de Python diseñada para evaluar la fiabilidad y el consenso en matrices de datos empíricos. Propone un nuevo marco topológico y termodinámico (El Marco N) que supera las limitaciones de la inferencia frecuentista asintótica, situando a la población en el centro del Intervalo de Confianza mediante IPW (Simulación Ponderada).

Además de los nuevos coeficientes Naturales (NI, NN, NO), la librería incluye motores ultra-optimizados (vectorizados y en C) para calcular los estimadores clásicos de consenso y sus remuestreos por Bootstrap Clásico, así como un avanzado motor de simulación de Monte Carlo para someter a los estimadores a pruebas de estrés.

La arquitectura de nmetrics se divide en tres topologías fundamentales. Cada una cuenta con su Coeficiente Natural, estimadores clásicos de contraste y un arsenal de comandos de consola (CLI) para análisis empírico y simulaciones teóricas.

💡 Comandos Globales y Comparativos: Además de los individuales, puedes usar nmetrics-interval, nmetrics-nominal y nmetrics-ordinal para análisis empíricos comparativos. Para simulaciones masivas de estrés que enfrentan a los tres motores de una familia simultáneamente, utiliza nmetrics-interval-comp, nmetrics-nominal-comp y nmetrics-ordinal-comp.

El núcleo de validación matemática de la librería reside en su módulo generador_escenarios. Este motor permite recrear paneles de jueces virtuales (Sujetos x Evaluadores) bajo condiciones controladas de ruido termodinámico y sesgo.

Permite modelar el comportamiento de evaluación humana inyectando "ruido paramétrico" (para escalas intervalares) o "ruido categórico" (para escalas nominales/ordinales). Incluye 5 escenarios universales predefinidos:

1. Casi Nulo: Acuerdo destruido por entropía máxima (ruido extremo).
2. Aleatorio: Respuestas generadas por puro azar combinatorio.
3. Razonable: Consenso humano típico con desacuerdos locales moderados.
4. Casi Perfecto: Jueces altamente calibrados con desviaciones mínimas.
5. Casi Idéntico: Unanimidad absoluta o varianza topológica tendente a cero.

Gracias a los comandos CLI terminados en -cob y -comp, puedes cruzar el generador de escenarios con los estimadores. Estos comandos lanzan experimentos de Monte Carlo masivos que:

• Generan matrices dinámicas basadas en los escenarios descritos.
• Establecen la Verdad Poblacional Termodinámica (el centro topológico exacto del Marco N).
• Evalúan si el Intervalo de Confianza generado (por Simulación Ponderada o Bootstrap Clásico) logra "atrapar" o cubrir esa verdad poblacional, revelando los sesgos empíricos de los estimadores tradicionales.

Puedes instalar la librería en tu entorno local (o entorno virtual) ejecutando el siguiente comando desde la raíz del proyecto (donde se encuentra el archivo pyproject.toml):

La instalación te otorga acceso a 24 comandos de terminal completos.

1. Análisis Empírico Individual con Auditoría (Marco N)

Ejecutar el Coeficiente Natural Ordinal (NO), auditar anomalías a 2.5 sigmas para detectar jueces problemáticos y exportar las réplicas:

Bash

nmetrics-no encuestas_clinicas.csv -u 2.5 --exportar output_replicas.csv

2. Tabla Comparativa Global de Datos Empíricos

Analizar datos categóricos guardados con comas (la librería traduce automáticamente letras como 'A', 'B' a isomorfismos numéricos):

Bash

nmetrics-nominal diagnosticos.csv -k 7 -s "," -r 5000

3. Lanzar un Stress Test de Cobertura Matemática Individual

Simular 500 paneles de 10 jueces evaluando a 100 sujetos en escala de 5 para poner a prueba el Coeficiente Natural Intervalar (NI), guardando los resultados:

Bash

nmetrics-ni-cob -n 100 -m 10 -k 5 -e 500 -o validacion_ni.csv

4. Batalla de Estimadores (Stress Test Global)

Enfrentar a las tres métricas ordinales (NO, AKO, Kendall W) en una simulación de Monte Carlo de 100 experimentos para demostrar la superioridad de la Simulación Ponderada frente al Bootstrap Clásico:

Bash

nmetrics-ordinal-comp -n 50 -m 7 -k 5 -e 100 -r 1000 -o comparativa_ordinal.csv

Si prefieres integrar nmetrics en tus pipelines, la librería expone una arquitectura limpia de núcleos matemáticos y simuladores.

Python

import numpy as np
from nmetrics.interval import calcular_estadisticas_ni
from nmetrics.simulation.generador_escenarios import generar_matriz_dinamica

# 1. Simular un panel clínico de 30 pacientes, 5 médicos, escala 1-10 en escenario 'Razonable'
matriz_simulada = generar_matriz_dinamica(n_sujetos=30, m_jueces=5, k_escala=10, 
                                          escenario='Razonable', tipo_escala='paramétrica')

# 2. Ejecutar el motor de Simulación Ponderada Intervalar
# Retorna: Muestra, Ponderado, Límite Inf, Límite Sup, Réplicas, Matrices, Índices
ni_mu, ni_pob, ic_inf, ic_sup, *_ = calcular_estadisticas_ni(matriz_simulada, S_replicas=2000, k_escala=10, metodo_ic='SP')

print(f"Acuerdo Empírico (Muestra): {ni_mu:.4f}")
print(f"Acuerdo Poblacional (Proyectado): {ni_pob:.4f}")
print(f"Intervalo de Confianza del Panel: [{ic_inf:.4f}, {ic_sup:.4f}]")

• Todos los motores de inferencia toleran datos faltantes (NaN) de forma nativa.

• En la topología Ordinal, la auditoría de anomalías topológicas evalúa a las columnas (Jueces), mientras que en las familias Intervalar y Nominal evalúa a las filas (Sujetos).

• Los Coeficientes Naturales incluyen un Nivel III que calcula analíticamente la Esperanza Nula (Límite de Azar Termodinámico) exacto según la combinatoria del hiperespacio, informando de la validez topológica del consenso a través de su $p$-valor Topológico exacto ($p_{top}$).