gpmp.kernel priors¶

Prior terms are used by REMAP parameter selection. Prior functions return log-prior values. REMAP objective functions combine these prior terms with the negative restricted likelihood and return a negative log-posterior criterion to minimize.

The priors documented here operate on covariance-parameter vectors. For the sigma2_rho convention, the vector is

[log(sigma2), -log(rho_0), ..., -log(rho_{d-1})].

When a prior is expressed in logrho = log(rho), the value is obtained from covparam through logrho_j = -covparam[j + 1].

Basic prior terms¶

log_prior_jeffreys_variance is a variance-only Jeffreys-style term. It is not the full multivariate Jeffreys prior for all covariance parameters. With \(\ell_\sigma=\log(\sigma^2)=\mathrm{covparam}[0]\), GPmp uses

\[\log \pi(\theta) = -\lambda_{\mathrm{var}} \ell_\sigma.\]

For lambda_var=1, this is proportional to \(1/\sigma^2\).

log_prior_power_law is a pragmatic power-law regularization term with soft cutoffs. In the sigma2_rho convention, write \(u_j=-\log(\rho_j)\). The implemented term has a variance power-law part, an inverse-lengthscale power-law part, and linear penalties outside prescribed cutoffs. It is a regularization term, not an objective reference prior.

log_prior_reference computes a Jeffreys-rule/reference-style log prior from the Fisher information supplied by the model:

\[\log \pi_{\mathrm{J}}(\theta) = \frac{1}{2}\log\det I(\theta).\]

In multiparameter problems, Jeffreys-rule priors and formal reference priors do not necessarily coincide. See the function docstring for references.

log_prior_jeffreys_variance¶

gpmp.kernel.log_prior_jeffreys_variance(covparam, lambda_var=1.0)[source]¶

Compute Jeffreys-type log-prior on variance.

Parameters:

covparam (array_like) – Covariance parameter vector. covparam[0] is log(sigma^2).
lambda_var (float, default=1.0) – Scaling coefficient in log p = -lambda_var * log(sigma^2).

Returns:

Log-prior value.

Return type:

scalar

Notes

This is a Jeffreys-style prior component on the variance term only, not the full multivariate Jeffreys prior for all covariance parameters.

References

Jeffreys, H. (1946). An invariant form for the prior probability in estimation problems. Proceedings of the Royal Society A, 186(1007), 453-461.

log_prior_power_law¶

gpmp.kernel.log_prior_power_law(covparam, lambda_var=1.0, cut_logvariance_high=9.21, lambda_lengthscales=0.0, cut_loginvrho_low=-9.21, cut_loginvrho_high=9.21, penalty_factor=100)[source]¶

Compute power-law log-prior with soft cutoffs on covariance parameters.

Parameters:

covparam (array_like) – Covariance parameter vector [log(sigma^2), loginvrho_0, ..., loginvrho_{d-1}].
lambda_var (float, default=1.0) – Power-law exponent coefficient for log(sigma^2).
cut_logvariance_high (float, default=9.21) – Upper soft cutoff for log(sigma^2).
lambda_lengthscales (float, default=0.0) – Power-law exponent coefficient for inverse length-scales.
cut_loginvrho_low (float, default=-9.21) – Lower soft cutoff for loginvrho components.
cut_loginvrho_high (float, default=9.21) – Upper soft cutoff for loginvrho components.
penalty_factor (float, default=100) – Linear penalty slope outside cutoff region.

Returns:

Log-prior value.

Return type:

scalar

Notes

This is a pragmatic regularization prior (power-law + soft cutoffs), not a canonical objective prior in the Jeffreys/reference sense.

References

Berger, J. O., De Oliveira, V., and Sanso, B. (2001). Objective Bayesian analysis of spatially correlated data. JASA, 96(456), 1361-1374. Paulo, R. (2005). Default priors for Gaussian processes. Annals of Statistics, 33(2), 556-582.

log_prior_reference¶

gpmp.kernel.log_prior_reference(model, covparam, xi)[source]¶

