Metadata-Version: 2.3
Name: psymarkers
Version: 0.1.11
Summary: TBD
Keywords: nlp,text-analysis,psychology,mental-health,sentiment-analysis,linguistics,feature-extraction
Author: blazaid
Author-email: blazaid <alber.diaz@pm.me>
License: GPL-3.0-or-later
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Healthcare Industry
Classifier: Intended Audience :: Developers
Classifier: Topic :: Text Processing :: Linguistic
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Dist: nltk>=3.10.3
Requires-Dist: textstat>=0.7.13
Requires-Python: >=3.13
Project-URL: Repository, https://codeberg.org/knodis/psymarkers
Description-Content-Type: text/markdown

# psymarkers

[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)
[![Python Version](https://img.shields.io/badge/python-3.13%2B-blue)](https://www.python.org/)

Biblioteca de Python rápida y eficiente para extraer marcadores psicológicos y lingüísticos de textos. Está basada en
literatura clínica y psicológica, y cuantifica patrones del lenguaje comúnmente asociados con estados de depresión,
ansiedad, rumiación cognitiva o ideación suicida.

## Instalación

Puedes instalar la biblioteca directamente desde [PyPi](https://pypi.org/):

```text
pip install psymarkers
```

**Nota**: Requiere la descarga previa de los diccionarios de `nltk` si no los tienes en tu entorno:

- `nltk.download('punkt')`
- `nltk.download('vader_lexicon')`
- `nltk.download('averaged_perceptron_tagger')`

## Indicadores disponibles

Los indicadores actuales incluyen:

- `absolutist_ratio`: Proporción de palabras absolutistas (always, never, completely), marcador de ansiedad y depresión.
- `pronouns_ratio`: Proporción de pronombres singulares de primera persona (I, me, my), asociado a focalización en uno
  mismo.
- `pronouns_plural_ratio`: Proporción de pronombres plurales (we, us). Su disminución es un indicador de aislamiento
  social.
- `somatic_ratio`: Uso de palabras relacionadas con el cuerpo, dolor y fatiga.
- `hopelessness_ratio`: Proporción de léxico que expresa desesperanza y falta de futuro.
- `negative_sentiment` / `compound_sentiment`: Valencia emocional negativa y polaridad afectiva general (mediante
  VADER).
- `type_token_ratio`: Diversidad léxica. Un ratio bajo indica vocabulario repetitivo (rumiación cognitiva).
- `temporal_myopia_index`: Ratio de verbos en pasado frente a verbos modales futuros, indicando estrechamiento temporal
  o incapacidad de proyectarse al futuro.
- `readability_score`: Nivel de legibilidad de Flesch-Kincaid. Textos muy desorganizados se asocian a deterioro 
  cognitivo o psicosis.
- `insomnia_post`: Validador de metadatos que retorna 1.0 si el texto fue publicado en horario nocturno (2 AM - 5 AM).

## Ejemplos de uso

### Como _pipeline_ en aprendizaje automático

Ya que (intentamos) que todos los indicadores compartan una interfaz común, se puede usar para crear vectores de
características limpios y listos para entrenar modelos:

```python
from psymarkers import markers

# 1. Defines tu pipeline de extracción
metrics_pipeline = [
    markers.absolutist_ratio,
    markers.pronouns_ratio,
    markers.hopelessness_ratio,
    markers.negative_sentiment,
    markers.temporal_myopia_index,
    markers.type_token_ratio
]

text = "I am completely exhausted and have no future."
date = "2023-10-27T03:15:00Z"

# 2. Extraes todas las características en un diccionario en una sola pasada
features = {
    metric.__class__.__name__: metric(text, date=date) 
    for metric in metrics_pipeline
}

# 3. Haces lo que quireas con los datos
print(features)  # Salida esperada: {'RegexRatioMetric': 0.11, 'SentimentMetric': 0.8, ...}
```

## Licencia

Este proyecto está licenciado bajo los términos de la **GNU General Public License v3.0 (GPLv3)**. Eres libre de usar,
modificar y distribuir este software, siempre y cuando las obras derivadas se distribuyan bajo la misma licencia
abierta. Para más información, por favor consulta el fichero [`LICENSE`](./LICENSE).