Skip to content

API reference

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
  • Surprise Ratio
  • Kao et al.'s Ambiguity
  • Kao et al.'s Distinctiveness

Parameters:

Name Type Description Default
language str

The language of analysis.

required
embeddings_path str

Directory with embeddings.safetensors and vocab.txt. If None, the default embeddings for the language are downloaded.

None
skipgram_path str

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.

None
skipgram_vocab_path Union[str, None]

CSV vocabulary used to train the skipgram model (column ngram). Required when skipgram_path is given.

None
ngram_dir_path str

Directory with 1gram.csv and 3gram.csv. If None, the default n-gram tables for the language are downloaded.

None
transformer_model_name str

Name of the transformer model to use. Defaults to None.

None
device Union[str, device, None]

Device for the neural models. If None, eses a GPU when available.

None

Raises:

Type Description
ValueError

If the specified language is not supported.

kao_ambiguity(sentence, pun_sign, alt_sign)

Calculate Kao et al.'s ambiguity of a sentence.

Parameters:

Name Type Description Default
sentence str

The sentence to analyze.

required
pun_sign str

The pun sign. The word or phrase that is ambiguous or humorous.

required
alt_sign str

The alternative sign. The word or phrase that is evoked by the pun sign.

required

Returns:

Type Description
float

Ambiguity score.

See Also

kaoetal.KaoAmbiguity.score : Method that performs the actual scoring.

kao_distinctiveness(sentence, pun_sign, alt_sign)

Calculate Kao et al.'s distinctiveness of a sentence.

Parameters:

Name Type Description Default
sentence str

The sentence to analyze.

required
pun_sign str

The pun sign. The word or phrase that is ambiguous or humorous.

required
alt_sign str

The alternative sign. The word or phrase that is evoked by the pun sign.

required

Returns:

Type Description
float

Distinctiveness score.

See Also

kaoetal.KaoDistinctiveness.score : Method that performs the actual scoring.

quantum_incongruity(sentence, backend='word_embeddings')

Calculate the quantum incongruity of a sentence.

Parameters:

Name Type Description Default
sentence str

The sentence to analyze.

required
backend (word_embeddings, transformer)

The backend to use for embeddings. Defaults to 'word_embeddings'.

'word_embeddings'

Returns:

Type Description
float or None

The quantum incongruity score, or None if it cannot be calculated.

Raises:

Type Description
ValueError

If an unknown backend is specified.

See Also

quantum_entropy.QuantumIncongruity.score : Method that performs the actual scoring.

quantum_uncertainty(sentence, backend='word_embeddings')

Calculate the quantum uncertainty of a sentence.

Parameters:

Name Type Description Default
sentence str

The sentence to analyze.

required
backend (word_embeddings, transformer)

The backend to use for embeddings. Defaults to 'word_embeddings'.

'word_embeddings'

Returns:

Type Description
float or None

The quantum uncertainty score, or None if it cannot be calculated.

Raises:

Type Description
ValueError

If an unknown backend is specified.

See Also

quantum_entropy.QuantumUncertainty.score : Method that performs the actual scoring.

surprise_ratio(sentence, pun_sign, alt_sign)

Calculate the surprise ratio of a sentence.

Parameters:

Name Type Description Default
sentence str

The sentence to analyze.

required
pun_sign str

The pun sign. The word or phrase that is ambiguous or humorous.

required
alt_sign str

The alternative sign. The word or phrase that is evoked by the pun sign.

required

Returns:

Type Description
float

The surprise ratio score.

See Also

surprise.SurpriseRatio.score : Method that performs the actual scoring.

kaoetal

This module implements the humor metrics proposed by Kao et al. (2016)_[1].

References

[1] Justine T. Kao, Roger Levy, and Noah D. Goodman. 2016. A Computational Model of Linguistic Humor in Puns. Cogn Sci 40, 5 (July 2016), 1270–1285. https://doi.org/10.1111/cogs.12269

KaoAmbiguity

Bases: KaoMetricBase

Calculates the ambiguity metric from Kao et al. (2016).

score()

Calculate the ambiguity score.

Returns:

Type Description
float

Ambiguity score.