Compute Jeffreys-rule log-prior from Fisher information.

Parameters:

model (gpmp.core.Model) – GP model instance exposing fisher_information.
covparam (array_like) – Covariance parameter vector.
xi (array_like) – Design/input locations used to compute Fisher information.

Returns:

0.5 * log(det(FisherInfo(theta))).

Return type:

scalar

Notes

This is the Jeffreys-rule form for the parameter block. In multiparameter settings, strict reference priors may differ from Jeffreys-rule priors and depend on parameter ordering.

References

Jeffreys, H. (1946). An invariant form for the prior probability in estimation problems. Proceedings of the Royal Society A, 186(1007), 453-461. Bernardo, J. M. (1979). Reference Posterior Distributions for Bayesian Inference. JRSS-B, 41(2), 113-128. Berger, J. O., Bernardo, J. M., and Sun, D. (2009). The formal definition of reference priors. Annals of Statistics, 37(2), 905-938.

Gaussian prior on log variance¶

log_prior_gaussian_logsigma2 defines a Gaussian prior on log(sigma2). The center is supplied by log_sigma2_0. The scale is calibrated by gamma and sigma2_coverage so that the interval [sigma2_0 / gamma, sigma2_0 * gamma] receives the requested central Gaussian probability mass.

Let \(c\) be sigma2_coverage and \(z_c = \Phi^{-1}((1+c)/2)\). The log-space standard deviation is

\[s_\sigma = \frac{\log(\gamma)}{z_c}.\]

The implemented log prior is

\[\log \pi_{\sigma^2}(\theta) = -\frac{1}{2} \left( \frac{\ell_\sigma-\ell_{\sigma,0}}{s_\sigma} \right)^2,\]

up to an additive normalization constant. The default values are gamma=1.5 and sigma2_coverage=0.95 unless changed through gpmp.kernel.prior_defaults.

log_prior_gaussian_logsigma2¶

gpmp.kernel.log_prior_gaussian_logsigma2(covparam, log_sigma2_0, gamma=None, sigma2_coverage=None)[source]¶

Compute Gaussian log-prior on log(sigma^2).

Parameters:

covparam (array_like) – Covariance parameter vector. covparam[0] is log(sigma^2).
log_sigma2_0 (scalar) – Prior mean for log(sigma^2).
gamma (float, optional) – Multiplicative factor around sigma2_0 used for prior calibration. If None, default from gpmp.kernel.prior_defaults is used.
sigma2_coverage (float, optional) – Central Gaussian probability mass assigned to [sigma2_0 / gamma, sigma2_0 * gamma]. If None, default from gpmp.kernel.prior_defaults is used.

Returns:

Gaussian log-prior value (up to an additive normalization constant).

Return type:

scalar

Notes

The standard deviation in log(sigma^2) is derived from gamma and sigma2_coverage so that:

P(sigma^2 in [sigma2_0 / gamma, sigma2_0 * gamma]) = sigma2_coverage.

This is a weakly informative regularization prior.

Log-lengthscale barrier and linear penalty¶

The logrho prior prevents degenerate solutions with too-small lengthscales and also penalizes overly large lengthscales. It is expressed on logrho = log(rho). The function neglog_f_logrho returns the elementwise penalty. log_prior_logrho_barrier_linear applies this penalty to a covparam vector and returns the corresponding log-prior value.

logrho_min is a componentwise hard lower bound. logrho_0 is the componentwise minimum of the penalty. alpha is the linear right-tail slope.

For each coordinate, define

\[s_j = \log(\rho_j) - \log(\rho_{\min,j}), \qquad a_j = \alpha\left(\log(\rho_{0,j})-\log(\rho_{\min,j})\right).\]

For \(s_j>0\), the negative log-prior contribution is

\[\phi_j(s_j) = -a_j \log(s_j) + \alpha s_j.\]

For \(s_j \leq 0\), the contribution is \(+\infty\). The derivative vanishes at \(\log(\rho_j)=\log(\rho_{0,j})\), so logrho_0 is the componentwise minimum. The log prior returned by log_prior_logrho_barrier_linear is

