API reference¶

Data module¶

Utilities for handling and manipulating strain data from gravitational-wave detectors.

class ringdown.data.AutoCovariance(*args, delta_t=None, ifo=None, attrs=None, **kwargs)¶

Bases: TimeSeries

Contains and manipulates autocovariance functions, a special kind of TimeSeries.

property cholesky: ndarray¶: Cholesky factor \(L\) of covariance matrix \(C = L^TL\).

compute_snr(x, y=None) → float¶

Efficiently compute the signal-to_noise ratio \(\mathrm{SNR} = \left\langle x \mid y \right\rangle / \sqrt{\left\langle x \mid x \right\rangle}\), where the inner product is defined by \(\left\langle x \mid y \right\rangle \equiv x_i C^{-1}_{ij} y_j\). This is internally computed using Cholesky factors to speed up the computation.

If x is a signal and y is noisy data, then this is the matched filter SNR; if both of them are a template, then this is the optimal SNR.

Parameters:

x (array) – target time series.
y (array) – reference time series. Defaults to x.

Returns:

snr – signal-to-noise ratio

Return type:

float

classmethod from_data(d, n=None, delta_t=None, method='fd', **kws)¶

Estimate AutoCovariance from time domain data using Welch’s method by default.

Parameters:

d (Data, array) – data time series.
n (int) – length of output ACF. Defaults to len(d).
delta_t (float) – time-sample spacing, necessary if d is a simple array with no associated timing information. Defaults to d.delta_t if d is Data.
method (str) – whether to use Welch’s method ('fd'), or simply auto-correlate the data ('td'). The latter is highly discouraged and will result in a warning. Defaults to fd.
**kws – additional keyword arguments passed to PowerSpectrum.fom_data().

Returns:

acf – estimate of the autocovariance function.

Return type:

AutoCovariance

property matrix: ndarray¶: Covariance matrix built from ACF, \(C_{ij} = \rho(|i-j|)\).

to_psd() → PowerSpectrum¶

Returns corresponding PowerSpectrum, obtained by Fourier transforming ACF.

Returns:: psd – power spectral density.
Return type:: PowerSpectrum

whiten(data) → Data | TimeSeries | ndarray¶

Whiten stretch of data using ACF.

Parameters:: data (array, TimeSeries) – unwhitened data.
Returns:: w_data – whitened data.
Return type:: Data

class ringdown.data.Data(*args, ifo=None, attrs=None, **kwargs)¶

Bases: TimeSeries

Container for time-domain strain data from a given GW detector.

ifo¶

detector identifier (e.g., ‘H1’ for LIGO Hanford).

Type:: str

attrs¶

optional additional information, e.g., to identify data provenance.

Type:: dict

Condition data.

Parameters:

t0 (float) – target time to be preserved after downsampling.
ds (int) – decimation factor for downsampling.
f_min (float) – lower frequency for high passing.
f_max (float) – higher frequency for low passing.
trim (float) – fraction of data to trim from edges after conditioning, to avoid spectral issues if filtering (default 0.25).
digital_filter (bool) – apply digital antialiasing filter by discarding Fourier components higher than Nyquist; otherwise, filter through scipy.signal.decimate().(default True).
remove_mean (bool) – explicitly remove mean from time series after conditioning (default True).
decimate_kws (dict) – options for decimation function.
slice_left (float) – number of seconds before t0 to slice the strain data, e.g. to avoid NaNs
slice_right (float) – number of seconds after t0 to slice the strain data, e.g. to avoid NaNs

Returns:

cond_data – conditioned data object.

Return type:

Data

property detector: <MagicMock id='140036714563584'>¶: lal object containing detector information.

classmethod from_psd(psd: PowerSpectrum, **kws)¶

Generate data from a given PSD.

Parameters:: psd (PowerSpectrum) – power spectral density.
Returns:: data – time series data.
Return type:: Data

get_acf(**kws)¶: Estimate ACF from data, see AutoCovariance.from_data().

get_psd(**kws)¶: Estimate PSD from data, see PowerSpectrum.from_data().

class ringdown.data.FrequencySeries(data=None, index=None, dtype: Dtype | None = None, name=None, copy: bool | None = None, fastpath: bool | lib.NoDefault = <no_default>)¶

Bases: Series

A container for frequency domain data based on pandas.Series; the index should contain frequency stamps for uniformly-sampled data.

property delta_f: float¶: Fourier frequency spacing.

property delta_t: float¶: Sampling time interval.

property duration: float¶: Time series duration (time spanned between first and last samples).

property f_samp: float¶: Sampling frequency (1/delta_t).

property freq: Index¶: Frequency stamps.

interpolate_to_index(freq: ndarray | None = None, delta_f: float | None = None, f_min: float | None = None, f_max: float | None = None, log: bool = False, **kws)¶

Interpolate the FrequencySeries to new index. Inherits from Series.interpolate_to_index().

If no frequency arguments are specified, it will interpolate to a a frequency array with the same span as the original, but enforcing uniform spacing based on the difference between the first two frequency samples.

Parameters:

freq (list or numpy array or pd.Series) – array of frequency bins to label the new frequencies
delta_f (float) – frequency steps of the new interpolated signal
f_min (float) – instead of an array of frequencies, one can provide the starting frequency f_min, the highest frequency f_max and the frequency spacing delta_f.
f_max (float) – max frequency of the new interpolated signal
log (bool) – interpolate in log-log space [EXPERIMENTAL] (default False)

Returns:

new_series – interpolated series

Return type:

FrequencySeries

to_time_series(epoch=0.0)¶

Inverse Fourier transform frequency series to time series.

Returns:: time_series – time series.
Return type:: TimeSeries

class ringdown.data.PowerSpectrum(*args, delta_f=None, ifo=None, attrs=None, complete_power_of_two=True, **kwargs)¶

Bases: FrequencySeries

Contains and manipulates power spectral densities, a special kind of FrequencySeries.

complete_low_frequencies(f_min: float = 0.0, fill_value: float | None = None, **kws) → PowerSpectrum¶

Complete low frequencies in power spectrum, extending all the way down to f_min, which defaults to 0. If fill_value is not provided, it will be set to 10 times the maximum PSD value.

If f_min is not below the lowest frequency in the PSD, nothing is done and the PSD is returned as is.

Additional arguments are passed to PowerSpectrum.interpolate_to_index().

Parameters:

f_min (float) – lower frequency threshold.
fill_value (float) – value with which to patch PSD below f_min.
kws (**) – additional keyword arguments passed to PowerSpectrum.interpolate_to_index().

Returns:

psd – power spectrum with low frequencies completed.

Return type:

PowerSpectrum

compute_snr(x: FrequencySeries, y: FrequencySeries | None = None, f_min: float | None = None, f_max: float | None = None) → float¶

Efficiently compute the signal-to_noise ratio \(\mathrm{SNR} = \left\langle x \mid y \right\rangle / \sqrt{\left\langle x \mid x \right\rangle}\), where the inner product is defined by \(\left\langle x \mid y \right\rangle \equiv 4 \delta_f \Re \sum x_i y_i / S_i\).

If x is a signal and y is noisy data, then this is the matched filter SNR; if both of them are a template, then this is the optimal SNR (default).

Parameters:

x (array) – target frequency series.
y (array) – reference frequency series. Defaults to x.

Returns:

snr – signal-to-noise ratio

Return type:

float

Draw Fourier-domain noise from the PSD, with variance consistent with the LIGO definition of the PSD (cf. GW likelihood), namely

