population-error

Welcome to the documentation for population-error, a JAX based python package for calculating the information loss due to Monte Carlo approximations in hierarchical inference. This package is intended for use with gravitational-wave population analyses. It is designed to interface easily with gwpopulation, but is designed to be lightweight and flexible enough to interface with any general population analysis scheme.

Contents

Examples

API Reference

population_error.statistics.bilby_model_to_model_function(bilby_model, conversion_function=<function <lambda>>, rate=False, rate_key='rate')[source]

Wrap a Bilby or gwpopulation jax-compatible model into a callable function interface.

Note: if using the rate-full likelihood, this model should return dN/d heta. It should not be in comoving rate density in units Gpc^{-3} yr^{-1}. Instead, it is expected to be in a density in redshift.

Parameters:

  • bilby_model (bilby.hyper.model.Model or callable Model object to be converted. If it is already) – a callable, it is returned unchanged.

  • conversion_function (callable, optional) – Function applied to parameter dictionaries before evaluating the model. Should take a dict of parameters and return (modified_parameters, added_keys).

  • rate (bool, default=False) – Whether to be used with the rate-full hierarchical likelihood.

  • rate_key (string, default='rate') – The key to recognize as N, where N is the total number of mergers in the Universe during the observing time, e.g., dN/d heta = Np( heta | Lambda). This is only used if rate=True and using bilby_model as bilby.hyper.model.Model, as this only returns probability densities.

Returns:

A function with signature (data, parameters) -> probability values, where data is a dictionary of GW parameter samples and parameters are hyperparameters of the population model.

Return type:

callable

population_error.statistics.error_statistics(model_function, injections, event_posteriors, hyperposterior, vt_model_function=None, include_likelihood_correction=True, conversion_function=<function <lambda>>, nobs=None, verbose=True, rate=False, rate_key='rate')[source]

Compute error, precision, and accuracy statistics from model, hyperposterior, and data.

Parameters:

  • model_function (bilby.hyper.model.Model, callable) – Population model with interface (dataset, parameters) -> probabilities.

  • injections (dict) – Injection dataset, including ‘prior’ and ‘total_generated’ keys.

  • event_posteriors (dict) – Event posterior samples, including ‘prior’ key.

  • hyperposterior (pandas.DataFrame or dict of jnp.ndarray) – If pandas.DataFrame, converts to appropriate format. Otherwise, hyperposterior samples with keys as hyperparameters, and values are jnp.ndarray with first dimension indexing the hyperposterior sample

  • vt_model_function (bilby.hyper.model.Model, callable, optional) – Optional separate model instance for evaluating the selection function. Population model with interface (dataset, parameters) -> probabilities. If not included, set to model_function

  • include_likelihood_correction (bool, default=True) – Whether to include likelihood correction in accuracy estimate. Set to False if the hyperlikelihood for sampling from the posterior was estimated using the unbiased likelihood of Eq. 24 of https://arxiv.org/abs/2509.07221

  • conversion_function (callable, optional) – Function to convert hyperposterior parameters before model evaluation.

  • nobs (int, optional) – Number of observed events. If None, inferred from event_posteriors.

  • verbose (bool, default=True) – Whether to print progress and summary messages.

  • rate (bool, default=False) – Whether to treat the VT weights as rate-weighted. TESTTHIS!!!

  • rate_key (string, default='rate') – The key which to access the overall merger rate within the posterior.

Returns:

Dictionary with keys: - ‘error_statistic’ : float, total information loss in bits. - ‘precision_statistic’ : float, information loss due to variance. - ‘accuracy_statistic’ : float, information loss due to bias.

Return type:

dict

population_error.statistics.error_statistics_from_weights(vt_weights, event_weights, total_generated, include_likelihood_correction=True)[source]

Compute error statistics for hyperposterior, Eqs. 36-39 of arxiv:2509.07221

Parameters:

  • vt_weights (jnp.ndarray) – Array of shape (n_samples, n_injections), injection weights per hyperposterior sample.

  • event_weights (jnp.ndarray) – Array of shape (n_samples, n_obs, n_pe), event posterior weights per hyperposterior sample.

  • total_generated (int or float) – Total number of injections.

  • include_likelihood_correction (bool, default=True) – Whether to include the likelihood correction term in the accuracy statistic. Set to True if inference did not include the likelihood correction term, set to False if inference did include the likelihood correction.

Returns:

(precision, accuracy, error), where: - precision : float

Expected information lost to uncertainty in posterior estimator.

  • accuracyfloat

    Expected information lost to bias in posterior estimator

  • errorfloat

    Expected information lost to both bias and uncertainty in posterior estimator.

Return type:

tuple of floats

population_error.statistics.event_log_covariances(event_pe_weights_n, event_pe_weights_m)[source]

Compute covariances of log Bayes factors between two sets of event weights.

Parameters:

  • event_pe_weights_n (jnp.ndarray) – First array of event posterior sample weights, shape (Nobs, NPE).

  • event_pe_weights_m (jnp.ndarray) – Second array of event posterior sample weights (same shape as above).

Returns:

Covariances per event, shape (Nobs,).

Return type:

jnp.ndarray

population_error.statistics.format_hyperposterior(hyperposterior)[source]
population_error.statistics.likelihood_log_correction(weights, total_generated, Nobs)[source]

Compute the likelihood log-correction term for variance estimation.

Parameters:

  • weights (jnp.ndarray) – Importance weights for injection samples.

  • total_generated (int or float) – Total number of injections.

  • Nobs (int) – Number of observed events.

Returns:

Likelihood log-correction value.

Return type:

float

population_error.statistics.log_likelihood_covariance(vt_weights_n, vt_weights_m, event_pe_weights_n, event_pe_weights_m, total_generated)[source]

Compute covariance of log-likelihood estimates from injection and event weights.

Parameters:

  • vt_weights_n (jnp.ndarray) – Injection weights for the first hyperposterior sample.

  • vt_weights_m (jnp.ndarray) – Injection weights for the second hyperposterior sample.

  • event_pe_weights_n (jnp.ndarray) – Event posterior weights for the first sample, shape (Nobs, NPE).

  • event_pe_weights_m (jnp.ndarray) – Event posterior weights for the second sample, shape (Nobs, NPE).

  • total_generated (int or float) – Total number of injections.

Returns:

Log-likelihood covariance estimate.

Return type:

float

population_error.statistics.reweighted_event_bayes_factors(event_pe_weights)[source]

Compute reweighted Bayes factors for a set of events.

Parameters:

event_pe_weights (jnp.ndarray) – Array of shape (Nobs, NPE) with posterior sample weights per event.

Returns:

Array of mean Bayes factors per event, shape (Nobs,).

Return type:

jnp.ndarray

population_error.statistics.selection_function(weights, total_generated)[source]

Compute the selection function given weights and total number of injections.

Parameters:

  • weights (jnp.ndarray) – Array of importance weights for injection samples.

  • total_generated (int or float) – Total number of injections.

Returns:

Estimated selection function value (mean weight normalized by total samples).

Return type:

float

population_error.statistics.selection_function_log_covariance(weights_n, weights_m, total_generated)[source]

Compute the covariance of log selection functions between two weight sets.

Parameters:

  • weights_n (jnp.ndarray) – First set of importance weights.

  • weights_m (jnp.ndarray) – Second set of importance weights (must match shape of weights_n).

  • total_generated (int or float) – Total number of injections.

Returns:

Covariance between log selection function estimates.

Return type:

float