Notes

Since \(P(m_a|\vec{w}) + P(m_b|\vec{w})\) is not necessarily 1, we normalize the posteriors before calculating the entropy.

KaoConfig

A configuration class for the Kao et al. (2016) metrics.

Parameters:

Name Type Description Default
sentence str

The sentence to be analyzed.

required
language str

The language of analysis.

required
spacy_model Language

The spaCy language model to use for tokenization.

required
skipgram SGNS

Distant skip-gram model_[1] used to approximate the empirical association measures from the original paper.

required
References

[1] He He, Nanyun Peng, and Percy Liang. 2019. Pun Generation with Surprise. In Proceedings of the 2019 Conference of the North American Chapter of the Association for Computational Linguistics: Human Language Technologies, 2019. Association for Computational Linguistics, Minneapolis, 1734–1744. https://doi.org/10.18653/v1/N19-1172

KaoDistinctiveness

Bases: KaoMetricBase

Calculates the distinctiveness metric from Kao et al. (2016).

score()

Calculate the distinctiveness score.

Returns:

Type Description
float

Distinctiveness score.

KaoMetricBase

A base class for the Kao et al. (2016) metrics.

This class provides common functions for calculating both metrics proposed by Kao et al. (2016)_[1]: ambiguity and distinctiveness. Namely, it handles the preparation of n-gram probabilities and the calculation of word posteriors given a hidden variable configuration (\(P(w_i|m,f_i)\)).

Parameters:

Name Type Description Default
config KaoConfig

The configuration object.

required
pun_sign str

The pun sign. The word or phrase that is ambiguous or humorous.

required
alt_sign str

The alternative sign. The word or phrase that is evoked by the pun sign.

required
ngram1 DataFrame

A DataFrame with 1-gram frequencies following the format of orgtre/google-books-ngram-frequency. We expect at least two columns: 'ngram' (str) and 'freq' (int).

required
ngram3 DataFrame

A DataFrame with 3-gram frequencies following the format of orgtre/google-books-ngram-frequency. We expect at least two columns: 'ngram' (str) and 'freq' (int).

required
References

[1] Justine T. Kao, Roger Levy, and Noah D. Goodman. 2016. A Computational Model of Linguistic Humor in Puns. Cogn Sci 40, 5 (July 2016), 1270–1285. https://doi.org/10.1111/cogs.12269

surprise

This module implements the surprise-based humor metric from He et al. (2019)_[1].

References

[1] He He, Nanyun Peng, and Percy Liang. 2019. Pun Generation with Surprise. In Proceedings of the 2019 Conference of the North American Chapter of the Association for Computational Linguistics: Human Language Technologies, 2019. Association for Computational Linguistics, Minneapolis, 1734–1744. https://doi.org/10.18653/v1/N19-1172

SurpriseRatio

Calculate the surprise-based humor metric from He et al. (2019).

Parameters:

Name Type Description Default
sentence str

The sentence to be analyzed.

required
pun_sign str

The pun sign. The word or phrase that is ambiguous or humorous.

required
alt_sign str

The alternative sign. The word or phrase that is evoked by the pun sign.

required

get_local_context(window_size)

Get the local context around the pun sign.

Parameters:

Name Type Description Default
window_size int

The size of the window around the pun sign.

required

Returns:

Type Description
str

The local context.

score(tokenizer, lm)

Calculate the Surprise Ratio score.

Parameters:

Name Type Description Default
tokenizer PreTrainedTokenizer

The transformer tokenizer to use.

required
lm PreTrainedModel

The language model to retrieve probabilities from.

required

Returns:

Type Description
float

The Surprise Ratio score. If any error occurs, returns -1.

surprisal(context, tokenizer, lm)

Calculate the surprisal of the pun sign given a context.

Parameters:

Name Type Description Default
context str

The context to use for calculating surprisal.

required
tokenizer PreTrainedTokenizer

The transformer tokenizer to use.

required
lm PreTrainedModel

The language model to retrieve probabilities from.

required

Returns:

Type Description
float

The surprisal score.

quantum_entropy

This module implements the quantum entropy-based humor metrics from Liu and Hou (2023).

References

