Metadata-Version: 2.4
Name: n-metrics
Version: 0.2.0
Summary: N Framework: The Exact Thermodynamics of Consensus
Author-email: Manuel Narbona Sarria <manuel.narsa@gmail.com>
License: GNU General Public License v3.0
Project-URL: Homepage, https://github.com/manuel-narsa/n-metrics
Project-URL: Documentation, https://github.com/manuel-narsa/n-metrics/wiki
Project-URL: Source, https://github.com/manuel-narsa/n-metrics
Project-URL: Issues, https://github.com/manuel-narsa/n-metrics/issues
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Science/Research
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.20.0
Requires-Dist: pandas>=1.3.0
Requires-Dist: scipy>=1.7.0
Dynamic: license-file



```
# 🚀 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.

---

## 🗺️ Cuadro General de la Librería

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.

| Topología | Escala | Coeficiente Natural | Estimadores Clásicos | Comandos de Análisis CLI | Comandos de Stress Test (Cobertura) |
| :--- | :--- | :--- | :--- | :--- | :--- |
| **Intervalar** | Numérica Continua | **NI** (Natural Interval) | **AKI** (Alpha Krippendorff)<br>**ICC(2,1)** (F-ANOVA) | `nmetrics-ni`<br>`nmetrics-aki`<br>`nmetrics-icc21` | `nmetrics-ni-cob`<br>`nmetrics-aki-cob`<br>`nmetrics-icc21-cob` |
| **Nominal** | Categórica (Sin orden) | **NN** (Natural Nominal) | **AKN** (Alpha Krippendorff)<br>**KF** (Kappa Fleiss) | `nmetrics-nn`<br>`nmetrics-akn`<br>`nmetrics-kf` | `nmetrics-nn-cob`<br>`nmetrics-akn-cob`<br>`nmetrics-kf-cob` |
| **Ordinal** | Categórica (Ordenada) | **NO** (Natural Ordinal) | **AKO** (Alpha Krippendorff)<br>**W** (Kendall W) | `nmetrics-no`<br>`nmetrics-ako`<br>`nmetrics-w` | `nmetrics-no-cob`<br>`nmetrics-ako-cob`<br>`nmetrics-w-cob` |

*💡 **Comandos Globales:** Además de los individuales, puedes usar `nmetrics-interval`, `nmetrics-nominal` y `nmetrics-ordinal` para generar tablas comparativas de todos los coeficientes de una misma familia.*

---

## 🎲 Motor de Simulación y Generador de Escenarios

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.

### ¿Qué hace el Generador de Escenarios?
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.

### Análisis de Cobertura (Stress Testing)
Gracias a los 9 comandos CLI terminados en `-cob` (ej. `nmetrics-ni-cob`), 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.
- Calculan la *Población Real Asintótica* de esa matriz.
- Evalúan si el Intervalo de Confianza generado (por Simulación Ponderada o Bootstrap Clásico) logra "atrapar" o cubrir el valor poblacional real.

---

## 🛠️ Instalación

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`):
```bashpip install -e .
```

---

## 💻 Uso por Terminal (CLI) - Ejemplos Rápidos

La instalación te otorga acceso a **21 comandos de terminal**.

**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**

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**

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
```

---

## 🐍 Uso de la API en Python (Jupyter / Scripts)

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}]")
```

---

### Notas para el Investigador:

- 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.

```

```
