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 |
None
|
skipgram_path
|
str
|
Path to the skip-gram model file is safetensors format. If None (together with |
None
|
skipgram_vocab_path
|
Union[str, None]
|
CSV vocabulary used to train the skipgram model (column |
None
|
ngram_dir_path
|
str
|
Directory with |
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 |
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. |