Metadata-Version: 2.3
Name: psymarkers
Version: 0.1.15
Summary: A Python library for extracting psychological and linguistic markers from text.
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 recursos léxicos de `nltk` si no los tienes en tu entorno. Puedes descargarlos todos automáticamente usando la función `download_nltk_resources`, integrada en la biblioteca:

```python
import nltk

from psymarkers.resources import download_nltk_resources

download_nltk_resources()
nltk.download('punkt')
nltk.download('punkt_tab')
nltk.download('vader_lexicon')
nltk.download('averaged_perceptron_tagger_eng')
```

**Nota**: Los léxicos NRC son de uso exclusivamente no comercial (investigación o educación), por lo que no se
distribuyen con la biblioteca. Para usar los indicadores que dependen de ellos, descárgalos desde la web de sus autores
([EmoLex](https://saifmohammad.com/WebPages/NRC-Emotion-Lexicon.htm) y [VAD v1](https://saifmohammad.com/WebPages/nrc-vad.html))
e indica su ruta en las variables de entorno `PSYMARKERS_NRC_EMOLEX` (fichero
`NRC-Emotion-Lexicon/NRC-Emotion-Lexicon-Wordlevel-v0.92.txt` del zip) y `PSYMARKERS_NRC_VAD` (fichero
`NRC-VAD-Lexicon/NRC-VAD-Lexicon.txt` del zip de la v1, no el de la carpeta `BipolarScale`).

## Indicadores disponibles

Los indicadores actuales incluyen:

- `absolutist_ratio`: Proporción de palabras absolutistas (always, never, completely), marcador de ansiedad y depresión. Source: [In an Absolute State: Elevated Use of Absolutist Words Is a Marker Specific to Anxiety, Depression, and Suicidal Ideation](https://doi.org/10.1177/2167702617747074).
- `pronouns_ratio`: Proporción de pronombres singulares de primera persona (I, me, my), asociado a focalización en uno
  mismo. Source: [A meta-analysis of correlations between depression and first person singular pronoun use](https://doi.org/10.1016/j.jrp.2017.02.005)
- `pronouns_plural_ratio`: Proporción de pronombres plurales (we, us). Su disminución es un indicador de aislamiento
  social. Source: [Language use of depressed and depression-vulnerable college students](https://doi.org/10.1080/02699930441000030).
- `somatic_ratio`: Uso de palabras relacionadas con el cuerpo, dolor y fatiga. Source: [Somatic symptoms in depression](https://doi.org/10.31887/DCNS.2006.8.2/hpkapfhammer).
- `hopelessness_ratio`: Proporción de léxico que expresa desesperanza y falta de futuro. Source: [Hopelessness and eventual suicide: a 10-year prospective study of patients hospitalized with suicidal ideation](https://doi.org/10.1176/ajp.142.5.559).
- `negative_sentiment` / `compound_sentiment`: Valencia emocional negativa y polaridad afectiva general (mediante
  VADER). Sources: [Facebook language predicts depression in medical records](https://doi.org/10.1073/pnas.1802331115) and [Predicting depression via social media](https://doi.org/10.1609/icwsm.v7i1.14432) resp.
- `type_token_ratio`: Diversidad léxica. Un ratio bajo indica vocabulario repetitivo (rumiación cognitiva). Source: [The psychological meaning of words: LIWC and computerised text analysis methods](https://doi.org/10.1177/0261927X09351676?urlappend=%3Futm_source%3Dresearchgate.net%26utm_medium%3Darticle).
- `moving_average_type_token_ratio`: Diversidad léxica (MATTR) independiente de la longitud del texto, calculada sobre
  ventanas de `window` palabras (10 por defecto); NaN si el texto es más corto que la ventana. Source: [Cutting the Gordian Knot: The Moving-Average Type–Token Ratio (MATTR)](https://doi.org/10.1080/09296171003643098).
- `fear_ratio` / `sadness_ratio` / `anger_ratio`: Proporción de palabras asociadas a miedo, tristeza e ira según el
  NRC Emotion Lexicon ([Crowdsourcing a Word–Emotion Association Lexicon](https://doi.org/10.1111/j.1467-8640.2012.00460.x)). Sources: [Sentiment Analysis of Suicide Notes: A Shared Task](https://doi.org/10.4137/BII.S9042) and [An emotion and cognitive based analysis of mental health disorders from social media data](https://doi.org/10.1016/j.future.2021.05.032).
- `arousal_score` / `dominance_score`: Activación y dominancia medias de las palabras según el NRC VAD Lexicon v1
  ([Obtaining Reliable Human Ratings of Valence, Arousal, and Dominance for 20,000 English Words](https://doi.org/10.18653/v1/P18-1017)). Source: [Language and Mental Health: Measures of Emotion Dynamics from Text as Linguistic Biosocial Markers](https://doi.org/10.18653/v1/2023.emnlp-main.188).
- `temporal_myopia_index`: Ratio de verbos en pasado frente a verbos modales futuros, indicando estrechamiento temporal
  o incapacidad de proyectarse al futuro. Source: [Suicide as escape from self](https://doi.org/10.1037/0033-295x.97.1.90).
- `readability_score`: Nivel de legibilidad de Flesch-Kincaid. Textos muy desorganizados se asocian a deterioro 
  cognitivo o psicosis. Source: [Linguistic features identify Alzheimer’s disease in narrative
    speech](https://doi.org/10.3233/jad-150520).
- `insomnia_post`: Validador de metadatos que retorna 1.0 si el texto fue publicado en horario nocturno (2 AM - 5 AM). Source: [The Mind After Midnight: Nocturnal Wakefulness, Behavioral Dysregulation, and Psychopathology](https://doi.org/10.3389/fnetp.2021.830338).

## 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

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

# 1. Define your feature extraction pipeline
metrics_pipeline = [
    markers.absolutist_ratio,
    markers.pronouns_ratio,
    markers.hopelessness_ratio,
    markers.negative_sentiment,
    markers.temporal_myopia_index,
    markers.type_token_ratio
]

# 2. Extract all features into a dictionary in a single pass
features = {
    metric.__name__: metric(text, date=date)
    for metric in metrics_pipeline
}

# 3. Do whatever you like with the data
print(features)
```

## 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).