instancespace.model

Data about the output of running InstanceSpace.

DEFAULT_DIRECTORY_NAME = 'output'

class ModelSignatureError(builtins.Exception):

A Model file's signature could not be verified, or its presence is invalid.

Covers a mismatched signature, a missing signature when secret_key was given, and a present signature when secret_key was not given (the downgrade-attack case - see Model.load()).

@dataclass(frozen=True)

class Model:

The output of running InstanceSpace.

data: instancespace.data.model.Data

data_dense: instancespace.data.model.DataDense | None

feat_sel: instancespace.data.model.FeatSel

prelim: instancespace.data.model.PrelimOut

sifted: instancespace.data.model.SiftedOut

pilot: instancespace.data.model.PilotOut

cloister: instancespace.data.model.CloisterOut

pythia: instancespace.data.model.PythiaOut

trace: instancespace.data.model.TraceOut

opts: instancespace.InstanceSpaceOptions

stage_options: dict[str, dict[str, typing.Any]]

preprocessing_features: tuple[str, ...] | None = None

@classmethod

def from_stage_runner_output( cls: type[~T], stage_runner_output: dict[str, typing.Any], options: instancespace.InstanceSpaceOptions) -> ~T:

Initialize a Model object from the output of an InstanceSpace StageRunner.

Parameters

cls (type[T]): The class.
stage_runner_output (dict[str, Any]): The output of the StageRunner for an InstanceSpace.
options (InstanceSpaceOptions): The options that built the instance space.

Returns

Model: The Model object.

def save(self, path: pathlib.Path | str, secret_key: bytes | None = None) -> None:

Serialise this Model to path via joblib, mirroring MATLAB's persistence.

Trained scikit-learn/shapely objects (PYTHIA's classifiers, TRACE's footprint polygons) round-trip natively - no flattening step.

If secret_key is given, an HMAC-SHA256 signature of the serialised bytes is written alongside the model at <path>.sig, and load() will refuse to deserialise unless the same key verifies it. If secret_key is None (the default - the local/desktop-development case with no server-managed secret), no signature is written and load() performs no verification, the same trust caveat any other unsigned pickle/joblib file already carries.

On the production web platform, every server code path that calls load() must always supply secret_key and must never accept a user-supplied path - that invariant lives in the deployment, not in this method.

@classmethod

def load( cls: type[~T], path: pathlib.Path | str, secret_key: bytes | None = None) -> ~T:

Deserialise a Model previously written by save().

Four cases, matching save()'s two modes:

secret_key given, signature present: verified before deserialising - raises ModelSignatureError on mismatch.
secret_key given, signature absent: raises - a caller expecting a verified load must never silently fall through to an unverified one.
secret_key is None, signature absent: deserialises directly (the desktop/dev path).
secret_key is None, signature present: raises. This is the downgrade-attack guard - a signed file must not become loadable-unverified just because the caller omitted the key.

def save_to_csv(self, output_directory: pathlib.Path | str) -> None:

Save csv outputs to a directory.

def save_for_web(self, output_directory: pathlib.Path | str) -> None:

Save csv outputs used for the web frontend to a directory.

def save_graphs(self, output_directory: pathlib.Path | str) -> None:

Save instance-space plots as PNG files in the output directory.

def save_to_mat(self, output_directory: pathlib.Path | str) -> None:

Save the algorithm-label-only MAT compatibility file for the dashboard.

Use save() for complete model persistence, including PILOT's numeric projection and optimized viewpoint.

def save_zip(self, zip_filename: str, output_directory: pathlib.Path | str) -> None:

Save serializer outputs in a structured ZIP archive.