cogwheel.likelihood.marginalized_extrinsic.MarginalizedExtrinsicLikelihood

class cogwheel.likelihood.marginalized_extrinsic.MarginalizedExtrinsicLikelihood(event_data, waveform_generator, par_dic_0, fbin=None, pn_phase_tol=None, spline_degree=3, t_range=(-0.07, 0.07), coherent_score=None, dlnl_marginalized_threshold=30.0)

Bases: BaseMarginalizedExtrinsicLikelihood

Class to evaluate the likelihood marginalized over sky location, time of arrival, polarization, distance and orbital phase for quasicircular waveforms with generic harmonic modes and spins, and to resample these parameters from the conditional posterior for demarginalization in postprocessing.

Parameters:

event_datadata.EventData

waveform_generatorwaveform.WaveformGenerator

par_dic_0dict

Parameters of the reference waveform, should be close to the maximum likelihood waveform. Keys should match self.waveform_generator.params.

fbin1-d array or None

Array with edges of the frequency bins used for relative binning [Hz]. Alternatively, pass pn_phase_tol.

pn_phase_tolfloat or None

Tolerance in the post-Newtonian phase [rad] used for defining frequency bins. Alternatively, pass fbin.

spline_degreeint

Degree of the spline used to interpolate the ratio between waveform and reference waveform for relative binning.

t_range2-tuple of floats

Bounds of a time range (s) over which to compute matched-filtering series, relative to event_data.tgps + par_dic_0['t_geocenter'].

coherent_scoreCoherentScoreHM or CoherentScoreQAS, or dict

Instance of coherent score, optional. If a dict is passed, it is interpreted as keyword arguments to create one automatically. None (default) will create one with default settings.

dlnl_marginalized_thresholdfloat

The extrinsic marginalization will not be refined further if at some point the estimate is lower than the maximum previously observed lnl_marginalized by more than this amount (so as not to waste computation on low likelihood points). Use conservatively since the estimate of lnl_marginalized may be noisy.

Methods

compute_asd_drift	Estimate local standard deviation of the matched-filter output at the time of the event for each detector.
from_reference_waveform_finder	Instantiate with help from a ReferenceWaveformFinder instance, which provides waveform_generator, event_data and par_dic_0 objects.
get_average_frequency	Return average frequency in Hz.
get_blob	Draw a sample of extrinsic parameters from the conditional posterior.
get_init_dict	Return keyword arguments to reproduce the class instance.
get_module_name	Name of the module that defines the instance's class.
lnlike	Return log-likelihood (float).
lnlike_and_metadata	Natural log of the likelihood marginalized over extrinsic parameters (sky location, time of arrival, polarization, distance and orbital phase).
lnlike_fft	Return log likelihood computed on the FFT grid, without using relative binning.
optimize_beta_temperature	Set .coherent_score.beta_temperature to a value that optimizes the importance sampling efficiency (for the intrinsic parameter values in par_dic).
plot_whitened_wf	Plot the whitened strain and waveform model in the time domain in all detectors.
postprocess_samples	Add extrinsic parameter samples to given intrinsic parameters, with values taken randomly from the conditional posterior.
reinstantiate	Return a new instance of the class, possibly updating init_kwargs.
to_json	Write class instance to json file.

Attributes

asd_drift	Array of length ndetectors with ASD drift-correction.
fbin	Edges of the frequency bins for relative binning [Hz].
par_dic_0	Dictionary with reference waveform parameters.
params
pn_phase_tol	Tolerance in the post-Newtonian phase [rad] used for defining frequency bins.
spline_degree	Integer between 1 and 5, degree of the spline used to interpolate waveform ratios.
subclass_registry

property asd_drift

Array of length ndetectors with ASD drift-correction.

Values > 1 mean local noise variance is higher than average.

compute_asd_drift(par_dic, tol=0.02, max_tcorr_contiguous_low=16.0, **kwargs)

Estimate local standard deviation of the matched-filter output at the time of the event for each detector.

Note: all harmonic_modes of the approximant are used even if waveform_generator.harmonic_modes is set differently. This is so that asd_drift does not change and one can make apples-to- apples comparisons of the likelihood toggling harmonic modes on and off.

Parameters:

par_dicdict

Waveform parameters, keys should match self.waveform_generator.params.

tolfloat

Stochastic measurement error tolerance, used to decide the number of samples.

max_tcorr_contiguous_lowfloat

Maximum number of contiguous correlation times with values below the average noise level to allow (these are classified as a hole and disregarded in the average).

**kwargs

Passed to safe_std, keys include: expected_high, reject_nearby.

property fbin

Edges of the frequency bins for relative binning [Hz]. Setting this will automatically round them to fall in the FFT array, recompute the splines and summary data, and set ._pn_phase_tol to None to keep logs clean.

classmethod from_reference_waveform_finder(reference_waveform_finder, approximant, fbin=None, pn_phase_tol=0.05, spline_degree=3, **kwargs)

