Examples Gallery

The examples below build on the quick-start workflow. Each snippet assumes the model and data from Getting Started are already in scope.

Composite Kernel Inspection

Decompose a sum kernel and inspect each component individually:

import GPy
import numpy as np
import gpclarity

kernel = GPy.kern.RBF(1) + GPy.kern.Periodic(1) + GPy.kern.White(1)
model = GPy.models.GPRegression(X, y[:, None], kernel)
model.optimize()

# Tree structure
print(gpclarity.format_kernel_tree(model))

# Full flat parameter dict
params = gpclarity.extract_kernel_params_flat(model)
for name, value in params.items():
    print(f"  {name}: {value:.4f}")

# Summary with custom thresholds
from gpclarity.kernel_summary import InterpretationConfig, LengthscaleThresholds
cfg = InterpretationConfig(
    lengthscale=LengthscaleThresholds(rapid_variation=0.3, smooth_trend=3.0)
)
gpclarity.summarize_kernel(model, config=cfg)

Uncertainty Region Classification

Identify extrapolation and high-uncertainty regions:

profiler = gpclarity.UncertaintyProfiler(model, X_train=X)
X_test = np.linspace(-5, 15, 300).reshape(-1, 1)

regions = profiler.classify_regions(X_test, X_train=X)

from gpclarity.uncertainty_analysis import UncertaintyRegion
extrap_mask = regions == UncertaintyRegion.EXTRAPOLATION
print(f"Extrapolation: {extrap_mask.sum()} / {len(X_test)} points")

Uncertainty Calibration

Calibrate model uncertainty using a held-out validation set:

X_val = np.linspace(0, 10, 20).reshape(-1, 1)
y_val = np.sin(X_val).flatten() + 0.1 * np.random.randn(20)

cal = profiler.calibrate_uncertainty(X_val, y_val, method="scaling")
print(f"Optimal sigma scale: {cal.get('optimal_scale', 1.0):.3f}")
print(f"Miscalibration: {cal.get('miscalibration', 0.0):.4f}")

Comparing Multiple Models

Rank models by uncertainty quality side-by-side:

from gpclarity.uncertainty_analysis import compare_uncertainty_profiles

models = {
    "RBF": model_rbf,
    "Matern32": model_mat32,
    "RBF+Periodic": model_composite,
}

profiles = compare_uncertainty_profiles(models, X_test, X_train=X)
for name, diag in profiles.items():
    print(f"{name}: mean_var={diag['mean_uncertainty']:.4f}, CV={diag['coefficient_of_variation']:.2f}")

Optimization Issue Detection

Automatically detect and diagnose convergence problems:

tracker = gpclarity.HyperparameterTracker(model)
tracker.wrapped_optimize(max_iters=200)

issues = tracker.detect_optimization_issues()
for w in issues['warnings']:
    print(f"Warning: {w}")
for r in issues['recommendations']:
    print(f"Tip: {r}")

Exporting Tracker History

Export the optimization trajectory to a CSV file for offline analysis:

df = tracker.to_dataframe()
print(df.head())
df.to_csv("optimization_history.csv", index=False)

Parallel Leave-One-Out Analysis

Speed up LOO variance computation on large datasets using all CPU cores:

influence = gpclarity.DataInfluenceMap(model)
var_increase, pred_errors = influence.compute_loo_variance_increase(
    X, y, n_jobs=-1, verbose=True
)

# Points with both high variance increase AND high prediction error are outliers
threshold = np.percentile(var_increase, 90)
outlier_mask = var_increase > threshold
print(f"Potential outliers: {outlier_mask.sum()} points")