humetrix 0.3.0__py3-none-any.whl

humetrix/__init__.py

@@ -0,0 +1,14 @@
+from .analyzer import HumorAnalyzer
+from .quantum_entropy import QuantumUncertainty, QuantumIncongruity
+from .surprise import LocalGlobalSurprise
+from .kaoetal import KaoConfig, KaoAmbiguity, KaoDistinctiveness
+
+__all__ = [
+    "HumorAnalyzer",
+    "QuantumUncertainty",
+    "QuantumIncongruity",
+    "LocalGlobalSurprise",
+    "KaoConfig",
+    "KaoAmbiguity",
+    "KaoDistinctiveness"
+]

humetrix/_resources.py

@@ -0,0 +1,58 @@
+"""Download and load the external resources used by the metrics."""
+
+from pathlib import Path
+from typing import Iterable, Optional
+
+import safetensors.numpy
+from gensim.models import KeyedVectors
+from huggingface_hub import hf_hub_download
+
+from .configs import EXTERNAL_EMBEDDINGS, RESOURCES_REPO, RESOURCES_REVISION
+
+
+def download_resource(
+    filenames: Iterable[str],
+    subfolder: Optional[str] = None,
+    repo_id: str = RESOURCES_REPO,
+    revision: str = RESOURCES_REVISION,
+) -> Path:
+    """Download files from the Hugging Face Hub repository and return their directory."""
+
+    paths = [
+        hf_hub_download(repo_id, filename, subfolder=subfolder, revision=revision)
+        for filename in filenames
+    ]
+
+    if not paths:
+        raise ValueError("At least one filename is required.")
+    return Path(paths[0]).parent
+
+
+def download_embeddings(language: str) -> Path:
+    """Download the default glove embeddings for a language."""
+    filenames = ["embeddings.safetensors", "vocab.txt"]
+    if language in EXTERNAL_EMBEDDINGS:
+        repo_id, revision = EXTERNAL_EMBEDDINGS[language]
+        return download_resource(filenames, repo_id=repo_id, revision=revision)
+    return download_resource(filenames, subfolder=f"glove/{language}")
+
+
+def load_embeddings(directory: Path) -> KeyedVectors:
+    """Load embeddings from `embeddings.safetensors` + `vocab.txt` files."""
+    tensors = safetensors.numpy.load_file(directory / "embeddings.safetensors")
+    vectors = tensors["embeddings"]
+
+    with open(directory / "vocab.txt", encoding="utf-8", newline="\n") as f:
+        vocab = f.read().split("\n")
+    if vocab[-1] == "":
+        vocab.pop()
+
+    if len(vocab) != len(vectors):
+        raise ValueError(
+            f"{directory}: vocab.txt has {len(vocab)} words, "
+            f"but the matrix has {len(vectors)} rows."
+        )
+
+    embeddings = KeyedVectors(vector_size=vectors.shape[1])
+    embeddings.add_vectors(vocab, vectors)
+    return embeddings

humetrix/analyzer.py

