Proyecto TFG: Detección de ideas suicidas

Proyecto de inteligencia artificial para la detección de ideas suicidas mediante técnicas de procesamiento de lenguaje natural.

Requisitos previos

• Python 3.10 o superior
• pip (gestor de paquetes de Python)
• git (opcional, para clonar el repositorio)

Instalación

1. Clonar o descargar el repositorio

git clone https://github.com/Marta-munoz/TFG_Marta_Munoz_Martinez.git

O descarga el proyecto directamente y navega a la carpeta del proyecto.

2. Instalar Hatch

El proyecto usa Hatch como gestor de entornos y construcción. Instala Hatch:

pip install hatch

3. Crear el entorno de desarrollo con Hatch

Crea el entorno de desarrollo que instalará todas las dependencias automáticamente:

hatch env create

4. Activar el entorno de desarrollo

Para trabajar en el proyecto, activa el entorno de desarrollo:

hatch shell dev

Esto instalará automáticamente todas las dependencias principales.

5. Instalar torch y transformers

pip install transformers torch evaluate accelerate

Estructura del proyecto

Codigos_TFG_Marta/
├── data/                          # Almacenamiento de conjuntos de datos y recursos
│   ├── raw/                       # Datos originales e inmutables (descargados/externos)
│   │   ├── spanish_suicide_intent_dataset/  # Dataset PrevenIA original de Hugging Face
│   │   ├── suicidio_notacion.csv  # Dataset original de Valeriano et al. (2020)
│   │   ├── stopwords.txt          # Stopwords de Valeriano et al.
│   │   ├── embeddings-m-model.bin # Modelo de embeddings Word2Vec en español (SBWCE)
│   │   ├── embeddings/            # Carpeta con embeddings preentrenados adicionales
│   │   │   ├── medical_embeddings.zip # Archivo zip original de embeddings médicos en español (v2.0)
│   │   │   └── medical_embeddings/ # Embeddings médicos descomprimidos (Scielo, Wikipedia, etc.)
│   │   ├── NRC-Emotion-Lexicon-ForVariousLanguages.txt # Lexicón de emociones
│   │   ├── spanish_suicide_intent_train.csv # Partición de train de PrevenIA
│   │   ├── spanish_suicide_intent_val.csv   # Partición de dev/validation de PrevenIA
│   │   └── spanish_suicide_intent_test.csv  # Partición de test de PrevenIA
│   └── interim/                   # Datos intermedios y preprocesados
│       ├── dev_suicidio_notacion.csv        # Partición de desarrollo de Valeriano preprocesada
│       ├── dev_suicidio_notacion_raw.csv    # Partición de desarrollo de Valeriano sin preprocesar
│       ├── test_suicidio_notacion.csv       # Partición de prueba de Valeriano preprocesada
│       ├── test_suicidio_notacion_raw.csv   # Partición de prueba de Valeriano sin preprocesar
│       ├── train_suicidio_notacion.csv      # Partición de entrenamiento de Valeriano preprocesada
│       ├── train_suicidio_notacion_raw.csv  # Partición de entrenamiento de Valeriano sin preprocesar
│       ├── suicidio_notacion_balanced.csv   # Dataset de Valeriano balanceado
│       ├── train_suicidio_augmented.csv     # Dataset de entrenamiento de Valeriano aumentado (paráfrasis con LLM)
│       ├── train_suicidio_augmented_sintetico.csv # Dataset de entrenamiento de Valeriano aumentado (sintético con LLM)
│       ├── temp_aug_clase_0.csv             # Fragmento temporal de aumento por paráfrasis (clase 0)
│       ├── temp_aug_clase_1.csv             # Fragmento temporal de aumento por paráfrasis (clase 1)
│       ├── temp_aug_sintetico_clase_0.csv   # Fragmento temporal de aumento sintético (clase 0)
│       ├── temp_aug_sintetico_clase_1.csv   # Fragmento temporal de aumento sintético (clase 1)
│       └── lexico_suicida.txt               # Lexicón de palabras del dominio de suicidio adaptado
├── models/                        # Modelos entrenados y guardados para su uso
│   ├── beto_finetuned_raw/        # BETO entrenado en texto crudo (sin preprocesar)
│   ├── robertuito_finetuned_raw/  # RoBERTuito entrenado en texto crudo (sin preprocesar)
│   ├── robertuito_parafrasis/     # RoBERTuito reentrenado con aumento por paráfrasis (usado en la demo web)
│   ├── robertuito_sintetico/      # RoBERTuito reentrenado con aumento sintético
│   ├── bin_vectorizer.joblib      # Vectorizador binario serializado (base)
│   ├── bin_RL.joblib              # Regresión Logística con pesado binario (base, usado en la demo web)
│   ├── bin_SVM.joblib             # SVM con pesado binario (base)
│   ├── bin_vectorizer_parafrasis.joblib # Vectorizador binario (aumento por paráfrasis)
│   ├── bin_RL_parafrasis.joblib   # Regresión Logística con pesado binario (aumento por paráfrasis)
│   ├── bin_SVM_parafrasis.joblib  # SVM con pesado binario (aumento por paráfrasis)
│   ├── bin_vectorizer_sintetico.joblib # Vectorizador binario (aumento sintético)
│   ├── bin_RL_sintetico.joblib    # Regresión Logística con pesado binario (aumento sintético)
│   ├── bin_SVM_sintetico.joblib   # SVM con pesado binario (aumento sintético)
│   ├── tfidf_model.joblib         # Vectorizador TF-IDF serializado (estándar)
│   ├── tfidf_RL.joblib            # Regresión Logística entrenada con TF-IDF
│   ├── tfidf_SVM.joblib           # SVM entrenada con TF-IDF
│   ├── tfidf_use_idf_model.joblib # Vectorizador TF-IDF con uso de IDF serializado
│   ├── tfidf_RL_use_idf.joblib    # Regresión Logística entrenada con TF-IDF (con IDF)
│   ├── tfidf_SVM_use_idf.joblib   # SVM entrenada con TF-IDF (con IDF)
│   └── w2v_*.joblib               # Variantes de Word2Vec con embeddings biomédicos (Wikipedia, SciELO, etc.)
├── notebooks/                     # Jupyter Notebooks para experimentación, análisis y entrenamiento
│   ├── prevenia_descriptive_analysis.ipynb   # Análisis exploratorio del dataset PrevenIA
│   ├── valeriano_descriptive_analysis.ipynb # Análisis exploratorio del dataset de Valeriano et al.
│   ├── keywords_system.ipynb      # Evaluación del baseline basado en keywords
│   ├── replicar_valeriano.ipynb   # Réplica de Valeriano et al. y experimentación de clasificadores clásicos con diversas representaciones
│   ├── clasificacion_aleatoria.ipynb # Baseline de clasificación aleatoria
│   ├── data_augmentation_llm_parafrasis.ipynb # Generación de paráfrasis con la API de Gemini
│   ├── data_augmentation_llm_sintetico.ipynb  # Generación de ejemplos sintéticos con la API de Gemini
│   ├── zero_shot_llm_raw.ipynb    # Clasificación zero-shot con LLMs
│   ├── zero_shot_llm_temperatura0.ipynb    # Clasificación zero-shot con LLMs con temperatura 0
│   ├── few_shot_llm_raw.ipynb     # Clasificación few-shot con LLMs
│   ├── few_shot_llm_temperatura0.ipynb     # Clasificación few-shot con LLMs con temperatura 0
│   ├── modelo_clasico_data_augmentation_*.ipynb # Re-entrenamiento de SVM/Regresión Logística con aumento de datos
│   ├── beto_raw.ipynb             # Ajuste fino inicial de BETO
│   ├── robertuito_raw.ipynb       # Ajuste fino inicial de RoBERTuito
│   ├── robertuito_evaluar_test.ipynb # Evaluación en test de RoBERTuito con aumento mediante paráfrasis
│   ├── analisis_comparativo.ipynb # Notebook comparativo global de todos los resultados
│   └── analisis_curva_roc.ipynb   # Notebook para visualización y comparación de curvas ROC y AUC
├── reports/                       # Reportes generados
│   ├── experiments_results.csv    # Tabla consolidada donde se registran los resultados de los experimentos
│   └── tabla_predicciones.csv     # Predicciones detalladas de los modelos para análisis cualitativo de errores
├── src/                           # Código fuente empaquetado del proyecto
│   ├── __init__.py
│   ├── analyze.py                 # Lógica de análisis de métricas y registro de experimentos
│   ├── app.py                     # Aplicación web Flask e interfaz gráfica de demostración
│   ├── augmentation.py            # Funciones y flujos de aumento de datos con LLM (paráfrasis/sintético)
│   ├── data_keywords.py           # Preparación de datos para el baseline de keywords
│   ├── data_ml.py                 # Pipeline de extracción de características y particiones para modelos clásicos
│   ├── download_prevenia.py       # Script de descarga y guardado local del dataset PrevenIA
│   ├── download_valeriano.py      # Script de descarga y guardado local del dataset Valeriano
│   ├── keywords_logic.py          # Lógica para la clasificación por palabras clave
│   ├── llm_logic.py               # Módulo de interacción con la API de Gemini (Google Generative AI)
│   ├── logger.py                  # Sistema global de logging del proyecto
│   ├── ml_utils.py                # Funciones auxiliares para modelos clásicos (embeddings, carga de W2V, etc.)
│   ├── preprocessing.py           # Funciones de normalización de textos (limpieza, stopwords, lematización)
│   ├── random_baseline.py         # Implementación matemática de clasificación aleatoria
│   ├── templates/                 # Vistas y plantillas HTML para la aplicación Flask
│   └── utils/                     # Utilidades adicionales de bajo nivel (logger simplificado)
├── pyproject.toml                 # Configuración general y declaración de dependencias gestionadas por Hatch
└── README.md                      # Documentación del proyecto (este archivo)