\[\tilde{h}(f) \sim \mathcal{N}(0, \sqrt{\frac{S(f)}{4\Delta f}\]

where the covariance matrix is diagonal, and \(\Delta f = 1/T\) is the PSD.

Can specify a frequency array or frequency range and spacing to which interpolate or extrapolate the PSD.

Other keyword arguments are passed to the interpolation rutine PowerSpectrum.interpolate_to_index().

Parameters:

freq (array) – frequencies over which to draw noise (default to PSD index).
delta_f (float) – frequency spacing; can be used to create freq if not provided).
f_min (float) – minimum frequency to draw noise.
f_max (float) – maximum frequency to draw noise.
prng (int, np.random.Generator) – random number generator.
kws (dict) – additional keyword arguments passed to PowerSpectrum.interpolate_to_index().

Returns:

noise – noise realization.

Return type:

FrequencySeries

Draw time-domain noise from the PSD.

Duration and sampling rate are determined from the PSD if not provided. If a frequency range is provided, the PSD is interpolated/extrapolated to that range before drawing the noise.

Additional keyword arguments are passed to PowerSpectrum.draw_noise_fd().

Parameters:

duration (float) – duration of the time series (provide this argument or delta_f).
f_samp (float) – sampling frequency (provide this argument or f_high which will be half of f_samp; alternatively, f_samp will be determined from delta_t).
delta_t (float) – time step (provide this argument or f_samp or f_high).
f_min (float) – minimum frequency to draw noise.
f_max (float) – maximum frequency to draw noise.
delta_f (float) – frequency step (provide this argument or duration)
epoch (float) – initial time of the time series.
kws (dict) – additional keyword arguments passed to PowerSpectrum.draw_noise_fd().

Returns:

noise – noise realization.

Return type:

Data

Estimate PowerSpectrum from time domain data using Welch’s method.

Parameters:

data (Data, array) – data time series.
f_min (float, None) – optional lower frequency at which to taper PSD via PowerSpectrum.patch(). Defaults to None (i.e., no patching).
f_max (float, None) – optional higher frequency at which to taper PSD via PowerSpectrum.patch(). Defaults to None (i.e., no patching).
fill_value (float, tuple, None) – value with which to patch PSD; if a tuple, then these (psd_low, psd_high) values are used at the low and high ends respectively; if a float, the same value is used in both ends; if None, will patch with 10x the maximum PSD value in the respective patched region.
**kws – additional keyword arguments passed to scipy.signal.Welch().

Returns:

psd – power specturm estimate.

Return type:

PowerSpectrum

Obtain PowerSpectrum from LALSimulation function.

Parameters:

func (str, builtin_function_or_method) – LALSimulation PSD function, or name thereof (e.g., SimNoisePSDaLIGOZeroDetHighPower).
freq (array) – frequencies over which to evaluate PSD.
f_min (float) – lower frequency threshold for padding: PSD will be patched below this value.
delta_f (float) – frequency spacing (required if freq is not provided).
fill_value (float) – value with which to patch PSD below f_min.
**kw – additional arguments passed to padding function PowerSpectrum.patch().

Returns:

psd – power spectrum frequency series.

Return type:

PowerSpectrum

inner_product(x: FrequencySeries, y: FrequencySeries | None = None, f_min: float | None = None, f_max: float | None = None) → complex¶

Compute the noise weighterd inner product between x and y defined by \(\left\langle x \mid y \right\rangle \equiv 4 \delta_f \Re \sum x_i y_i / S_i\).

Parameters:

x (array) – target frequency series.
y (array) – reference frequency series. Defaults to x.
f_min (float) – lower frequency bound (default derived from x)
f_max (float) – upper frequency bound (default derived from x)

Returns:

snr – signal-to-noise ratio

Return type:

float

patch(f_min, f_max=None, patch_level=None, in_place=False, fill_value=None)¶

Modify PSD at low or high frequencies so that it patches to a constant.

Parameters:

f_min (float) – low frequency threshold.
f_max (float) – high frequency threshold (def., None).
patch_level (float,tuple) – value with which to patch PSD; if a tuple, then these (psd_low, psd_high) values are used at the low and high ends respectively; if a float, the same value is used in both ends; if None, will patch with 10x the maximum PSD value in the respective patched region.
fill_value (float) – an alias for patch level for consistency with interp1d
in_place (bool) – modify PSD in place; otherwise, returns copy. Defaults to False.

Returns:

psd – returns PSD only if not in_place.

Return type:

PowerSpectrum, None

to_acf()¶

Return cyclic ACF corresponding to PSD obtained by inverse Fourier transforming.

Returns:: acf – autocovariance function.
Return type:: AutoCovariance

class ringdown.data.Series(data=None, index=None, dtype: Dtype | None = None, name=None, copy: bool | None = None, fastpath: bool | lib.NoDefault = <no_default>)¶

Bases: Series

A wrapper of pandas.Series with some additional functionality.

Download open data or discover data using NDS2 (requires GWpy).

Uses GWpy’s gwpy.timeseries.TimeSeries.fetch_open_data() or gwpy.timeseries.TimeSeries.get() to download data. If channel is ‘GWOSC’, then it will download open data from GWOSC; otherwise, it will attempt to discover remote or local data using NDS2.

Parameters:

channel (str) – channel name or ‘GWOSC’ for public data.
start (float) – start GPS time.
end (float) – end GPS time.
t0 (float) – center time of segment to fetch (alternative to start and end).
seglen (float) – length of segment to fetch (alternative to start and end).
frametype (str) – specify frame type to facilitate NDS frame discovery.
**kws – additional keyword arguments passed to GWpy’s fetch function.

Returns:

series – series downloaded from GWOSC or NDS.

Return type:

Series

interpolate_to_index(new_index, **kwargs)¶

Reinterpolate the Series to new index.

Makes use of scipy.interpolate.interp1d() to which additional arguments are passed (by default {'kind': 'cubic', 'fill_value': 0, 'bounds_error': False})

Parameters:: new_index (list or numpy array or pd.Series) – new index over which to interpolate
Returns:: new_series – interpolated Series
Return type:: Series

classmethod load(path: str | None = None, channel: str | None = None, **kws)¶

Universal load function to read data from disk or discover GWOSC/NDS data using GWpy.

Only one of path or channel can be provided. If a path is provided, it will attempt to read the data from disk using Series.read(); if channel is provided, it will attempt to discover and fetch the data using Series.fetch(), which leverages GWpy’s NDS2 interface.

A special case of the latter is when channel is ‘GWOSC’ (case insensitive); if so, it will download open data from GWOSC.

Parameters:

path (str) – path to file, or None if fetching remote data
channel (str) – channel name or ‘GWOSC’ for public data (case insensitive)
**kws – additional keyword arguments passed to Series.read() or Series.fetch().

classmethod read(path: str, kind: str | None = None, channel: str | None = None, **kws)¶

Load data from disk.

If kind is gwosc assumes input is an strain HDF5 file downloaded from GWOSC. If kind is frame and the keyword channel is given, then attempt to load the given path(s) using gwpy’s frame file reading. Otherwise, it is a wrapper around pandas.read_hdf() or pandas.read_csv() functions, for kind = 'hdf' or kind = 'csv'.

If kind is None, guesses filetype from extension.

Parameters:

path (str) – path to file, or None if fetching remote data.
kind (str) – kind of file to load: gwsoc, hdf or csv.
channel (str) – channel name to use when reading GW frame files (not required otherwise).

Returns:

series – series loaded from disk

Return type:

Series

class ringdown.data.TimeSeries(data=None, index=None, dtype: Dtype | None = None, name=None, copy: bool | None = None, fastpath: bool | lib.NoDefault = <no_default>)¶

Bases: Series

A container for time series data based on pandas.Series; the index should contain time stamps for uniformly-sampled data.

property delta_f: float¶: Fourier frequency spacing.

property delta_t: float¶: Sampling time interval.

property duration: float¶: Time series duration (time spanned between first and last samples).

property epoch: float¶: Time of first sample.

property f_samp: float¶: Sampling frequency (1/delta_t).

interpolate_to_index(time=None, t0=None, duration=None, delta_t=None, fsamp=None, **kws)¶

Reinterpolate the TimeSeries to new index. Inherits from Series.interpolate_to_index().

Parameters:

time (list or numpy array or pd.Series) – new times over which to interpolate
t0 (float) – instead of an array of times, one can provide the start time t0 the duration and sample rate. If these and time are provided then the duration and sampling rate are taken from the time array, setting t0 to be the original one
duration (float) – duration of the new interpolated signal
fsamp (float) – sample rate of the new interpolated signal

Returns:

new_series – interpolated series

Return type:

TimeSeries

property time: Index¶: Time stamps.

to_frequency_series()¶

Fourier transform time series to frequency series.

Returns:: freq_series – frequency series.
Return type:: FrequencySeries

Fit module¶

Module defining the core Fit class.

class ringdown.fit.Fit(modes=None, strain_scale='auto', **kws)¶

Bases: object

A ringdown fit. Contains all the information required to setup and run a ringdown inference analysis, as well as to manipulate the result.

Example usage:

import ringdown as rd
fit = rd.Fit(modes=[(1,-2,2,2,0), (1,-2,2,2,1)])
fit.load_data('{i}-{i}1_GWOSC_16KHZ_R1-1126259447-32.hdf5',
              ifos=['H1', 'L1'], kind='gwosc')
fit.set_target(1126259462.4083147, ra=1.95, dec=-1.27, psi=0.82,
               duration=0.05)
fit.condition_data(ds=8)
fit.update_model(A_scale=1e-21, M_min=50, M_max=150)
fit.run()

data¶

dictionary containing data, indexed by detector name.

Type:: dict

acfs¶

dictionary containing autocovariance functions corresponding to data, if already computed.

Type:: dict

start_times¶

target truncation time for each detector.

Type:: dict

antenna_patterns¶

dictionary of tuples (Fp, Fc) with plus and cross antenna patterns for each detector (only applicable depending on model).

Type:: dict

target¶

information about truncation time at geocenter and, if applicable, source right ascension, declination and polarization angle.

Type:: Target

result¶

if model has been run, arviz object containing fit result

Type:: Result, arviz.data.inference_data.InferenceData

prior¶

if model prior has been run, arviz object containing prior

Type:: Result, arviz.data.inference_data.InferenceData

modes¶

if applicable, list of (p, s, l, m, n) tuples identifying modes to be fit (else, None).

Type:: list

n_modes¶

number of modes to be fit.

Type:: int

ifos¶

list of detector names.

Type:: list

t0¶

target geocenter start time.

Type:: float

sky¶

tuple with source right ascension, declination and polarization angle.

Type:: tuple

analysis_data¶

dictionary of truncated analysis data that will be fed to Stan model.

Type:: dict

model_data¶

arguments passed to Stan model internally.

Type:: dict

info¶

information that can be used to reproduce a fit (e.g., data provenance, or conditioning options), stored as dictionary of dictionaries whose outer (inner) keys will be interpreted as sections (options) when creating a configuration file through Fit.to_config().

Type:: dict

add_data(data, time=None, ifo=None, acf=None)¶

Add data to fit.

Parameters:

data (array,Data) – time series to be added.
time (array) – array of time stamps (only required if data is not ringdown.data.Data).
ifo (str) – interferometer key (optional).
acf (array,AutoCovariance) – autocovariance series corresponding to these data (optional).

property analysis_data: dict¶: Slice of data to be analyzed for each detector. Extracted from Fit.data based on information in analysis target Fit.target.

property analysis_injections: dict¶: Slice of injection to be analyzed for each detector. Extracted from Fit.conditioned_injections based on information in analysis target Fit.target.

property analysis_times: dict¶: Time arrays for analysis data.

property antenna_patterns¶

property attrs¶

compute_acfs(shared=False, ifos=None, **kws)¶

Compute ACFs for all data sets in Fit.data.

Parameters:

shared (bool) – specifies if all IFOs are to share a single ACF, in which case the ACF is only computed once from the data of the first IFO (useful for simulated data) (default False)
ifos (list) – specific set of IFOs for which to compute ACF, otherwise computes it for all
constructor (extra kwargs are passed to ACF)

compute_injected_snrs(optimal=True, network=True) → dict | float¶

Return a dictionary of injected SNRs for each detector.

Parameters:

optimal (bool) – if True, return optimal SNRs (def. True); otherwise return matched filter SNRs.
network (bool) – if True, return total network SNR (def. True).

Returns:

snrs – dictionary of SNRs for each detector if network=False, otherwise the total network SNR.

Return type:

dict | float

condition_data(preserve_acfs: bool = False, **kwargs)¶

Condition data for all detectors by calling ringdown.data.Data.condition(). Docstring for that function below.

The preserve_acfs argument determines whether to preserve original ACFs in fit after conditioning (default False).

Condition data.

Parameters:

t0 (float) – target time to be preserved after downsampling.
ds (int) – decimation factor for downsampling.
f_min (float) – lower frequency for high passing.
f_max (float) – higher frequency for low passing.
trim (float) – fraction of data to trim from edges after conditioning, to avoid spectral issues if filtering (default 0.25).
digital_filter (bool) – apply digital antialiasing filter by discarding Fourier components higher than Nyquist; otherwise, filter through scipy.signal.decimate().(default True).
remove_mean (bool) – explicitly remove mean from time series after conditioning (default True).
decimate_kws (dict) – options for decimation function.
slice_left (float) – number of seconds before t0 to slice the strain data, e.g. to avoid NaNs
slice_right (float) – number of seconds after t0 to slice the strain data, e.g. to avoid NaNs

Returns:

cond_data – conditioned data object.

Return type:

Data

property conditioned_injections: dict¶: Conditioned injections, if available.

copy()¶

Produce a deep copy of this Fit object.

Returns:: fit_copy – deep copy of Fit.
Return type:: Fit

property duration: float¶: Analysis duration in the units of time presumed by the Fit.data and Fit.acfs objects (usually seconds). Defined as \(T = N\times\Delta t\), where \(N\) is the number of analysis samples (n_analyze) and \(\Delta t\) is the time sample spacing.

Generate synthetic data for a given set of interferometers.

If PSDs are provided, draws time-domain data from PSDs using ringdown.data.PowerSpectrum.draw_noise_td(). If no PSDs are provided, initializes empty data arrays with specified time stamps.

Parameters:

ifos (list) – list of detector keys (e.g., ['H1', 'L1']); also accepts a single string if adding a single detector.
psds (dict) – dictionary of PSDs indexed by interferometer keys, or: (1) PSD string replacement pattern, e.g., 'path/to/{ifo}-PSD.txt' where ifo will be replaced by the detector key (e.g., H1 for LIGO Hanford); (2) name of a PSD function available in LALSimulation.
duration (float) – duration of data segment (default None); not required if PSD is provided.
delta_t (float) – time step of data (default None).
freq (float) – frequency array to create PSD (default None).
f_samp (float) – sampling frequency of data (default None).
f_min (float) – minimum frequency of data (default None).
f_max (float) – maximum frequency of data (default None).
delta_f (float) – frequency step of PSD (default None).
t0 (float) – time of data segment center (default None); if not provided, the target time will be used if available.
epoch (float) – time of data segment start (default None); if not provided, will be set based on t0 or target time.
prng (int, np.random.Generator) – random number generator seed or object (default None).
psd_kws (dict) – additional keyword arguments passed to PSD constructor.
record_acfs (bool) – record ACFs for this data (default False).
**kws – additional keyword arguments passed to ringdown.data.Data.draw_noise_td().

classmethod from_config(config_input: str | ConfigParser, no_cond: bool = False, result: str | None = None)¶

Creates a Fit instance from a configuration file.

Has the ability to load and condition data, as well as to inject a simulated signal and to compute or load ACFs. Does not run the fit automatically.

Parameters:

config_input (str, configparser.ConfigParser) – path to config file on disk, or preloaded configparser.ConfigParser
no_cond (bool) – option to ignore conditioning

Returns:

fit – Ringdown Fit object.

Return type:

Fit

get_templates(signal_buffer='auto', **kws)¶

Produce templates at each detector for a given set of parameters. Can be used to generate waveforms from model samples, or a full coalescence.

This is a wrapper around ringdown.waveforms.get_detector_signals().

Parameters:

signal_buffer (float, str) – span of time around target for which to evaluate polarizations, to avoid doing so over a very long time array (for speed). By default, signal_buffer='auto' sets this to a multiple of the analysis duration; otherwise this should be a float, or inf for no signal_buffer. (see docs for ringdown.waveforms.Ringdown.from_parameters(); this option has no effect for coalescence signals)
**kws – arguments passed to ringdown.waveforms.get_detector_signals().

Returns:

waveforms – dictionary of Data waveforms for each detector.

Return type:

dict

property has_injections: bool¶: Whether injections have been added with Fit.inject().

property has_target: bool¶: Whether an analysis target has been set with Fit.set_target().

property ifos: list¶: Instruments to be analyzed.

inject(no_noise=False, **kws) → None¶

Add simulated signal to data, and records it in Fit.injections.

Warning

This method overwrites data stored in in Fit.data.

Arguments are passed to Fit.get_templates().

Parameters:: no_noise (bool) – if true, replaces data with injection, instead of adding the two. (def. False)

property injection_parameters: dict | Parameters¶: Injection parameters, if available.

load_acfs(path, ifos=None, from_psd=False, **kws)¶

Load autocovariances from disk. Can read in a PSD, instead of an ACF, if using the from_psd argument.

Additional arguments are passed to ringdown.data.AutoCovariance.read() (or, ringdown.data.PowerSpectrum.read() if from_psd).

Parameters:

path (dict, str) – dictionary of ACF paths indexed by interferometer keys, or path string replacement pattern, e.g., 'path/to/acf_{i}_{ifo}.dat' where i and ifo will be respectively replaced by the first letter and key for each detector listed in ifos (e.g., H and H1 for LIGO Hanford).
ifos (list) – list of detector keys (e.g., ['H1', 'L1']), not required if path_input is a dictionary.
from_psd (bool) – read in a PSD and convert to ACF.

Load data from disk.

Additional arguments are passed to ringdown.data.Data.load().

If a seglen argument is provided (e.g., to fetch data from GWOSC), the segment will be assumed to be centered on a GPS time t0, which (if not provided) defaults to the target time Fit.t0 (if t0 is not provided and no target was set, an error will be raised).

Parameters:

path (dict, str) – dictionary of data paths indexed by interferometer keys, or path string replacement pattern, e.g., 'path/to/{i}-{ifo}_GWOSC_16KHZ_R1-1126259447-32.hdf5' where i and ifo will be respectively replaced by the first letter and key for each detector listed in ifos (e.g., H and H1 for LIGO Hanford).
ifos (list) – list of detector keys (e.g., ['H1', 'L1']), not required if path_input is a dictionary.
channel (dict, str) – dictionary of channel names indexed by interferometer keys, or channel name string replacement pattern, e.g., '{ifo}:GWOSC-16KHZ_R1_STRAIN' where i and ifo will be respectively replaced by the first letter and key for each detector listed in ifos (e.g., H and H1 for LIGO Hanford). Only used when kind = ‘frame’.
frametype (dict, str) – dictionary of frame types indexed by interferometer keys, or frame type string replacement pattern, e.g., ‘H1_HOFT_C00’, with same replacement rules as for channel and path. Only used when kind = ‘discover’.
slide (dict) – optional dictionary of time slides to apply to each detector, e.g., {'H1': 0.1, 'L1': -0.05}; if provided, the data of each detector will be rolled by an integer number of samples closest to the requested time shift, i.e., np.roll(data, int(slide / delta_t).

property model_settings: dict¶: Prior options as currently set.

property n_analyze: int¶: Number of data points included in analysis for each detector.

property n_modes: int¶: Number of damped sinusoids to be included in template.

property raw_data: dict¶

reset(preserve_conditioning=False)¶: Reset all priors and results, but keep data and target information.

run(prior: bool = False, predictive: bool = True, store_h_det: bool = False, store_h_det_mode: bool = True, store_residuals: bool = False, rescale_strain: bool = True, suppress_warnings: bool = True, min_ess: int | None = None, prng: ArrayImpl | int | None = None, validation_enabled: bool = False, return_model: bool = False, **kwargs)¶

Fit model.

Additional keyword arguments not listed below are passed to the sampler with the following defaults when sampling:

{‘dense_mass’: True, ‘num_warmup’: 1000, ‘num_samples’: 1000, ‘num_chains’: 4}

See docs for numpyro.infer.NUTS() and numpyro.infer.MCMC() to see all available options.

Parameters:

prior (bool) – whether to sample the prior (def. False).
predictive (bool) – draw secondary quantities from the posterior predictive after runtime (def. True).
store_h_det (bool) – store detector templates in result (def. False).
store_h_det_mode (bool) – store individual-mode templates in result (def. True).
store_residuals (bool) – compute whitened residuals point-wise (def. False).
rescale_strain (bool) – rescale strain-like quantites by strain_scale, if strain was rescaled before running, as could be the case when using float32 (def. True).
suppress_warnings (bool) – suppress some sampler warnings (def. True).
min_ess (number) – if given, keep re-running the sampling with longer chains until the minimum effective sample size exceeds min_ess (def. None).
validation_enabled (bool) – if True, run with numpyro.validation_enabled() to get verbose error messages
return_model (bool) – returns numpyro model instead of running it (def. False).
**kwargs – arguments passed to sampler.

property run_input: list¶: Arguments to be passed to model function at runtime: [times, strains, ls, fp, fc].

set_modes(modes: int | list[tuple[int, int, int, int, int]])¶

Establish list of modes to include in analysis template.

Modes can be an integer, in which case n arbitrary damped sinusoids will be fit.

Modes identified by their (p, s, l, m, n) indices, where:

p is 1 for prograde modes, and -1 for retrograde modes;
s is the spin-weight (-2 for gravitational waves);
l is the azimuthal quantum number;
m is the magnetic quantum number;
n is the overtone number.

See ringdown.indexing.ModeIndexList.

Parameters:: modes (list) – list of tuples with quasinormal mode (p, s, l, m, n) numbers.

set_strain_scale(scale)¶

Establish truncation target, stored to self.target.

Provide a targeted analysis start time t0 to serve as beginning of truncated analysis segment; this will be compared against timestamps in fit.data objects so that the closest sample to t0 is preserved after conditioning and taken as the first sample of the analysis segment.

Important

If the model accepts multiple detectors, t0 is assumed to be defined at geocenter; truncation time at individual detectors will be determined based on specified sky location.

The source sky location and orientation can be specified by the ra, dec, and psi arguments. These are use to both determine the truncation time at different detectors, as well as to compute the corresponding antenna patterns. Specifying a sky location is only required if the model can handle data from multiple detectors.

The argument duration specifies the length of the analysis segment in the unit of time used to index the data (e.g., s). Based on the sampling rate, this argument is used to compute the number of samples to be included in the segment, beginning from the first sample identified from t0.

Alternatively, the n_analyze argument can be specified directly. If neither duration nor n_analyze are provided, the duration will be set based on the shortest available data series in the Fit object.

Warning

Failing to explicitly specify duration or n_analyze risks inadvertently extremely long analysis segments, with correspondingly long run times.

Parameters:

t0 (float, dict) – target time (at geocenter for a detector network, if no reference_ifo is specified), or a dictionary of start times.
ra (float) – source right ascension (rad).
dec (float) – source declination (rad).
psi (float) – source polarization angle (rad).
duration (float) – analysis segment length in seconds, or time unit indexing data (overrides n_analyze).
antenna_patterns (dict) – dictionary with tuples for plus and cross antenna patterns for each detector {ifo: (Fp, Fc)} (optional)
reference_ifo (str) – if specified, use this detector as reference for delays and antenna patterns, otherwise assume t0 defined at geocenter.

set_tone_sequence(nmode, p=1, s=-2, l=2, m=2)¶

Set template modes to be a sequence of overtones with a given angular structure.

To set an arbitrary set of modes, use Fit.set_modes()

Parameters:

nmode (int) – number of tones (nmode=1 includes only fundamental mode).
p (int) – prograde (p=1) vs retrograde (p=-1) flag.
s (int) – spin-weight.
l (int) – azimuthal quantum number.
m (int) – magnetic quantum number.

property settings¶

property start_indices: dict¶: Locations of first samples in Fit.data to be included in the ringdown analysis for each detector.

property start_times¶

property strain_scale¶

property t0: float¶: Target truncation time (defined at geocenter if model accepts multiple detectors).

to_config(path=None)¶

Create configuration file to reproduce this fit by calling Fit.from_config().

Note

This will only result in a working configuration file if all data provenance information is available in Fit.info. This field is automatically populated if the Fit.load_data() method is used to add data to fit.

Parameters:: path (str) – optional destination path for configuration file.
Returns:: config – configuration file object.
Return type:: configparser.ConfigParser

to_json(indent=4, **kws)¶

update_info(section: str, **kws) → None¶

Update fit information stored in Fit.info, e.g., data provenance or injection properties. If creating a config file through Fit.to_config(), section will operate as a name for a section with options determined by the keyword arguments passed here.

Keyword arguments are stored as “options” for the given section, e.g.,:

fit.update_info('data', path='path/to/{ifo}-data.h5')

adds an entry to fit.info like:

{'data': {'path': 'path/to/{ifo}-data.h5')}}

Parameters:: section (str) – name of information category, e.g., data, injection, condition.

update_model(**kws)¶

Set or modify prior options or other model settings. For example, fit.update_model(A_scale=1e-21) sets the A_scale parameter to 1e-21.

Valid arguments for the selected model can be found in Fit.valid_model_settings.

update_prior(*args, **kwargs)¶

property valid_model_settings: list¶: Valid prior parameters for the selected model. These can be set through Fit.update_model().

whiten(datas: dict) → dict¶

Return whiten data for all detectors using ACFs stored in Fit.acfs.

Parameters:: datas (dict) – dictionary of data to be whitened for each detector.
Returns:: whitened_datas – dictionary of ringdown.data.Data with whitened data for each detector.
Return type:: dict

Model module¶

Convert a numpyro sampler to an arviz dataset.

Parameters:

sampler (numpyro.MCMC) – The sampler to convert after running.
modes (None or array_like) – Coordinates of modes to include in the dataset; if None, then all modes are included and indexed by integers.
ifos (None or array_like) – The ifos to include in the dataset. If None, then all ifos are included.
injections (None or array_like) – The injections to include in the dataset. If None, then no injections are included.
epoch (None or array_like) – The epoch of each ifo. If None, then all epochs are set to zero.
scale (None or float) – The scale of the strain. If None, then the scale is set to one.
attrs (None or dict) – Attributes to include in the arviz dataset.
record_data (bool) – Whether to record the observed data and auxiliary quantities in the arviz dataset.

Returns:

dataset – The arviz dataset.

Return type:

arviz.InferenceData

Parameters:

modes (int or list[tuple]) – If integer, the number of damped sinusoids to use. If list of tuples, each entry should be of the form (p, s, ell, m), where p is 1 for prograde -1 for retrograde; s is the spin weight (-2 for the usual GW modes); and ell and m refer to the usual angular numbers.
a_scale_max (float) – The maximum value of the amplitude scale parameter. This is used to define the prior on the amplitude scale parameter.
marginalized (bool) – Whether or not to marginalize over the quadrature amplitudes analytically.
m_min (float) – The minimum mass of the black hole in solar masses.
m_max (float) – The maximum mass of the black hole in solar masses.
chi_min (float) – The minimum dimensionless spin of the black hole.
chi_max (float) – The maximum dimensionless spin of the black hole.
cosi_min (float or None) – The minimum inclination angle to the angular orbital momentum of the black hole.
cosi_max (float or None) – The maximum inclination angle to the angular orbital momentum of the black hole.
cosi (float or None) – The inclination angle to the angular orbital momentum of the black hole. If not None, then cosi_min and cosi_max are ignored and the value of cosi is fixed.
df_min (None or float or list[None or float]) – The minimum fractional deviation from the GR frequency. If a list then it should have the same length as modes.
df_max (None or float or list[None or float]) – The maximum fractional deviation from the GR frequency. If a list, then it should have the same length as modes.
dg_min (None or float or list[None or float]) – The minimum fractional deviation from the GR damping rate. If a list, then it should have the same length as modes.
dg_max (None or float or list[None or float]) – The maximum fractional deviation from the GR damping rate. If a list, then it should have the same length as modes.
flat_amplitude_prior (bool) – Whether or not to impose a flat prior on the amplitude scale parameter. This is only relevant if marginalized is False.
mode_ordering (None or str) – Relevant to the case where modes is an integer, and the model consists of arbitrary damped sinusoids. If None, then the frequencies and damping rates are only constrained by the bounds f_min, f_max, g_min, and g_max. If ‘f’, then the frequencies are constrained to be in increasing order; if ‘g’, then the damping rates are constrained to be in increasing order.
single_polarization (bool) – if true, assumes a single, linear polarization: either plus or cross, with theta = 0. This should only be used for testing in simulated data for a single detector! (default: False)
prior (bool) – Whether or not to compute the likelihood. If True, then the likelihood is not computed, and the model is used for prior predictive sampling.
predictive (bool) – Whether to generate the quadrature amplitudes when marginalized=True.
store_h_det (bool) – Whether to store the detector-frame waveform in the model.
store_h_det_mode (bool) – Whether to store the mode-by-mode detector-frame waveform in the model.

Returns:

model – A model function that can be used with numpyro to sample from the posterior distribution of the ringdown parameters.

Return type:

function

Result module¶

Module defining the core Result class.

class ringdown.result.Result(*args, config=None, produce_h_det=True, **kwargs)¶

Bases: InferenceData

Result from a ringdown fit.

property cholesky_factors: ndarray¶: Cholesky L factors used in analysis.

compute_posterior_snr_timeseries(optimal: bool = True, network: bool = True) → ndarray¶

Efficiently computes cumulative signal-to-noise ratio from posterior samples as a function of time.

Depending on the optimal argument, returns either the optimal SNR:

snr_opt = sqrt(dot(template, template))

or the matched filter SNR:

snr_mf = dot(data, template) / snr_opt

NOTE: the last time sample of the returned SNR timeseries corresponds: to the total accumulated SNR, which is the same as returned by compute_posterior_snrs(); however, that function is 10x faster, so use it if you only need the total SNR.

Parameters:

optimal (bool) – return optimal SNR, instead of matched filter SNR (def., True)
network (bool) – return network SNR, instead of individual-detector SNRs (def., True)

Returns:

snrs – stacked array of cumulative SNRs, with shape (time, samples,) if network = True, or (ifo, time, samples) otherwise; the number of samples equals the number of chains times the number of draws.

Return type:

array

Waveforms module¶

Utilities for generating and handling gravitational-wave templates.

class ringdown.waveforms.Coalescence(*args, modes=None, **kwargs)¶

Bases: Signal

An inspiral-merger-ringdown signal from a compact binary coalescence.

classmethod from_parameters(time, model=None, approximant=None, ell_max=None, single_mode=None, window=0.125, manual_epoch=False, subsample_placement=False, **kws)¶

Construct coalescence waveform from compact-binary parameters.

Additional keyword arguments are passed to Parameters to construct the input for ls.SimInspiralChooseTDWaveform(). This should include masses, spins, inclination, refrence phase, reference frequency, minimum frequency, and trigger time.

In order to reproduce waveform placement for time-domain waveforms as carried out by LALInference, use manual_epoch = False. Otherwise, will place waveform such that the empirical peak of the waveform envelope falls on the specified trigger time. If subsample_placement, the peak is identified via quadratic sub-sample interpolation and the waveform is shifted in the Fourier domain so that the interpolated peak falls on a sample (this option necessarily reduces performance).

By default, a one-sided Tukey window with a ramp up of \(\alpha = 0.125\) is applied to the left-hand side of the signal. This means that frequencies below \(\approx 1/\left(\alpha \times T\right)\) will be corrupted, where \(T\) is the intrinsic duration of the waveform as determined by f_low. This behavior is turned off if window is 0 or False, but at risk of having a sharp turn on of time-domain waveforms in band (this should be safe for frequency-domain waveforms).

(Note that an estimate on \(T\) can be obtained through XLALSimInspiralChirpTimeBound(f_min, m1, m2, S1z, S2z).)

Parameters:

time (array) – time array over which to evaluate waveform.
model (str) – name of waveform approximant (e.g., “NRSur7dq4”).
approximant (str) – alias for model.
ell_max (int) – highest angular harmonic ell mode to include, defined in the coprecessing frame per the convention inherited from LALSimulation Defaults to None, which includes all available modes.
single_mode (tuple) – single (ell, m) spherical mode to include, e.g., (2, 2); includes both left and right handed contributions, i.e., (l, m) and (l, -m). Defaults to None, which includes all available modes.
window (float, bool) – window signal from the left to avoid sharp turn ons in time-domain approximants; numerical value is interpreted as fraction of time for tukey() window ramp up. Defaults to 0.125.
manual_epoch (bool) – align waveform based on empirically found waveform peak (i.e., peak of \(h_+^2 + h_\times^2\)), not the epoch reported by approximant. Defaults to False.
subsample_placement (bool) – if manual_epoch, find waveform peak using quadratic subsample interpolation; else, find maximum of waveform envelope in samples. Defaults to False.
kws – additional keyword arguments passed to Parameters.

Returns:

h – compact binary coalescence signal.

Return type:

Coalescence

get_invariant_peak_time(ell_max=None, force=False)¶

Compute time of the peak of the invariant strain \(H^2\), which is defined as

\[H^2(t) \equiv \sum_{\ell m} H_{\ell m}^2(t)\]

where \(H_{\ell m}(t)\) are the coefficients associated with the spherical harmonic factors \({}_{-2} Y_{\ell m}\) in the strain, namely

\[h(t) = \sum_{\ell m} H_{\ell m}(t) {}_{-2} Y_{\ell m}\]

Note

This currently only works with some time domain approximants (e.g., NRSur7dq4), as it relies on ls.SimInspiralChooseTDModes().

Parameters:

ell_max (int) – maximum \(\ell\) to include in the computation of the peak
force (bool) – redo the computation ignoring cached results

Returns:

t_peak – peak time of the invariant strain

Return type:

float

class ringdown.waveforms.Parameters(mass_1: float, mass_2: float, spin_1x: float = 0, spin_1y: float = 0, spin_1z: float = 0, spin_2x: float = 0, spin_2y: float = 0, spin_2z: float = 0, luminosity_distance: float = None, iota: float = 0, phase: float = 0, long_asc_nodes: float = 0, eccentricity: float = 0, mean_per_ano: float = 0, f_low: float = 20, f_ref: float = 20, psi: float = 0, ra: float = None, dec: float = None, trigger_time: float = 0)¶

Bases: object

Container for CBC parameters.

Spin information is encoded in Cartesian components (LALSimulation convention).

property chirp_mass¶

mathcal{M}_c = left(m_1 m_2right)^{3/5}/ left(m_1 + m_2right)^{1/5}.

Type:: Chirp mass
Type:: math

compute_remnant_mchi(model: str = 'NRSur7dq4Remnant', solar_masses=True) → tuple¶

Estimate remnant mass and spin using a remnant model.

Parameters:

model (str) – name of remnant model to use (default: ‘NRSur7dq4Remnant’)

Returns:

mf (float) – remnant mass.
chif (float) – remnant dimensionless spin magnitude.

classmethod construct(**kws)¶

property cos_iota¶: Cosine of the Newtonian inclination at reference frequency.

dec: float = None¶

eccentricity: float = 0¶

property extrinsic¶: Extrinsic parameters.

f_low: float = 20¶

f_ref: float = 20¶

property final_mass¶

property final_mass_seconds¶

property final_mass_si¶

property final_spin¶

get_choosetdmodes_args(delta_t)¶

Construct input for ls.SimInspiralChooseTDModes().

Parameters:: delta_t (float) – time spacing for waveform array
Returns:: args – list of arguments ready for ls.SimInspiralChooseTDModes()
Return type:: list

get_choosetdwaveform_args(delta_t)¶

Construct input for ls.SimInspiralChooseTDWaveform().

Parameters:: delta_t (float) – time spacing for waveform array
Returns:: args – list of arguments ready for ls.SimInspiralChooseTDWaveform()
Return type:: list

property intrinsic¶: Intrinsic parameters.

iota: float = 0¶

items(*args, **kwargs)¶

keys(*args, **kwargs)¶

long_asc_nodes: float = 0¶

luminosity_distance: float = None¶

property luminosity_distance_si¶: Luminosity distance in meters.

mass_1: float¶

property mass_1_si¶: First component mass in kg.

mass_2: float¶

property mass_2_si¶: Second component mass in kg.

property mass_ratio¶: Mass ratio \(q = m_2/m_1\) for \(m_1 \geq m_2\).

mean_per_ano: float = 0¶

phase: float = 0¶

psi: float = 0¶

ra: float = None¶

property spin_1¶: 3D dimensionless spin for first component.

property spin_1_mag¶: Dimensionless spin magnitude for first component.

spin_1x: float = 0¶

spin_1y: float = 0¶

spin_1z: float = 0¶

property spin_2¶: 3D dimensionless spin for second component.

property spin_2_mag¶: Dimensionless spin magnitude for second component.

spin_2x: float = 0¶

spin_2y: float = 0¶

spin_2z: float = 0¶

to_dict() → dict¶

property total_mass¶: Total mass in solar masses, \(M = m_1 + m_2\).

trigger_time: float = 0¶

values(*args, **kwargs)¶

class ringdown.waveforms.Ringdown(*args, modes=None, **kwargs)¶

Bases: Signal

Compute complex-valued ringdown mode waveform, as given by Eq. (8) in Isi & Farr (2021), namely

\[h = \frac{1}{2} A e^{-t \gamma}*\left((1 + \epsilon) e^{-i(\omega t - \phi_p)} + (1 - \epsilon) e^{i (\omega*t + \phi_m)}\right)\]

where \(\phi_p = \phi - \theta\) and \(\phi_m = -(\phi + \theta)\).

Parameters:

time (array) – time array [t].
omega (float) – angular frequency of the mode [1/t].
gamma (float) – damping rate of the mode [1/t].
a (float) – amplitude of the mode.
ellip (float) – ellipticity of the mode.
theta (float) – angle of ellipse in \(h_+,h_\times\) space, in radians.
phi (float) – phase angle in radians.

Returns:

h – complex-valued waveform.

Return type:

array

classmethod from_parameters(time: array, t0: float = 0, signal_buffer: float = inf, two_sided: bool = True, df_pre: float = 0, dtau_pre: float = 0, mode_isel: float = None, **kws)¶

Create injection: a sinusoid up to t0, then a damped sinusoid. The (A_pre, df_pre, dtau_pre) parameters can extend the damped sinusoid backwards into a sinusoid or a ring-up, to produce a ring-up. Can incorporate several modes, if (A, phi0, f, tau) are 1D.

Parameters:

time (array) – time array [t].
t0 (float) – ringdown model start time.
signal_buffer (float) – window of time around t0 over which to evaluate model (default np.inf, the full time segment).
two_sided (bool) – whether to include a ring-up in times preceding t0 (default True).
df_pre (float) – frequency shift for ring-up (default 0).
dtau_pre (float) – damping shift for ring-up (default 0).
mode_isel (list, int) – index or indices of modes to include in template; if None includes all modes (default).

get_mode_parameters(mode)¶

get_parameter(k, *args, **kwargs)¶

Get parameter k from Signal.parameters.

Parameters:: k (str) – parameter key.
Returns:: value – parameter value.
Return type:: any

property n_modes¶

class ringdown.waveforms.Signal(*args, parameters=None, **kwargs)¶

Bases: TimeSeries

Base class for gravitational wave signals, with methods for projection onto detectors and signal processing.

property envelope: Signal¶

classmethod from_parameters(*args, **kwargs) → Signal¶

Produce a gravitational wave from parameters, for either a full compact binary coalescence, or the ringdown alone.

Input is passed to the corresponding constructor method, depending on the model specified in arguments. Assumes signal is ringdown by default.

Parameters:

*args – arguments passed to constructor.
**kwargs – keyword arguments passed to constructor.

Returns:

signal – subclass of signal.

Return type:

Signal

get_parameter(k: str, *args)¶

Get parameter k from Signal.parameters.

Parameters:: k (str) – parameter key.
Returns:: value – parameter value.
Return type:: any

property hc: Signal¶

property hp: Signal¶: Plus polarization component of the waveform.

property peak_time¶: Empirical estimate of the time of waveform envelope peak, \(\max\left(h_+^2 + h_\times^2\right)\), obtained through quadratic sub-sample interpolation.

plot(ax=None, envelope: bool = False)¶

Plot the series’ plus and cross components. Remember that the value of this timeseries is h = hp - 1j*hc.

Parameters:

ax (matplotlib.pyplot.Axes, None) – axis on which to plot, or None to create a new figure.
envelope (bool) – plot the envelope of the waveform, \(|h|\), as a dashed line.

Project waveform onto detector, multiplying by antenna patterns and shifting by time-of-flight delay (if required).

Parameters:

ifo (str) – name of detector onto which to project signal, used to compute antenna_patterns and delay, if not provided explicitly.
t0 (float) – trigger time used to compute antenna_patterns and delay, if not provided explicitly; if projecting from ifo name, assumes this is GPS time. Defaults to Signal.t0.
antenna_patterns (tuple[float]) – tuple of floats with plus and cross antenna pattern values (Fp, Fc); computed based on ifo and sky location if not given.
delay (float, str) – numerical delay by which to shift signal, or 'from_geo' to indicate delay is to be computed relative to geocenter for detector specified by ifo. Defaults to 0, which results in no time shift.
ra (float) – source right ascension (rad), only used if projecting based on detector name.
dec (float) – source declination (rad), only used if projecting based on detector name.
psi (float) – source polarization angle (rad), only if projecting based on detector name.
fd_shift (bool) – time shift signal in the Fourier domain, if time shifting at all (determined by delay argument). Defaults to False.
interpolate (bool) – use cubic subsample signal interpolation when shifting in the time domain (fd_shift = False); otherwise, rolls by number of samples closest to delay. Defaults to False.

Returns:

data – signal projected onto detector.

Return type:

Data

property t0¶: Reference time t0, or alias, from Signal.parameters. Valid aliases are: [‘t0’, ‘geocent_time’, ‘trigger_time’, ‘triggertime’, ‘tc’, ‘tgps_geo’, ‘tgps_geocent’].

ringdown.waveforms.get_delay(ifo: str, t0: <MagicMock name='mock.__ror__()' id='140036753758288'>, ra: float, dec: float, reference: str = 'from_geo')¶

Compute time-of-flight delay from geocenter to detector, or between detectors.

Parameters:

ifo (str) – detector prefix.
t0 (float, LIGOTimeGPS) – reference time.
ra (float) – right ascension (rad).
dec (float) – declination (rad).
reference (str) – reference for time-of-flight delay; can be either 'from_geo' to compute delay from geocenter to detector, or the prefix of another detector to compute delay between detectors.

Returns:

dt – time-of-flight delay.

Return type:

float

Produce templates at each detector for a given set of parameters. Can be used to generate waveforms from model samples, or to obtain IMR injections.

Additional keyword arguments are passed to Signal.from_parameters() and Signal.project().

Parameters:

times (dict, array) – a dictionary with time stamps for each detector, or a single array of time stamps to be shared by all detectors.
ifos (list) – list of detector names, only required if times is a single array.
antenna_patterns (dict, None) – optional dictionary of tuples with plus and cross antenna patterns for each detector, (Fp, Fc); if not given, computed from sky location provided in keyword arguments.
trigger_times (dict, None) – dictionary of arrival-times at each detector; computed from sky location and reference trigger time if not given.
t0_default (float) – optional default trigger time, to be used if no other valid trigger time argument is provided in keyword arguments.
fast_projection (bool) – if true, evaluates polarization functions only once using the time array of the first interferometer and then projects onto each detector by time shifting; otherwise, evaluates polarizations for each detector, ensuring that there are no off-by-one alignment errors. (Def. False)
**kws – arguments passed to Signal.from_parameters() and/or Signal.project().

Returns:

sdict – dictionary of Data waveforms for each detector.

Return type:

dict

QNMs module¶

class ringdown.qnms.KerrMode(*args, **kwargs)¶

Bases: object

A Kerr quasinormal mode.

property coefficients¶

static compute_coefficients(mode, n_chi=4096, **kws)¶

fgamma(chi, m_msun=None, approx=False)¶

ftau(chi, m_msun=None, approx=False)¶

ringdown.qnms.get_ftau(M, chi, n, l=2, m=2)¶

Get the frequency and damping time of a Kerr quasinormal mode.

This is a wrapper around the package qnm.

Parameters:

M (float) – Black hole mass in solar masses.
chi (float) – Dimensionless spin parameter.
n (int) – Overtone number.
l (int) – Spherical harmonic index (def. 2)
m (int) – Azimuthal harmonic index (def. 2)

Returns:

f (float) – Frequency of the mode in Hz.
tau (float) – Damping time of the mode in seconds.

Indexing module¶

class ringdown.indexing.GenericIndex(i: int)¶

Bases: ModeIndex

Generic mode index for non-harmonic modes (a wrapper around an integer).

classmethod construct(i)¶

get_coordinate()¶

get_label(**kws)¶

i: int¶

property is_prograde¶

class ringdown.indexing.ModeIndex¶

Bases: ABC

Abstract class to construct mode indices. Use the construct method to create a mode index object from a string, tuple, or other object.

as_dict()¶

classmethod construct(*mode)¶

abstract get_coordinate()¶

abstract get_label(**kws)¶

abstract property is_prograde¶

class ringdown.indexing.ModeIndexList(indices=None)¶

Bases: object

get_coordinates()¶

get_labels(**kws)¶

index(x)¶

property is_generic¶

property n_modes¶

property value¶

ringdown.indexing.get_mode_coordinate(mode, **kws)¶

ringdown.indexing.get_mode_label(mode, **kws)¶

Target module¶

Module defining the core Target class.

class ringdown.target.DetectorTarget(detector_times: dict | None = None, antenna_patterns: dict | None = None)¶

Bases: Target

Target for a ringdown analysis defined from explicit detector times and antenna patterns, rather than a sky location and a geocenter time.

antenna_patterns: dict | None = None¶

Create a target object from a set of detector times and antenna patterns.

The preferred input is two dictionaries of detector times and antenna pattern (Fp, Fc) tuples indexed by interferometer name. Alternatively, lists of values can be provided for both detector_times and antenna_patterns to be indexed by a list of interferometer names ifo.

If a single time is provided, it will be used for all detectors. If a single tuple is provided for antenna patterns, it will be used if only a single detector was specified through ifos.

If no detector names are specified as either keys of antenna_patterns or the ifos argument, then will assume a single detector named None.

detector_times: dict | None = None¶

get_antenna_patterns(ifo) → tuple[float, float]¶

get_detector_time(ifo) → float¶

property sky: tuple[None]¶: Sky location is (None, None, None)

property t0: None¶: Geocenter reference time is None

class ringdown.target.SkyTarget(geocenter_time: <MagicMock name='mock.__ror__().__or__()' id='140036490402688'> = None, ra: float | None = None, dec: float | None = None, psi: float | None = None)¶

Bases: Target

Sky location target for a ringdown analysis.

classmethod construct(t0: float, ra: float, dec: float, psi: float, reference_ifo: str | None = None, **kws)¶

Create a sky location from a reference time, either a specific detector or geocenter.

Parameters:

t0 (float) – detector time.
ra (float) – source right ascension.
dec (float) – source declination.
psi (float) – source polarization angle.
reference_ifo (str, None) – detector name, or None for geocenter (default None)

Returns:

sky – a target object.

Return type:

Target

dec: float | None = None¶

geocenter_time: <MagicMock name='mock.__ror__().__or__()' id='140036490402688'> = None¶

get_antenna_patterns(ifo) → tuple[float, float]¶

Compute antenna patterns based on sky location.

Parameters:: ifos (list) – list of detector names.
Returns:: antenna_patterns – dictionary of antenna patterns.
Return type:: dict

get_detector_time(ifo) → float¶

Compute detector times based on sky location.

Parameters:: ifo (list) – detector name.
Returns:: times – time for specified detector.
Return type:: float

psi: float | None = None¶

ra: float | None = None¶

property sky: tuple[float | None]¶: Return sky location as a tuple (ra, dec, psi).

property t0: float | None¶: Alias for time_geocenter.

class ringdown.target.Target¶

Bases: ABC

Abstract class to define a target for a ringdown analysis. A target can be defined either by a sky location or by detector times and antenna patterns. Use the construct method to create a target object from a dictionary or keyword arguments.

as_dict() → dict¶

Create a target object from a dictionary or keyword arguments. The source sky location and orientation can be specified by the ra, dec, and psi arguments. These are use to both determine the truncation time at different detectors, as well as to compute the corresponding antenna patterns.

Alternatively, analysis times and antenna patterns can be specified directly for each detector. In this case, the t0 argument should be a dictionary with detector names as keys and start times as values.

Cannot simultaneously provide both sky location and detector times.

Parameters:

t0 (float, dict) – start time for the analysis, either a single time or a dictionary of times for each detector.
ra (float, None) – source right ascension.
dec (float, None) – source declination.
psi (float, None) – source polarization angle.
reference_ifo (str, None) – detector name for time reference, or None for geocenter (default None)
antenna_patterns (dict, None) – dictionary of antenna patterns for each detector, or None to compute from sky location.

abstract get_antenna_patterns(ifo) → tuple[float, float] | None¶

get_antenna_patterns_dict(ifos) → dict¶

abstract get_detector_time(ifo) → float | None¶

get_detector_times_dict(ifos) → dict¶

property has_sky: bool¶

property is_set: bool¶

abstract property sky: tuple[float | None]¶

abstract property t0: float | None¶

class ringdown.target.TargetCollection(targets: list | None = None, index=None, reference_mass=None, reference_time=None, info=None)¶

Bases: MultiIndexCollection

Collection of targets for a ringdown analysis. The collection can be initialized with a list of Target objects, or by specifying the start times and sky locations for each target. The collection can also store a reference time to label start times, as well as a reference mass (in solar masses) to label time steps in units of mass. The collection can be indexed by start times, and can provide time differences with respect to the reference time, or time steps in units of mass.

classmethod from_config(config_input, t0_sect='pipe', sky_sect='target')¶

Identify target analysis times. There will be three possibilities:: 1- listing the times explicitly 2- listing time differences with respect to a reference time 3- providing start, stop, step instructions to construct start times (potentially relative to a reference time)

Time steps/differences can be specified in seconds or M, if a reference mass is provided (in solar masses).

get(key) → list | ndarray¶: Get attribute key for each target in the collection.

get_antenna_patterns(ifo) → list[tuple[float, float]]¶: Get antenna patterns for each target in the collection.

get_detector_times(ifo) → list[float]¶: Get detector times for each target in the collection.

property index: list¶: Index for the collection; defaults to start times if none provided.

property reference_mass: float | None¶: Reference mass in solar masses to use for time steps in units of mass.

property reference_mass_time: float | None¶: Reference mass in units of seconds.

property reference_time: float | None¶: Reference time relative to which to compute time differences.

set_reference_mass(mref: float | None) → None¶: Set the reference mass for the collection.

set_reference_time(t0: float | None) → None¶: Set the reference time for the collection.

property step_mass: float | None¶: Time step for the collection, in units of mass.

property step_time: float | None¶: Time step for the collection, in seconds.

property t0: ndarray¶: Start times for each target in the collection.

property t0m: ndarray¶: Start times relative to the reference time in units of mass.

property targets: list¶: List of targets in the collection.

update_info(section: str, **kws) → None¶: Update fit information stored in TargetCollection.info

Utilities module¶

class ringdown.utils.Bounded_1d_kde(pts, x_min=None, x_max=None, *args, **kwargs)¶

Bases: gaussian_kde

Represents a one-dimensional Gaussian kernel density estimator for a probability distribution function that exists on a bounded domain.

Authorship: Ben Farr, LIGO

evaluate(pts)¶: Return an estimate of the density evaluated at the given points.

property x_max¶: The upper bound of the x domain.

property x_min¶: The lower bound of the x domain.

class ringdown.utils.Bounded_2d_kde(pts, x_min=None, x_max=None, y_min=None, y_max=None, *args, **kwargs)¶

Bases: gaussian_kde

Represents a two-dimensional Gaussian kernel density estimator for a probability distribution function that exists on a bounded domain.

evaluate(pts)¶: Return an estimate of the density evaluated at the given points.

property x_max¶: The upper bound of the x domain.

property x_min¶: The lower bound of the x domain.

property y_max¶: The upper bound of the y domain.

property y_min¶: The lower bound of the y domain.

class ringdown.utils.ConfigParser(defaults=None, dict_type=<class 'dict'>, allow_no_value=False, *, delimiters=('=', ':'), comment_prefixes=('#', ';'), inline_comment_prefixes=None, strict=True, empty_lines_in_values=True, default_section='DEFAULT', interpolation=<object object>, converters=<object object>)¶

Bases: RawConfigParser

ConfigParser implementing interpolation.

add_section(section)¶: Create a new section in the configuration. Extends RawConfigParser.add_section by validating if the section name is a string.

set(section, option, value=None)¶: Set an option. Extends RawConfigParser.set by validating type and interpolation syntax on the value.

class ringdown.utils.IMRResult(data=None, index: Axes | None = None, columns: Axes | None = None, dtype: Dtype | None = None, copy: bool | None = None)¶

Bases: DataFrame

property final_mass: ndarray¶

property final_spin: ndarray¶

get_kerr_frequencies(modes, **kws)¶

Get the Kerr QNM frequencies corresponding to the remnant mass and spin for a list of modes.

Parameters:: modes (list of str | list of indexing.ModeIndex) – any argument accepted by indexing.ModeIndexList.

get_mode_parameter_dataframe(modes, **kws)¶

get_remnant_parameters(f_ref: float = -1, model: str = 'NRSur7dq4Remnant', nproc: int | None = None, force: bool = False)¶

Compute remnant parameters using the LALSuite nrfits module.

Parameters:

f_ref (float) – Reference frequency for the remnant parameters in Hz; if -1, uses earliest point in the waveform.
model (str) – Name of the model to use for the remnant parameters; default is ‘NRSur7dq4Remnant’.
nproc (int | None) – Number of processes to use for parallel computation; if None, uses serial computation.
force (bool) – If True, forces recomputation of the remnant parameters if already present in the DataFrame.

Returns:

df – view of DataFrame columns with the remnant parameters: ‘final_mass’ and ‘final_spin’.

Return type:

IMRResult

class ringdown.utils.MultiIndexCollection(data=None, index=None, reference_mass=None, reference_time=None, info=None)¶

Bases: object

add(key, value)¶

get(key)¶

property index¶

items()¶

keys()¶

property reference_mass¶

property reference_time¶

reindex(new_index)¶

set_reference_mass(reference_mass)¶

set_reference_time(reference_time)¶

values()¶

ringdown.utils.docstring_parameter(*args, **kwargs)¶

ringdown.utils.form_opt(x)¶: Utility to format options in config.

ringdown.utils.get_dict_from_pattern(path, ifos=None, abspath=False)¶

ringdown.utils.get_tqdm(progress: bool = True)¶: Return the appropriate tqdm based on the execution environment.

ringdown.utils.kdeplot(xs, ys=None, **kws)¶

ringdown.utils.literal_eval(node_or_string)¶

Evaluate an expression node or a string containing only a Python expression. The string or node provided may only consist of the following Python literal structures: strings, bytes, numbers, tuples, lists, dicts, sets, booleans, and None.

Caution: A complex expression can overflow the C stack and cause a crash.

ringdown.utils.load_config(config_input)¶

ringdown.utils.load_config_dict(config_input)¶

ringdown.utils.np2(x)¶: Returns the next power of two as big as or larger than x.

ringdown.utils.string_to_tuple(s)¶

ringdown.utils.try_parse(x)¶: Attempt to parse a string as a number, dict, or list.

API reference¶

Data module¶

Fit module¶

Model module¶

Result module¶

Waveforms module¶

QNMs module¶

Indexing module¶

Target module¶

Utilities module¶

ringdown

Navigation

Related Topics