@@ -0,0 +1,397 @@
+"""
+This module provides a centralized API for analyzing humor in text using various metrics.
+
+The HumorAnalyzer class requires at least the analysis language. Depending on the metrics
+to be used, additional resources such as word embeddings, skip-gram models, and n-gram models
+may need to be provided.
+
+Resources are loaded as needed to optimize performance.
+"""
+
+import importlib
+from pathlib import Path
+from typing import Dict, Union
+
+import polars as pl
+import safetensors.torch
+import spacy
+import torch
+from gensim.models import KeyedVectors
+from spacy.language import Language
+from transformers import AutoModelForMaskedLM, AutoTokenizer, Pipeline, pipeline
+
+from ._resources import download_embeddings, download_resource, load_embeddings
+from .configs import SPACY_MODELS, TOKENIZER_MODELS, TRANSFORMER_MODELS
+from .kaoetal import KaoAmbiguity, KaoConfig, KaoDistinctiveness
+from .quantum_entropy import QuantumIncongruity, QuantumUncertainty
+from .skipgram import SGNS, build_vocabulary
+from .surprise import LocalGlobalSurprise
+
+
+def _load_spacy_model(name: str) -> Language:
+    """Load a spacy mode, downloading it on first use if needed."""
+    try:
+        return spacy.load(name)
+    except OSError:
+        pass
+
+    from spacy.cli.download import download
+
+    try:
+        download(name)
+    except SystemExit:
+        raise OSError(
+            f"spacy model {name} is not installed and could not be "
+            f"downloaded automatically. Install it with:\n"
+            f"    python -m spacy download {name}"
+        ) from None
+
+    importlib.invalidate_caches()
+    return spacy.load(name)
+
+
+class HumorAnalyzer:
+    """
+    A class to analyze humor in text using different metrics.
+
+    Some of the metrics implemented here require external resources such as word embeddings,
+    skip-gram models, and n-gram models.
+
+    Supported metrics include:
+    - Quantum Incongruity
+    - Quantum Uncertainty
+    - Local-Global Surprise
+    - Kao et al.'s Ambiguity
+    - Kao et al.'s Distinctiveness
+
+    Parameters
+    ----------
+    language : str
+        The language of analysis.
+    embeddings_path : str, optional
+        Directory with `embeddings.safetensors` and `vocab.txt`. If None, the default embeddings for the language are downloaded.
+    skipgram_path : str, optional
+        Path to the skip-gram model file is safetensors format. If None (together with `skipgram_vocab_path`), the default model for the language is downloaded.
+    skipgram_vocab_path: str, optional
+        CSV vocabulary used to train the skipgram model (column `ngram`). Required when `skipgram_path` is given.
+    ngram_dir_path : str, optional
+        Directory with `1gram.csv` and `3gram.csv`. If None, the default n-gram tables for the language are downloaded.
+    transformer_model_name : str, optional
+        Name of the transformer model to use. Defaults to None.
+    device: str or torch.device, optional
+        Device for the neural models. If None, eses a GPU when available.
+
+    Raises
+    ------
+    ValueError
+        If the specified language is not supported.
+    """
+
+    def __init__(
+        self,
+        language: str,
+        embeddings_path: Union[str, None] = None,
+        skipgram_path: Union[str, None] = None,
+        skipgram_vocab_path: Union[str, None] = None,
+        ngram_dir_path: Union[str, None] = None,
+        transformer_model_name: Union[str, None] = None,
+        device: Union[str, torch.device, None] = None,
+    ) -> None:
+        self.language = language
+        if language not in SPACY_MODELS:
+            raise ValueError(f"Unsupported language: {language}")
+
+        if device is None:
+            device = "cuda" if torch.cuda.is_available() else "cpu"
+        self.device = torch.device(device)
+
+        self._transformer_model_name = transformer_model_name
+        self._paths = {
+            "embeddings": embeddings_path,
+            "skipgram": skipgram_path,
+            "skipgram_vocab": skipgram_vocab_path,
+            "ngram_dir": ngram_dir_path,
+        }
+        self._models = {}
+
+    def _load_model(
+        self, name: str
+    ) -> Union[Language, Dict, KeyedVectors, pl.DataFrame, SGNS, Pipeline]:
+        """
+        Load and cache the specified model.
+
+        Parameters
+        ----------
+        name : str
+            The name of the model to load.
+
+        Returns
+        -------
+        spacy model or dict or gensim KeyedVectors or polars DataFrame or SGNS model or transformers pipeline
+            The loaded model.
+
+        Raises
+        ------
+        ValueError
+            If the model type is unknown or required paths are not provided.
+        """
+        if name not in self._models:
+            if name == "spacy":
+                model_name = SPACY_MODELS[self.language]
+                self._models[name] = _load_spacy_model(model_name)
+            elif name == "tokenizer":
+                if self.language in TOKENIZER_MODELS:
+                    model_name = TOKENIZER_MODELS[self.language]
+                    self._models[name] = _load_spacy_model(model_name)
+                else:
+                    self._models[name] = spacy.blank(self.language)
+            elif name == "bert":
+                model_name = TRANSFORMER_MODELS[self.language]
+                tokenizer = AutoTokenizer.from_pretrained(model_name)
+                lm = AutoModelForMaskedLM.from_pretrained(
+                    model_name, device_map=self.device
+                )
+                self._models[name] = {"tokenizer": tokenizer, "lm": lm}
+            elif name == "embeddings":
+                directory = self._paths["embeddings"]
+                if directory is None:
+                    directory = download_embeddings(self.language)
+                self._models[name] = load_embeddings(Path(directory))
+            elif name == "ngram1" or name == "ngram3":
+                ngram_dir = self._paths["ngram_dir"]
+                if ngram_dir is None:
+                    ngram_dir = download_resource(
+                        ["1gram.csv", "3gram.csv"], subfolder=f"ngrams/{self.language}"
+                    )
+                ngram_path = Path(ngram_dir) / f"{name[-1]}gram.csv"
+                self._models[name] = pl.read_csv(ngram_path)
+            elif name == "kao_models":
+                skipgram_path = self._paths["skipgram"]
+                vocab_path = self._paths["skipgram_vocab"]
+                if skipgram_path is None and vocab_path is None:
+                    skipgram_dir = download_resource(
+                        ["model.safetensors"], subfolder=f"skipgram/{self.language}"
+                    )
+                    vocab_dir = download_resource(
+                        ["1gram.csv"], subfolder=f"ngrams/{self.language}"
+                    )
+                    skipgram_path = skipgram_dir / "model.safetensors"
+                    vocab_path = vocab_dir / "1gram.csv"
+                elif skipgram_path is None or vocab_path is None:
+                    raise ValueError(
+                        "Provide both `skipgram_path` and `skipgram_vocab_path`, "
+                        "or neither to use the default skipgram model."
+                    )
+                vocab = build_vocabulary(str(vocab_path))
+                state_dict = safetensors.torch.load_file(skipgram_path)
+                embedding_dim = state_dict["embeddings.weight"].shape[1]
+                sgns = SGNS(vocab, embedding_dim)
+                sgns.load_state_dict(state_dict)
+                sgns.eval()
+                self._models[name] = {
+                    "skipgram": sgns,
+                    "ngram1": self._load_model("ngram1"),
+                    "ngram3": self._load_model("ngram3"),
+                }
+            elif name == "transformer_pipeline":
+                if self._transformer_model_name:
+                    model_name = self._transformer_model_name
+                else:
+                    model_name = TRANSFORMER_MODELS[self.language]
+                self._models[name] = pipeline(
+                    "feature-extraction", model_name, device=self.device
+                )
+            else:
+                raise ValueError(f"Unknown model type: {name}")
+        return self._models[name]
+
+    def quantum_incongruity(
+        self, sentence: str, backend: str = "word_embeddings"
+    ) -> Union[float, None]:
+        """
+        Calculate the quantum incongruity of a sentence.
+
+        Parameters
+        ----------
+        sentence : str
+            The sentence to analyze.
+        backend : {'word_embeddings', 'transformer'}, optional
+            The backend to use for embeddings. Defaults to 'word_embeddings'.
+
+        Returns
+        -------
+        float or None
+            The quantum incongruity score, or None if it cannot be calculated.
+
+        Raises
+        ------
+        ValueError
+            If an unknown backend is specified.
+
+        See Also
+        --------
+        quantum_entropy.QuantumIncongruity.score : Method that performs the actual scoring.
+        """
+        if backend == "word_embeddings":
+            embeddings = self._load_model("embeddings")
+        elif backend == "transformer":
+            embeddings = self._load_model("transformer_pipeline")
+        else:
+            raise ValueError(f"Unknown backend for quantum incongruity: {backend}")
+        scorer = QuantumIncongruity(
+            sentence=sentence,
+            embeddings=embeddings,
+            spacy_model=self._load_model("tokenizer"),
+            device=self.device,
+        )
+        return scorer.score()
+
+    def quantum_uncertainty(
+        self, sentence: str, backend: str = "word_embeddings"
+    ) -> Union[float, None]:
+        """
+        Calculate the quantum uncertainty of a sentence.
+
+        Parameters
+        ----------
+        sentence : str
+            The sentence to analyze.
+        backend : {'word_embeddings', 'transformer'}, optional
+            The backend to use for embeddings. Defaults to 'word_embeddings'.
+
+        Returns
+        -------
+        float or None
+            The quantum uncertainty score, or None if it cannot be calculated.
+
+        Raises
+        ------
+        ValueError
+            If an unknown backend is specified.
+
+        See Also
+        --------
+        quantum_entropy.QuantumUncertainty.score : Method that performs the actual scoring.
+        """
+        if backend == "word_embeddings":
+            embeddings = self._load_model("embeddings")
+        elif backend == "transformer":
+            embeddings = self._load_model("transformer_pipeline")
+        else:
+            raise ValueError(f"Unknown backend for quantum uncertainty: {backend}")
+        scorer = QuantumUncertainty(
+            sentence=sentence,
+            embeddings=embeddings,
+            spacy_model=self._load_model("tokenizer"),
+            device=self.device,
+        )
+        return scorer.score()
+
+    def local_global_surprise(
+        self, sentence: str, pun_sign: str, alt_sign: str
+    ) -> float:
+        """
+        Calculate the local-global surprise of a sentence.
+
+        Parameters
+        ----------
+        sentence : str
+            The sentence to analyze.
+        pun_sign : str
+            The pun sign. The word or phrase that is ambiguous or humorous.
+        alt_sign : str
+            The alternative sign. The word or phrase that is evoked by the pun sign.
+
+        Returns
+        -------
+        float
+            The local-global surprise score.
+
+        See Also
+        --------
+        surprise.LocalGlobalSurprise.score : Method that performs the actual scoring.
+        """
+        bert_models = self._load_model("bert")
+        scorer = LocalGlobalSurprise(
+            sentence=sentence,
+            pun_sign=pun_sign,
+            alt_sign=alt_sign,
+            spacy_model=self._load_model("tokenizer"),
+        )
+        return scorer.score(tokenizer=bert_models["tokenizer"], lm=bert_models["lm"])
+
+    def kao_ambiguity(self, sentence: str, pun_sign: str, alt_sign: str) -> float:
+        """
+        Calculate Kao et al.'s ambiguity of a sentence.
+
+        Parameters
+        ----------
+        sentence : str
+            The sentence to analyze.
+        pun_sign : str
+            The pun sign. The word or phrase that is ambiguous or humorous.
+        alt_sign : str
+            The alternative sign. The word or phrase that is evoked by the pun sign.
+
+        Returns
+        -------
+        float
+            Ambiguity score.
+
+        See Also
+        --------
+        kaoetal.KaoAmbiguity.score : Method that performs the actual scoring.
+        """
+        kao_models = self._load_model("kao_models")
+        config = KaoConfig(
+            sentence=sentence,
+            language=self.language,
+            spacy_model=self._load_model("spacy"),
+            skipgram=kao_models["skipgram"],
+        )
+        scorer = KaoAmbiguity(
+            config=config,
+            pun_sign=pun_sign,
+            alt_sign=alt_sign,
+            ngram1=kao_models["ngram1"],
+            ngram3=kao_models["ngram3"],
+        )
+        return scorer.score()
+
+    def kao_distinctiveness(self, sentence: str, pun_sign: str, alt_sign: str) -> float:
+        """
+        Calculate Kao et al.'s distinctiveness of a sentence.
+
+        Parameters
+        ----------
+        sentence : str
+            The sentence to analyze.
+        pun_sign : str
+            The pun sign. The word or phrase that is ambiguous or humorous.
+        alt_sign : str
+            The alternative sign. The word or phrase that is evoked by the pun sign.
+
+        Returns
+        -------
+        float
+            Distinctiveness score.
+
+        See Also
+        --------
+        kaoetal.KaoDistinctiveness.score : Method that performs the actual scoring.
+        """
+        kao_models = self._load_model("kao_models")
+        config = KaoConfig(
+            sentence=sentence,
+            language=self.language,
+            spacy_model=self._load_model("spacy"),
+            skipgram=kao_models["skipgram"],
+        )
+        scorer = KaoDistinctiveness(
+            config=config,
+            pun_sign=pun_sign,
+            alt_sign=alt_sign,
+            ngram1=kao_models["ngram1"],
+            ngram3=kao_models["ngram3"],
+        )
+        return scorer.score()

