cogwheel.likelihood.reference_waveform_finder.ReferenceWaveformFinder

class cogwheel.likelihood.reference_waveform_finder.ReferenceWaveformFinder(event_data, waveform_generator, par_dic_0, fbin=None, pn_phase_tol=None, spline_degree=3, time_range=(-0.25, 0.25), mchirp_range=None)

Bases: RelativeBinningLikelihood

Find parameters of a high-likelihood solution.

Some simplfying restrictions are placed, for speed:

• (2, 2) mode

• Aligned, equal spins

• Inclination = 1 radian

• Polarization = 0

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.

time_range(float, float)

Minimum and maximum times to search relative to tgps (s).

Methods

compute_asd_drift	Estimate local standard deviation of the matched-filter output at the time of the event for each detector.
find_bestfit_pars	Find a good fit solution with restricted parameters (face-on, equal aligned spins).
from_event	Constructor that finds a reference waveform solution automatically by maximizing the likelihood.
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	Return dictionary of ancillary information ("blob").
get_coordinate_system_kwargs	Return dictionary with parameters commonly required to set up coordinate system for sampling.
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	Return log likelihood using relative binning.
lnlike_detectors_no_asd_drift	Return an array of length n_detectors with the values of (d|h) - (h|h)/2, no ASD-drift correction applied, using relative binning.
lnlike_fft	Return log likelihood computed on the FFT grid, without using relative binning.
lnlike_max_amp_phase	Return log likelihood maximized over amplitude and phase coherently across detectors (the same amplitude rescaling and phase are applied to all detectors).
lnlike_max_amp_phase_time	Return log likelihood maximized over amplitude, phase and time incoherently across detectors.
plot_whitened_wf	Plot the whitened strain and waveform model in the time domain in all detectors.
postprocess_samples	Placeholder method that will be called after sampling and may be overriden by subclasses.
reinstantiate	Return a new instance of the class, possibly updating init_kwargs.
set_mchirp_range	Set ._mchirp_range automatically.
to_json	Write class instance to json file.

Attributes

asd_drift	Array of length ndetectors with ASD drift-correction.
chieff_range
eta_range
fbin	Edges of the frequency bins for relative binning [Hz].
mchirp_range	If self._mchirp_range is set return that, otherwise return a crude estimate based on the reference waveform's chirp mass.
par_dic_0	Dictionary with reference waveform parameters.
params	Parameters expected in par_dic for likelihood evaluation.
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
time_range	Minimum and maximum times to search relative to tgps (s).

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.

find_bestfit_pars(seed=0, freeze_f_ref=False)

Find a good fit solution with restricted parameters (face-on, equal aligned spins). Additionally, use that to set self.mchirp_range if it has not been set already. Will update self.par_dic_0 in stages. The relative binning summary data (and asd_drift) will be updated after maximizing over intrinsic parameters.

First maximize likelihood incoherently w.r.t. intrinsic parameters using mchirp, eta, chieff. Then maximize likelihood w.r.t. extrinsic parameters, leaving the intrinsic fixed. Speed is prioritized over quality of the maximization. Use Posterior.refine_reference_waveform() to refine the solution if needed.

Parameters:

seed

To initialize the random state of stochastic maximizers.

classmethod from_event(event, mchirp_guess, approximant='IMRPhenomXAS', pn_phase_tol=0.02, spline_degree=3, time_range=(-0.25, 0.25), mchirp_range=None, f_ref=None)

Constructor that finds a reference waveform solution automatically by maximizing the likelihood.

For injections with aligned spin, it will skip the maximization and simply use the injected waveform (except that equal-mass and face-on configurations are avoided, as they do not have all harmonics).

Parameters:

eventdata.EventData or str

String may be an event name (must correspond to a file in data.DATADIR), or a path to a .npz file with an EventData instance.

mchirp_guessfloat

Estimate of the detector-frame chirp mass of the signal.

approximantstr

Approximant name.

pn_phase_tolfloat

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

spline_degreeint

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

time_range(float, float)

Range of arrival times relative to tgps to explore (s). (tgps is given by the data.EventData instance created from event.)

mchirp_range(float, float), optional.

Range of chirp mass to explore (Msun). If not provided, an automatic choice will be made (see method set_mchirp_range).

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)

Return dictionary of ancillary information (“blob”). This will be appended to the posterior samples as extra columns.

get_coordinate_system_kwargs()

Return dictionary with parameters commonly required to set up coordinate system for sampling. Can be used to instantiate some classes defined in cogwheel.gw_prior.

Returns:

dictionary with entries for:

• tgps

• par_dic_0

• f_avg

• f_ref

• ref_det_name

• detector_pair

• t0_refdet

• mchirp_range

• event_data

• approximant

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)

Return log likelihood using relative binning.

lnlike_detectors_no_asd_drift(par_dic)

Return an array of length n_detectors with the values of (d|h) - (h|h)/2, no ASD-drift correction applied, using relative binning.

Parameters:

par_dicdict

Waveform parameters, keys should match self.params.

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.

lnlike_max_amp_phase(par_dic, ret_amp_phase_bf=False, det_inds=Ellipsis)

Return log likelihood maximized over amplitude and phase coherently across detectors (the same amplitude rescaling and phase are applied to all detectors).

lnlike_max_amp_phase_time(par_dic, return_by_detectors=False)

Return log likelihood maximized over amplitude, phase and time incoherently across detectors.

property mchirp_range

If self._mchirp_range is set return that, otherwise return a crude estimate based on the reference waveform’s chirp mass.

See also

set_mchirp_range

property par_dic_0

Dictionary with reference waveform parameters.

property params

Parameters expected in par_dic for likelihood evaluation.

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)

Placeholder method that will be called after sampling and may be overriden by subclasses. (E.g. marginalized likelihoods demarginalize the distribution in postprocessing.)

Parameters:

samplespandas.DataFrame

Rows are samples, columns must contain .params.

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.

set_mchirp_range(lnl_drop=5.0, max_doublings=2, seed=0)

Set ._mchirp_range automatically.

Set self._mchirp_range as (mchirp_min, mchirp_max), bounds for the chirp mass that are deemed safe for parameter estimation bounds. The criterion is that the incoherent likelihood maximized over (eta, chieff) drops by at least lnl_drop of its value for the reference waveform. Note this can give wrong results if the reference waveform is not close to maximum likelihood, or the likelihood is multimodal as a function of chirp mass. The chirp-mass range is expanded (roughly doubled) a maximum number of times given by max_doublings, if this is reached a warning is issued.

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.

property time_range

Minimum and maximum times to search relative to tgps (s).

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.