psymarkers 0.1.11__tar.gz

psymarkers-0.1.11/PKG-INFO

@@ -0,0 +1,105 @@
+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).

psymarkers-0.1.11/README.md

@@ -0,0 +1,81 @@
+# 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).

psymarkers-0.1.11/pyproject.toml

@@ -0,0 +1,100 @@
+[project]
+name = "psymarkers"
+version = "0.1.11"
+description = "TBD"
+readme = "README.md"
+requires-python = ">=3.13"
+keywords = [
+    "nlp",
+    "text-analysis",
+    "psychology",
+    "mental-health",
+    "sentiment-analysis",
+    "linguistics",
+    "feature-extraction",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Science/Research",
+    "Intended Audience :: Healthcare Industry",
+    "Intended Audience :: Developers",
+    "Topic :: Text Processing :: Linguistic",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Topic :: Scientific/Engineering :: Medical Science Apps.",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+]
+dependencies = [
+    "nltk>=3.10.3",
+    "textstat>=0.7.13",
+]
+
+[project.license]
+text = "GPL-3.0-or-later"
+
+[[project.authors]]
+name = "blazaid"
+email = "alber.diaz@pm.me"
+
+[project.urls]
+Repository = "https://codeberg.org/knodis/psymarkers"
+
+[build-system]
+requires = ["uv_build>=0.12.23"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "bump-my-version>=1.5.1",
+    "mypy>=2.4.0",
+    "pre-commit>=4.6.2",
+    "pytest>=9.1.1",
+    "ruff>=0.16.10",
+]
+
+[tool.mypy]
+strict = true
+ignore_missing_imports = true
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 80
+target-version = "py313"
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+
+[tool.ruff.lint]
+select = [
+    "E",
+    "F",
+    "I",
+    "W",
+    "UP",
+    "B",
+]
+ignore = []
+
+[tool.ruff.lint.pycodestyle]
+max-doc-length = 72
+
+[tool.bumpversion]
+current_version = "0.1.11"
+commit = true
+tag = true
+tag_name = "v{new_version}"
+
+[[tool.bumpversion.files]]
+filename = "pyproject.toml"
+search = 'version = "{current_version}"'
+replace = 'version = "{new_version}"'
+
+[[tool.bumpversion.files]]
+filename = "src/psymarkers/__init__.py"
+search = '__version__ = "{current_version}"'
+replace = '__version__ = "{new_version}"'

psymarkers-0.1.11/pyproject.toml.orig

@@ -0,0 +1,91 @@
+[project]
+name = "psymarkers"
+version = "0.1.11"
+description = "TBD"
+readme = "README.md"
+requires-python = ">=3.13"
+license = { text = "GPL-3.0-or-later" }
+authors = [
+    { name = "blazaid", email = "alber.diaz@pm.me" }
+]
+keywords = [
+    "nlp",
+    "text-analysis",
+    "psychology",
+    "mental-health",
+    "sentiment-analysis",
+    "linguistics",
+    "feature-extraction"
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Science/Research",
+    "Intended Audience :: Healthcare Industry",
+    "Intended Audience :: Developers",
+    "Topic :: Text Processing :: Linguistic",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Topic :: Scientific/Engineering :: Medical Science Apps.",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+]
+
+dependencies = [
+    "nltk>=3.10.3",
+    "textstat>=0.7.13",
+]
+
+[project.urls]
+Repository = "https://codeberg.org/knodis/psymarkers"
+
+[build-system]
+requires = ["uv_build>=0.12.23"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "bump-my-version>=1.5.1",
+    "mypy>=2.4.0",
+    "pre-commit>=4.6.2",
+    "pytest>=9.1.1",
+    "ruff>=0.16.10",
+]
+
+[tool.mypy]
+strict = true
+ignore_missing_imports = true
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 80
+target-version = "py313"
+
+[tool.ruff.lint.pycodestyle]
+max-doc-length = 72
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "W", "UP", "B"]
+ignore = []
+
+[tool.bumpversion]
+current_version = "0.1.11"
+commit = true
+tag = true
+tag_name = "v{new_version}"
+
+[[tool.bumpversion.files]]  # Para actualizar pyproject.toml
+filename = "pyproject.toml"
+search = 'version = "{current_version}"'
+replace = 'version = "{new_version}"'
+
+[[tool.bumpversion.files]]  # Para actualizar el __init__.py
+filename = "src/psymarkers/__init__.py"
+search = '__version__ = "{current_version}"'
+replace = '__version__ = "{new_version}"'

psymarkers-0.1.11/src/psymarkers/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.11"

psymarkers-0.1.11/src/psymarkers/markers.py

@@ -0,0 +1,235 @@
+import abc
+import logging
+import re
+from datetime import datetime
+from functools import lru_cache
+from typing import Any
+
+import nltk
+from nltk.sentiment import SentimentIntensityAnalyzer
+from textstat import textstat
+
+logger = logging.getLogger(__name__)
+
+
+@lru_cache(maxsize=1024)
+def get_cached_tokens(text: str) -> tuple[str, ...]:
+    """Tokenises the given text and returns a tuple of the tokens.
+
+    :param text: The text to be tokenised.
+    :return: A tuple of the tokenised text.
+    """
+    return tuple(nltk.word_tokenize(text))
+
+
+class TextMetric(metaclass=abc.ABCMeta):
+    """Base functor for all text metrics."""
+
+    def __call__(self, text: str, **kwargs: Any) -> float:
+        """Executes the text metric over the specified text.
+
+        :param text: The text to be evaluated.
+        :return: The metric value.
+        """
+        return self.compute(text, **kwargs)
+
+    @abc.abstractmethod
+    def compute(self, text: str, **kwargs: Any) -> float:
+        """Specific logic to implement by each metric.
+
+        :param text: The text to be evaluated.
+        :return: The metric value.
+        """
+
+
+class RegexRatioMetric(TextMetric):
+    """It generalises metrics that analyse word proportions.
+
+    They look for a pattern specified as a parameter and divide it by
+    the total number of words in the text.
+    """
+
+    def __init__(self, pattern: str | re.Pattern[str]) -> None:
+        """Initialises this object.
+
+        :param pattern: The pattern to search for.
+        """
+        self.pattern = (
+            re.compile(pattern, re.IGNORECASE)
+            if isinstance(pattern, str)
+            else pattern
+        )
+
+    def compute(self, text: str, **kwargs: Any) -> float:
+        total_words = len(get_cached_tokens(text))
+        if total_words == 0:
+            return 0.0
+
+        matches = len(self.pattern.findall(text))
+        return matches / total_words
+
+
+# The proportion of absolutist words in the text. Source: Al-Mosaiwi,
+# M., & Johnstone, T. (2018). In an Absolute State: Elevated Use of
+# Absolutist Words Is a Marker Specific to Anxiety, Depression, and
+# Suicidal Ideation. Clinical Psychological Science.
+absolutist_ratio = RegexRatioMetric(
+    r"\b(absolutely|all|always|complete|completely|constant|constantly|"
+    r"definitely|entire|ever|every|everyone|everything|full|must|never|"
+    r"nothing|totally|whole)\b"
+)
+# The proportion of 1st-person plural pronouns (we, us, our). Source:
+# Rude, S., Gortner, E. M., & Pennebaker, J. W. (2004). Language use of
+# depressed and depression-vulnerable college students. Cognition &
+# Emotion. (Apparently, a decrease in first-person plural pronouns
+# indicates social withdrawal and a lack of belongingness, which are
+# pre-suicidal markers in something called "Interpersonal Theory of
+# Suicide".
+pronouns_plural_ratio = RegexRatioMetric(r"\b(we|us|our|ours|ourselves)\b")
+
+# The proportion of words related to physical body, pain, and fatigue.
+# Source: Kapfhammer, H. P. (2006). Somatic symptoms in depression.
+# Dialogues in Clinical Neuroscience.
+somatic_ratio = RegexRatioMetric(
+    r"\b(sleep|tired|ache|pain|fatigue|exhausted|exhaustion|body|"
+    r"stomach|hurt|insomnia|sick|ill|headache|nausea|weak)\b"
+)
+
+# The proportion of first-person singular pronouns (I, me, my, mine,
+# myself). Source: Edwards, T., & Holtzman, N. S. (2017). A
+# meta-analysis of correlations between depression and first person
+# singular pronoun use. Journal of Research in Personality.
+pronouns_ratio = RegexRatioMetric(r"\b(i|me|my|mine|myself)\b")
+
+# The proportion of words expressing hopelessness and lack of future.
+# Source: Beck, A. T., et al. (1985). Hopelessness and eventual suicide:
+# a 10-year prospective study of patients hospitalized with suicidal
+# ideation. American Journal of Psychiatry.
+hopelessness_ratio = RegexRatioMetric(
+    r"\b(hopeless|worthless|pointless|give up|no future|too late|"
+    r"useless|trapped|despair|end it|meaningless)\b"
+)
+
+
+class SentimentMetric(TextMetric):
+    """Generalises specific scores from the sentiment analyser."""
+
+    _analyzer: SentimentIntensityAnalyzer | None = None
+
+    def __init__(self, sentiment_key: str):
+        """Initialises this object.
+
+        :param sentiment_key: The key of the sentiment analyser (for
+        SentimentIntensityAnalyzer of nltk).
+        """
+        self.key = sentiment_key
+
+    def compute(self, text: str, **kwargs: Any) -> float:
+        if SentimentMetric._analyzer is None:
+            SentimentMetric._analyzer = SentimentIntensityAnalyzer()
+
+        assert self._analyzer is not None
+        return float(self._analyzer.polarity_scores(text)[self.key])
+
+
+# The proportion of strictly negative emotional valence in the text.
+# Source: Eichstaedt, J. C., et al. (2018). Facebook language predicts
+# depression in medical records. Proceedings of the National Academy of
+# Sciences (PNAS). (Elevated baseline negative sentiment is an indicator
+# of depressive disorders).
+negative_sentiment = SentimentMetric("neg")
+
+# The overall compound emotional polarity, balancing positive, negative,
+# and neutral markers. Source: De Choudhury, M., Gamon, M., Counts, S.,
+# & Horvitz, E. (2013). Predicting depression via social media.
+# Proceedings of the International AAAI Conference on Web and Social
+# Media (ICWSM). (Captures affective shifts.
+compound_sentiment = SentimentMetric("compound")
+
+
+def type_token_ratio(text: str) -> float:
+    """Lexical diversity through the Type-Token Ratio (unique / total).
+
+    Source: Tausczik, Y. R., & Pennebaker, J. W. (2010). The
+    psychological meaning of words: LIWC and computerised text analysis
+    methods. Journal of Language and Social Psychology. (A low
+    Type-Token Ratio indicates a highly repetitive vocabulary, which
+    correlates with cognitive rumination).
+
+    :param text: The text of the sentence.
+    :return: A value from 0.0 (extreme repetition) to 1.0 (every word is
+        unique).
+    """
+    tokens = [w.lower() for w in get_cached_tokens(text) if w.isalnum()]
+    if tokens:
+        return len(set(tokens)) / len(tokens)
+    else:
+        return 0.0
+
+
+def temporal_myopia_index(text: str) -> float:
+    """Compares the usage of past tense vs future tense verbs.
+
+    Source: Baumeister, R. F. (1990). Suicide as escape from self.
+    Psychological Review. (People in suicidal crises often experience
+    temporal narrowing, losing the ability to think of themselves into
+    the future. A high ratio indicates being 'stuck in the past' with an
+    absence of future orientation).
+
+    :param text: The text of the sentence.
+    :return: A value where higher means more past-oriented (myopia) and
+        lower means future-oriented.
+    """
+    tokens = get_cached_tokens(text)
+    tags = nltk.pos_tag(tokens)
+
+    # VBD: Tiempo pasado, VBN: Participio
+    past_verbs = sum(1 for word, tag in tags if tag in ("VBD", "VBN"))
+    # MD: Verbos modales (will, shall, can), que indican proyección de
+    # futuro o posibilidad
+    future_modals = sum(1 for word, tag in tags if tag == "MD")
+
+    return past_verbs / (
+        future_modals + 1.0
+    )  # No dividir entre 0 que se borra la Internet
+
+
+def readability_score(text: str) -> float:
+    """The Flesch-Kincaid Grade Level (thought disorganisation).
+
+    Source: Mota, N. B., et al. (2018). Speech analysis by graph theory
+    to assess cognitive impairment. Schizophrenia Research. (The thought
+    disorganisation is typical in depression, mania, or psychosis).
+
+    :param text: The text of the sentence.
+    :return: Float representing the U.S. school grade required to
+        understand the text.
+    """
+    return float(textstat.flesch_kincaid_grade(text))
+
+
+def insomnia_post(text: str, date: str = "") -> float:
+    """Determines if the post is published during nighttime (insomnia).
+
+    :param text: The text of the sentence (unused here, but required by
+        signature).
+    :param date: The timestamp of the post.
+    :return: 1.0 if the post was between 2 AM and 5 AM, otherwise 0.0.
+    """
+    if not date:
+        return 0.0
+    try:
+        dt = datetime.fromisoformat(date.replace("Z", "+00:00"))
+        if dt.hour in [2, 3, 4, 5]:
+            return 1.0
+    except ValueError:
+        try:
+            dt = datetime.strptime(date, "%Y-%m-%d %H:%M:%S")
+            if dt.hour in (2, 3, 4, 5):
+                return 1.0
+        except Exception as e:
+            logger.error(f"Error parsing {date}: {e}", exc_info=True)
+    except Exception as e:
+        logger.error(f"Error parsing {date}: {e}", exc_info=True)
+
+    return 0.0

psymarkers-0.1.11/src/psymarkers/resources.py

@@ -0,0 +1,23 @@
+import os
+
+import nltk
+
+
+def download_nltk_resources(download_dir: str | None = None) -> None:
+    """Downloads the required lexical resources.
+
+    :param download_dir: Directory to download the resources to.
+    """
+    if download_dir is None:
+        download_dir = os.path.join(os.path.expanduser("~"), "nltk_data")
+
+    os.makedirs(download_dir, exist_ok=True)
+    nltk.data.path.append(download_dir)
+
+    for res in [
+        "vader_lexicon",
+        "punkt",
+        "punkt_tab",
+        "averaged_perceptron_tagger_eng",
+    ]:
+        nltk.download(res, download_dir=download_dir, quiet=True)