gw.result.Result
gw.result.Result(**kwargs)A dataset class to hold a collection of gravitational-wave parameter samples and perform various operations on them.
Compared to the base class, this class implements the domain, prior, and likelihood. It also includes a method for sampling the binary reference phase parameter based on the other parameters and the likelihood.
Attributes: samples : pd.Dataframe Contains parameter samples, as well as (possibly) log_prob, log_likelihood, weights, log_prior, delta_log_prob_target. domain : Domain The domain of the data (e.g., UniformFrequencyDomain), needed for calculating likelihoods. prior : PriorDict The prior distribution, used for importance sampling. likelihood : Likelihood The Likelihood object, needed for importance sampling. context : dict Context data from which the samples were produced (e.g., strain data, ASDs). metadata : dict Metadata inherited from the Sampler object. This describes the neural networks and sampling settings used. event_metadata : dict Metadata for the event analyzed, including time, data conditioning, channel, and detector information. log_evidence : float Calculated log(evidence) after importance sampling. log_evidence_std : float (property) Standard deviation of the log(evidence) effective_sample_size, n_eff : float (property) Number of effective samples, (_i w_i)^2 / _i w_i^2 sample_efficiency : float (property) Number of effective samples / Number of samples synthetic_phase_kwargs : dict kwargs describing the synthetic phase sampling.
Attributes
| Name | Description |
|---|---|
| approximant | |
| calibration_marginalization_kwargs | |
| calibration_sampling_kwargs | |
| dataset_type | |
| f_ref | |
| interferometers | |
| maximum_frequency | |
| minimum_frequency | |
| pesummary_prior | The prior in a form suitable for PESummary. |
| phase_marginalization_kwargs | |
| synthetic_phase_kwargs | |
| t_ref | |
| time_marginalization_kwargs | |
| use_base_domain |
Methods
| Name | Description |
|---|---|
| get_pesummary_samples | Samples in a form suitable for PESummary. |
| get_samples_bilby_phase | Convert the spin angles phi_jl and theta_jn to account for a difference in |
| sample_calibration_parameters | Sample calibration parameters from the calibration prior and add them to the |
| sample_synthetic_phase | Sample a synthetic phase for the waveform. This is a post-processing step |
| update_prior | Update the prior based on a new dict of priors. Use the existing prior for |
get_pesummary_samples
gw.result.Result.get_pesummary_samples(
num_processes=1,
resampling_method='clip+rejection',
)Samples in a form suitable for PESummary.
These samples are adjusted to undo certain conventions used internally by Dingo: * Times are corrected by the reference time t_ref. * Samples are unweighted, using a fixed random seed for sampling importance resampling. * The spin angles phi_jl and theta_jn are transformed to account for a difference in phase definition. * Some columns are dropped: delta_log_prob_target, log_prob
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| num_processes | int | Number of processes for spin conversion. | 1 |
| resampling_method | str | Method for producing unweighted samples from weighted ones. ‘clip+rejection’: clip extreme weights then rejection sample (default). ‘sir’: sampling importance resampling (old behavior). | 'clip+rejection' |
get_samples_bilby_phase
gw.result.Result.get_samples_bilby_phase(num_processes=1)Convert the spin angles phi_jl and theta_jn to account for a difference in phase definition compared to Bilby.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| num_processes | Number of parallel processes. | 1 |
Returns
| Name | Type | Description |
|---|---|---|
| pd.DataFrame | Samples |
sample_calibration_parameters
gw.result.Result.sample_calibration_parameters(calibration_sampling_kwargs)Sample calibration parameters from the calibration prior and add them to the samples DataFrame. Also updates self.prior with the calibration priors and adjusts self.samples[“log_prob”] accordingly.
This should be called before importance_sample() when importance sampling over calibration uncertainty. The calibration prior log_prob is added to self.samples[“log_prob”] so that it is properly accounted for in the importance sampling weights.
After calling this method, each sample will have calibration parameters (e.g., recalib_H1_amplitude_0, recalib_H1_phase_0, etc.) that will be used by the likelihood to apply calibration corrections.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| calibration_sampling_kwargs | dict | Calibration sampling parameters. Keys: calibration_envelope : dict Dictionary of the form {“H1”: filepath, “L1”: filepath, …} with locations of calibration envelope files (.txt). num_calibration_nodes : int Number of log-spaced frequency nodes for the calibration spline model. correction_type : str or dict or None, default “data” Whether envelopes are over eta (“data”) or alpha (“template”). Can be a string (applied to all detectors), a dict mapping ifo names to correction types, or None (uses defaults from CALIBRATION_CORRECTION_TYPE_LOOKUP). | required |
sample_synthetic_phase
gw.result.Result.sample_synthetic_phase(synthetic_phase_kwargs, inverse=False)Sample a synthetic phase for the waveform. This is a post-processing step applicable to samples theta in the full parameter space, except for the phase parameter (i.e., 14D samples). This step adds a phase parameter to the samples based on likelihood evaluations.
A synthetic phase is sampled as follows.
* Compute and cache the modes for the waveform mu(theta, phase=0) for
phase 0, organize them such that each contribution m transforms as
exp(-i * m * phase).
* Compute the likelihood on a phase grid, by computing mu(theta, phase) from
the cached modes. In principle this likelihood is exact, however, it can
deviate slightly from the likelihood computed without cached modes for
various technical reasons (e.g., slightly different windowing of cached
modes compared to full waveform when transforming TD waveform to FD).
These small deviations can be fully accounted for by importance sampling.
*Note*: when approximation_22_mode=True, the entire waveform is assumed
to transform as exp(2i*phase), in which case the likelihood is only exact
if the waveform is fully dominated by the (2, 2) mode.
* Build a synthetic conditional phase distribution based on this grid. We
use an interpolated prior distribution bilby.core.prior.Interped,
such that we can sample and also evaluate the log_prob. We add a constant
background with weight self.synthetic_phase_kwargs to the kde to make
sure that we keep a mass-covering property. With this, the importance
sampling will yield exact results even when the synthetic phase conditional
is just an approximation.Besides adding phase samples to self.samples[‘phase’], this method also modifies self.samples[‘log_prob’] by adding the log_prob of the synthetic phase conditional.
This method modifies self.samples in place.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| synthetic_phase_kwargs | dict | This should consist of the kwargs approximation_22_mode (optional) num_processes (optional) n_grid uniform_weight (optional) | required |
| inverse | bool | Whether to apply instead the inverse transformation. This is used prior to calculating the log_prob. In inverse mode, the posterior probability over phase is calculated for given samples. It is stored in self.samples[ ‘log_prob’]. | False |
update_prior
gw.result.Result.update_prior(prior_update)Update the prior based on a new dict of priors. Use the existing prior for parameters not included in the new dict.
If class samples have not been importance sampled, then save new sample weights based on the new prior. If class samples have been importance sampled, then update the weights.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| prior_update | dict | Priors to update. This should be of the form {key : prior_str}, where str is a string that can instantiate a prior via PriorDict(prior_update). The prior_update is provided in this form so that it can be properly saved with the Result and later instantiated. | required |