\[\log \pi_\rho(\theta) = -\sum_j \phi_j(s_j).\]

The default alpha is 1.0 unless changed through gpmp.kernel.prior_defaults.

neglog_f_logrho¶

gpmp.kernel.neglog_f_logrho(logrho, logrho_min, logrho_0, alpha=None)[source]¶

Compute elementwise barrier + linear-tail penalty on logrho.

Parameters:

logrho (array_like) – Log-lengthscale vector.
logrho_min (array_like) – Componentwise hard lower bound.
logrho_0 (array_like) – Componentwise reference value (penalty minimum).
alpha (float, optional) – Linear right-tail slope parameter of the penalty. If None, default from gpmp.kernel.prior_defaults is used.

Returns:

Componentwise non-negative penalty. Returns +inf where logrho <= logrho_min.

Return type:

array_like

Notes

This is a structural regularization penalty (barrier + tail control), not a Jeffreys/reference prior.

log_prior_logrho_barrier_linear¶

gpmp.kernel.log_prior_logrho_barrier_linear(covparam, logrho_min, logrho_0, alpha=None)[source]¶

Compute log-prior on rho from barrier+linear penalty on logrho.

Parameters:

covparam (array_like) – Covariance parameter vector with inverse length-scales in log-domain: loginvrho = covparam[1:].
logrho_min (array_like) – Lower bound for logrho components.
logrho_0 (array_like) – Reference values for logrho components.
alpha (float, optional) – Linear right-tail slope parameter. If None, default from gpmp.kernel.prior_defaults is used.

Returns:

Log-prior value.

Return type:

scalar

Notes

Induces a prior on lengthscales through logrho = -loginvrho with hard lower support and linear tail regularization.

REMAP posterior objectives¶

These functions return negative restricted posterior criteria. They are the objective functions used by the named REMAP selection methods.

The combined log-variance and log-lengthscale REMAP objective is

\[J(\theta) = J_{\mathrm{REML}}(\theta) - \log \pi_{\sigma^2}(\theta) - \log \pi_\rho(\theta).\]

The other REMAP objectives are the same construction with only the selected prior term. The current named REMAP selection methods target the sigma2_rho covariance-parameter convention. GPmp does not currently provide a named REMAP method with a prior on the continuous Matérn regularity \(\nu\).

neg_log_restricted_posterior_power_laws_prior¶

gpmp.kernel.neg_log_restricted_posterior_power_laws_prior(model, covparam, xi, zi)[source]¶

Compute negative restricted posterior with power-law prior.

Parameters:

model (gpmp.core.Model) – GP model instance.
covparam (array_like) – Covariance parameter vector.
xi (array_like) – Observation inputs and targets.
zi (array_like) – Observation inputs and targets.

Returns:

negative_log_restricted_likelihood - log_prior_power_law.

Return type:

scalar

Notes

This objective corresponds to MAP with a regularization prior, not an objective reference prior.

neg_log_restricted_posterior_logsigma2_prior¶

gpmp.kernel.neg_log_restricted_posterior_logsigma2_prior(model, covparam, xi, zi, log_sigma2_0, gamma=None, sigma2_coverage=None)[source]¶

Compute negative restricted posterior with Gaussian prior on log(sigma^2).

Parameters:

model (gpmp.core.Model) – GP model instance.
covparam (array_like) – Covariance parameter vector.
xi (array_like) – Observation inputs and targets.
zi (array_like) – Observation inputs and targets.
log_sigma2_0 (scalar) – Prior mean for log(sigma^2).
gamma (float, optional) – Multiplicative factor around sigma2_0 used for prior calibration. If None, default from gpmp.kernel.prior_defaults is used.
sigma2_coverage (float, optional) – Central Gaussian probability mass assigned to [sigma2_0 / gamma, sigma2_0 * gamma]. If None, default from gpmp.kernel.prior_defaults is used.

Returns:

