to_mgcv_dict()

Export a fitted GAM as an mgcv-compatible dictionary.

Usage

to_mgcv_dict(model)

Builds a plain dict whose keys and nested structure mirror the fields of a fitted gam object from R’s mgcv package, rather than whittaker’s own internal representation. Use this when you need to hand a Python-fitted model to R code — typically by serializing the result with json.dumps and reading it in R with jsonlite::fromJSON, or comparing a whittaker fit against an equivalent mgcv::gam() fit term by term.

Top-level keys include coefficients (the fitted coefficient vector), sp (smoothing parameters), scale and scale.estimated, gcv.ubre, edf and edf.total, deviance and null.deviance, aic, n (observation count) and p (coefficient count), converged, iter, method, formula (as a string), family (a nested dict with the family name and any extra parameter such as a Tweedie power or negative-binomial theta), smooth (a list, one entry per smooth term), nsdf, and intercept.

Each entry in smooth describes one smooth term with mgcv-style field names: term (covariate names), bs (the two-letter mgcv basis-type code), label, first.para/ last.para (1-based coefficient column range), null.space.dim, df, optionally by/by.level for by-variable smooths, and S (a list of penalty matrix blocks, sliced from the model’s full penalty matrices down to just this term’s coefficient columns). The bs code is produced by mapping the whittaker basis class name to mgcv’s naming convention, e.g. TPRS maps to "tp", ShrinkageTPRS to "ts", CRS to "cr", PSpline to "ps", CyclicPSpline to "cp", RandomEffectBasis to "re", and so on; a basis with no known mgcv counterpart falls back to its whittaker class name unchanged.

Parameters

model: GAM: A fitted ~whittaker.gam.GAM instance.

Returns

dict: An mgcv-compatible dictionary with keys such as coefficients, sp, family, smooth, edf, and deviance, suitable for JSON serialization and import into R.

Raises

TypeError: If model is not a GAM instance.
RuntimeError: If model has not been fitted (model.is_fitted is False).

Notes

This function is intended to interoperate with the R mgcv package’s gam object structure so that a whittaker fit can be inspected or compared from R. Full fidelity is not guaranteed: not every mgcv field is populated (for example, no Vp/Vc covariance matrices are exported), and not every whittaker family or basis has a direct mgcv equivalent, in which case the original class name is used as-is rather than an invented mgcv code.

Examples

import json
import numpy as np
import whittaker as wt
from whittaker.io import to_mgcv_dict

rng = np.random.default_rng(2)
x = np.sort(rng.uniform(0, 1, 100))
y = x**2 + rng.normal(scale=0.1, size=100)

model = wt.GAM("y ~ s(x)").fit({"x": x, "y": y})
mgcv_dict = to_mgcv_dict(model)

sorted(mgcv_dict.keys())

['aic',
 'coefficients',
 'converged',
 'deviance',
 'edf',
 'edf.total',
 'family',
 'formula',
 'gcv.ubre',
 'intercept',
 'iter',
 'method',
 'n',
 'nsdf',
 'null.deviance',
 'p',
 'scale',
 'scale.estimated',
 'smooth',
 'sp']

# The dict is JSON-serializable and can be written out for R to read.
payload = json.dumps(mgcv_dict)
mgcv_dict["smooth"][0]["bs"]

'tp'