Covariance estimation¶
The proposal covariance is the most important ingredient: too narrow and the proposal misses posterior mass, too wide and acceptance collapses. There are two routes for estimating it, plus several options that shape the result.
The two routes (fisher_method)¶
"hessian" (default)¶
Finite-differences the scalar log-posterior at the MAP and inverts the result. Works for any Bilby likelihood. This computes the negative Hessian of the log-posterior — see Background for why this is the observed information (including the prior), not the Fisher matrix.
The Hessian is computed with scipy.differentiate.hessian (adaptive step,
Richardson extrapolation). In unit-cube space (use_unit_cube=True) the parameter
scales are already normalised by the prior CDF transform, and the precision is
floored at the prior precision before inversion (a uniform prior has variance
1/12 in unit-cube coordinates). Because a bounded posterior can never be broader
than its prior, this bounds the covariance by the prior: a noisy, indefinite, or
non-finite curvature estimate degrades gracefully to prior width instead of blowing
up, while well-constrained directions (precision ≫ the prior) are untouched.
hessian_kwargs and maxiter
scipy.differentiate.hessian shrinks the step each iteration
(initial_step / step_factor**k), so a larger maxiter reaches a smaller
final step. On a numerically noisy objective (e.g. a marginalised likelihood)
an over-small step is dominated by round-off and the curvature estimate
degrades — more iterations is not automatically better. The prior floor above
keeps such a degraded estimate bounded, but the accurate regime is a step that
is a modest fraction of the posterior width, not the smallest possible.
"waveform" (gravitational-wave likelihoods)¶
Builds the genuine Fisher matrix
from derivatives of the projected detector strain, where \( (a\mid b) \) is the noise-weighted inner product. This is positive semi-definite by construction, needs only first derivatives of the waveform (far better behaved under finite differencing than a scalar second derivative), and drops the noisy, realisation-dependent term that can make the Hessian indefinite. The result is the likelihood Fisher plus a diagonal prior precision, returned in parameter space.
result = bilby.run_sampler(
likelihood=gw_likelihood, priors=priors, sampler="laplace",
fisher_method="waveform",
fisher_kwargs=dict(eps=1e-6, eps_mass=1e-8), # finite-difference steps
)
Marginalised likelihoods¶
Phase, time, and distance marginalisation are supported. Those parameters are
reinstated in the Fisher — built over the augmented set (your sampled parameters
plus the marginalised ones), evaluated at reference values (the injection where
available and use_injection_for_map=True, otherwise reconstructed from the
likelihood at the MAP) — and then
removed via the Schur complement of the marginalised block. This is equivalent
to inverting the full precision and keeping the sampled-parameter sub-block, i.e.
it marginalises over those parameters (propagating their degeneracies) rather than
conditioning on (fixing) them.
The reduced precision is then floored at the prior precision (the same bound as the
unit-cube Hessian path, generalised to parameter space by rescaling with the prior
standard deviation width / sqrt(12)), so no marginal variance can exceed the prior.
Detector-based sky frames are handled: if the likelihood samples zenith/azimuth
(via reference_frame), the Fisher applies the likelihood's own conversion to
ra/dec at each finite-difference point, so those parameters are constrained
correctly rather than appearing as null directions.
Accuracy of the marginalised block
The Schur complement reproduces the analytic marginalisation exactly only where
the joint posterior is Gaussian in the marginalised parameters. Distance and time
are usually well-behaved; phase is not — it is periodic and often poorly
constrained, so its Gaussian approximation is weak and parameters degenerate with
it (notably the polarisation angle psi) tend to be only prior-constrained. The
prior floor keeps these bounded at prior width rather than letting them run away,
but if you need such a parameter tightly constrained, prefer
fisher_method="hessian", which differentiates the actual marginalised
likelihood.
Requirements and limitations
fisher_method="waveform" requires a GravitationalWaveTransient-like
likelihood (exposing interferometers and waveform_generator). It refuses:
- calibration marginalisation — it integrates a discrete calibration index, not a continuous Fisher direction;
- ROQ and multi-banded likelihoods, whose inner product differs from the full-resolution one used here.
Relative-binning likelihoods are supported: the Fisher is built on the full frequency grid.
It works directly in parameter space, so use_unit_cube and
jacobian_cap_scale are ignored.
Conditioning¶
Before inversion the precision is diagonally preconditioned (rescaled by \( \sqrt{\mathrm{diag}} \) to near-unit diagonal). This removes scale-driven ill-conditioning — most effective in the parameter-space path, where raw parameter scales differ by orders of magnitude. Small or negative eigenvalues are then floored at a relative threshold, which keeps poorly-constrained or indefinite directions wide (the right behaviour for a proposal) rather than zeroing them out. The before/after condition number is logged.
In the unit-cube path this relative floor is a secondary safety net: the precision has already been floored at the prior precision (see above), so those directions are bounded at prior width rather than left arbitrarily wide.
Shaping the proposal¶
| Option | Effect |
|---|---|
cov_scaling |
Multiplies the covariance (each value scales a parameter's variance, so 4 widens its sigma by 2x). Pass a scalar to scale everything uniformly, or a dict like {'chirp_mass': 4.0} for per-parameter scaling (unlisted parameters default to 1.0, or use the reserved 'others' key to set that default, e.g. {'chirp_mass': 4.0, 'others': 2.0}). Off-diagonal terms scale by sqrt(v_i*v_j), preserving correlations. Increase to widen the proposal when acceptance is low or the posterior is wider than the Gaussian predicts. |
sampling_cov |
Bypass estimation entirely and supply a precomputed covariance (see below). |
jacobian_cap_scale |
(Hessian unit-cube path) Caps each parameter's Jacobian p(θ) at jacobian_cap_scale / prior_width when mapping the unit-cube precision back to parameter space. The cap applies wherever the prior density at the MAP exceeds it, and widens that parameter's covariance; values <1 widen further. |
prior_parameters |
Replace the proposal for listed parameters with independent prior draws — for parameters whose posterior is essentially the prior and which the Hessian constrains poorly. |
proposal_covariance |
How the Gaussian becomes the proposal. "diagonal" draws each parameter independently with its Laplace marginal width, dropping the correlations, which makes a wider, defensive seed. "full" draws the full correlated Gaussian, discarding draws outside the prior box. The default (None) is "full" for resample="inprior", whose output is the proposal, and "diagonal" for every method that corrects it (rejection, importance, smc, emcee). "full" is incompatible with prior_parameters. |
hessian_kwargs |
Forwarded to scipy.differentiate.hessian (e.g. initial_step). |
Additionally, the Hessian-derived covariance is validated along its principal axes: at 1-sigma from the MAP the log-likelihood should drop by 0.5; directions where the posterior is notably wider are inflated to match (never shrunk).
Supplying your own covariance (sampling_cov)¶
If you already have a covariance — for example from a gwfast or GWFish Fisher analysis — pass it directly and skip the MAP-based estimate of the matrix (the MAP search still runs for the mean):
import pandas as pd
# Either a parameter-named DataFrame...
cov_df = pd.DataFrame(C, index=parameter_names, columns=parameter_names)
result = bilby.run_sampler(..., sampler="laplace", sampling_cov=cov_df)
# ...or a (names, matrix) tuple
result = bilby.run_sampler(..., sampler="laplace", sampling_cov=(parameter_names, C))
The names are validated against the model parameters (missing/extra/duplicate names,
wrong shape, non-symmetry, and non-positive-semi-definiteness all raise up front).
cov_scaling and the covariance validation still apply. Not compatible with
n_modes > 1.