Full API

phazap.gw_utils module

phazap.gw_utils.FpFx(det, ra, dec, psi, geocent_time)[source]

Compute antenna pattern functions.

See Eq. A.1 in https://arxiv.org/abs/2308.06616.

Wrap to LAL function ComputeDetAMResponse. See https://docs.ligo.org/lscsoft/lalsuite/lal/antenna_8py_source.html

Parameters:

  • det (str) – detector

  • ra (np.ndarray) – right ascension

  • dec (np.ndarray) – declination

  • psi (np.ndarray) – polarization

  • geocent_time (np.ndarray) – geocentric time

Returns:

  • np.ndarray – Fp antenna pattern function

  • np.ndarray – Fx antenna pattern function

phazap.gw_utils.N_dot_cross_d123(ra, dec, gpstime, d1, d2, d3)[source]

Compute the dot product between the unit vector pointing from the source to geocenter and the cross product between the unit vector pointing from detector 1 to detector 2 and the unit vector pointing from detector 1 to detector 3

See Eq. C1 in https://arxiv.org/abs/2308.06616

Parameters:

  • ra (float) – right ascension

  • dec (float) – declination

  • gpstime (float) – geocentric time

  • d1 (np.ndarray) – detector 1 position

  • d2 (np.ndarray) – detector 2 position

  • d3 (np.ndarray) – detector 3 position

Returns:

dot product

Return type:

float

phazap.gw_utils.N_dot_d12(ra, dec, gpstime, d1, d2)[source]

Compute the dot product between the unit vector pointing from the source to geocenter and the unit vector pointing from detector 1 to detector 2

This is useful to compute the time delay between detector 1 and detector 2 See Eq. 3 in https://arxiv.org/abs/2308.06616

Parameters:

  • ra (float) – right ascension

  • dec (float) – declination

  • gpstime (float) – geocentric time

  • d1 (np.ndarray) – detector 1 position

  • d2 (np.ndarray) – detector 2 position

Returns:

dot product

Return type:

float

phazap.gw_utils.Nvector(source_right_ascension_radians, source_declination_radians, gpstime)[source]

Compute the unit vector pointing from the source to geocenter.

For details see “Source position unit vector” section in page 28 of the PDF in https://dcc.ligo.org/LIGO-T010110/public

For LAL implementation see L53 https://docs.ligo.org/lscsoft/lalsuite/lal/_time_delay_8c_source.html

Parameters:

  • source_right_ascension_radians (float) – right ascension

  • source_declination_radians (float) – declination

  • gpstime (float) – geocentric time

Returns:

unit vector pointing from the source to geocenter

Return type:

np.ndarray

phazap.gw_utils.hp_hx(binary_parameters, waveform_generator)[source]

Generate waveform plus and cross polarizations

Parameters:

  • binary_parameters (dict) – binary parameters

  • waveform_generator (bilby.gw.waveform_generator.WaveformGenerator) – waveform generator

Returns:

  • hp (np.ndarray) – waveform plus polarization

  • hx (np.ndarray) – waveform cross polarization

phazap.gw_utils.time_delay_det(detec, ra, dec, geocent_time)[source]

Compute time delay from Earth center to detector.

Wrap to LAL function TimeDelayFromEarthCenter. See L83 in https://docs.ligo.org/lscsoft/lalsuite/lal/_time_delay_8c_source.html

Parameters:

  • detec (str) – detector

  • ra (float) – right ascension

  • dec (float) – declination

  • geocent_time (float) – geocentric time

Returns:

time delay in seconds

Return type:

float

phazap.gwphase module

phazap.gwphase.chi22_det(Fp, Fx, a22, zeta)[source]

Chi_22 at detector D. See Eq. B10 and B11 of https://arxiv.org/pdf/2308.06616.pdf

Parameters:

  • Fp (np.ndarray) – plus polarization of antenna pattern function

  • Fx (np.ndarray) – cross polarization of antenna pattern function

  • a22 (np.ndarray) – Tangent of beta, the ratio of the semi-major and minor axes. It is a function of the inclination at new frequency. See Eqs. B4 and B14 of https://arxiv.org/pdf/2308.06616.pdf

  • zeta (np.ndarray) – polarization rotation at new frequency. See Eq. B5 of https://arxiv.org/pdf/2308.06616.pdf