humetrix/configs.py

@@ -0,0 +1,36 @@
+"""
+Definition of constants: language codes, spacy models, transformer models, and content word POS tags.
+"""
+
+SPACY_MODELS = {
+    "pt": "pt_core_news_lg",
+    "en": "en_core_web_trf",
+    "fr": "fr_dep_news_trf",
+    "es": "es_dep_news_trf",
+    "zh": "zh_core_web_trf",
+}
+# Pipelines used only for tokenization in QE and Suprise metrics.
+# Languages not listed here use spacy.blank(language).
+TOKENIZER_MODELS = {"zh": "zh_core_web_sm"}
+TRANSFORMER_MODELS = {
+    "pt": "neuralmind/bert-base-portuguese-cased",
+    "en": "bert-base-cased",
+    "fr": "camembert-base",
+    "es": "dccuchile/bert-base-spanish-wwm-cased",
+    "zh": "bert-base-chinese",
+}
+CONTENT_WORD_TAGS = {
+    "pt": {"ADJ", "ADV", "AUX", "NOUN", "NUM", "PART", "PROPN", "VERB"},
+    "en": {"ADJ", "ADV", "AUX", "NOUN", "NUM", "PART", "PROPN", "VERB"},
+    "fr": {"ADJ", "ADV", "AUX", "NOUN", "NUM", "PART", "PROPN", "VERB"},
+    "es": {"ADJ", "ADV", "AUX", "NOUN", "NUM", "PART", "PROPN", "VERB"},
+}
+
+# Hugging Face Hub repository with GloVe, skip-gram and n-gram resources
+RESOURCES_REPO = "NLP-CISUC/humetrix-resources"
+RESOURCES_REVISION = "cef7d0ac55fae7c154b4bb588de0be2f6d43432b"
+
+# GloVe embeddings hosted elsewere: language -> (repo_id, revision)
+EXTERNAL_EMBEDDINGS = {
+    "pt": ("nilc-nlp/glove-300d", "44dac98d46b885135a7fe1565f5c67f0f897a4ea")
+}