pod.fit_variance_model
fit_variance_model(X, y, mean_model, auto_bandwidth=True, bandwidth_ratio=0.1)Calculates residuals and defines the smoothing bandwidth for variance estimation.
This function acts as the setup phase for modeling heteroscedasticity ([M25] Sec. 2e). It computes the residuals from the provided mean model and establishes the smoothing bandwidth either via automated Cross-Validation or a fixed user-defined ratio.
For polynomial mean models the residuals are the in-sample residuals, as in [M25] Eq. 2.9. For Kriging models they are the leave-one-out residuals y - loo_means_ [digiqual]. A Kriging model with a learned nugget partly fits the scatter at the training points, so its in-sample residuals understate the scatter, which would make the PoD curve too steep. The LOO residuals measure how far a new observation falls from a prediction made without it.
The Kriging outlier factor gamma ([M26] Sec. 2.2.5.2) is not applied here. In [M26] it widens the Kriging interpolation uncertainty used for the PoD bound only, and the PoD curve itself is unchanged; digiqual’s bound comes from the bootstrap, so gamma is kept as a diagnostic (see compute_kriging_loo_residuals).
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| X | np.ndarray | The 1D array of original input data (e.g., parameter of interest). | required |
| y | np.ndarray | The 1D array of original outcome data (e.g., signal response). | required |
| mean_model | Any | A fitted scikit-learn estimator (e.g., Pipeline or GaussianProcessRegressor) that implements a .predict() method. |
required |
| auto_bandwidth | bool | If True, dynamically calculates the optimal bandwidth using Leave-One-Out Cross-Validation. If False, falls back to the fixed bandwidth_ratio. Defaults to True. |
True |
| bandwidth_ratio | float | The kernel smoothing window size as a fraction of the largest range of the standardised inputs. Only used if auto_bandwidth is False. Defaults to 0.1. |
0.1 |
Returns
| Name | Type | Description |
|---|---|---|
| tuple[np.ndarray, float] | tuple[np.ndarray, float]: - residuals: Differences between y and the mean model predictions (leave-one-out predictions for Kriging). - bandwidth: The selected smoothing window size, in standard deviations of the inputs. |
Examples
import numpy as np
from sklearn.linear_model import LinearRegression
# 1. Setup dummy data and a basic mean model
X = np.linspace(0, 10, 50)
y = 2.5 * X + np.random.normal(0, 1, 50)
model = LinearRegression()
model.fit(X.reshape(-1, 1), y)
# 2. Extract residuals and optimized bandwidth
residuals, bandwidth = fit_variance_model(
X, y,
mean_model=model,
auto_bandwidth=True
)
print(f"Calculated Bandwidth: {bandwidth:.4f}")