Returns:

chi22_det – Chi_22 at detector D. See Eq. B10 and B11 of https://arxiv.org/pdf/2308.06616.pdf

Return type:

np.ndarray

phazap.gwphase.phase_d(phase, a22, zeta, Fp, Fx)[source]

Compute the phase at a detector. For details see Appendix B in https://arxiv.org/pdf/2308.06616.pdf

Parameters:

  • phase (np.ndarray) – phase at new frequency

  • a22 (np.ndarray) – Tangent of beta, the ratio of the semi-major and minor axes. It is a function of the inclination at new frequency. See Eqs. B4 and B14 of https://arxiv.org/pdf/2308.06616.pdf

  • zeta (np.ndarray) – polarization rotation at new frequency. See Eq. B5 of https://arxiv.org/pdf/2308.06616.pdf

  • Fp (np.ndarray) – plus polarization of antenna pattern function

  • Fx (np.ndarray) – cross polarization of antenna pattern function

Returns:

phase_D – phase at detector D at new frequency. See Eq. B11 of https://arxiv.org/pdf/2308.06616.pdf

Return type:

np.ndarray

phazap.gwphase.phases_f_ev(waveform_generator, rang_fs, mass_1=30, mass_2=30, a_1=0, a_2=0, tilt_1=0, tilt_2=0, phi_12=0, phi_jl=0, luminosity_distance=500, theta_jn=0.1, psi=0.1, phase_ref=0.0, geocent_time=0.0, ra=0.0, dec=0.0)[source]

Compute the phase at a new frequencies For details see Appendix B in https://arxiv.org/pdf/2308.06616.pdf

Parameters:

  • waveform_generator (bilby.gw.waveform_generator.WaveformGenerator) – waveform generator

  • rang_fs (np.ndarray) – range of frequencies

  • mass_1 (float) – primary mass

  • mass_2 (float) – secondary mass

  • a_1 (float) – primary aligned spin

  • a_2 (float) – secondary aligned spin

  • tilt_1 (float) – primary spin tilt

  • tilt_2 (float) – secondary spin tilt

  • phi_12 (float) – relative spin phase

  • phi_jl (float) – angle between J and L

  • luminosity_distance (float) – luminosity distance

  • theta_jn (float) – angle between J and N

  • psi (float) – polarization angle

  • phase_ref (float) – phase at reference frequency

  • geocent_time (float) – geocentric time

  • ra (float) – right ascension

  • dec (float) – declination

Returns:

phazap.gwphase.phases_fs(waveform_generator, detec, rang_fs, i_best, mass_1=30, mass_2=30, a_1=0, a_2=0, tilt_1=0, tilt_2=0, phi_12=0, phi_jl=0, luminosity_distance=500, theta_jn=0.1, psi=0.1, phase_ref=0.0, geocent_time=0.0, ra=0.0, dec=0.0, duration=4.0, sampling_frequency=1024.0)[source]

Compute the phase at a new frequency. For details see Appendix B in https://arxiv.org/pdf/2308.06616.pdf

Parameters:

  • waveform_generator (bilby.gw.waveform_generator.WaveformGenerator) – waveform generator

  • detec (str) – detector name

  • rang_fs (np.ndarray) – range of frequencies

  • i_best (int) – index of new frequency

  • mass_1 (float) – primary mass

  • mass_2 (float) – secondary mass

  • a_1 (float) – primary aligned spin

  • a_2 (float) – secondary aligned spin

  • tilt_1 (float) – primary spin tilt

  • tilt_2 (float) – secondary spin tilt

  • phi_12 (float) – relative spin phase

  • phi_jl (float) – angle between J and L

  • luminosity_distance (float) – luminosity distance

  • theta_jn (float) – angle between J and N

  • psi (float) – polarization angle

  • phase_ref (float) – phase at reference frequency

  • geocent_time (float) – geocentric time

  • ra (float) – right ascension

  • dec (float) – declination

  • duration (float) – duration of the signal

  • sampling_frequency (float) – sampling frequency of the signal

Returns:

phazap.gwphase.phases_unwrap(phase_fs)[source]

Unwrap the phase over 2pi period.

Parameters:

phase_fs (np.ndarray) – phase at new frequencies

