Quick Start Guide

5-Minute Tour

Train a GP and get instant insights:

import numpy as np
import GPy
import gpclarity

# 1. Create toy data
np.random.seed(42)
X = np.linspace(0, 10, 50).reshape(-1, 1)
y = np.sin(X).flatten() + 0.1 * np.random.randn(50)

# 2. Build and train GP
kernel = GPy.kern.RBF(1) + GPy.kern.White(1)
model = GPy.models.GPRegression(X, y[:, None], kernel)
model.optimize(messages=True)

# 3. Get clarity
print(gpclarity.summarize_kernel(model, verbose=True))

Output:

 KERNEL SUMMARY
==================================================
Structure: ['rbf', 'white']

Thresholds:
  Lengthscale: rapid<0.5, smooth>2.0
  Variance: very_low<0.01, high>10.0

 rbf (parts[0])
  └─ lengthscale: 1.2345
    Moderate flexibility (1.23)

 white (parts[1])
  └─ variance: 0.0101
    Very low noise (≈0.010)

Common Workflows

Assess Model Complexity

from gpclarity import compute_complexity_score

report = compute_complexity_score(model, X)
print(f"Complexity: {report['category']}")
# > Complexity: MODERATE
# > Well-balanced complexity
# > Risk level: LOW

Analyze Uncertainty

from gpclarity import UncertaintyProfiler

profiler = UncertaintyProfiler(model, X_train=X)

# Test on new grid
X_test = np.linspace(-2, 12, 200).reshape(-1, 1)

# Get diagnostics
diag = profiler.compute_diagnostics(X_test)
print(f"Extrapolation points: {diag['n_extrapolation_points']}")
# > Extrapolation points: 40

# Visualize
profiler.plot(X_test, X_train=X, y_train=y)

# Identify concerning regions
regions = profiler.identify_uncertainty_regions(X_test)
print(f"High uncertainty ratio: {regions['high_uncertainty_ratio']:.2%}")

Track Optimization

from gpclarity import HyperparameterTracker

tracker = HyperparameterTracker(model)

# Optimize with tracking
history = tracker.wrapped_optimize(max_iters=100)

# Check convergence
report = tracker.get_convergence_report()
for param, metrics in report.items():
    print(f"{param}: {'✓ converged' if metrics['is_converged'] else '✗ not converged'}")

# Plot trajectories
fig = tracker.plot_evolution()

Analyze Data Influence

from gpclarity import DataInfluenceMap

influence = DataInfluenceMap(model)

# Fast leverage scores
result = influence.compute_influence_scores(X)

# Detailed leave-one-out analysis (slower)
loo_var, loo_err = influence.compute_loo_variance_increase(X, y)

# Get comprehensive report
report = influence.get_influence_report(X, y)
print(f"Most influential point: index {report['most_influential_point']['index']}")

# Visualize
influence.plot_influence(X, result)

Next Steps

See GPClarity User Guide for detailed tutorials on each module.