Settings

Various settings in dolfen can be configured, although the default settings should be acceptable for use with systems that roughly comply with the description of the ideal sort of system dolfen is designed for (i.e., slow evolution signals consisting of a large number of datapoints). Some understanding of the background theory is required to know how changing the settings could affect the accuracy of dolfen’s representation of the likelihood, for example, uniform downsampling can be expected to lead to aliasing.

All settings are passed when creating an instance of likelihood. The most important settings are the number of samples, the downsampling scheme (how to select remaining datapoints) and method (approximate FIM preservation, or using FIM Jeffreys’ divergence minimisation), and the MCS override - see more details in the API below.

API and standard configuration

These are general settings which apply to the whole algorithm and are parsed to likelihood. However some of these settings, such as prsrv_FIM which defines what method is used, will affect the ability to find solutions given the number of samples chosen.

class dolfen.likelihood(t, model, inj_params, PSD, priors, numsamps=400, scheme='rand', prsrv_FIM=None, MCS_override=0, addnoise=False, f_low_cut=0.0, f_high_cut=0.0, GWmodel_margphase=None, blocksize=1, param_diffs=None, save_load_FIM=True, overwritesavedFIM=False, phase_int_points=2357, resume_dir='', numprocs=0, forcerun=False)

The ‘downsampled’ approximation of the Bayesian likelihood function defined by the signal and noise models, and injection parameters.

Parameters

t1D numpy array: The set of time-stamps of the ‘original’ dataset, sampled at least at the Nyquist frequency of all waveforms with non-negligible probability (just above the Nyquist frequency of the injected signal should do).
modelcallable: The user-defined waveform model, the first argument must be the times-stamps, t.
inj_paramsdict: The signal’s injection parameters for each parameter of the signal model: key=param name, value=param value.
PSDcallable: The ‘Power Spectral Density’, a function of frequency, f. This encodes the noise model. Must return 1D array when passed a 1D array.
priorsdict: The parameters (dict keys) and the priors (values). If the parameter is known the prior should be a float, otherwise it should be an object with a “.minimum” and a “.maximum” property.
numsampsint: The number of datapoints to use for downsampling.
schemestring: The ‘downsampling scheme’ that should be employed by dolfen. Currently accepted schemes are

“rand”: random downsampling;

“unif”: uniform downsampling (a.k.a. decimation);

“hybrid”: a 50/50 split of uniform and random downsampling;

“cluster,n”: random samples are taken from ‘n’ uniformly spaced blocks of size ‘blocksize’. if n is not specified, n is set to the number of model parameters;

“prand”: ‘pseudo-random’ downsampling. Mainly used for testing dolfen, for any given system, a seed is fixed for random sample selection.
prsrv_FIMBool: True to use the (approximate) FIM preservation method of downsampling. This is the most accurate method. False to use the minimisation of Jeffreys’ divergence of the FIMs of fully- and down-sampled datasets. If not supplied, dolfen will try to find FIM preservation solutions a number of times, then revert to FIM Jeffreys’ divergence minimisation if no solution can be found.
MCS_overrideint: The number of maximum correlated samples of any given sample as determined by the inverse autocorrelation function. Minimum 1; a value <1 means dolfen will automatically compute this.
addnoiseBool: True to add a random noise realisation to the data from the PSD.
f_low_cut, f_high_cutfloats: Lowest and highest frequencies at which the PSD is irrelevant to the likelihood; the PSD below f_low_cut is set equal to the PSD at f_low_cut, the PSD above f_high_cut is set equal to the PSD at f_high_cut.
GWmodel_margphasecallable: Dolfen was created for studying likelihoods of gravitational waves of low-mass CBCs in LISA. Numerically marginalising the phase of the time-domain CBC GW waveform is possible as per the example included with dolfen; the model is required to separately return the plus and cross GW polarisations so that the phase marginalised likelihood can be computed quickly.
blocksizeint: For use with “cluster” downsampling; size of blocks from which to sample
param_diffslist: The step-sizes for numerical derivatives of signal model with respect to its parameters, in case dolfen has difficulty in automatically computing them.
save_load_FIMBool: True if one wishes to write to disk the computed Fisher matrix and derivative step-sizes.
overwritesavedFIMBool: If FIM data has already been saved to disk, overwrite it.
phase_int_pointsint: The number of discrete integration points to use for marginalising GW phase.
resume_dirstring: Directory for writing/reading downsampling solution information for given dolfen inputs.
numprocsint: Number of processors to use to compute the Fisher information matrix. Uses all available if not set.
forcerunBool: True to force run even if the MCS is large and downsampling would not be expected to yield a significant reduction in likelihood evaluation time.