gwkokab.analysis.core.synthetic_events¶

Drawing a synthetic population of compact binary coalescences.

The first step of the end-to-end workflow. Given a population model and its true hyper-parameters, SyntheticEventsBase draws the number of detections from a Poisson distribution with the model’s own expected rate, then draws that many events from the model and thins them by the selection function – so the saved population is what a search would actually have recovered, not what the universe contains.

The output HDF5 keeps both: the events that survive selection and the buffer_events they were drawn from, with the indices and resampling weights linking them, so the effect of the selection function can be inspected afterwards.

See also

gwkokab.analysis.core.synthetic_pe

The next step, which blurs these true events into mock PE samples.

Classes¶

SyntheticEventsBase

Base class for the synthetic_events_<family> console scripts.

Functions¶

injection_generator_parser(→ argparse.ArgumentParser)

Build the command line argument parser shared by the population generators.

Module Contents¶

class gwkokab.analysis.core.synthetic_events.SyntheticEventsBase(filename: str, model_fn: collections.abc.Callable[..., gwkokab.models.utils.ScaledMixture], model_params_filename: str, poisson_mean_filename: str, n_buffer_events: int, derive_parameters: bool = False)¶

Bases: gwkokab.analysis.core.utils.PRNGKeyMixin, abc.ABC

Base class for the synthetic_events_<family> console scripts.

Subclasses supply the parameters and model_parameters properties, which name the event coordinates and the population hyper-parameters respectively.

See __init__() for the constructor arguments.

Read the true hyper-parameters and instantiate the population model.

Parameters:

  • filename (str) – Destination HDF5 path for the generated population.

  • model_fn (Callable[..., ScaledMixture]) – Factory building the population model from its hyper-parameters.

  • model_params_filename (str) – Path to a JSON file of true hyper-parameter values, keyed by regex in the same way as prior_cfg.json.

  • poisson_mean_filename (str) – Path to pmean_cfg.json, which supplies the selection function.

  • n_buffer_events (int) – Size of the pool drawn from the model before selection. It must exceed the realised number of detections, since events are thinned out of it.

  • derive_parameters (bool) – Derive every reachable parameter with default_relation_mesh() before saving. Defaults to False.

from_inverse_transform_sampling() → None¶

Draw a population and write it out.

The number of detections is itself random: it is drawn from a Poisson distribution whose mean is the expected rate the Poisson mean estimator reports for this model, so the synthetic catalogue has the same statistical character as a real one.

Raises:

LoggedValueError – If the drawn size exceeds n_buffer_events, in which case the buffer must be enlarged, or if the expected rate is non-positive, which points at a misconfigured model or selection function.

modify_model_params(params: dict) → dict¶

Hook for subclasses to modify parameters before model instantiation.

save_population(population: numpy.ndarray, indices: numpy.ndarray, buffer_population: numpy.ndarray, buffer_indices: numpy.ndarray, resample_idx: numpy.ndarray, resample_prob: numpy.ndarray) → None¶

Write the population and its provenance to HDF5.

When derive_parameters is set, every parameter reachable from those drawn is derived first, so downstream steps can use whichever coordinates they prefer.

Parameters:

  • population (np.ndarray) – The events that survived selection.

  • indices (np.ndarray) – Index of the mixture component each surviving event came from.

  • buffer_population (np.ndarray) – The full pool the events were drawn from, before selection.

  • buffer_indices (np.ndarray) – Component index of each pooled event.

  • resample_idx (np.ndarray) – Positions within the pool that were selected.

  • resample_prob (np.ndarray) – Selection weight of each pooled event.

derive_parameters = False¶
filename¶
model_fn¶
property model_parameters: list[str]¶
Abstractmethod:

Returns the model parameters.

Returns:

list of model parameters.

Return type:

list[str]

model_params¶
n_buffer_events¶
property parameters: tuple[str, ...]¶
Abstractmethod:

Returns the parameters (intrinsic + extrinsic).

Returns:

list of parameters.

Return type:

tuple[str, …]

poisson_mean_filename¶
gwkokab.analysis.core.synthetic_events.injection_generator_parser() → argparse.ArgumentParser¶

Build the command line argument parser shared by the population generators.

Also enables NumPyro distribution argument validation, so a physically impossible hyper-parameter in the model parameters file is caught at construction rather than producing NaNs.

Returns:

A parser carrying the input/output, model and selection-function arguments common to every synthetic_events_<family> script.

Return type:

ArgumentParser