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

September 4, 2025 · View on GitHub

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)

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()