Returns:

phase_new_fs – unwrapped phase at new frequencies

Return type:

np.ndarray

phazap.pe_input module

class phazap.pe_input.ParameterEstimationInput(posterior_samples, reference_frequency, sampling_frequency, duration, waveform_approximant, ifo_list)[source]

Bases: object

__init__(posterior_samples, reference_frequency, sampling_frequency, duration, waveform_approximant, ifo_list)[source]

A class to store the input for parameter estimation

Parameters:

  • posterior_samples (dict) – A dictionary of posterior samples

  • reference_frequency (float) – Reference frequency chosen for this set of samples

  • sampling_frequency (float) – Sampling frequency

  • duration (float) – Duration

  • waveform_approximant (str) – Waveform approximant

  • ifo_list (list) – List of interferometers

Returns:

The ParameterEstimationInput instance

Return type:

ParameterEstimationInput

classmethod from_PESummary_file(hdf5_file)[source]

Load the parameter estimation input from a PESummary hdf5 file

Parameters:

hdf5_file (str) – Path to the PESummary file

Returns:

The ParameterEstimationInput instance

Return type:

ParameterEstimationInput

classmethod from_bilby_result_file(result_file)[source]

Load the parameter estimation input from a bilby result file

Parameters:

result_file (str) – Path to the result file

Returns:

The ParameterEstimationInput instance

Return type:

ParameterEstimationInput

phazap.phazap module

phazap.phazap.phases_events(event1_postprocessed_phase, event2_postprocessed_phase)[source]

Compute the detector, time-delay and \(\Delta\phi_f\) phases of the two events.

The procedure is described in Sec. 2 of https://arxiv.org/pdf/2308.06616.pdf

Parameters:
Returns:

  • parameters_1 (np.ndarray) – The parameters (det_phase, tau_phase, Dphi_f) of the first event

  • parameters_2 (np.ndarray) – The parameters (det_phase, tau_phase, Dphi_f) of the second event

  • det_phases_1 (np.ndarray) – The detector phases of the first event

  • det_phases_2 (np.ndarray) – The detector phases of the second event

  • tau_phases_1 (np.ndarray) – The time delay phases of the first event

  • tau_phases_2 (np.ndarray) – The time delay phases of the second event

  • Dphi_f_1 (np.ndarray) – The \(\Delta\phi_f\) of the first event

  • Dphi_f_2 (np.ndarray) – The \(\Delta\phi_f\) of the second event

  • above_below (np.ndarray) – The dot product of \(\vec{n}\) with \(\vec{r}_{d_1 d_2} \times \vec{r}_{d_1 d_3}\) the second event where its sign indicates whether the source is above or below the plane of the detectors

phazap.phazap.phazap(event_1, event_2, plot=False, output_dir='./', output_filename=None)[source]

Compute the \(D_J\) statistic, the \(V_J\) statistic, the phase shift, and the \(p\)-value

Parameters:

  • event_1 (str or PostprocessedPhase) – The first event. If it is a string, it should be a file path to either a postprocessed phase file or a PE result file

  • event_2 (str or PostprocessedPhase) – The second event. If it is a string, it should be a file path to either a postprocessed phase file or a PE result file

  • plot (bool, optional) – Whether to plot the results, by default False

  • output_dir (str, optional) – The output directory, by default “./”

  • output_filename (str, optional) – The output filename, by default None

Returns:

  • D_J (float) – The \(D_J\) statistic

  • vol_J (float) – The \(V_J\) statistic

  • phase_shift (float) – The phase shift

  • D_J_n (np.ndarray) – The \(D_J\) statistic for each allowed phase shift

  • p_value (float) – The \(p\)-value

phazap.phazap.phazap_all_metrics_one_ordering(event1_postprocessed_phase, event2_postprocessed_phase)[source]

Compute all metrics for one ordering of the two events

The method is described in Sec. 4 of https://arxiv.org/pdf/2308.06616.pdf

