ValenPulse

ValenPulse es un proyecto de ciencia de datos que estudia si el lenguaje y la actividad histórica de Twitter pueden aportar señales para estimar la variación trimestral del PIB de la Comunitat Valenciana. Combina procesamiento de lenguaje natural, variables agregadas de actividad social y evaluación temporal reproducible sobre datos de 2012 a 2016.

El objetivo del dataset se conserva como dif_percentage. ValenPulse es un análisis exploratorio retrospectivo y no una previsión económica oficial ni un sustituto de las fuentes estadísticas públicas.

Funcionalidad

• Descarga y validación del dataset histórico.
• Agregación de tuits y señales numéricas por trimestre.
• Variables temporales y retardos construidos únicamente con información pasada.
• Backtesting de ventana expansiva, sin mezclar trimestres futuros en el entrenamiento.
• Pipelines con imputación, escalado y TF-IDF ajustados dentro de cada fold.
• Comparación de modelos Ridge, Random Forest y una referencia ingenua.
• Métricas fuera de muestra y comparaciones de Wilcoxon con corrección de Holm.
• Exportación de control de calidad, predicciones, métricas, gráficos y modelo final.

Metodología

La unidad de evaluación es el trimestre, no cada tuit individual. Todos los tuits y las señales de actividad se agregan antes del entrenamiento para evitar tratar observaciones del mismo trimestre como objetivos independientes.

La columna pib contemporánea se excluye de los predictores porque no estaría disponible al estimar la variación del mismo trimestre. El backtest utiliza una ventana expansiva: cada predicción se entrena solo con los trimestres anteriores.

Aunque el dataset contiene muchos tuits, dispone de aproximadamente veinte objetivos trimestrales independientes. Por ese motivo se priorizan modelos regularizados y un Random Forest como comparación no lineal. Una red profunda sobre el objetivo repetido por tuit aumentaría de forma artificial el tamaño aparente de la muestra y elevaría el riesgo de sobreajuste.

Estructura

ValenPulse/
├── src/valenpulse/
│   ├── cli.py          # interfaz de comandos
│   ├── config.py       # configuración reproducible
│   ├── data.py         # descarga, validación y agregación trimestral
│   ├── modeling.py     # modelos, backtesting, métricas y Wilcoxon
│   ├── pipeline.py     # ejecución completa y persistencia
│   └── reporting.py    # informes y visualizaciones
├── tests/test_pipeline.py
├── pyproject.toml
└── README.md

Requisitos e instalación

El proyecto requiere Python 3.10 o posterior.

git clone https://github.com/rld8/ValenPulse.git
cd ValenPulse
python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e .
valenpulse --help

En PowerShell:

python -m venv .venv
.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -e .
valenpulse --help

Instalación alternativa con uv:

uv venv --python 3.12
source .venv/bin/activate
uv pip install -e .

Datos

Descarga el dataset configurado por el proyecto:

valenpulse download

Por defecto se guarda en:

data/ComunidadValencianaTweetsPIB_2012_2016.csv.gz

La ruta y la URL pueden cambiarse con --data-path y --url. Los datos descargados y los resultados de ejecución se excluyen de Git.

Ejecución

Valida el esquema, los trimestres y las variables sin entrenar:

valenpulse validate

Ejecuta el pipeline completo:

valenpulse run

Si el dataset no está disponible, run lo descarga automáticamente. Para una prueba más rápida:

valenpulse run \
  --min-train-quarters 4 \
  --random-forest-trees 50 \
  --max-text-features 500

Consulta todos los parámetros con:

valenpulse run --help

Modelos

valenpulse list-models

Modelo	Descripción
naive_last	Repite el último valor conocido y actúa como referencia mínima.
numeric_ridge	Ridge con señales trimestrales, estacionalidad y retardos.
text_ridge	TF-IDF del texto agregado por trimestre y Ridge.
multimodal_ridge	Combina texto y señales numéricas en un mismo pipeline.
random_forest	Comparación no lineal sobre variables numéricas.

La referencia naive_last es obligatoria. Un modelo solo aporta valor práctico dentro del experimento si mejora esa referencia en las métricas fuera de muestra.

Resultados

La carpeta outputs/valenpulse/ contiene:

• summary.json: configuración, calidad de datos y modelo seleccionado;
• data_quality.json: filas válidas, duplicados, rango temporal y columnas excluidas;
• quarterly_features.csv: variables trimestrales sin el texto completo;
• backtest_predictions.csv: predicciones fuera de muestra;
• model_metrics.csv: MAE, RMSE, R² y exactitud de dirección;
• wilcoxon_comparisons.csv: comparaciones pareadas con corrección de Holm;
• eda.png, backtest_predictions.png y model_comparison.png;
• best_model.joblib, o el estado de la referencia ingenua si resulta ganadora.

Pruebas

python -m unittest discover -s tests -v

Las pruebas generan un dataset sintético, comprueban la ausencia de información futura, ejecutan los modelos y validan los artefactos producidos por el pipeline.

Ejecución y despliegue

ValenPulse es un pipeline de análisis por lotes con interfaz de línea de comandos. El repositorio no incluye una API, un dashboard, un contenedor Docker ni un despliegue web. La forma de ejecución soportada es instalar el paquete en un entorno Python y lanzar valenpulse run localmente o desde un ejecutor de trabajos compatible.

Limitaciones

• El número de trimestres es pequeño y las métricas tienen incertidumbre elevada.
• Twitter no representa de manera uniforme a la población ni a toda la actividad económica.
• La relación observada no implica causalidad.
• Los resultados se limitan al periodo y al dataset analizados.
• El modelo no sustituye las estadísticas oficiales ni debe utilizarse como única base para decisiones económicas.