Kernel Interpretation

A GP’s kernel encodes prior beliefs about the smoothness, periodicity, and scale of the function being modelled. GPy stores these beliefs as hyperparameter objects on a model.kern tree — but a raw lengthscale of 2.7 or a variance of 0.04 is not immediately meaningful. The kernel_summary module translates these values into plain-language descriptions and displays composite kernels as an ASCII hierarchy.

Basic Summary

import gpclarity

summary = gpclarity.summarize_kernel(model)

print(summary["interpretation"])   # e.g. "Smooth, long-range dependencies"
print(summary["n_components"])     # number of leaf kernels

for comp in summary["components"]:
    print(comp["name"])
    print(comp["lengthscale_interpretation"])
    print(comp["variance_interpretation"])

The returned dictionary always contains "interpretation", "components", "n_components", and "kernel_type". Each component dict includes the raw hyperparameter values alongside their plain-language counterparts.

Kernel Tree

For composite kernels (sums, products), format_kernel_tree() prints an ASCII hierarchy showing how the components are combined:

gpclarity.format_kernel_tree(model)

Example output for an RBF + Matern52 kernel:

RBF
Matern52

For deeply nested products and sums:

Add
├── RBF
└── Mul
    ├── Matern52
    └── Periodic

Component Interpretation

The two interpretation helpers work on scalar values directly, which is useful when scanning a parameter sweep or comparing models:

ls_text = gpclarity.interpret_lengthscale(2.7)
# e.g. "Moderate lengthscale — captures medium-range structure"

var_text = gpclarity.interpret_variance(0.04)
# e.g. "Low variance — model explains relatively little signal"

Default thresholds classify lengthscales as “very short” (< 0.1), “short” (0.1–0.5), “moderate” (0.5–2.0), “long” (2.0–10.0), or “very long” (> 10.0). Variance uses analogous bands. If your data is on a different scale — say, time in years rather than seconds — you should adjust these thresholds (see below).

Parameter Extraction

extract_kernel_params_flat() returns all hyperparameters as a flat dictionary keyed by "<kernel_name>.<param_name>":

params = gpclarity.extract_kernel_params_flat(model)
# e.g. {"rbf.variance": 1.0, "rbf.lengthscale": 2.7, "Gaussian_noise.variance": 0.01}

for name, value in params.items():
    print(f"{name}: {value:.4f}")

For quick access to the most common values:

ls    = gpclarity.get_lengthscale(model)     # scalar or array for ARD kernels
noise = gpclarity.get_noise_variance(model)  # Gaussian noise variance

n = gpclarity.count_kernel_components(model.kern)
print(f"Kernel has {n} leaf component(s)")

Custom Thresholds

If your input domain spans a very different range than the defaults assume (e.g. inputs in the range 0–1000 rather than 0–10), the default threshold bands will label nearly every lengthscale as “very short”. Override them with InterpretationConfig:

from gpclarity.kernel_summary import (
    InterpretationConfig, LengthscaleThresholds, VarianceThresholds
)

config = InterpretationConfig(
    lengthscale=LengthscaleThresholds(
        very_short=10.0,
        short=50.0,
        moderate=200.0,
        long=1000.0,
    ),
    variance=VarianceThresholds(
        very_low=0.01,
        low=0.1,
        moderate=1.0,
        high=10.0,
    ),
)

summary = gpclarity.summarize_kernel(model, config=config)

Pass the same config to interpret_lengthscale() and interpret_variance() for consistent categorisation across all calls in your analysis.