Instantiate with help from a ReferenceWaveformFinder instance, which provides waveform_generator, event_data and par_dic_0 objects.

Parameters:

reference_waveform_finderlikelihood.ReferenceWaveformFinder

approximantstr

Approximant name.

fbin1-d array or None

Array with edges of the frequency bins used for relative binning [Hz]. Alternatively, pass pn_phase_tol.

pn_phase_tolfloat or None

Tolerance in the post-Newtonian phase [rad] used for defining frequency bins. Alternatively, pass fbin.

spline_degreeint

Degree of the spline used to interpolate the ratio between waveform and reference waveform for relative binning.

**kwargs

Keyword arguments, in case a subclass needs them.

Returns:

Instance of cls.

get_average_frequency(par_dic, ref_det_name=None, moment=1.0)

Return average frequency in Hz.

The average frequency is defined as (avg(f^moment))^(1/moment) where avg is the frequency-domain average with weight ~ |h(f)|^2 / PSD(f).

The answer is rounded to nearest Hz to ease reporting.

Parameters:

par_dicdict

Waveform parameters, keys should match self.waveform_generator.params.

ref_det_namestr or None

Name of the detector from which to get the PSD, e.g. ‘H’ for Hanford, or None (default) to combine the PSDs of all detectors.

momentnonzero float

Controls the frequency weights in the average.

get_blob(metadata)

Draw a sample of extrinsic parameters from the conditional posterior.

Parameters:

metadataMarginalizationInfo

Second output of .lnlike_and_metadata

Returns:

dict with extrinsic parameters.

get_init_dict(**kwargs)

Return keyword arguments to reproduce the class instance.

get_module_name()

Name of the module that defines the instance’s class.

lnlike(par_dic)

Return log-likelihood (float). Mainly for backwards compatibility.

lnlike_and_metadata(par_dic)

Natural log of the likelihood marginalized over extrinsic parameters (sky location, time of arrival, polarization, distance and orbital phase).

This quantity is estimated via Quasi Monte Carlo integration so it is not deterministic (calling the method twice with the same parameters does not produce the same answer).

Side effects: Updates ._max_lnl_marginalized and ._t_arrival_prob.

Parameters:

par_dicdict

Must contain keys for all .params.

Returns:

lnlikefloat

Log of the marginalized likelihood.

lnlike_fft(par_dic)

Return log likelihood computed on the FFT grid, without using relative binning.

Parameters:

par_dicdict

Waveform parameters, keys should match self.waveform_generator.params.

optimize_beta_temperature(par_dic)

Set .coherent_score.beta_temperature to a value that optimizes the importance sampling efficiency (for the intrinsic parameter values in par_dic).

property par_dic_0

Dictionary with reference waveform parameters.

plot_whitened_wf(par_dic, trng=(-0.7, 0.1), plot_data=True, fig=None, figsize=None, by_m=False, **wf_plot_kwargs)

Plot the whitened strain and waveform model in the time domain in all detectors.

Parameters:

par_dicdict

Waveform parameters, keys should match self.waveform_generator.params.

trng(float, float)

Range of time to plot relative to self.tgps (s).

plot_databool

Whether to include detector data in plot.

figmatplotlib.figure.Figure, optional

None (default) creates a new figure.

figsize(float, float)

Figure width and height in inches, used if fig=None.

**wf_plot_kwargs

Keyword arguments passed to plt.plot() for waveform. Additionally, keyword arguments for the data plot can be passed as a dict data_plot_kwargs.

Returns:

matplotlib.figure.Figure

Figure with plots.

property pn_phase_tol

Tolerance in the post-Newtonian phase [rad] used for defining frequency bins. Setting this will recompute frequency bins such that across each frequency bin the change in the post-Newtonian waveform phase with respect to the fiducial waveform is bounded by pn_phase_tol [rad].

postprocess_samples(samples: DataFrame, num=None)

Add extrinsic parameter samples to given intrinsic parameters, with values taken randomly from the conditional posterior. samples is edited in-place.

Parameters:

samplespd.DataFrame

Dataframe of intrinsic parameter samples, needs to have columns for all self.params.

numNone (default) or int

How many extrinsic parameters to draw for every intrinsic. If None, columns for extrinsic parameters are added to samples. If an int, rows are added so that the total is num * len(samples). Each intrinsic parameter value will be repeated num times. The index will not be preserved.

reinstantiate(**new_init_kwargs)

Return a new instance of the class, possibly updating init_kwargs.

Values not passed will be taken from the current instance.

property spline_degree

Integer between 1 and 5, degree of the spline used to interpolate waveform ratios. Editing it will automatically recompute the splines and summary data.

to_json(dirname, basename=None, *, dir_permissions=493, file_permissions=420, overwrite=False)

Write class instance to json file.

It can then be loaded with read_json.