Metadata-Version: 2.4
Name: Twotuples
Version: 1.9.8
Summary: Libreria para clasificar texto
Home-page: https://github.com/crgv7/TwotuplesClasificator
Author: Carlos Garcia Vargas y Orlando Toledano
Author-email: 
License: MIT
Description-Content-Type: text/markdown
Requires-Dist: scikit-learn>=1.0.0
Requires-Dist: numpy
Requires-Dist: pandas
Requires-Dist: matplotlib
Requires-Dist: sentiment-analysis-spanish
Requires-Dist: tqdm
Dynamic: author
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license
Dynamic: requires-dist
Dynamic: summary

# Twotuples: Clasificador de Texto con Lógica Difusa

[![GitHub Repo](https://img.shields.io/badge/GitHub-Repository-blue?logo=github)](https://github.com/crgv7/TwotuplesClasificator)


La librería **twotuples** tiene como objetivo clasificar opiniones o comentarios en tres categorías: positivo (POS), negativo (NEG) o neutral (NEU). 

A diferencia de otras librerías de procesamiento de lenguaje natural (NLP), **twotuples** utiliza tres clasificadores de texto robustos internamente y combina sus resultados utilizando un **clasificador difuso basado en el modelo de 2-tuplas lingüísticas**, ofreciendo resultados más precisos y de consenso.

Durante su desarrollo, la librería fue probada con 21,847 comentarios de hoteles extraídos de TripAdvisor, obteniendo resultados excelentes evaluados a través del análisis de diversas métricas.

## Características
- Integración de múltiples modelos de estado del arte: **Pysentimiento**, **Bert Multilingual** y **Asent**.
- Sistema de decisión consensuada basado en **Lógica Difusa (Fuzzy Logic)**.
- Soporte para textos nativos, utilizando modelos multilingües que evitan la necesidad de traducciones previas.
- Exportación automática de resultados y métricas a archivos **Excel**.

## Instalación

Puedes instalar la librería utilizando `pip`. Como la librería está alojada en TestPyPI, debes incluir el parámetro `--extra-index-url` para que las dependencias estándar se descarguen de PyPI correctamente.

```bash
pip install -i https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ Twotuples==1.3.8
```

> [!TIP]
> **Recomendación:** Es altamente aconsejable ejecutar e instalar esta librería en entornos como **Google Colab** o un entorno virtual local dedicado, ya que requiere descargar modelos pesados de Machine Learning y diccionarios como `transformers` y `spacy`.

## Uso Rápido (Quickstart)

### 1. Clasificación Difusa de Opiniones

Esta es la funcionalidad principal. Toma un archivo Excel con una columna de textos, ejecuta los tres modelos, aplica la lógica difusa y devuelve archivos Excel con las predicciones.

```python
from Twotuples import Twotuples

# 1. Definimos la ruta al archivo y la columna a analizar
archivo_excel = "data.xlsx"
nombre_columna = "Opinion"

# 2. Ejecutamos el clasificador difuso
Twotuples.difuso_clasificator(data=archivo_excel, ColumnName=nombre_columna)
```

**Archivos generados tras la ejecución:**
- `score_diffuse.xlsx`: **Archivo final recomendado.** Contiene el texto original y una nueva columna llamada `Clasicacion_Difusa` con las etiquetas finales (POS, NEG, NEU).
- `score_pysentiment.xlsx`, `score_bert.xlsx`, `score_asent.xlsx`: Archivos con los resultados individuales por cada modelo.
- `score.xlsx`: Resumen unificado numérico.

### 2. Evaluación de Métricas

Si tu archivo Excel original contiene una columna con las etiquetas reales o esperadas (Ground Truth), puedes comparar las predicciones de la librería con la realidad utilizando la función `Metric`.

```python
# Reporte de métricas (Precision, Recall, F1-Score)
# Sustituye 'Etiqueta_Real' por el nombre de la columna que contiene los valores esperados en tu Excel.
Twotuples.Metric(etiqueta='Etiqueta_Real', metric='ClassificationReport', sorter='difuse', ClassNumber=3)

# Mostrar la matriz de confusión de forma gráfica
Twotuples.Metric(etiqueta='Etiqueta_Real', metric='ConfusionMatrix', sorter='difuse', ClassNumber=3)
```

## Referencia de la API

### `Twotuples.difuso_clasificator(data, ColumnName, C=False)`
Ejecuta la predicción sobre un dataset completo.
- **`data`** *(str)*: Ruta al archivo `.xlsx` que contiene los datos. Debe tener una hoja llamada `Sheet1`.
- **`ColumnName`** *(str)*: Nombre de la columna en el Excel que contiene el texto a analizar.
- **`C`** *(bool, opcional)*: Parámetro heredado por compatibilidad; ya no es necesario activarlo porque los modelos son multilingües.

### `Twotuples.Metric(etiqueta, metric='ClassificationReport', sorter='difuse', ClassNumber=3)`
Evalúa y visualiza el rendimiento de las predicciones.
- **`etiqueta`** *(str)*: Nombre de la columna con las clasificaciones manuales/reales.
- **`metric`** *(str, opcional)*: Tipo de visualización. Opciones: `'ClassificationReport'` (tabla de texto) o `'ConfusionMatrix'` (gráfico visual).
- **`sorter`** *(str, opcional)*: Define qué modelo específico evaluar. Opciones: `'difuse'`, `'pysentiment'`, `'bert'`, `'asent'`. Por defecto es `'difuse'`.
- **`ClassNumber`** *(int, opcional)*: Cantidad de clases de salida. Valores válidos son `2` o `3`. Por defecto es `3`.

## Tecnologías Usadas
* **[Pysentimiento](https://pypi.org/project/pysentimiento/)** (v0.7.2): Herramienta de NLP basada en Transformers para español e inglés.
* **[Bert Multilingual Sentiment](https://huggingface.co/nlptown/bert-base-multilingual-uncased-sentiment)**: Modelo fine-tuned de BERT para clasificación de reseñas en múltiples idiomas.
* **[Asent](https://pypi.org/project/asent/)** (v0.8.0): Análisis de sentimientos basado en reglas para Spacy.
* **Transformers & PyTorch**: Framework principal para los modelos de deep learning subyacentes.
* Otras dependencias: `spacy`, `scikit-learn`, `pandas`, `numpy`, `matplotlib`.
