Scikit-learn
human-activity-recognition
wearable
wrist
time-series
cpu
scikit-learn
File size: 8,047 Bytes
93a9282
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
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
"""The adaptive HMM switch (``decoder="adaptive"``) and the validation-data handling it shares.

Decision rule. The same fitted model decodes the validation windows twice: with the HMM
(offline Viterbi per group) and with per-window argmax. The HMM is kept only when its
validation macro-F1 is strictly higher; a tie gives ``"none"``. The final model is then fitted
on all fitting data with the chosen decoder, so it is the fixed-decoder model with that setting.

Decision data: an explicit validation set when one is given, otherwise a group-wise hold-out of
the training windows (``validation_size``, default 0.125, ``GroupShuffleSplit`` seeded with
``random_state``, as in WISPSelect/WISPSearch). Test data are never used.

Edge cases:

* no ``groups``: the HMM is unavailable, the decoder is ``"none"`` (reason ``"no groups"``);
* no sequences: when no training group has two or more windows the HMM has no transitions to
  learn, and decoding a one-window sequence gives ``argmax_k(prior_k * P_k)`` (``prior_k`` is the
  class frequency in the training labels). That is prior reweighting, not sequence smoothing,
  so the decoder is ``"none"`` (reason ``"no sequences"``);
* fewer than two groups, so no group-wise hold-out is possible: the recipe's own decoder is used
  with a warning (reason ``"fewer than 2 groups"``).

Reasons recorded in ``decoder_reason_``: ``"validation"``, ``"no groups"``, ``"no sequences"``,
``"fewer than 2 groups"`` and ``"fixed"`` (a decoder other than ``"adaptive"`` was requested).
"""
from __future__ import annotations

import warnings
from dataclasses import dataclass
from typing import Any

import numpy as np

from ._validation import as_windows, check_aligned

DECODERS = ("adaptive", "recipe", "hmm", "none", "auto")

VALIDATION = "validation"
FIXED = "fixed"
NO_GROUPS = "no groups"
NO_SEQUENCES = "no sequences"
FEW_GROUPS = "fewer than 2 groups"


def normalize_decoder(value: Any) -> str:
    """Check ``decoder`` and map the deprecated alias ``"auto"`` to ``"recipe"``."""
    if value not in DECODERS:
        raise ValueError(f"decoder must be one of {', '.join(map(repr, DECODERS[:4]))}; got {value!r}")
    if value == "auto":
        warnings.warn("decoder='auto' is deprecated and will be removed; use decoder='recipe' (same meaning: "
                      "the recipe's own decoder setting)", FutureWarning, stacklevel=3)
        return "recipe"
    return value


def has_sequences(groups: Any) -> bool:
    """True when at least one group has two or more windows."""
    if groups is None:
        return False
    _, counts = np.unique(np.asarray(groups), return_counts=True)
    return bool(counts.size and counts.max() >= 2)


def macro_f1(y_true: Any, y_pred: Any, n_classes: int) -> float:
    """Validation macro-F1 with the benchmark scorer (``wisp_release.scoring.score``)."""
    from wisp_release.scoring import score
    return float(score(np.asarray(y_true, dtype=np.int64), np.asarray(y_pred, dtype=np.int64), int(n_classes))["macro_f1"])


def compare(y_true: Any, hmm_pred: Any, none_pred: Any, n_classes: int) -> tuple[str, dict[str, float]]:
    """The decision rule: keep the HMM only if its macro-F1 is strictly higher."""
    scores = {"hmm": macro_f1(y_true, hmm_pred, n_classes), "none": macro_f1(y_true, none_pred, n_classes)}
    return ("hmm" if scores["hmm"] > scores["none"] else "none"), scores


def hmm_labels(model: Any, proba: np.ndarray, groups: Any, time_index: Any) -> np.ndarray:
    """HMM-decoded labels of a fitted kernel model with a smoother, from its probabilities."""
    if hasattr(model, "decode_proba"):
        return np.asarray(model.decode_proba(proba, groups=groups, time_index=time_index))
    smoother = getattr(model, "smoother_", None)
    if smoother is None:
        raise RuntimeError("the decision model has no HMM smoother")
    return np.asarray(smoother.predict_from_proba(proba, groups=groups, time_index=time_index))


