🧩 Pipeline para Derivar una Taxonomía de Investigación en Software Visualization (VISSOFT)

Este repositorio contiene el paquete de replicación del estudio de análisis temático aplicado al corpus de publicaciones de VISSOFT.
El objetivo principal es construir una taxonomía basada en datos utilizando scraping, enriquecimiento semántico mediante LLMs, modelado de tópicos con BERTopic, análisis temporal y organización jerárquica de los temas resultantes.

---

📑 Tabla de Contenidos

• Descripción General
• Requisitos
• Estructura del Proyecto
• Descripción de los Scripts
• Pipeline del Análisis
• Salida Esperada
• Cómo Reproducir el Pipeline
• Posibles Extensiones
• Contribuciones
• Contacto

---

🔍 Descripción General

El pipeline trabaja sobre artículos de VISSOFT obtenidos desde DBLP e IEEE Xplore.
A grandes rasgos, se siguen estos pasos:

1. Scraping y adquisición de metadatos desde DBLP e IEEE Xplore (título, año, resumen, palabras clave).
2. Enriquecimiento del documento, unificando título, resumen y keywords en un solo campo de texto para modelado.
3. Modelado de tópicos con BERTopic usando embeddings científicos (SPECTER u otro modelo de sentence-transformers).
4. Etiquetado automático de tópicos con un modelo LLM (por ejemplo, gpt-4o-mini), generando etiquetas humanas concisas.
5. Análisis temporal de la distribución de tópicos por año y construcción de una taxonomía jerárquica.

---

🛠 Requisitos

Lenguaje

• Python 3.10+ (o superior).

Paquetes principales

Instalar con:

pip install     beautifulsoup4     requests     pandas     umap-learn     hdbscan     bertopic     sentence-transformers     matplotlib     seaborn     openai

API para LLM (opcional pero recomendado)

Para el etiquetado automático de tópicos (Step 4), se utiliza la API de OpenAI:

export OPENAI_API_KEY="tu_api_key_aqui"

Sin esta variable, el script de etiquetado no podrá llamar al modelo LLM.

---

📂 Estructura del Proyecto

Una estructura típica del repositorio es:

.

├── vissoft_ieee.sqlite
├── vissoft_docs_with_topics.csv
├── vissoft_topics.csv
└── vissoft_topics_labeled.csv
|
├── scraping_vissoft.py
├── 01-CorpusConstuctor.py
├── 02-BertTopic.py
├── 03-TopicLabels.py
├── 04-TopicTrends.py
│
├── topic_trends.png
├── topic_heatmap.png
├── pipeline.tex
└── README.md

Puedes adaptar los nombres de los archivos según tus necesidades (por ejemplo, cambiar vissoft por otra conferencia).

---

📜 Descripción de los Scripts

scraping_vissoft.py

• Lee un archivo de entrada (por ejemplo, XML de DBLP) con información básica de los artículos.
• Extrae:
  • título,
  • año,
  • DOI / URL (ee),
  • autores.
• Para cada DOI o URL:
  • accede a la página de IEEE Xplore,
  • extrae título, abstract y author keywords usando BeautifulSoup y selectores/XPath,
  • maneja errores de red y reintentos.
• Guarda los resultados en una base SQLite, por ejemplo:

CREATE TABLE papers (
    id INTEGER PRIMARY KEY,
    year INTEGER,
    title TEXT,
    abstract TEXT,
    keywords TEXT,
    ee_url TEXT
);

Salida principal:

• data/vissoft.sqlite

---

01-CorpusConstuctor.py

• Lee la base SQLite (vissoft.sqlite) o un CSV intermedio.
• Realiza:
  • limpieza básica de texto (lowercase, espacios, etc.),
  • eliminación de filas sin abstract (si se desea),
  • unión de title + abstract + keywords en un campo text_for_topic.
• Opcionalmente:
  • llama a un LLM para obtener keyphrases adicionales por artículo,
  • concatena dichas keyphrases al campo de texto.

Ejemplo de salida:

• data/corpus_vissoft.csv con columnas:
  • id, year, title, abstract, keywords, ee_url, text_for_topic.

---

02-BertTopic.py