negative_log_restricted_likelihood - log_prior_gaussian_logsigma2.

Return type:

scalar

Notes

This objective corresponds to MAP with a weakly informative prior on log(sigma^2).

neg_log_restricted_posterior_with_logrho_prior¶

gpmp.kernel.neg_log_restricted_posterior_with_logrho_prior(model, covparam, xi, zi, logrho_min, logrho_0, alpha=None)[source]¶

Compute negative restricted posterior with prior on logrho.

Parameters:

model (gpmp.core.Model) – GP model instance.
covparam (array_like) – Covariance parameter vector.
xi (array_like) – Observation inputs and targets.
zi (array_like) – Observation inputs and targets.
logrho_min (array_like) – Lower bounds for logrho.
logrho_0 (array_like) – Reference values for logrho.
alpha (float, optional) – Linear right-tail slope parameter. If None, default from gpmp.kernel.prior_defaults is used.

Returns:

negative_log_restricted_likelihood - log_prior_logrho_barrier_linear.

Return type:

scalar

Notes

This objective corresponds to MAP with a constrained regularization prior on logrho.

neg_log_restricted_posterior_logsigma2_and_logrho_prior¶

gpmp.kernel.neg_log_restricted_posterior_logsigma2_and_logrho_prior(model, covparam, xi, zi, log_sigma2_0, gamma=None, sigma2_coverage=None, logrho_min=None, logrho_0=None, alpha=None)[source]¶

Compute negative restricted posterior with priors on log(sigma^2) and logrho.

The objective is the REML criterion regularized by two additive prior terms:

\[J(\theta) = -\log p(z \mid x, \theta)_{\mathrm{REML}} - \log p_{\sigma^2}(\theta) - \log p_{\rho}(\theta),\]

where theta = covparam, log(sigma^2) = covparam[0] and logrho = -covparam[1:].

The variance prior term log p_{\sigma^2} is Gaussian in log(sigma^2) with center log_sigma2_0. Its log-space standard deviation is calibrated from gamma and sigma2_coverage so that:

P(sigma2_0 / gamma <= sigma^2 <= sigma2_0 * gamma) = sigma2_coverage.

The lengthscale term log p_{\rho} is a barrier + linear-tail prior in logrho with componentwise hard support logrho > logrho_min and minimum at logrho_0. The public parameter alpha controls the linear right-tail slope; the barrier strength is adjusted internally per component so the minimum remains at logrho_0.

Parameters:

model (gpmp.core.Model) – GP model instance.
covparam (array_like) – Covariance parameter vector.
xi (array_like) – Observation inputs and targets.
zi (array_like) – Observation inputs and targets.
log_sigma2_0 (scalar) – Gaussian prior center for log(sigma^2).
gamma (float, optional) – Multiplicative factor around sigma2_0 used for prior calibration. If None, default from gpmp.kernel.prior_defaults is used.
sigma2_coverage (float, optional) – Central Gaussian probability mass assigned to [sigma2_0 / gamma, sigma2_0 * gamma]. If None, default from gpmp.kernel.prior_defaults is used.
logrho_min (array_like, optional) – Lower bounds for logrho components.
logrho_0 (array_like, optional) – Reference values for logrho components.
alpha (float, optional) – Linear right-tail slope for the logrho prior. If None, default from gpmp.kernel.prior_defaults is used.

Returns:

negative_log_restricted_likelihood minus both prior log-densities.

Return type:

scalar

Prior defaults and data-derived logrho bounds¶

Prior defaults are stored in gpmp.kernel.prior_defaults. They are used when prior hyperparameters are not passed explicitly.

compute_logrho_min_from_xi computes a componentwise lower bound for logrho from observation points. It combines the smallest positive spacing in each coordinate with a range-based safeguard.

For coordinate j, the bound is

\[\log(\rho_{\min,j}) = \max\left\{ \log(\Delta^{\mathrm{gap}}_j), \log(\Delta^{\mathrm{range}}_j f_\rho) \right\},\]

