datanarrator 0.1.5

Convierte cualquier DataFrame de pandas en un análisis en lenguaje natural

datanarrator 📊

datanarrator convierte cualquier DataFrame de pandas en un análisis en lenguaje natural. En lugar de leer tablas de números, obtienes texto interpretado con hallazgos, alertas y recomendaciones automáticas y reportes HTML interactivos.

---

Instalación

pip install datanarrator

---

Uso rápido

import pandas as pd
from datanarrator import Narrator

df = pd.read_csv("datos.csv")
n = Narrator(df, lang="es")

print(n.describe())

---

Métodos disponibles

Método	Descripción
describe()	Análisis completo en lenguaje natural
executive_summary()	Resumen ejecutivo de 2-3 oraciones
alerts_only()	Solo alertas y recomendaciones
quality_score()	Score de calidad del dataset de 0 a 100 con grado A–F
narrative()	Análisis narrativo interpretativo en párrafos
suggest()	Sugiere modelos ML y pasos de preprocesamiento
compare(df2)	Compara dos datasets y detecta data drift
export(filepath)	Exporta a .txt, .md o reporte .html interactivo

---

Ejemplos de uso

Análisis completo

n = Narrator(df, lang="es")
print(n.describe())

--- Resumen general ---
El dataset contiene 891 registros con 12 columnas: 7 numéricas, 5 categóricas.
Valores nulos: 866 (8.1% del total).
--- Columnas numéricas ---
Age: media=29.7, mediana=28.0, std=14.53. Se detectaron 11 posibles outliers.
--- Correlaciones relevantes ---
Pclass ↔ Fare: correlación moderada negativa (-0.55)
--- Alertas y recomendaciones ---
⚠  'Cabin' tiene 77.1% de valores nulos.
→ Considera imputar o eliminar esta columna.

Sugerencias de modelado

print(n.suggest())

--- Sugerencias para modelado ---
Tipo de problema detectado: clasificacion binaria
Variable objetivo probable: Survived
Modelos recomendados:
→ Logistic Regression — buen baseline para clasificacion
→ Random Forest — robusto con variables mixtas
→ XGBoost — recomendado si priorizas accuracy
Preprocesamiento recomendado:
→ Imputar nulos en: Age
→ Encodear variables categoricas: Name, Sex, Ticket, Cabin, Embarked

Comparar dos datasets

n = Narrator(df_train, lang="es")
print(n.compare(df_produccion))

--- Comparación de datasets ---
El segundo dataset tiene 267 registros menos.
'Age': media subió de 29.7 a 44.34 (+49.3%).
⚠  Posible data drift en: Age.
→ Dispersión cambió más del 30%. Revisa antes de producción.

Score de calidad

resultado = n.quality_score()
print(resultado["resumen"])
print(resultado["penalizaciones"])

El dataset obtuvo un score de 72/100 (grado C).
{'nulos': 12.15, 'duplicados': 0, 'constantes': 0, 'cardinalidad': 0, 'cols_nulas': 10}

Análisis narrativo

print(n.narrative())

Con 891 registros y 12 columnas, el dataset es de tamaño moderado — adecuado
para la mayoría de algoritmos de machine learning. Contiene 7 variables numéricas
y 5 categóricas. El problema de calidad más crítico es la columna "Cabin", que
concentra el 77.1% de valores nulos...

Exportar reporte HTML interactivo

n.export("reporte_titanic.html")  # reporte visual con gráficas
n.export("reporte_titanic.txt")   # texto plano

El reporte HTML incluye navegación por secciones, semáforo de salud por columna, histogramas, gráficas interactivas con Chart.js, score de calidad y sugerencias de ML.

Soporte multilenguaje

n_es = Narrator(df, lang="es")  # Español
n_en = Narrator(df, lang="en")  # English

---

Correr con Docker

# Clonar el repositorio
git clone https://github.com/ikernavarro4/data-narrator.git
cd data-narrator

# Construir y correr el contenedor
docker compose up --build

El contenedor instala la librería desde PyPI y corre automáticamente el script de ejemplo con el dataset del Titanic.

---

Correr los tests

pip install pytest
pytest tests/ -v

---

Repositorio y links

• GitHub: https://github.com/ikernavarro4/data-narrator
• PyPI: https://pypi.org/project/datanarrator/
• Tutorial en Colab: https://colab.research.google.com/github/ikernavarro4/data-narrator/blob/main/notebooks/tutorial.ipynb