PySS3: Interpretable Machine Learning for Text Classification (Try our Live Demo! 🍰)
PySS3 implements SS3, a simple supervised machine learning model for interpretable text classification. SS3 can self-explain its rationale, making it a reliable choice for tasks where understanding model decisions is critical.
It was originally introduced in Section 3 of "A text classification framework for simple and effective early depression detection over social media streams" (arXiv preprint) and obtained the best and second-best results, consecutively, in the three CLEF eRisk editions from 2019 to 2021 [Burdisso et al. 2019; Loyola et al. 2021].
PySS3 also includes variants of SS3, such as t-SS3, which dynamically recognizes variable-length word n-grams "on the fly" for early risk detection (paper, arXiv).
What is PySS3?
PySS3 is a Python library for working with SS3 in a visual, interactive, and straightforward way.
It provides tools to:
- Analyze, monitor, and understand what your model has learned.
- Visualize classification decisions and model insights.
- Evaluate and optimize hyperparameters efficiently.
The library is organized into three main components:
👉 SS3 class
The core classifier with a clean API similar to sklearn:
from pyss3 import SS3
clf = SS3()
clf.fit(x_train, y_train)
y_pred = clf.predict(x_test)
Other useful methods include:
extract_insight()– Returns a list of text fragments involved in the classification decision, allowing you to understand the rationale behind the model’s predictions.classify_multilabel()– Multi-label classification support:
doc = "Liverpool CEO Peter Moore on Building a Global Fanbase"
label = clf.classify_label(doc) # 'business'
labels = clf.classify_multilabel(doc) # ['business', 'sports']
See all tutorials for step-by-step guidance.
👉 Live_Test class
Interactively test models in your browser, with one line of code:
from pyss3.server import Live_Test
Live_Test.run(clf, x_test, y_test)
Try our online live demos:
👉 Evaluation class
Evaluate and optimize your model easily:
from pyss3.util import Evaluation
best_s, best_l, best_p, _ = Evaluation.grid_search(
clf, x_train, y_train,
s=[0.2, 0.32, 0.44, 0.56, 0.68, 0.8],
l=[0.1, 0.48, 0.86, 1.24, 1.62, 2],
p=[0.5, 0.8, 1.1, 1.4, 1.7, 2],
k_fold=4
)
Evaluation.plot()
- Interactive 3D plots for hyperparameter evaluation
- Automatic history tracking of experiments
- Exportable HTML plots for sharing and reporting
Explore example evaluation plots:
Getting Started 👓 ☕
Installation
pip install pyss3
Full tutorial and documentation
Contributing ✨:octocat:✨
Any contributions are welcome! Code, bug reports, documentation, examples, or ideas – everything helps.
Use the "Edit" button on GitHub to propose changes directly, and follow these guidelines for commit messages.
Contributors 💪😎👍
Thanks goes to these awesome people (emoji key):
 Florian Angermeir 💻 🤔 🔣 |
 Muneeb Vaiyani 🤔 🔣 |
 Saurabh Bora 🤔 |
 Hubert Baniecki 🤔 📖 |
This project follows the all-contributors specification. Contributions of any kind welcome!
Further Readings 📜
1 maintainer
Release files for pyss3 0.6.5
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| pyss3-0.6.5.tar.gz | 1.9 MB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| pyss3-0.6.5-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 3.8 MB
Release files / pyss3-0.6.5.tar.gz
| Download URL | pyss3-0.6.5.tar.gz |
|---|---|
| Size | 1.9 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
926d8ca13f380f3f9a60997222f910d7d413e7396dc886f1b5999857cb10a2f6
|
|
BLAKE2b-256 checksum How to use checksums |
90809d77df7831cd3294678df64658c3b4007c4317e557274a494cc526a3f0e7
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.10.4
|
Release files / pyss3-0.6.5-py3-none-any.whl
| Download URL | pyss3-0.6.5-py3-none-any.whl |
|---|---|
| Size | 1.9 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
59fec943346a10634ff91afdecebb2fccee7b2f33fa5eb9d7f33912ca8f71f99
|
|
BLAKE2b-256 checksum How to use checksums |
73ae67aeba02aefff0678e7b462223435cd72c5d0593b043b8c87a4257a196c3
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.10.4
|