[1] Yang Liu and Yuexian Hou. 2023. Mining Effective Features Using Quantum Entropy for Humor Recognition. In Findings of the Association for Computational Linguistics: EACL 2023, May 2023. Association for Computational Linguistics, Dubrovnik, Croatia, 2048–2053. Retrieved August 23, 2023 from https://aclanthology.org/2023.findings-eacl.152

QuantumEntropy

A base class for quantum entropy-based humor metrics.

This class provides general methods for tokenizing sentences and calculating density matrices. Specific humor metrics can be implemented by subclassing this class and implementing the score method.

Parameters:

Name Type Description Default
sentence str

The sentence to be analyzed.

required
embeddings Gensim embeddings or Transformers feature extraction pipeline

The embedding model to use for token representations.

required
spacy_model spaCy model

The spaCy language model for tokenization.

required
mean_vector Tensor or None

A vector of shape (dim,) subtracted from every embedding before normalization. If None, no centering is applied.

None
device str or device or None

Device for the density matrix computations. If None, uses a GPU when available.

None

density_matrix(tokens)

Calculate the density matrix for a list of tokens.

Parameters:

Name Type Description Default
tokens list of str

The tokens to calculate the density matrix for.

required

Returns:

Type Description
Tensor or None

The density matrix, or None if no valid embeddings were found.

Notes

The density matrix is calculated as the mean of the outer products of the normalized token embeddings: \(\rho = \frac{1}{n} \sum_{i=1}^n |w_i\rangle\langle w_i|\), where \(|w_i\rangle = \frac{\vec{w_i} - \mu}{\|\vec{w_i} - \mu\|}\) and \(\mu\) is the mean vector (zero if not provided).

score() abstractmethod

Calculate the humor score.

token_embeddings(tokens)

Calculate the embeddings for each given token.

Parameters:

Name Type Description Default
tokens list of str

The tokens to calculate word embeddings for.

required

Returns:

Type Description
Tensor

A tensor of shape (n, dim), one row per token with a valid embedding. Tokens absent from the static vocabulary, or that have no subtokens, are skipped, so n may be smaller than len(tokens).

Notes

If the embedding model is a Transformer, we average the subtokens into one single word embedding, special tokens are discarted, and embeddings come from the model's last layer.

tokenize_sentence()

Tokenize the sentence into setup and punchline.

Returns:

Type Description
tuple containing two lists of str or None:

The tokens in the joke setup and punchline, respectively, or None if the text produces less or more than two segments.

Notes

The spaCy model is modified to include a sentencizer component. Sentences are also split at commas and semicolons, and tokens are lowercased.

Returns None unless the text produces exactly two segements, since the metrics are only defined for a setup followed by a punchline.

von_neumann_entropy(d_matrix, hermitian=True)

Calculate the von Neumann entropy of a density matrix.

Parameters:

Name Type Description Default
d_matrix Tensor

The density matrix, with trace equal to 1.

required
hermitian bool

Whether d_matrix is Hermitian. If True, eigenvalues are computed with a symmetric solver; otherwise, a general solver is used and only the real part of the eigenvalues is kept.

True

Returns:

Type Description
float

The von Neumann entropy.

Notes

The entropy is calculated from the eigenvalues: \(-\sum_i \lambda_i \log \lambda_i\), ignoring eigenvalues smaller than \(10^{-12}\). We use the natural logarithm.

QuantumIncongruity

Bases: QuantumEntropy

Liu and Hou (2023) quantum entropy Incongruity scoring.

score()

Calculate the quantum incongruity score.

Returns:

Type Description
float or None

The quantum incongruity score, or None if the text does not have exactly two segments or if density matrices could not be calculated.

Notes

\(\rho_p\rho_s\) is usually non-Hermitian nor has a unit trace. We normalize it by its trace and calculate its entropy using hermitian=False.

QuantumUncertainty

Bases: QuantumEntropy

Liu and Hou (2023) quantum entropy Uncertainty scoring.

score()

Calculate the quantum uncertainty score.

Returns:

Type Description
float or None

The quantum uncertainty score, or None if the thext does not have exactly two segments density matrix could not be calculated.