Humetrix
Automatic metrics for humorous texts. Currently supporting English, Spanish, French, Portuguese and Mandarin Chinese.
| Metric | Method | Reference |
|---|---|---|
| Quantum Uncertainty / Incongruity | quantum_uncertainty, quantum_incongruity |
Liu and Hou (2023) |
| Surprise Ratio | surprise_ratio |
He et al. (2019) |
| Ambiguity / Distinctiveness | kao_ambiguity, kao_distinctiveness |
Kao et al. (2016) |
Description
Humetrix is a Python library that provides a collection of automatic metrics for evaluating humor in text. Quantum Entropy metrics apply to any text with a setup and a punchline, while Surprise Ratio and Ambiguity/Distinctiveness are designed for puns and need the pun and alternative words.
All resources are downloaded automatically on first use, but the repository also contains the scripts used to train our models (see docs/skipgram.md)
Installation
Humetrix requires Python 3.12 or above:
pip install humetrix
PyTorch is installed from PyPI by default. For a CPU-only install, install PyTorch first following the official instructions.
Usage
Here is a simple example of how to use Humetrix:
from humetrix import HumorAnalyzer
# Needed resources are downloaded automatically on first use
analyzer = HumorAnalyzer(language='en')
sent = 'Not all math puns are bad. Just sum of them.'
sign = 'sum'
alt_sign = 'some'
qi_score = analyzer.quantum_incongruity(sent)
qi_xlm_score = analyzer.quantum_incongruity(sent, backend='transformer')
qu_score = analyzer.quantum_uncertainty(sent)
qu_xlm_score = analyzer.quantum_uncertainty(sent, backend='transformer')
sr_score = analyzer.surprise_ratio(sent, sign, alt_sign)
kao_amb_score = analyzer.kao_ambiguity(sent, sign, alt_sign)
kao_dist_score = analyzer.kao_distinctiveness(sent, sign, alt_sign)
Metrics return None when they cannot be computed.
Use HumorAnalyzer(<language>, device="cpu") too choose where neural models run, and transformer_model_name to choose the model for the transformer backend.
Full API Documentation is available at https://nlp-cisuc.github.io/Humetrix/.
Resources
Embeddings, skip-gram models, n-gram tables, spaCy and transformer models are downloaded on first use and cached locally, so the first call of each metric may take a while. They are hosted at NLP-CISUC/humetrix-resources.
Development
To reproduce the experiments of the paper, clone the repository and use uv:
uv sync
License
This project is licensed under the MIT License - see the LICENSE file for details.
The resources have their own licenses, listed in the resources repository.
How to cite
To be announced
Metadata
Release files for humetrix 0.4.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| humetrix-0.4.0.tar.gz | 17.8 MB | Without provenance | Details for humetrix-0.4.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| humetrix-0.4.0-py3-none-any.whl | Python 3 | none | any | Details for humetrix-0.4.0-py3-none-any.whl |
Total release size: 17.8 MB
Release files / humetrix-0.4.0.tar.gz
| Download URL | humetrix-0.4.0.tar.gz |
|---|---|
| Size | 17.8 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
766438b0569464c1d3abc9f0409a19ecd33843a7a5ba6519acd8c6f2bc5c3e24
|
|
BLAKE2b-256 checksum How to use checksums |
21164dc9020adc17d86b0af478c7386c4c00b118fa26933d79eb5ee49a189c53
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.13.1 {"installer":{"name":"uv","version":"0.13.1","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Pop!_OS","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / humetrix-0.4.0-py3-none-any.whl
| Download URL | humetrix-0.4.0-py3-none-any.whl |
|---|---|
| Size | 21.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
67c2b9148993697244f4511e7ae258de27d6280404c818b59adf9465403f4327
|
|
BLAKE2b-256 checksum How to use checksums |
60729e6252446a5b581cf9ef522131efd41d6d44b214d87a3c5b8bc313a0601a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.13.1 {"installer":{"name":"uv","version":"0.13.1","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Pop!_OS","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Security for humetrix 0.4.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.