from_mgcv_dict()

Import an mgcv gam object exported as a dictionary.

Usage

from_mgcv_dict(
    d,
    data=None,
)

The inverse of to_mgcv_dict: reconstructs a ~whittaker.gam.GAM from a dictionary shaped like an R mgcv::gam object, typically produced in R with jsonlite::toJSON(gam_model) (or an equivalent hand-built dict) and passed into Python after parsing the JSON. Use this to bring a model fitted in R into whittaker for further prediction, plotting, or comparison against a Python fit.

There are two modes, selected by whether data is supplied:

Without data (the default): only the formula, family, fitted coefficients, and smoothing parameters are restored onto the returned GAM. No model matrix or smooth basis is built, so the result is a lightweight container for inspecting the imported coefficients — it is not usable for predict(), since the smooth bases (knots, constraints, etc.) that the coefficients were fit against are not reconstructed.
With data (the original training data, as {name: 1-D array}): ~whittaker.model_matrix .build_model_matrix is called on data to refit each smooth’s basis and assemble the design matrix, the linear predictor and fitted values are recomputed from the imported coefficients, and a full FitResult (deviance, residuals, etc.) is attached. In this mode the returned model is fully usable for predict() on new data, since its smooth bases were rebuilt from the same training data mgcv used.

The R family name in d["family"]["family"] is translated to the corresponding whittaker family class via an internal mapping (_mgcv_family_map), e.g. "gaussian" -> Gaussian, "poisson" -> Poisson, "binomial" -> Binomial, "Gamma" -> Gamma, "inverse.gaussian" -> InverseGaussian, "Tweedie" -> Tweedie, "nb" -> NegativeBinomial, "cox.ph" -> CoxPH, and "betar" -> Beta. A family name not in this table is passed through unchanged and will raise ValueError if it does not match a known whittaker family class.

Parameters

d: dict: An mgcv-compatible dictionary, e.g. parsed from jsonlite::toJSON(gam_model) in R, or produced by to_mgcv_dict. Must contain at least "coefficients"; "formula", "family", "sp", and "smooth" are used when present to reconstruct the formula, family, and smoothing parameters as accurately as possible.
data: dict[str, numpy.ndarray] = None: The original training data used to fit the model in R, as {name: 1-D array}. When given, smooth bases are rebuilt from this data and the returned model supports predict(). When omitted (the default), only coefficients and smoothing parameters are restored and the model cannot be used for prediction.

Returns

GAM: A ~whittaker.gam.GAM instance. Fully fitted and prediction-ready when data is provided; otherwise a formula/family/coefficient container only.

Notes

This function is intended to interoperate with the R mgcv package’s gam object structure. Full fidelity is not guaranteed: only the family names listed in _mgcv_family_map are recognized, and mgcv fields with no whittaker counterpart (e.g. certain smooth-specific xt options) are ignored rather than reconstructed.

Examples

import numpy as np
import whittaker as wt
from whittaker.io import to_mgcv_dict, from_mgcv_dict

rng = np.random.default_rng(3)
x = np.sort(rng.uniform(0, 1, 120))
y = np.sin(2 * x) + rng.normal(scale=0.1, size=120)
data = {"x": x, "y": y}

model = wt.GAM("y ~ s(x)").fit(data)
mgcv_dict = to_mgcv_dict(model)

# Round-trip through the mgcv-style dict, refitting bases from the training data.
reimported = from_mgcv_dict(mgcv_dict, data=data)
reimported.predict({"x": np.linspace(0, 1, 3)}).values

array([0.04610469, 0.86859144, 0.90262436])