Instructions to use Zipeng365/WISP with libraries, inference providers, notebooks, and local apps. Follow these links to get started.
- Libraries
- Scikit-learn
How to use Zipeng365/WISP with Scikit-learn:
from huggingface_hub import hf_hub_download import joblib model = joblib.load( hf_hub_download("Zipeng365/WISP", "sklearn_model.joblib") ) # only load pickle files from sources you trust # read more about it here https://skops.readthedocs.io/en/stable/persistence.html - Notebooks
- Google Colab
- Kaggle
Download src/wisp/recipes.py from Zipeng365/WISP: direct link, hf CLI and curl.
- Browser
- Download file 12.7 kB
-
https://huggingface.co/Zipeng365/WISP/resolve/main/src/wisp/recipes.py
- Command line
-
hf download hf://Zipeng365/WISP/src/wisp/recipes.py
-
curl -L -o recipes.py https://huggingface.co/Zipeng365/WISP/resolve/main/src/wisp/recipes.py
12.7 kB
| """Recipe descriptions and the catalog of recipes that have saved results. | |
| A :class:`Recipe` is an immutable description of one WISP configuration. Its dictionary | |
| form is the ``canonical_recipe`` format of ``results/search_selections.csv``:: | |
| {"name": "state_rocket_interval_hmm", | |
| "params": {"classifier": "ridge", "n_intervals": 24, "n_kernels": 384, "use_hmm": true}, | |
| "route": "cpu"} | |
| The catalog (``list``/``get``/``best``) only contains recipes with rows in the saved | |
| result files: the seven fixed families, the six CIS block subsets (plus ``"cis:RIS"``, | |
| which is ``"cis"``) and one search best recipe per data stream. ``search_runs()`` exposes | |
| the 360 per-search final recipes for checking where ``best`` comes from; they are not | |
| catalog entries. | |
| """ | |
| from __future__ import annotations | |
| import csv | |
| import json | |
| from functools import lru_cache | |
| from importlib import resources | |
| from typing import Any | |
| __all__ = ["Recipe", "list", "get", "best", "search_runs", "resolve", "dataset_id", "FAMILIES"] | |
| _list = list # the module defines ``list()``; keep the builtin reachable | |
| #: The seven kernel family names (``name`` in the canonical recipe format). | |
| FAMILIES = ("har_sculpt_forest_hmm", "rocket_sketch_ridge_hmm", "symbolic_interval_forest", | |
| "hybrid_cpu_ensemble", "invariant_interval_shape_forest", "state_rocket_interval_hmm", | |
| "posterior_cpu_ensemble") | |
| #: Families whose recipe has one feature vector and one readout. | |
| SINGLE_READOUT = ("har_sculpt_forest_hmm", "rocket_sketch_ridge_hmm", "symbolic_interval_forest", | |
| "invariant_interval_shape_forest", "state_rocket_interval_hmm") | |
| _CODE_CLASS_TO_FAMILY = { | |
| "HarSculptForestHMM": "har_sculpt_forest_hmm", "RocketSketchRidgeHMM": "rocket_sketch_ridge_hmm", | |
| "SymbolicIntervalForest": "symbolic_interval_forest", "HybridCPUEnsemble": "hybrid_cpu_ensemble", | |
| "InvariantIntervalShapeForest": "invariant_interval_shape_forest", | |
| "StateRocketIntervalHMM": "state_rocket_interval_hmm", "PosteriorCPUEnsemble": "posterior_cpu_ensemble", | |
| } | |
| _FIXED_SHORT = {"wisp_ss": "ss", "wisp_rc": "rc", "wisp_so": "so", "wisp_cse": "cse", "wisp_gis": "gis", | |
| "wisp_cis": "cis", "wisp_ese": "ese"} | |
| _RUNTIME_KEYS = ("seed", "n_jobs") | |
| def _freeze(value: Any) -> Any: | |
| """Top-level dict -> sorted item tuple; nested lists -> tuples (kernel convention).""" | |
| def seq(v): | |
| if isinstance(v, (_list, tuple)): | |
| return tuple(seq(x) for x in v) | |
| if hasattr(v, "item") and not isinstance(v, (str, bytes)): | |
| return v.item() | |
| return v | |
| return tuple(sorted((k, seq(v)) for k, v in value.items())) | |
| def _jsonable(value: Any) -> Any: | |
| if isinstance(value, tuple): | |
| return [_jsonable(v) for v in value] | |
| if isinstance(value, dict): | |
| return {k: _jsonable(v) for k, v in value.items()} | |
| return value | |
| class Recipe: | |
| """Immutable recipe: kernel family plus parameters, with catalog metadata. | |
| ``Recipe("state_rocket_interval_hmm", {"n_kernels": 128, "use_hmm": True})`` makes a | |
| custom recipe. ``params`` never contains the runtime keys ``seed`` or ``n_jobs``; the | |
| estimator's ``random_state`` and ``n_jobs`` supply them. | |
| """ | |
| __slots__ = ("family", "_params", "id", "paper_name", "source", "_provenance") | |
| def __init__(self, family: str, params: dict | None = None, *, id: str | None = None, | |
| paper_name: str | None = None, source: str = "custom", provenance: dict | None = None): | |
| if family not in FAMILIES: | |
| raise ValueError(f"Unknown WISP family {family!r}; expected one of {', '.join(FAMILIES)}") | |
| clean = {str(k): v for k, v in dict(params or {}).items() if k not in _RUNTIME_KEYS} | |
| for name, value in (("family", str(family)), ("_params", _freeze(clean)), ("id", id), | |
| ("paper_name", paper_name), ("source", str(source)), | |
| ("_provenance", json.dumps(provenance or {}, sort_keys=True, default=str))): | |
| object.__setattr__(self, name, value) | |
| def __setattr__(self, name, value): | |
| raise AttributeError("Recipe is immutable; use with_params() to derive a custom recipe") | |
| def __reduce__(self): | |
| return (_rebuild, (self.family, self.params, self.id, self.paper_name, self.source, self.provenance)) | |
| def _key(self): | |
| return (self.family, self._params, self.id, self.source) | |
| def __eq__(self, other): | |
| return isinstance(other, Recipe) and self._key() == other._key() | |
| def __hash__(self): | |
| return hash(self._key()) | |
| def __repr__(self): | |
| label = f"id={self.id!r}, " if self.id else "" | |
| return f"Recipe({label}family={self.family!r}, params={self.to_dict()['params']!r}, source={self.source!r})" | |
| # ---- views ---- | |
| def params(self) -> dict[str, Any]: | |
| """Parameters passed to the kernel family (sequences as tuples); a fresh copy.""" | |
| return {k: v for k, v in self._params} | |
| def provenance(self) -> dict[str, Any]: | |
| return json.loads(self._provenance) | |
| def use_hmm(self) -> bool: | |
| return bool(self.params.get("use_hmm", True)) | |
| def single_readout(self) -> bool: | |
| return self.family in SINGLE_READOUT | |
| def in_catalog(self) -> bool: | |
| return self.source in ("fixed", "cis_subset", "search_best") | |
| # ---- canonical dictionary / JSON ---- | |
| def to_dict(self) -> dict[str, Any]: | |
| """Canonical ``{"name", "params", "route"}`` form used by ``search_selections.csv``.""" | |
| return {"name": self.family, "params": _jsonable(dict(sorted(self.params.items()))), "route": "cpu"} | |
| def from_dict(cls, d: dict[str, Any]) -> "Recipe": | |
| if not isinstance(d, dict) or "name" not in d: | |
| raise ValueError("A recipe dictionary needs at least 'name' (and usually 'params')") | |
| if d.get("route", "cpu") != "cpu": | |
| raise ValueError("Only CPU recipes exist in this package") | |
| return cls(str(d["name"]), d.get("params", {})) | |
| def to_json(self) -> str: | |
| return json.dumps(self.to_dict(), sort_keys=True, separators=(",", ":")) | |
| def from_json(cls, text: str) -> "Recipe": | |
| return cls.from_dict(json.loads(text)) | |
| def with_params(self, **changes) -> "Recipe": | |
| """A custom (non-catalog) copy with some parameters changed.""" | |
| return Recipe(self.family, {**self.params, **changes}) | |
| def kernel_spec(self, *, seed: int, n_jobs: int) -> dict[str, Any]: | |
| """Spec for ``build_cpu_estimator`` with the runtime keys added.""" | |
| params = self.params | |
| params.update(seed=int(seed), n_jobs=int(n_jobs)) | |
| return {"name": self.family, "params": params, "route": "cpu"} | |
| def describe(self) -> dict[str, Any]: | |
| return {"id": self.id, "paper_name": self.paper_name, "source": self.source, **self.to_dict(), | |
| "provenance": self.provenance} | |
| def _rebuild(family, params, id, paper_name, source, provenance): | |
| return Recipe(family, params, id=id, paper_name=paper_name, source=source, provenance=provenance) | |
| # --------------------------------------------------------------------------- catalog | |
| def _data_text(name: str) -> str: | |
| return resources.files("wisp").joinpath("_data", name).read_text(encoding="utf-8") | |
| def _aliases() -> dict[str, str]: | |
| return json.loads(_data_text("dataset_aliases.json")) | |
| def dataset_id(name: str) -> str: | |
| """Map a short stream name (``"capture24"``) or full ID to the full dataset ID.""" | |
| ids = set(_aliases().values()) | |
| key = str(name).strip().lower().replace("-", "_") | |
| if key in ids: | |
| return key | |
| if key in _aliases(): | |
| return _aliases()[key] | |
| raise KeyError(f"Unknown data stream {name!r}; expected one of {sorted(_aliases())} or {sorted(ids)}") | |
| def _catalog() -> dict[str, Recipe]: | |
| from wisp.ablations import CIS_ABLATIONS | |
| from wisp.registry import list_specs | |
| out: dict[str, Recipe] = {} | |
| for spec in list_specs(): | |
| rid = _FIXED_SHORT[spec.method_id] | |
| out[rid] = Recipe(_CODE_CLASS_TO_FAMILY[spec.code_class], dict(spec.params), id=rid, | |
| paper_name=spec.paper_name, source="fixed", | |
| provenance={"method_id": spec.method_id, "results": "results/run_results.csv", | |
| "paper_ids": {"hmm": spec.method_id, | |
| **({"none": "cis_ablation_RIS_direct"} | |
| if spec.method_id == "wisp_cis" else {})}}) | |
| for spec in CIS_ABLATIONS: | |
| if not spec.use_hmm or spec.component_tag == "RIS": | |
| continue | |
| cand = spec.to_candidate(seed=0, n_jobs=1) | |
| rid = f"cis:{spec.component_tag}" | |
| out[rid] = Recipe(cand.name, cand.params, id=rid, paper_name=f"WISP-CIS block subset {spec.component_tag}", | |
| source="cis_subset", | |
| provenance={"component_tag": spec.component_tag, | |
| "results": "results/cis_and_budget_runs.csv", | |
| "paper_ids": {"hmm": f"cis_ablation_{spec.component_tag}_viterbi", | |
| "none": f"cis_ablation_{spec.component_tag}_direct"}}) | |
| for row in json.loads(_data_text("search_best.json")): | |
| out[row["id"]] = Recipe(row["family"], row["params"], id=row["id"], paper_name=row["paper_name"], | |
| source="search_best", provenance=row["provenance"]) | |
| return out | |
| def get(name: str) -> Recipe: | |
| """Catalog recipe by name: ``"cis"``, ``"cis:RS"``, ``"best:capture24"`` (``"cis:RIS"`` is ``"cis"``).""" | |
| key = str(name).strip() | |
| low = key.lower() | |
| if low.startswith("best:"): | |
| return best(key.split(":", 1)[1]) | |
| if low.startswith("cis:"): | |
| tags = key.split(":", 1)[1].strip().upper() | |
| if tags and not set(tags) - set("RIS") and len(set(tags)) == len(tags): | |
| tags = "".join(c for c in "RIS" if c in tags) | |
| low = "cis" if tags == "RIS" else f"cis:{tags}" | |
| try: | |
| return _catalog()[low] | |
| except KeyError: | |
| raise KeyError(f"Unknown recipe {name!r}. Catalog: {', '.join(sorted(_catalog()))}") from None | |
| def best(stream: str) -> Recipe: | |
| """The search's best recipe on one data stream (see docs/RECIPES.md for the rule).""" | |
| full = dataset_id(stream) | |
| for recipe in _catalog().values(): | |
| if recipe.source == "search_best" and recipe.provenance.get("dataset_id") == full: | |
| return recipe | |
| raise KeyError(f"No search best recipe for {stream!r}") | |
| def list(source: str | None = None): | |
| """Table of all catalog recipes (a pandas DataFrame when pandas is installed, else a list of dicts).""" | |
| rows = [] | |
| for rid, r in _catalog().items(): | |
| if source is not None and r.source != source: | |
| continue | |
| prov = r.provenance | |
| rows.append({"id": rid, "paper_name": r.paper_name, "source": r.source, "family": r.family, | |
| "params": json.dumps(r.to_dict()["params"], sort_keys=True), "use_hmm": r.use_hmm, | |
| "single_readout": r.single_readout, | |
| "results": prov.get("results", prov.get("source_file")), | |
| "selected": prov.get("selected"), "folds_covered": prov.get("folds_covered"), | |
| "same_as": prov.get("same_as")}) | |
| try: | |
| import pandas as pd | |
| except ImportError: | |
| return rows | |
| return pd.DataFrame(rows) | |
| def search_runs(): | |
| """The 360 final recipes of the budget-329 searches (read-only; for checking ``best``).""" | |
| rows = [] | |
| reader = csv.DictReader(_data_text("search_selections.csv").splitlines()) | |
| for row in reader: | |
| if int(float(row["budget"])) == 329: | |
| rows.append({k: row[k] for k in ("method_id", "dataset_id", "fold", "model_seed", "candidate_id", | |
| "family", "use_hmm", "canonical_recipe")}) | |
| try: | |
| import pandas as pd | |
| except ImportError: | |
| return rows | |
| return pd.DataFrame(rows) | |
| def resolve(recipe: Any) -> Recipe: | |
| """Accept a catalog name, a :class:`Recipe` or a canonical-format dictionary.""" | |
| if isinstance(recipe, Recipe): | |
| return recipe | |
| if isinstance(recipe, str): | |
| return get(recipe) | |
| if isinstance(recipe, dict): | |
| return Recipe.from_dict(recipe) | |
| raise TypeError(f"recipe must be a catalog name, a Recipe or a dict; got {type(recipe).__name__}") | |