Uso

Descargar el dataset

El proyecto utiliza el dataset PrevenIA/spanish-suicide-intent. Antes de ejecutar cualquier análisis, debes descargar y preparar los datos iniciales:

hatch run dev:download-prevenia

También se utiliza el dataset suicidio-notacion de Valeriano et al. 2020. Antes de ejecutar cualquier análisis, debes descargar y preparar los datos iniciales:

hatch run dev:download-valeriano

Trabajar con Jupyter Notebooks

Sigue estos pasos para ejecutar los notebooks en el entorno del proyecto:

1. Activar el entorno de desarrollo

hatch shell dev

2. Verificar que Jupyter esté instalado

Jupyter ya debería estar instalado si seguiste los pasos de instalación. Si no, instálalo con:

pip install jupyter jupyterlab

3. Iniciar Jupyter

Desde la raíz del proyecto, ejecuta:

hatch run dev:install-notebook-kernel

4. Abrir y ejecutar notebooks

• Navega a la carpeta notebooks/
• Haz clic en el notebook que quieras abrir (por ejemplo, valeriano_descriptive_analysis.ipynb)
• Asegurate de seleccionar el kernel correcto (debería ser el entorno que creaste con Hatch)
• Ejecuta las celdas con Shift + Enter o usando el botón "Run"

Ejecutar la aplicación web

Para iniciar el servidor web Flask:

hatch run dev:run-app

La aplicación estará disponible en http://127.0.0.1:5000/.

Dependencias principales

El proyecto gestiona sus entornos y dependencias mediante Hatch. A continuación se detallan las librerías fundamentales requeridas para el desarrollo del proyecto, clasificadas por su ámbito de uso:

Procesamiento de datos y aprendizaje automático clásico

Modelos de aprendizaje profundo (Deep Learning)

[!NOTE] Estas librerías se utilizan para la inicialización, ajuste fino (fine-tuning) y evaluación de los modelos basados en Transformers (BETO y RoBERTuito).

Aumento de datos e inteligencia artificial generativa

Entorno de desarrollo y visualización

Seguimiento de experimentos

Para mantener un orden en los resultados, se ha implementado un sistema de log automatizado. Cada vez que se ejecuta un experimento, se registra automáticamente en un archivo experiments_results.csv.

Autor

• Marta Muñoz Martinez