Scikit-learn
human-activity-recognition
wearable
wrist
time-series
cpu
scikit-learn
File size: 18,106 Bytes
4731b11
 
 
 
 
 
 
 
 
 
 
93a9282
 
4731b11
 
 
 
 
 
 
 
 
 
 
 
 
93a9282
 
 
 
 
 
 
 
 
 
4731b11
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
93a9282
 
 
 
 
 
 
 
4731b11
 
93a9282
4731b11
 
 
 
 
 
 
 
 
 
 
 
 
93a9282
4731b11
 
 
 
 
 
 
93a9282
 
 
4731b11
93a9282
4731b11
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
93a9282
4731b11
 
 
 
 
 
93a9282
 
 
 
 
 
 
 
 
4731b11
 
93a9282
4731b11
93a9282
 
 
4731b11
 
93a9282
 
 
 
4731b11
 
93a9282
 
 
4731b11
93a9282
 
 
 
 
 
 
 
 
4731b11
93a9282
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
4731b11
93a9282
4731b11
93a9282
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
4731b11
 
 
 
93a9282
4731b11
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
93a9282
 
4731b11
 
 
 
 
 
 
 
93a9282
 
 
4731b11
 
 
 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
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
53
54
55
56
57
58
59
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
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
"""WISPClassifier: a WISP recipe as a scikit-learn classifier."""
from __future__ import annotations

import pickle
import time
import warnings

import numpy as np
from sklearn.base import BaseEstimator, ClassifierMixin, clone
from sklearn.utils.validation import check_is_fitted

from . import _adaptive as adaptive
from ._validation import (SEQUENCES, SPEEDS, as_windows, check_aligned, check_choice, check_disjoint_groups,
                          check_input_shape, check_targets, encode_labels, kernel_context)
from .recipes import Recipe, resolve


