Metadata-Version: 2.4
Name: n-metrics
Version: 0.4.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

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.

---

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

---

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

---

## 🛠️ 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

```

---

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

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

---

## 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 a través de su **$p$-valor Topológico exacto ($p_{top}$)**.