Parameters:
Returns:

  • neff (float) – The number of effective phases

  • vol_1 (float) – The volume of the posterior distribution of the first event, considering all phases

  • vol_2 (float) – The volume of the posterior distribution of the second event, considering all phases

  • vol_phases_1 (float) – The volume of the posterior distribution of the first event, only considering the detector phases

  • vol_phases_2 (float) – The volume of the posterior distribution of the second event, only considering the detector phases

  • dist_all (float) – The distance of the posterior distribution between the two events, considering all phases

  • dist_phases (float) – The distance of the posterior distribution between the two events, only considering the detector phases

  • dist_Tphases (float) – The distance of the posterior distribution between the two events, only considering the time delay phases

  • dist_Dphi (float) – The distance of the posterior distribution between the two events, only considering \(\Delta\phi_f\)

phazap.phazap.phazap_one_ordering(event1_postprocessed_phase, event2_postprocessed_phase)[source]

Compute the volume, distance and number of effective phases for one ordering of the two events.

The method is described in Sec. 4 of https://arxiv.org/pdf/2308.06616.pdf

Parameters:
Returns:

  • vol_phases_1 (float) – The volume of the posterior distribution of the first event, only considering the detector phases

  • dist_all (float) – The distance of the posterior distribution between the two events, considering all phases

  • neff (float) – The number of effective phases

phazap.phazap.phazap_summary(event_1, event_2, plot=False, output_dir='./', output_filename=None)[source]

Compute the \(D_J\) statistic, the \(V_J\) statistic, the phase shift, and the \(p\)-value

Parameters:

  • event_1 (str or PostprocessedPhase) – The first event. If it is a string, it should be a file path to either a postprocessed phase file or a PE result file

  • event_2 (str or PostprocessedPhase) – The second event. If it is a string, it should be a file path to either a postprocessed phase file or a PE result file

  • plot (bool, optional) – Whether to plot the results, by default False

  • output_dir (str, optional) – The output directory, by default “./”

  • output_filename (str, optional) – The output filename, by default None

Returns:

  • D_J (float) – The \(D_J\) statistic

  • vol_J (float) – The \(V_J\) statistic

  • phase_shift (float) – The phase shift

  • p_value (float) – The \(p\)-value

phazap.plot_utils module

phazap.plot_utils.phazap_plot(event1_postprocessed_phase, event2_postprocessed_phase, output_dir='./', output_filename=None, use_latex=True)[source]

Plot the postprocessed phase for two events

Parameters:

  • event1_postprocessed_phase (PostprocessedPhase) – PostprocessedPhase instance for event 1

  • event2_postprocessed_phase (PostprocessedPhase) – PostprocessedPhase instance for event 2

  • output_dir (str, optional) – Output directory

  • output_filename (str, optional) – Output filename

  • use_latex (bool, optional) – Use LaTeX for the labels

Returns:

The figure object

Return type:

matplotlib.figure.Figure

phazap.postprocess_phase module

class phazap.postprocess_phase.PostprocessedPhase(dataset, flow, fhigh, fbest, superevent_name=None, label=None)[source]

Bases: object

__init__(dataset, flow, fhigh, fbest, superevent_name=None, label=None)[source]

A class to store the postprocessed phase

Parameters:

  • dataset (dict) – A dictionary containing the postprocessed phase data

  • flow (float) – Lower frequency cutoff for computing \(\Delta \phi_f\)

  • fhigh (float) – Upper frequency cutoff for computing \(\Delta \phi_f\)

  • fbest (float) – Frequency at which the phase is best measured

  • superevent_name (str) – Name of the superevent

  • label (str) – Label for the postprocessed phase

Returns:

An instance of PostprocessedPhase class

Return type:

PostprocessedPhase

classmethod from_file(hdf5_file)[source]

Load the postprocessed phase from a hdf5 file

Parameters:

hdf5_file (str) – Path to the hdf5 file

Returns:

An instance of PostprocessedPhase class

Return type:

PostprocessedPhase

phazap.postprocess_phase.postprocess_phase(pe_result, flow=20.0, fhigh=100.0, fbest=40.0, superevent_name=None, label=None, output_dir='/home/docs/.phazap', output_filename=None)[source]

Postprocess the phase of the GW signal.

The procedure is described in Sec. II of https://arxiv.org/pdf/2308.06616.pdf