where \(\Delta^{\mathrm{gap}}_j\) is the smallest positive spacing in coordinate j, \(\Delta^{\mathrm{range}}_j\) is the coordinate range, and \(f_\rho\) is rho_min_range_factor. The default is rho_min_range_factor=1/20.

For select_parameters_sigma2_rho_with_remap_logsigma2_logrho_prior, prior anchors are resolved as follows:

prior_log_sigma2_0 overrides the variance anchor.
Otherwise the variance anchor is covparam0_prior[0].
prior_logrho_0 overrides the lengthscale anchor.
Otherwise the lengthscale anchor is -covparam0_prior[1:].
If prior_logrho_min is not supplied, it is computed from xi or from dataloader.dataset.x_list.

The optimizer start and the prior anchor are separate roles. Use covparam0_init for the optimizer start and covparam0_prior for the prior anchor when they should differ.

compute_logrho_min_from_xi¶

gpmp.kernel.compute_logrho_min_from_xi(xi, prior_rho_min_range_factor=None)[source]¶

Compute safeguarded componentwise prior_logrho_min from observation points.

The bound combines two componentwise lower bounds and keeps the tightest (largest) admissible one:

log(min nonzero gap)
log(range * prior_rho_min_range_factor)

Parameters:

xi (array_like of shape (n, d)) – Observation points.
prior_rho_min_range_factor (float, optional) – Safeguard factor for the range-based lower bound. If None, the default configured in gpmp.kernel.prior_defaults is used.

Returns:

prior_logrho_min – Safeguarded componentwise lower bound for logrho.

Return type:

array_like of shape (d,)

get_default_prior_hyperparameters¶

gpmp.kernel.prior_defaults.get_default_prior_hyperparameters(xi=None)[source]¶

Return default prior hyperparameters.

Parameters:: xi (array_like, optional) – Observation points. If provided, must have shape (n, d). Current defaults are dataset-agnostic; this argument is reserved for future dataset-conditioned policies.
Returns:: Dictionary with keys gamma, sigma2_coverage, alpha, rho_min_range_factor.
Return type:: dict

set_default_prior_hyperparameters¶

gpmp.kernel.prior_defaults.set_default_prior_hyperparameters(*, gamma=None, sigma2_coverage=None, alpha=None, rho_min_range_factor=None)[source]¶

Update one or more default prior hyperparameters.

Parameters:

gamma (float, optional) – Multiplicative factor for sigma2 prior calibration. Must be > 1.
sigma2_coverage (float, optional) – Central coverage used for log-variance Gaussian prior calibration. Must be in (0, 1).
alpha (float, optional) – Linear tail slope parameter for logrho prior. Must be > 0.
rho_min_range_factor (float, optional) – Range-based safeguard factor for logrho_min construction. Must be > 0.

Bounds¶

empirical_bounds_factory builds optimizer bounds for parameter-selection procedures from observation ranges and empirical output variance. It is not a prior term, but it is part of the parameter-selection API.

empirical_bounds_factory¶

gpmp.kernel.empirical_bounds_factory(xi, zi, *, mean_paramlength=0, var_lower_factor=2.0, var_upper_factor=10.0, length_lower_factor=2.0)[source]¶

Build empirical optimizer bounds.

The returned bounds follow the parameter vector [mean..., log(sigma2), -log(rho_0), ..., -log(rho_{d-1})].

Parameters:

xi (array_like, shape (n, d)) – Observation points.
zi (array_like, shape (n,) or (n, 1)) – Observations.
mean_paramlength (int, default=0) – Number of leading mean-parameter entries.
var_lower_factor (float, default=2.0) – Multiplicative lower factor applied to the empirical variance.
var_upper_factor (float, default=10.0) – Multiplicative upper factor applied to the empirical variance.
length_lower_factor (float, default=2.0) – Multiplicative factor applied to the smallest nonzero coordinate gap when building the upper bound on -log(rho_j).

Returns:

Lower and upper optimizer bounds.

Return type:

array_like, shape (mean_paramlength + d + 1, 2)