PySS3 Logo

Documentation Status Build Status codecov PyPI version Downloads Binder

PySS3: Interpretable Machine Learning for Text Classification (Try our Live Demo! :cake:)


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:

:point_right: 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.

:point_right: 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)

img

Try our online live demos:

:point_right: 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

img

Explore example evaluation plots:

Getting Started :eyeglasses: :coffee:

Installation

pip install pyss3

Full tutorial and documentation

Contributing :sparkles::octocat::sparkles:

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 :muscle::sunglasses::+1:

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 :scroll:

Full documentation

API documentation

Paper preprint

Project links

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for sergioburdisso from gravatar.com sergioburdisso

Credits

Maintainer: Sergio Burdisso

License

MIT License (MIT License)

Requires

Python >=2.7

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

pyss3-0.6.5.tar.gz (1.9 MB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

pyss3-0.6.5-py3-none-any.whl (1.9 MB view details)

Uploaded Python 3

File details

Details for the file pyss3-0.6.5.tar.gz.

File metadata

  • Download URL: pyss3-0.6.5.tar.gz
  • Upload date:
  • Size: 1.9 MB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.2.0 CPython/3.10.4

File hashes

Hashes for pyss3-0.6.5.tar.gz
Algorithm Hash digest
SHA256 926d8ca13f380f3f9a60997222f910d7d413e7396dc886f1b5999857cb10a2f6
MD5 7dcb23caa4fdfd848e2057be6852b2e3
BLAKE2b-256 90809d77df7831cd3294678df64658c3b4007c4317e557274a494cc526a3f0e7

See more details on using hashes here.

File details

Details for the file pyss3-0.6.5-py3-none-any.whl.

File metadata

  • Download URL: pyss3-0.6.5-py3-none-any.whl
  • Upload date:
  • Size: 1.9 MB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.2.0 CPython/3.10.4

File hashes

Hashes for pyss3-0.6.5-py3-none-any.whl
Algorithm Hash digest
SHA256 59fec943346a10634ff91afdecebb2fccee7b2f33fa5eb9d7f33912ca8f71f99
MD5 854a337854960523bfba974c82f6d58a
BLAKE2b-256 73ae67aeba02aefff0678e7b462223435cd72c5d0593b043b8c87a4257a196c3

See more details on using hashes here.

Release history Release notifications | RSS feed

This release

0.6.5 This release

2 files

0.6.4

2 files

0.6.3

2 files

0.6.2

2 files

0.6.1

2 files

0.6.0

2 files

0.5.9

2 files

0.5.8

2 files

0.5.7

2 files

0.5.6

2 files

0.5.5

2 files

0.5.4

2 files

0.5.3

2 files

0.5.2

2 files

0.5.1

2 files

0.5.0

2 files

0.4.1

2 files

0.4.0

2 files

0.3.9.2

2 files

0.3.9.1

2 files

0.3.9

2 files

0.3.8

2 files

0.3.7

2 files

0.3.6

2 files

0.3.5

2 files

0.3.4

2 files

0.3.3

2 files

0.3.2

2 files

0.3.0

2 files

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page