Parameters:

  • pe_result (str or ParameterEstimationInput) – Path to the bilby result/PESummary file or an instance of ParameterEstimationInput

  • flow (float) – Lower frequency cutoff for computing \(\Delta \phi_f\)

  • fhigh (float) – Upper frequency cutoff for computing \(\Delta \phi_f\)

  • fbest (float) – Frequency at which the phase is best measured

  • superevent_name (str) – Name of the superevent

  • label (str) – Label for the postprocessed phase

  • output_dir (str) – Path to the output directory

  • output_filename (str) – Name of the output file

Returns:

An instance of PostprocessedPhase class

Return type:

PostprocessedPhase

phazap.tension_utils module

phazap.tension_utils.distance(parameters_1, parameters_2)[source]

Compute distance between two sets of parameters. The definition is given in Eq. 10 of https://arxiv.org/pdf/2308.06616.pdf

Parameters:

  • parameters_1 (array_like) – First set of parameters.

  • parameters_2 (array_like) – Second set of parameters.

Returns:

distance – Distance between the two sets of parameters.

Return type:

float

phazap.tension_utils.distance1D(parameter_1, parameter_2)[source]

Compute distance between two sets of parameters in 1D. The definition is given in Eq. 10 of https://arxiv.org/pdf/2308.06616.pdf

Parameters:

  • parameter_1 (array_like) – First set of parameters.

  • parameter_2 (array_like) – Second set of parameters.

Returns:

distance – Distance between the two sets of parameters.

Return type:

float

phazap.tension_utils.distance_only_phases(phases_1, phases_2)[source]

Compute distance between two sets of phases accounting for the wrap around of the phases.

Parameters:

  • phases_1 (array_like) – First set of phases.

  • phases_2 (array_like) – Second set of phases.

Returns:

distance – Distance between the two sets of phases accounting for the wrap around of the phases.

Return type:

float

phazap.tension_utils.distance_only_phases_with_shift(parameters_1, parameters_2)[source]

Compute distance between two sets of phasess with possible lensing phase shifts.

Parameters:

  • parameters_1 (array_like) – First set of parameters.

  • parameters_2 (array_like) – Second set of parameters.

Returns:

distances – Distances between the two sets of phases with possible lensing phase shifts.

Return type:

array_like

phazap.tension_utils.distance_phases(parameters_1, parameters_2, nphases)[source]

Compute distance between two sets of parameters accounting for the wrap around of the phases.

Parameters:

  • parameters_1 (array_like) – First set of parameters.

  • parameters_2 (array_like) – Second set of parameters.

  • nphases (int) – Number of phases. It is assumed that the first nphases parameters are phases.

Returns:

distance – Distance between the two sets of parameters accounting for the wrap around of the phases.

Return type:

float

phazap.tension_utils.distance_phases_with_shift(parameters_1, parameters_2, nphases)[source]

Compute distance between two sets of parameters with possible lensing phase shifts. Details in Eq. 12 of https://arxiv.org/pdf/2308.06616.pdf

Parameters:

  • parameters_1 (array_like) – First set of parameters.

  • parameters_2 (array_like) – Second set of parameters.

  • nphases (int) – Number of phases.

Returns:

distances – Distances between the two sets of parameters with possible lensing phase shifts.

Return type:

array_like

phazap.tension_utils.n_eff(phases_1, phases_2, nphases, prior_range)[source]

Compute number of effective degrees of freedom. Definition in Eq. 11 of https://arxiv.org/pdf/2308.06616.pdf

Parameters:

  • phases_1 (array_like) – First set of phases.

  • phases_2 (array_like) – Second set of phases.

  • nphases (int) – Number of phases.

  • prior_range (float) – Prior range.

Returns:

n_eff – Number of effective degrees of freedom.

Return type:

float

phazap.tension_utils.n_eff_1D(phase_1, phase_2, prior_range)[source]

Compute number of effective degrees of freedom in 1D. Definition in Eq. 11 of https://arxiv.org/pdf/2308.06616.pdf

Parameters:

  • phase_1 (array_like) – First set of phases.

  • phase_2 (array_like) – Second set of phases.

  • prior_range (float) – Prior range.

Returns:

n_eff – Number of effective degrees of freedom.

Return type:

float

phazap.tension_utils.n_eff_pair(phases_1, phases_2, nphases, prior_range)[source]

Compute number of effective degrees of freedom for a pair. Definition in Eq. 11 of https://arxiv.org/pdf/2308.06616.pdf

