Persistence API

Fitted models can be saved to JSON and restored without depending on Python object pickling. Set include_data=True when stateful prediction should use the training history stored by the fitted model.

from pathlib import Path
from tempfile import TemporaryDirectory

import numpy as np

from pyscarcopula import GumbelCopula, load_model, save_model

rng = np.random.default_rng(2026)
source = GumbelCopula(rotate=180)
u = source.sample_at_parameter(200, np.full(200, 1.7), rng=rng)

model = GumbelCopula(rotate=180)
model.fit(u, method="mle")

with TemporaryDirectory() as directory:
    path = Path(directory) / "gumbel.json"
    save_model(model, path, include_data=True)
    restored = load_model(path)
    samples = restored.predict(20, rng=np.random.default_rng(7))

Model instances also expose model.save(...), and model classes provide a matching load(...) convenience method.

For Equicorr models fitted to EquicorrPreparedData, include_data=True retains the compact sufficient statistics, without reconstructing the original observations. Loading restores their validation and read-only arrays. Dataclass records encoded with the object tag are rejected; they must use the dataclass tag so that loading invokes their validating constructor. include_data=False omits both dense training observations and prepared statistics; fitted parameters and diagnostics are retained. Saving does not change the source model's retained history.

pyscarcopula.io.save_model(model, path, *, include_data=False)

Persist a fitted model to path as JSON.

Parameters:

Name	Type	Description	Default
model	object	Model instance to serialize.	required
path	str or Path	Destination file path.	required
include_data	bool	If False, drop cached training pseudo-observations stored as _last_u and prepared training statistics stored as _last_prepared before writing. This reduces file size and avoids persisting the training sample or its statistics. Fitted state, diagnostics, and cached likelihood values are still saved. Loaded dynamic models may require explicit data passed to prediction methods.	False

pyscarcopula.io.load_model(path, *, expected_type=None)

load_model(
    path: str | Path, *, expected_type: type[ModelT]
) -> ModelT

load_model(
    path: str | Path, *, expected_type: None = None
) -> Any

Load a model persisted by :func:save_model.

Parameters:

Name	Type	Description	Default
path	str or Path	Source JSON document.	required
expected_type	type or None	Optional runtime type constraint. Supplying it also gives static type checkers a precise return type.	None

Returns:

Type	Description
object	Reconstructed model instance.

Raises:

Type	Description
ValueError	If the document is not a supported pyscarcopula model format.
TypeError	If the reconstructed model is not an instance of expected_type.