Merge pull request #5 from complexluise/4-calcular-red-de-correlacion…

…es-de-topicos

Implementación de Red de Correlaciones Basada en Similaridad de Coseno para Análisis de Tópicos

.gitignore

@@ -0,0 +1,2 @@
+/modelos/*
+/.idea/*

README.md

@@ -2,102 +2,137 @@
 
 ## Descripción General
 
-**BibloClean** es un paquete Python diseñado para el procesamiento integral de datos bibliográficos, utilizando un pipeline ETL (Extracción, Transformación, Carga) para procesar registros MARC21 y normalizar la información extraída. El paquete extrae datos desde archivos CSV/Excel, realiza la limpieza y normalización del contenido, genera embeddings para análisis temático, e identifica y normaliza entidades dentro de los registros bibliográficos.
-
-Este paquete es ideal para bibliotecarios y gestores de información que necesitan procesar grandes volúmenes de registros bibliográficos y normalizarlos para mejorar la calidad de sus catálogos.
+**BibloClean** es un paquete Python diseñado para el procesamiento integral de datos bibliográficos, utilizando un pipeline ETL (Extracción, Transformación, Carga) para procesar registros MARC21 y normalizar la información extraída. Este paquete facilita la limpieza, normalización y análisis de datos bibliográficos, y es especialmente útil para bibliotecarios y gestores de información que manejan grandes volúmenes de registros MARC21.
 
 ### Características Principales
 
-- **Extracción de datos**: Carga registros desde archivos CSV/Excel
-- **Preprocesamiento de texto**: Limpia y normaliza campos bibliográficos
-- **Generación de embeddings**: Crea representaciones vectoriales para análisis temático
-- **Normalización de entidades**: Detecta y normaliza autores, títulos y lugares
-- **Exportación de resultados**: Guarda los datos procesados en formato estructurado
+- **Extracción de datos**: Carga registros desde archivos CSV/Excel.
+- **Preprocesamiento de texto**: Limpia y normaliza campos bibliográficos.
+- **Generación de embeddings**: Crea representaciones vectoriales para análisis temático.
+- **Normalización de entidades**: Detecta y normaliza autores, títulos y lugares.
+- **Red de correlaciones temáticas**: Genera redes de conexiones entre temas basados en umbrales de similitud.
+- **Exportación de resultados**: Guarda los datos procesados en un formato estructurado y exporta redes temáticas a formato GraphML.
 
 ### Limitaciones
 
-- El paquete asume que los datos de entrada están en formato CSV/Excel
-- Los pipelines están diseñados específicamente para datos bibliográficos MARC21
-- El rendimiento depende de la calidad de los modelos de embedding utilizados
-- Se requiere una estructura específica de columnas en los datos de entrada
+- Los datos de entrada deben estar en formato CSV o Excel.
+- Los pipelines están diseñados específicamente para datos bibliográficos MARC21.
+- El rendimiento depende de la calidad de los modelos de embedding y el tamaño de los datos.
+- La estructura de columnas en los datos de entrada debe cumplir con un formato específico.
+
+Para obtener más información detallada sobre las transformaciones realizadas visitar [Explicación de las normalizaciones](https://complexluise.github.io/bibloclean/explicacion_normalizacion).
 
 ## Prerrequisitos
 
 ### 1. Instalación
 
-Instalar el paquete y sus dependencias:
+Para instalar el paquete y sus dependencias:
 
 ```bash
 git clone https://github.com/complexluise/limpieza_marc21
 cd limpieza_marc21
-# Si tienes GPU debes instalar esta versión de pytoch de lo contrario omite la siguiente linea
+# Si tienes una GPU, instala PyTorch para mejor rendimiento en embeddings
 pip3 install torch --index-url https://download.pytorch.org/whl/cu118
 pip install -r requirements.txt
 ```
 
 ### 2. Estructura de Datos
 
-Los datos de entrada deben seguir la estructura de campos MARC21 especificada en la documentación, incluyendo:
+Los datos de entrada deben seguir la estructura de campos MARC21 especificada en la documentación, como:
 
-- Campos de autor (100$a)
-- Campos de título (245$a, 245$b)
-- Campos temáticos (650$a)
-- Campos de clasificación (082$a)
-- Campos de biblioteca (943$a-g)
+- **Campos de autor**: 100$a
+- **Campos de título**: 245$a, 245$b
+- **Campos temáticos**: 650$a
+- **Campos de clasificación**: 082$a
+- **Campos de biblioteca**: 943$a-g
 
-Ten en cuenta que se usan los nombres de la primera fila como la columnas a procesar.
-Tu archivo CSV o Excel debería tener las siguientes columnas:
+El archivo CSV o Excel debe tener las siguientes columnas:
 
 | 100$a             | 245$a                                   | 245$b                                         | 245$c             | 082$a | 082$b | 082$2 | 090$a | 090$b | 650$a                                       | 650$y | 650$v | 650$x              | 520$a                                                | 943$a     | 943$b | 943$c | 943$d | 943$e | 943$f | 943$g |
 |-------------------|-----------------------------------------|-----------------------------------------------|-------------------|-------|-------|-------|-------|-------|---------------------------------------------|--------|--------|--------------------|-------------------------------------------------------|-----------|--------|--------|--------|--------|--------|--------|
 | Nombre principal (autor) | Título principal                             | Subtítulo                                         | Mención de responsabilidad | Número de clasificación Dewey | Número adicional de clasificación | Edición de la clasificación Dewey | Clasificación local | Número de clasificación local adicional | Tema principal                                  | Periodo cronológico | Forma del término | Subdivisión temática   | Resumen | Biblioteca_1 | Biblioteca_2 | Biblioteca_3 | Biblioteca_6 | Biblioteca_5 | Biblioteca_4 | Biblioteca_7 |
 | Goldberg, Beatriz | ¿Cómo voy a hacer esto a la edad que tengo?: | aprenda a enfrentar las crisis y los cambios a cualquier edad/ | Beatriz Goldberg | 155.25 |       | 20    |       |       | Autoestima;Autorrealización (Psicología);Tristeza |        |        | Aspectos psicologicos | FAJM                                                  |           |        |        |        |        |        |        |
 
-
 ### 3. Directorios del Proyecto
-```
+
+```plaintext
 ├── raw_data/           # Datos de entrada sin procesar
 ├── clean_data/         # Datos procesados y limpios
 ├── modelos/            # Modelos de embeddings guardados
-└── bibloclean/                # Código fuente
+└── bibloclean/         # Código fuente
+└── analysis/           # Artefactos de salida de las redes temáticas
 ```
 
 ## Uso
+
 ### 1. Preparación de Datos
-1. Colocar los archivos CSV/Excel en la carpeta raw_data/
-2. Verificar que las columnas coincidan con la estructura requerida
-3. Asegurar que los datos estén codificados en UTF-8
+
+1. Colocar los archivos CSV/Excel en la carpeta `raw_data/`.
+2. Verificar que las columnas coincidan con la estructura requerida.
+3. Asegurar que los datos estén codificados en UTF-8.
+
 ### 2. Ejecución del Pipeline
-```python
-python bibloclean archivo.csv
-```
 
-Opciones disponibles:
+Las funcionalidades principales están disponibles a través de una interfaz de línea de comandos (CLI) que permite realizar la limpieza y generación de redes temáticas.
+
+#### Comandos Disponibles
+
+1. **Limpieza de datos bibliográficos de KOHA**
+
+   ```bash
+   python bibloclean limpiar-koha archivo.csv --salida <directorio> --verbose
+   ```
+
+   - **archivo**: Ruta al archivo CSV/Excel a procesar.
+   - **--salida, -s**: Directorio para guardar los resultados (por defecto: `clean_data`).
+   - **--verbose, -v**: Muestra información detallada del proceso.
+
+   Este comando procesa los datos, aplicando limpieza y normalización a los registros bibliográficos, y los guarda en el directorio de salida especificado.
+
+2. **Generación de red de correlaciones temáticas**
+
+   ```bash
+   python bibloclean analizar-red archivo.csv --umbral <valor> --modelo <nombre_modelo> --salida <ruta_salida>
+   ```
+
+   - **archivo**: Archivo CSV con los temas asignados.
+   - **--umbral, -u**: Umbral de similaridad para conexiones entre temas (rango de 0 a 1; por defecto: 0.7).
+   - **--modelo, -m**: Nombre del modelo de embeddings disponible en [SentenceTransformers](https://www.sbert.net/docs/sentence_transformer/pretrained_models.html) a utilizar (por defecto: `jinaai/jina-embeddings-v3`).
+   - **--salida, -s**: Ruta para guardar el archivo de la red en formato GraphML.
+
+   Este comando genera una red temática que representa las relaciones entre temas en el archivo CSV, basada en un umbral de similitud y un modelo de embeddings.
 
-- archivo: Ruta al archivo CSV/Excel a procesar
-- --salida, -s: Directorio para guardar resultados
-- --verbose, -v: Mostrar información detallada
 ### 3. Resultados
-Los datos procesados se guardan en clean_data/ con las siguientes mejoras:
 
-- Campos normalizados
-- Análisis temático
-- Estadísticas de procesamiento
+- Los datos procesados se guardan en `clean_data/` con los siguientes atributos mejorados:
+  - Campos normalizados.
+  - Análisis temático.
+  - Estadísticas de procesamiento.
+- La red de temas generada se guarda en el formato GraphML en la ubicación especificada por el usuario, ideal para visualización en herramientas de análisis de redes.
+
 ## Contribuciones
-Agradecemos las contribuciones a **bibloclean**:
+
+Agradecemos las contribuciones a **BibloClean**:
 
 ### Reportar Problemas
-1. Revisar los issues existentes
-2. Crear nuevo issue con descripción detallada
-3. Incluir pasos para reproducir el problema
+
+1. Revisar los issues existentes.
+2. Crear un nuevo issue con una descripción detallada.
+3. Incluir pasos para reproducir el problema.
+
 ### Realizar Mejoras
-1. Fork del repositorio
-2. Crear rama para nuevas características
-3. Seguir estándares de código del proyecto
-4. Enviar pull request
+
+1. Hacer fork del repositorio.
+2. Crear una rama para la nueva funcionalidad.
+3. Seguir los estándares de código del proyecto.
+4. Enviar un pull request.
+
 ### Proponer Cambios Mayores
-1. Abrir issue para discutir la propuesta
-2. Detallar justificación e implementación
-3. Esperar retroalimentación antes de comenzar
+
+1. Abrir un issue para discutir la propuesta.
+2. Detallar la justificación e implementación.
+3. Esperar retroalimentación antes de comenzar.
+
 ## Licencia
-Limpieza Koha está licenciado bajo Apache License Version 2.0.
+
+**BibloClean** está licenciado bajo Apache License Version 2.0.

analysis/statistics/analysis.md

@@ -0,0 +1,19 @@
+## **Analisis de los graficos estadisticos**
+
+### 1. **Distribución de Centralidad de Intermediación (Betweenness Centrality Distribution)**
+   - **Descripción General:** La gráfica muestra la distribución de los valores de centralidad de intermediación para los nodos en una red.
+   - **Interpretación:** La mayoría de los nodos tienen valores de centralidad de intermediación muy bajos (cercanos a 0), lo que indica que pocos nodos son esenciales en el flujo de información en la red. Solo algunos nodos presentan valores más altos, lo que sugiere que son puntos de conexión críticos en la red y actúan como "puentes" entre diferentes comunidades o subgrupos. Estos nodos de alto valor son potencialmente los más influyentes.
+   - **Observación de Datos Atípicos:** Hay pocos nodos con valores de centralidad extremadamente altos, representando una distribución desigual que es común en redes sociales y complejas, donde unos pocos nodos concentran gran parte de la intermediación.
+
+### 2. **Distribución de Centralidad de Cercanía (Closeness Centrality Distribution)**
+   - **Descripción General:** Esta gráfica representa la distribución de los valores de centralidad de cercanía en los nodos de la red.
+   - **Interpretación:** La centralidad de cercanía refleja qué tan cerca están los nodos del resto de la red. En este caso, muchos nodos tienen valores muy cercanos entre sí, lo cual indica que la red es relativamente homogénea en términos de cercanía promedio a otros nodos. Sin embargo, parece haber una concentración en valores bajos, sugiriendo que en promedio los nodos están alejados del centro de la red.
+   - **Rango de Valores:** Los valores de la gráfica varían desde aproximadamente -1 hasta 2. Esto puede indicar la presencia de nodos aislados o con baja conectividad dentro de la red, pues valores muy bajos en centralidad de cercanía indican un mayor "aislamiento".
+
+### 3. **Distribución de Excentricidad (Eccentricity Distribution)**
+   - **Descripción General:** La excentricidad de un nodo mide la distancia máxima entre ese nodo y cualquier otro nodo en la red.
+   - **Interpretación:** La gráfica muestra que la mayoría de los nodos tienen valores de excentricidad altos, lo que significa que están a una gran distancia máxima de otros nodos en la red. Esto sugiere una estructura dispersa o una red grande donde muchos nodos están distantes unos de otros.
+   - **Tendencia:** La excentricidad crece gradualmente y tiene un pico alrededor del valor 20, lo que indica que la mayoría de los nodos están a una distancia considerable del resto. Esto es característico de redes que no tienen un núcleo centralizado, sino que están formadas por varias secciones menos conectadas entre sí.
+
+### Conclusión General
+Estas tres métricas sugieren una red donde la mayoría de los nodos tienen baja influencia (baja intermediación y cercanía), mientras que unos pocos nodos tienen posiciones clave, especialmente en términos de intermediación. La excentricidad alta en la mayoría de los nodos indica una red más dispersa, posiblemente con una estructura modular o subdividida en comunidades menos interconectadas.

analysis/statistics/report.html

@@ -0,0 +1 @@
+<HTML> <BODY> <h1>Graph Distance  Report </h1> <hr><br><h2> Parameters: </h2>Network Interpretation:  undirected<br /><br /> <h2> Results: </h2>Diameter: 22<br />Radius: 0<br />Average Path length: 6.791314971123945<br /><IMG SRC="Betweenness Centrality Distribution.png"></IMG><br /><br /><IMG SRC="Closeness Centrality Distribution.png"></IMG><br /><br /><IMG SRC="Harmonic Closeness Centrality Distribution.png"></IMG><br /><br /><IMG SRC="Eccentricity Distribution.png"></IMG><br /><br /><h2> Algorithm: </h2>Ulrik Brandes, <i>A Faster Algorithm for Betweenness Centrality</i>, in Journal of Mathematical Sociology 25(2):163-177, (2001)<br /></BODY> </HTML>