Parameters:

  • phases_1 (array_like) – First set of phases.

  • phases_2 (array_like) – Second set of phases.

  • nphases (int) – Number of phases.

  • prior_range (float) – Prior range.

Returns:

n_eff – Number of effective degrees of freedom.

Return type:

float

phazap.tension_utils.n_eff_pair_1D(phases_1, phases_2, prior_range)[source]

Compute number of effective degrees of freedom in 1D for a pair. Definition in Eq. 11 of https://arxiv.org/pdf/2308.06616.pdf

Parameters:

  • phases_1 (array_like) – First set of phases.

  • phases_2 (array_like) – Second set of phases.

  • prior_range (float) – Prior range.

Returns:

n_eff – Number of effective degrees of freedom.

Return type:

float

phazap.tension_utils.volume(parameters)[source]

Volume of a set of parameters. Definition in Eq. 17 of https://arxiv.org/pdf/2308.06616.pdf

Parameters:

parameters (array_like) – Set of parameters.

Returns:

volume – Volume of the set of parameters.

Return type:

float

phazap.tension_utils.volume_only_phases(phases_1, phases_2)[source]

Volume of a set of parameters accounting for the wrap around of the phases.

Parameters:

  • phases_1 (array_like) – First set of phases.

  • phases_2 (array_like) – Second set of phases.

Returns:

volume – Volume of the set of parameters accounting for the wrap around of the phases.

Return type:

float

phazap.tension_utils.volume_phases(parameters, nphases)[source]

Volume of a set of parameters accounting for the wrap around of the phases.

Parameters:

  • parameters (array_like) – Set of parameters.

  • nphases (int) – Number of phases. It is assumed that the first nphases parameters are phases.

Returns:

volume – Volume of the set of parameters accounting for the wrap around of the phases.

Return type:

float

phazap.utils module

phazap.utils.format_pretty_phase_shift(phase_shift)[source]
phazap.utils.mode(posterior, bins=30)[source]

Compute mode of a posterior distribution

Parameters:

  • posterior (np.ndarray) – Posterior samples

  • bins (int) – Number of bins

Returns:

mode – Mode of the posterior

Return type:

float

phazap.utils.modes(posteriors, bins=30)[source]

Compute modes of a set of posterior distributions

Parameters:

  • posterior (np.ndarray) – Posterior samples

  • bins (int) – Number of bins

Returns:

modes – Modes of the posteriors

Return type:

np.ndarray

phazap.utils.p_sigma(dist, df)[source]

Compute p-value from chi2 distribution

Parameters:

  • dist (float) – Distance

  • df (int) – Degrees of freedom

Returns:

p – p-value

Return type:

float

phazap.utils.wrap_only_phases(phases_1, phases_2)[source]

Wrap phases around their modes to avoid discontinuities from periodic boundaries

Parameters:

  • phases_1 (np.ndarray) – Posterior samples of phases

  • phases_2 (np.ndarray) – Posterior samples of phases

Returns:

  • phases_1_wrap (np.ndarray) – Wrapped posterior samples of phases_1. The phases are wrapped around the modes of phases_1.

  • phases_2_wrap_mod (np.ndarray) – Wrapped posterior samples of phases_2. The phases are wrapped around the modes of phases_1.

phazap.utils.wrap_phase(phases_1)[source]

Wrap phases around their modes to avoid discontinuities from periodic boundaries

Parameters:

phases_1 (np.ndarray) – Posterior samples of phases

Returns:

phases_1_wrap – Wrapped posterior samples of phases_1. The phases are wrapped around their modes.

Return type:

np.ndarray

phazap.utils.wrap_phases(parameters_1, parameters_2, nphases)[source]

Wrap phases around their modes to avoid discontinuities from periodic boundaries

Parameters:

  • parameters_1 (np.ndarray) – Posterior samples

  • parameters_2 (np.ndarray) – Posterior samples

  • nphases (int) – Number of phases in the posterior samples. It is assumed that the first nphases parameters are phases.

Returns:

  • parameters_1_wrap_mod (np.ndarray) – Wrapped posterior samples of parameter_1. The phases are wrapped around the modes of parameters_1.

  • parameters_2_wrap_mod (np.ndarray) – Wrapped posterior samples of parameter_2. The phases are wrapped around the modes of parameters_1.