class WISPClassifier(ClassifierMixin, BaseEstimator):
    """Fit and predict with one WISP recipe.

    Parameters
    ----------
    recipe : str, Recipe or dict, default="cis"
        Catalog name (``"cis"``, ``"cis:RS"``, ``"best:capture24"``; see
        ``wisp.recipes.list()``), a :class:`~wisp.recipes.Recipe`, or a dictionary in the
        ``canonical_recipe`` format.
    decoder : {"adaptive", "recipe", "hmm", "none"}, default="adaptive"
        ``"adaptive"`` decides on validation data whether HMM decoding helps: the same model
        fitted on training windows decodes the validation windows with the HMM and with
        per-window argmax, the HMM is kept only if its validation macro-F1 is strictly higher,
        and the final model is fitted on all fitting data with the chosen decoder. Validation
        data are ``validation`` when given to :meth:`fit`, otherwise a group-wise hold-out of
        ``validation_size`` (default 0.125) of the groups. Without groups, or without
        sequences (no group with two or more windows), the decoder is ``"none"``.
        ``"recipe"`` uses the recipe's own setting (the paper configuration; ``"auto"`` is a
        deprecated alias), ``"hmm"`` forces sequence decoding, ``"none"`` forces argmax.
    readout : scikit-learn classifier or None, default=None
        ``None`` runs the recipe's own readout inside the frozen kernel. Otherwise the
        recipe's representation (:class:`~wisp.WISPRepresentation`) is fed to a clone of this
        estimator, which needs ``fit`` plus ``predict_proba`` or ``decision_function``.
        Only single-readout recipes (SS, RC, SO, GIS, CIS and its subsets) accept a readout.
    classes : array-like or None, default=None
        Global class table. Needed when the training windows miss a class.
    layout : {"NTC", "NCT"}, default="NTC"
        Axis order of the windows: ``(n, T, C)`` or ``(n, C, T)``.
    speed : {"exact", "fast"}, default="exact"
        ``"exact"``: outputs identical to the paper code (docs/SPEED.md). ``"fast"``:
        screened Ridge solver; Ridge readouts can change slightly, other recipes are
        unaffected.
    sequence : {"subject", "recording"}, default="subject"
        How the HMM decoder forms chains (see docs/METHODS.md, "Speed and HMM smoothing
        sequence"). ``"recording"`` needs :meth:`fit_confidence_scale` on validation data.
    n_jobs : int, default=1
        Threads for tree ensembles inside the kernel.
    random_state : int, default=42
        Recipe seed (random kernels, intervals, shapelets and tree seeds).

    Attributes
    ----------
    classes_, recipe_, model_, decoder_, decoder_scores_, decoder_reason_, has_paper_results_,
    fit_seconds_, decision_seconds_, model_size_mb_

    ``decoder_`` is the decoder of the final model (``"hmm"`` or ``"none"``),
    ``decoder_scores_`` the validation macro-F1 with each decoder (``"adaptive"`` only, else
    ``None``) and ``decoder_reason_`` why it was chosen (``"validation"``, ``"no groups"``,
    ``"no sequences"``, ``"fewer than 2 groups"`` or ``"fixed"``). ``decision_seconds_`` is the
    time of the extra fit on the training part used for the decision (0 when none was needed).
    """

    def __init__(self, recipe="cis", *, decoder="adaptive", readout=None, classes=None, layout="NTC",
                 speed="exact", sequence="subject", n_jobs=1, random_state=42):
        self.recipe = recipe
        self.decoder = decoder
        self.readout = readout
        self.classes = classes
        self.layout = layout
        self.speed = speed
        self.sequence = sequence
        self.n_jobs = n_jobs
        self.random_state = random_state

    # ------------------------------------------------------------------ helpers
    def _check_params(self):
        check_choice("decoder", self.decoder, adaptive.DECODERS)
        check_choice("speed", self.speed, SPEEDS)
        check_choice("sequence", self.sequence, SEQUENCES)
        if not isinstance(self.n_jobs, (int, np.integer)) or self.n_jobs < 1:
            raise ValueError("n_jobs must be a positive integer")
        if self.readout is not None and self.sequence != "subject":
            raise ValueError("sequence='recording' is available for the recipe's own readout only")

    def _use_hmm(self, recipe: Recipe, groups, decoder: str) -> bool:
        """Fixed decoders ("recipe", "hmm", "none")."""
        if decoder == "none":
            return False
        if decoder == "hmm":
            if groups is None:
                raise ValueError("decoder='hmm' needs groups (the sequence ID of every window) in fit")
            return True
        if recipe.use_hmm and groups is None:
            warnings.warn("This recipe uses the HMM decoder but fit() received no groups; fitting with "
                          "per-window prediction (decoder='none'). Pass groups (and time_index) to fit "
                          "and predict for sequence decoding, or set decoder='none' to silence this.",
                          UserWarning, stacklevel=3)
            return False
        return recipe.use_hmm

    def _paper_backed(self, recipe: Recipe, use_hmm: bool) -> bool:
        if self.readout is not None or self.speed != "exact" or self.sequence != "subject":
            return False
        if recipe.source in ("fixed", "cis_subset"):
            return ("hmm" if use_hmm else "none") in recipe.provenance.get("paper_ids", {})
        if recipe.source == "search_best":
            return use_hmm == recipe.use_hmm
        return False

    # ------------------------------------------------------------------ API
    def fit(self, X, y, groups=None, time_index=None, validation=None, validation_size=None):
        """Fit on windows ``X`` and labels ``y``.

        groups : array-like of shape (n,), optional
            Sequence (participant or recording) ID of each window; needed for HMM decoding.
        time_index : array-like of shape (n,), optional
            Position of each window within its sequence; row order is used when omitted.
        validation : tuple or array-like, optional
            ``(X_val, y_val, groups_val[, time_val])``, or validation rows of ``X`` (integer
            indices or a boolean mask). Validation windows are part of the fitting data: the
            final model is fitted on training plus validation windows (for a tuple, training
            windows first, as in the paper's train+validation refit). With
            ``decoder="adaptive"`` they also decide the decoder.
        validation_size : float, optional
            ``decoder="adaptive"`` without ``validation``: fraction of the groups held out to
            decide the decoder (default 0.125); the final model is then fitted on all of ``X``.
        """
        self._check_params()
        decoder = adaptive.normalize_decoder(self.decoder)
        recipe = resolve(self.recipe)
        if self.readout is not None and not recipe.single_readout:
            raise ValueError(f"readout replacement needs a single-readout recipe; {recipe.family} "
                             "(WISP-CSE/WISP-ESE) fuses several readouts")
        Xw = as_windows(X, self.layout)
        y = check_targets(self, y)
        if validation is not None and validation_size is not None:
            raise ValueError("Pass either validation or validation_size")
        if len(y) != len(Xw):
            raise ValueError(f"y has {len(y)} labels for {len(Xw)} windows")
        groups = check_aligned("groups", groups, len(Xw))
        time_index = check_aligned("time_index", time_index, len(Xw))
        mode, train, valid = adaptive.parse_validation(Xw, y, groups, time_index, validation, self.layout)
        labels = np.concatenate([np.asarray(y), np.asarray(valid[1])]) if mode == "tuple" else y
        self.classes_, _ = encode_labels(labels, self.classes)
        n_classes = len(self.classes_)
        full = self._encode(adaptive.concat(train, valid) if mode == "tuple" else (Xw, y, groups, time_index))
        scale = None
        self.decision_seconds_ = 0.0
        if decoder == "adaptive":
            decision = (self._holdout(full, validation_size) if mode == "none"
                        else (self._encode(train), self._encode(valid)))
            use_hmm, reason, scores, scale = self._decide(recipe, full, decision)
        else:
            use_hmm, reason, scores = self._use_hmm(recipe, full[2], decoder), adaptive.FIXED, None
        start = time.perf_counter()
        self._fit_final(recipe, full, use_hmm, n_classes)
        if scale is not None and use_hmm and self.readout is None:
            with kernel_context():
                self.model_.set_confidence_scale(scale)
        self.fit_seconds_ = time.perf_counter() - start
        self.recipe_ = recipe
        self.decoder_ = "hmm" if use_hmm else "none"
        self.decoder_scores_ = scores
        self.decoder_reason_ = reason
        self.input_shape_ = Xw.shape[1:]
        self.n_features_in_ = int(np.prod(self.input_shape_))
        self.has_paper_results_ = self._paper_backed(recipe, use_hmm)
        return self

    # ------------------------------------------------------------------ fitting helpers
    def _encode(self, part):
        X, y, g, t = part
        _, codes = encode_labels(y, self.classes_)
        return (X, codes, g, t)

    def _holdout(self, full, validation_size):
        """Group-wise hold-out of the fitting data for the decision, or None when impossible."""
        X, codes, g, t = full
        if g is None:
            return None
        if not adaptive.has_sequences(g):
            return "no sequences"
        if len(np.unique(np.asarray(g))) < 2:
            return "few"
        size = 0.125 if validation_size is None else float(validation_size)
        tr, va = adaptive.group_holdout(len(X), g, size, int(self.random_state))

        def take(a, idx):
            return None if a is None else np.asarray(a)[idx]
        return tuple(take(a, tr) for a in full), tuple(take(a, va) for a in full)

    def _decide(self, recipe, full, decision):
        """``decoder="adaptive"``: (use_hmm, reason, scores, confidence scale)."""
        if full[2] is None or decision is None:
            return False, adaptive.NO_GROUPS, None, None
        if decision == "no sequences":
            return False, adaptive.NO_SEQUENCES, None, None
        if isinstance(decision, str):
            warnings.warn("decoder='adaptive' needs at least 2 groups for a group-wise hold-out; using the "
                          "recipe's own decoder", UserWarning, stacklevel=3)
            return recipe.use_hmm, adaptive.FEW_GROUPS, None, None
        (Xt, yt, gt, tt), (Xv, yv, gv, tv) = decision
        if gt is None or not adaptive.has_sequences(gt):
            return False, (adaptive.NO_GROUPS if gt is None else adaptive.NO_SEQUENCES), None, None
        if gv is None:
            raise ValueError("decoder='adaptive' needs groups for the validation windows")
        check_disjoint_groups(gt, gv)
        start = time.perf_counter()
        n_classes = len(self.classes_)
        scale = None
        if self.readout is None:
            model = self._kernel(recipe, True)
            with kernel_context():
                model.fit(Xt, yt, groups=gt, time_index=tt, n_classes=n_classes)
                P = model.predict_proba(Xv)
                if self.sequence == "recording":
                    model.fit_confidence_scale(Xv, yv)
                    scale = model.confidence_scale
                hmm = adaptive.hmm_labels(model, P, gv, tv)
        else:
            from wisp.cpu.hmm import TransitionSmoother
            from wisp.cpu.probability import estimator_proba
            rep, readout = self._fit_readout(recipe, Xt, yt)
            with kernel_context():
                P = estimator_proba(readout, rep.transform(Xv), np.arange(n_classes))
            smoother = TransitionSmoother().fit(yt, groups=gt, time_index=tt, n_classes=n_classes)
            hmm = smoother.predict_from_proba(P, groups=gv, time_index=tv)
        choice, scores = adaptive.compare(yv, hmm, adaptive.argmax_labels(P), n_classes)
        self.decision_seconds_ = time.perf_counter() - start
        return choice == "hmm", adaptive.VALIDATION, scores, scale

    def _kernel(self, recipe, use_hmm):
        from ._engine import build_kernel
        return build_kernel(recipe, use_hmm=use_hmm, speed=self.speed, sequence=self.sequence,
                            seed=int(self.random_state), n_jobs=int(self.n_jobs))

    def _fit_readout(self, recipe, X, codes):
        from .representation import WISPRepresentation
        rep = WISPRepresentation(recipe, layout="NTC", random_state=int(self.random_state))
        with kernel_context():
            Z = rep.fit_transform(X)
        readout = clone(self.readout).fit(Z, codes)
        if not (hasattr(readout, "predict_proba") or hasattr(readout, "decision_function")):
            raise ValueError("readout must provide predict_proba or decision_function")
        return rep, readout

    def _fit_final(self, recipe, full, use_hmm, n_classes):
        X, codes, groups, time_index = full
        if self.readout is None:
            model = self._kernel(recipe, use_hmm)
            with kernel_context():
                model.fit(X, codes, groups=groups, time_index=time_index, n_classes=n_classes)
            self.model_ = model
            self.representation_ = self.readout_ = self.smoother_ = None
        else:
            from wisp.cpu.hmm import TransitionSmoother
            rep, readout = self._fit_readout(recipe, X, codes)
            self.representation_, self.readout_ = rep, readout
            self.smoother_ = (TransitionSmoother().fit(codes, groups=groups, time_index=time_index,
                                                       n_classes=n_classes) if use_hmm else None)
            self.model_ = readout

    @property
    def model_size_mb_(self) -> float:
        """Size of the fitted model in MB (default-protocol pickle, as the paper's size column)."""
        check_is_fitted(self, "model_")
        obj = self.model_ if self.readout is None else (self.representation_, self.readout_, self.smoother_)
        return len(pickle.dumps(obj)) / (1024.0 * 1024.0)

    def _windows(self, X):
        check_is_fitted(self, "model_")
        Xw = as_windows(X, self.layout)
        check_input_shape(self, X, Xw)
        return Xw

    def _scores(self, Xw):
        if self.readout is None:
            with kernel_context():
                return self.model_.predict_proba(Xw)
        from wisp.cpu.probability import estimator_proba
        with kernel_context():
            Z = self.representation_.transform(Xw)
        return estimator_proba(self.readout_, Z, np.arange(len(self.classes_)))

    def predict_proba(self, X):
        """Per-window class scores in ``classes_`` order (never HMM-smoothed)."""
        return self._scores(self._windows(X))

    def predict(self, X, groups=None, time_index=None):
        """Labels. With ``groups`` and an active decoder, each sequence is HMM-decoded;
        without ``groups`` every window is classified independently (argmax)."""
        Xw = self._windows(X)
        groups = check_aligned("groups", groups, len(Xw))
        time_index = check_aligned("time_index", time_index, len(Xw))
        if self.readout is None:
            with kernel_context():
                codes = self.model_.predict(Xw, groups=groups, time_index=time_index)
        else:
            P = self._scores(Xw)
            if self.smoother_ is not None and groups is not None:
                codes = self.smoother_.predict_from_proba(P, groups=groups, time_index=time_index)
            else:
                codes = np.argmax(P, axis=1)
        return self.classes_[np.asarray(codes, dtype=np.int64)]

    def fit_confidence_scale(self, X_valid, y_valid):
        """``sequence="recording"`` only: choose the confidence scaling on validation windows."""
        check_is_fitted(self, "model_")
        if self.readout is not None:
            raise ValueError("Confidence scaling applies to the recipe's own readout")
        _, codes = encode_labels(y_valid, self.classes_)
        with kernel_context():
            self.model_.fit_confidence_scale(self._windows(X_valid), codes)
        return self

    @property
    def confidence_scale_(self):
        check_is_fitted(self, "model_")
        return getattr(self.model_, "confidence_scale", None)

    def __sklearn_tags__(self):
        tags = super().__sklearn_tags__()
        tags.input_tags.three_d_array = True
        return tags

    # used by WISPSelect / WISPSearch to adopt an already fitted kernel object
    def _adopt(self, model, *, classes, input_shape, use_hmm, fit_seconds, reason=adaptive.FIXED,
               scores=None, decision_seconds=0.0):
        self._check_params()
        recipe = resolve(self.recipe)
        self.classes_ = np.asarray(classes)
        self.model_ = model
        self.representation_ = self.readout_ = self.smoother_ = None
        self.fit_seconds_ = float(fit_seconds)
        self.recipe_ = recipe
        self.decoder_ = "hmm" if use_hmm else "none"
        self.decoder_scores_ = scores
        self.decoder_reason_ = reason
        self.decision_seconds_ = float(decision_seconds)
        self.input_shape_ = tuple(input_shape)
        self.n_features_in_ = int(np.prod(self.input_shape_))
        self.has_paper_results_ = self._paper_backed(recipe, use_hmm)
        return self