• Lee el corpus (corpus_vissoft.csv).
• Configura un modelo BERTopic, típicamente con:
  • embedding_model="allenai-specter" (o similar),
  • min_topic_size=10,
  • calculate_probabilities=True,
  • un CountVectorizer con stopwords técnicas (software, system, model, method, etc.).
• Ejecuta:

topics, _ = topic_model.fit_transform(texts)

• Devuelve:
  • vissoft_docs_with_topics.csv
    (cada documento con su Topic y topic_probability),
  • vissoft_topics.csv
    (información resumida de cada tópico),
  • una carpeta con el modelo BERTopic entrenado
    (vissoft_bertopic_model/).

---

03-TopicLabels.py

• Lee:
  • vissoft_topics.csv,
  • vissoft_docs_with_topics.csv.
• Para cada tópico:
  • toma las palabras representativas (Representation),
  • toma algunos títulos representativos (Representative_Docs),
  • construye un prompt y lo envía a un LLM (por ejemplo gpt-4o-mini),
  • recibe como respuesta una etiqueta corta (máx. 5 palabras).
• Genera:
  • vissoft_topics_labeled.csv, con columnas:
    • Topic,
    • Count,
    • Label,
    • Words,
    • Representative_Docs.

Este archivo se usa luego para el análisis temporal y la construcción de la taxonomía.

---

04-TopicTrends.py

• Lee:
  • vissoft_docs_with_topics.csv (de Step 3),
  • vissoft_topics_labeled.csv (de Step 4).
• Asegura la coherencia de nombres de columnas (por ejemplo, topic → Topic, Year → year).
• Calcula:
  • distribución de documentos por año y tópico,
  • tabla topic_year_counts.csv.
• Genera:
  • topic_trends.png: gráfica de líneas (Topic × Año),
  • topic_heatmap.png: mapa de calor Topic × Año.

Estos resultados permiten observar:

• qué temas crecen/disminuyen con los años,
• qué tópicos son históricos o emergentes.

---

🔬 Pipeline del Análisis

Resumidamente, los pasos son:

1. Scraping: desde DBLP/IEEE a vissoft.sqlite.
2. Preprocesamiento: construcción de text_for_topic e integración de keyphrases.
3. BERTopic: entrenamiento del modelo, asignación de tópicos a documentos.
4. Etiquetado LLM: etiquetas humanas para los tópicos.
5. Análisis Temporal: conteo por año, curvas de tendencia, heatmaps.
6. Taxonomía Final: organización en macro-áreas (estructura, ejecución, inmersivo).

---

📤 Salida Esperada

Al ejecutar todos los scripts, se espera como mínimo:

• data/vissoft.sqlite — base con metadatos y texto.
• data/corpus_vissoft.csv — corpus enriquecido para modelado.
• vissoft_docs_with_topics.csv — documentos con tópicos y probabilidades.
• vissoft_topics.csv — resumen de tópicos descubiertos.
• vissoft_topics_labeled_FULL.csv — tópicos con etiquetas humanas.
• topic_year_counts.csv — tabla Topic × Año.
• topic_trends.png — gráfica de evolución temporal de tópicos.
• topic_heatmap.png — heatmap de distribución Topic × Año.
• pipeline.tex — documento LaTeX que reporta el pipeline completo y la taxonomía.

---

▶️ Cómo Reproducir el Pipeline

Ejemplo de ejecución secuencial:

python 01_scraping.py
python 02_preprocess_keyphrases.py
python 03_topic_modeling.py
python 04_label_topics_llm.py
python 05_topic_trends.py

Revisar las rutas de entrada/salida dentro de cada script para adaptarlas a tu entorno (por ejemplo, carpeta data/).

---

🔭 Posibles Extensiones

• Aplicar el pipeline a otras conferencias (ICSME, MSR, CHASE, etc.).
• Probar otros modelos de embeddings (por ejemplo, all-mpnet-base-v2).
• Explorar diferentes configuraciones de UMAP/HDBSCAN.
• Usar LLMs locales en lugar de la API (Ollama, LLaMA, etc.).
• Comparar la taxonomía derivada con taxonomías propuestas en literatura previa.

---

🤝 Contribuciones

Las contribuciones son bienvenidas.
Ideas posibles:

• Mejorar el scraping y la robustez de extracción.
• Añadir notebooks para exploración interactiva.
• Incluir métricas de calidad de tópicos (coherencia, diversidad, etc.).

---