28. Skip to content

28. Supervised API

This page documents supervised baseline APIs. For CLI usage, see the CLI reference.

28.1 What it is for

The supervised brick exposes baseline classifiers with multiple backends (numpy, sklearn, torch). [1][2]

28.2 Examples

List classifiers and backends:

from modssc.supervised import available_classifiers

print(available_classifiers())

Create a classifier (auto backend):

from modssc.supervised import create_classifier

clf = create_classifier("knn", backend="numpy", params={"k": 3})

Backends and metadata are defined in src/modssc/supervised/registry.py. [2]

28.3 API reference

Supervised baselines for ModSSC.

This brick provides classic supervised classifiers used as baselines in SSL papers. It is designed to be backend-agnostic (numpy, scikit-learn, torch, etc.).

28.4 available_classifiers(*, available_only=False)

List classifiers and their backends.

28.4.0.1 Parameters

available_only: If True, filter out backends whose required module is not importable.

Source code in src/modssc/supervised/api.py 
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
def available_classifiers(*, available_only: bool = False) -> list[dict[str, Any]]:
    """List classifiers and their backends.

    Parameters
    ----------
    available_only:
        If True, filter out backends whose required module is not importable.
    """
    out: list[dict[str, Any]] = []
    for spec in iter_specs():
        d = spec.to_dict()
        if available_only:
            backends = {}
            for b, bs in d["backends"].items():
                extra = bs.get("required_extra")
                if extra is None:
                    backends[b] = bs
                    continue
                extra_to_module = {
                    "sklearn": "sklearn",
                    "vision": "torchvision",
                    "audio": "torchaudio",
                    "preprocess-text": "transformers",
                }
                module = extra_to_module.get(extra, extra)
                if extra.endswith("-torch"):
                    module = "torch"
                if has_module(module):
                    backends[b] = bs
            d["backends"] = backends
        out.append(d)
    return out

28.5 create_classifier(classifier_id, *, backend='auto', params=None, runtime=None)

Instantiate a classifier.

28.5.0.1 Notes

  • backend="auto" selects the first available backend from preferred_backends.
  • params are passed to the backend constructor (after runtime injection).
Source code in src/modssc/supervised/api.py 
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
def create_classifier(
    classifier_id: str,
    *,
    backend: str = "auto",
    params: dict[str, Any] | None = None,
    runtime: ClassifierRuntime | None = None,
) -> Any:
    """Instantiate a classifier.

    Notes
    -----
    - backend="auto" selects the first available backend from preferred_backends.
    - params are passed to the backend constructor (after runtime injection).
    """
    spec = get_spec(classifier_id)
    params = dict(params or {})
    runtime = runtime or ClassifierRuntime()

    chosen_backend: str
    if backend == "auto":
        chosen_backend = ""
        for b in spec.preferred_backends:
            if b not in spec.backends:
                continue
            bs = spec.backends[b]
            if bs.required_extra is None:
                chosen_backend = b
                break
            module = "sklearn" if bs.required_extra == "sklearn" else bs.required_extra
            if bs.required_extra and bs.required_extra.endswith("-torch"):
                module = "torch"
            if has_module(module):
                chosen_backend = b
                break
        if not chosen_backend:
            # no backend available, raise based on first preferred backend
            first = spec.preferred_backends[0] if spec.preferred_backends else "unknown"
            if first in spec.backends and spec.backends[first].required_extra:
                raise OptionalDependencyError(
                    extra=str(spec.backends[first].required_extra),
                    feature=f"supervised:{classifier_id}",
                )
            raise UnknownBackendError(classifier_id, "auto")
    else:
        chosen_backend = backend

    bs = get_backend_spec(classifier_id, chosen_backend)

    # runtime injection (do not override explicit params)
    if "seed" not in params and runtime.seed is not None:
        params["seed"] = int(runtime.seed)
    if "n_jobs" not in params and runtime.n_jobs is not None:
        params["n_jobs"] = int(runtime.n_jobs)

    cls = _load_object(bs.factory)
    return cls(**params)
Sources
  1. src/modssc/supervised/api.py
  2. src/modssc/supervised/registry.py