def argmax_labels(proba: np.ndarray) -> np.ndarray:
    return np.argmax(np.asarray(proba, dtype=np.float64), axis=1).astype(np.int64)


@dataclass
class Split:
    """Fitting data and decision data.

    ``train``/``valid`` hold ``(X, y, groups, time_index)``. ``full`` is all fitting data in
    the order the final model is fitted on: training then validation windows for an explicit
    validation tuple, the original rows of ``X`` otherwise. ``valid`` is ``None`` when no
    hold-out is possible or needed.
    """
    mode: str
    train: tuple
    valid: tuple | None
    full: tuple


def _rows_mask(validation: Any, n: int) -> np.ndarray | None:
    """A 1-D boolean mask or integer row indices of ``X`` given as ``validation``."""
    if isinstance(validation, (tuple, list)):
        return None
    arr = np.asarray(validation)
    if arr.ndim != 1:
        return None
    if arr.dtype == bool:
        if arr.shape != (n,):
            raise ValueError(f"a boolean validation mask needs one entry per window ({n})")
        mask = arr.copy()
    elif np.issubdtype(arr.dtype, np.integer):
        if arr.size and (arr.min() < -n or arr.max() >= n):
            raise ValueError("validation row indices fall outside X")
        mask = np.zeros(n, dtype=bool)
        mask[arr] = True
    else:
        return None
    if not mask.any() or mask.all():
        raise ValueError("validation rows must leave both training and validation windows")
    return mask


def parse_validation(Xw: np.ndarray, y: np.ndarray, groups: Any, time_index: Any, validation: Any,
                     layout: str) -> tuple[str, tuple, tuple | None]:
    """Explicit validation data: a tuple ``(X_val, y_val, groups_val[, time_val])`` or rows of ``X``.

    Returns ``(mode, train, valid)`` with mode ``"tuple"``, ``"rows"`` or ``"none"``.
    """
    if validation is None:
        return "none", (Xw, y, groups, time_index), None
    mask = _rows_mask(validation, len(Xw))
    if mask is not None:
        def take(a, m):
            return None if a is None else a[m]
        train = (Xw[~mask], y[~mask], take(groups, ~mask), take(time_index, ~mask))
        valid = (Xw[mask], y[mask], take(groups, mask), take(time_index, mask))
        return "rows", train, valid
    if not isinstance(validation, (tuple, list)) or len(validation) not in (3, 4):
        raise ValueError("validation must be (X_val, y_val, groups_val), (X_val, y_val, groups_val, time_val), "
                         "or validation rows of X (integer indices or a boolean mask)")
    Xv = as_windows(validation[0], layout)
    yv = np.asarray(validation[1])
    gv = check_aligned("validation groups", validation[2], len(Xv))
    tv = check_aligned("validation time_index", validation[3] if len(validation) == 4 else None, len(Xv))
    if len(yv) != len(Xv):
        raise ValueError("validation labels and windows differ in length")
    if Xv.shape[1:] != Xw.shape[1:]:
        raise ValueError("training and validation windows must share (T, C)")
    return "tuple", (Xw, y, groups, time_index), (Xv, yv, gv, tv)


def group_holdout(n: int, groups: Any, size: float, random_state: int) -> tuple[np.ndarray, np.ndarray]:
    """Group-wise hold-out (the splitter and seed handling of WISPSelect/WISPSearch)."""
    from sklearn.model_selection import GroupShuffleSplit
    if not 0 < size < 1:
        raise ValueError("validation_size must be in (0, 1)")
    split = GroupShuffleSplit(n_splits=1, test_size=size, random_state=int(random_state))
    tr, va = next(split.split(np.zeros((n, 1)), np.zeros(n), groups))
    return tr, va


def concat(a: tuple, b: tuple) -> tuple:
    """Training then validation windows (the paper's train+validation order)."""
    out = []
    for u, v in zip(a, b):
        if u is None or v is None:
            out.append(None if (u is None and v is None) else _fill(u, v))
        else:
            out.append(np.concatenate([np.asarray(u), np.asarray(v)]))
    return tuple(out)


def _fill(u, v):
    # one side has no time_index: the kernel then uses row order, so pass none at all
    return None