dingo.gw.domains package

Submodules

dingo.gw.domains.base module

class dingo.gw.domains.base.Domain

Bases: ABC

Defines the physical domain on which the data of interest live.

This includes a specification of the bins or points, and a few additional properties associated with the data.

abstract property domain_dict

Enables to rebuild the domain via calling build_domain(domain_dict).

abstract property duration: float

Waveform duration in seconds.

abstract property f_max: float

The maximum frequency [Hz] is set to half the sampling rate.

abstract property max_idx: int
abstract property min_idx: int
abstract property noise_std: float

Standard deviation of the whitened noise distribution

abstract property sampling_rate: float

The sampling rate of the data [Hz].

abstract time_translate_data(data, dt) → ndarray

Time translate strain data by dt seconds.

abstract update(new_settings: dict)

dingo.gw.domains.base_frequency_domain module

class dingo.gw.domains.base_frequency_domain.BaseFrequencyDomain

Bases: Domain, ABC

static add_phase(data: ndarray | Tensor, phase: ndarray | Tensor) → ndarray | Tensor

Add a (frequency-dependent) phase to a frequency series. Allows for batching, as well as additional channels (such as detectors). Accounts for the fact that the data could be a complex frequency series or real and imaginary parts.

Convention: the phase \(\phi(f)\) is defined via \(\exp[- i \phi(f)]\).

Parameters:

  • data (Union[np.array, torch.Tensor])

  • phase (Union[np.array, torch.Tensor])

Return type:

New array or tensor of the same shape as data.

check_data_compatibility(data: ndarray) → bool

Check that the trailing dimension of data is compatible with the domain, i.e., compare against the domain length.

Parameters:

data (np.ndarray)

Returns:

Whether the data are compatible with domain.

Return type:

bool

property delta_f: float | ndarray
abstract property f_min: float
abstract property frequency_mask: ndarray
abstract property frequency_mask_length: int
get_sample_frequencies_astype(data: ndarray | Tensor) → ndarray | Tensor

Returns a 1D frequency array compatible with the last index of data array.

Decides whether array is numpy or torch tensor (and cuda vs cpu).

Parameters:

data (Union[np.array, torch.Tensor]) – Sample data

Return type:

Frequency array compatible with last index, of the same type as input

property noise_std: float

Standard deviation per bin for white noise,

\[ \sigma_{\mathrm{noise}} = \sqrt{\frac{1}{4 \delta f}} \]

Historical note: Note we no longer use the noise std of the form

\[ \sigma_{\mathrm{noise}} = \sqrt{\frac{w}{4 \delta f}} \]
where \(w\) is the window factor. For the full discussion, see https://git.ligo.org/pe/pe-group-coordination/-/issues/1#note_1465275.

To scale noise such that it is consistent with a multivariate unit normal distribution in the, you must divide whitened data by the noise_std. For the UniformFrequencyDomain, noise_std is a number, as delta_f is constant across the domain. For the MultibandedFrequencyDomain, it is an array.

abstract property sample_frequencies: ndarray
property sample_frequencies_torch: Tensor
property sample_frequencies_torch_cuda: Tensor
time_translate_data(data: ndarray | Tensor, dt: float | ndarray | Tensor) → ndarray | Tensor

Time translate frequency-domain data by dt. Time translation corresponds (in frequency domain) to multiplication by

\[ \exp(-2 \pi i f \cdot dt). \]

This method allows for multiple batch dimensions. For torch.Tensor data, allow for either a complex or a (real, imag) representation.

Parameters:

  • data (array-like (numpy, torch)) –

    Shape (B, C, N), where

    • B corresponds to any dimension >= 0,

    • C is either absent (for complex data) or has dimension >= 2 (for data represented as real and imaginary parts), and

    • N is either len(self) or len(self)-self.min_idx (for truncated data).

  • dt (torch tensor, or scalar (if data is numpy)) – Shape (B)

Return type:

Array-like of the same form as data.

dingo.gw.domains.build_domain module

dingo.gw.domains.build_domain.build_domain(settings: dict) → Domain

Instantiate a domain class from settings.

Parameters:

settings (dict) – Dictionary with ‘type’ key denoting the type of domain, and keys corresponding to the kwargs needed to construct the Domain.

Return type:

A Domain instance of the correct type.

dingo.gw.domains.build_domain.build_domain_from_model_metadata(model_metadata: dict, base: bool = False) → Domain

Instantiate a domain class from settings of model.

Parameters:

  • model_metadata (dict) – model metadata containing information to build the domain typically obtained from the model.metadata attribute

  • base (bool = False) – If base=True, return domain.base_domain if this is an attribute of domain, else return domain. Example: MultibandedFrequencyDomain has a UniformFrequencyDomain object as a base_domain. In dingo_pipe, we want to load data in the base_domain, and later decimate from base_domain to domain.

Return type:

A Domain instance of the correct type.

dingo.gw.domains.multibanded_frequency_domain module

class dingo.gw.domains.multibanded_frequency_domain.MultibandedFrequencyDomain(nodes: Iterable[float], delta_f_initial: float, base_domain: UniformFrequencyDomain | dict)

Bases: BaseFrequencyDomain

Defines a non-uniform frequency domain that is made up of a sequence of uniform-frequency domain bands. Each subsequent band in the sequence has double the bin-width of the previous one, i.e., delta_f is doubled each band as one moves up the bands. This is intended to allow for efficient representation of gravitational waveforms, which generally have slower oscillations at higher frequencies. Indeed, the leading order chirp has phase evolution [see https://doi.org/10.1103/PhysRevD.49.2658],

\[ \Psi(f) = \frac{3}{4}(8 \pi \mathcal{M} f)^{-5/3}, \]
hence a coarser grid can be used at higher f.

The domain is partitioned into bands via a sequence of nodes that are specified at initialization.

In comparison to the UniformFrequencyDomain, the MultibandedFrequencyDomain has the following key differences:

  • The sample frequencies start at the first node, rather than f = 0.0 Hz.

  • Quantities such as delta_f, noise_std, etc., are represented as arrays rather than

scalars, as they vary depending on f.

The MultibandedFrequencyDomain furthermore has an attribute base_domain, which holds an underlying UniformFrequencyDomain object. The decimate() method decimates data in the base_domain to the multi-banded domain.

Parameters:

  • nodes (Iterable[float]) – Defines the partitioning of the underlying frequency domain into bands. In total, there are len(nodes) - 1 frequency bands. Band j consists of decimated data from the base domain in the range [nodes[j]:nodes[j+1]).

  • delta_f_initial (float) – delta_f of band 0. The decimation factor doubles between adjacent bands, so delta_f is doubled as well.

  • base_domain (Union[UniformFrequencyDomain, dict]) – Original (uniform frequency) domain of data, which is the starting point for the decimation. This determines the decimation details and the noise_std. Either provided as dict for build_domain, or as domain_object.

decimate(data: ndarray | Tensor) → ndarray | Tensor

Decimate data from the base_domain to the multi-banded domain.

Parameters:

data (array-like (np.ndarray or torch.Tensor)) – Decimation is done along the trailing dimension of this array. This dimension should therefore be compatible with the base frequency domain, i.e., running from 0.0 Hz or f_min up to f_max, with uniform delta_f.

Return type:

Decimated array of the same type as the input.

property domain_dict: dict

Enables to rebuild the domain via calling build_domain(domain_dict).

property duration: float

Waveform duration in seconds.

property f_max: float

The maximum frequency [Hz] is set to half the sampling rate.

property f_min: float
property frequency_mask: ndarray

Array of len(self) consisting of ones.

As the MultibandedFrequencyDomain starts from f_min, no masking is generally required.

property frequency_mask_length: int
property max_idx
property min_idx
property sample_frequencies: ndarray
property sampling_rate: float

The sampling rate of the data [Hz].

update(new_settings: dict)

Update the domain by truncating the frequency range (by specifying new f_min, f_max).

After calling this function, data from the original domain can be truncated to the new domain using self.update_data(). For simplicity, we do not allow for multiple updates of the domain.

Parameters:

new_settings (dict) – Settings dictionary. Keys must either be the keys contained in domain_dict, or a subset of [“f_min”, “f_max”].

update_data(data: ndarray | Tensor, axis: int = -1, **kwargs) → ndarray | Tensor

Truncates the data array to be compatible with the domain. This is used when changing f_min or f_max.

update_data() will only have an effect after updating the domain to have a new frequency range using self.update().

Parameters:

  • data (array-like (np.ndarray or torch.Tensor)) – Array should be compatible with either the original or updated MultibandedFrequencyDomain along the specified axis. In the latter case, nothing is done. In the former, data are truncated appropriately.

  • axis (int) – Axis along which to operate.

Return type:

Updated data of the same type as input.

dingo.gw.domains.multibanded_frequency_domain.decimate_uniform(data, decimation_factor: int)

Reduce dimension of data by decimation_factor along last axis, by uniformly averaging sets of decimation_factor neighbouring bins.

Parameters:

  • data – Array or tensor to be decimated.

  • decimation_factor – Factor by how much to compress. Needs to divide data.shape[-1].

Returns:

Uniformly decimated data, as array or tensor. Shape (*data.shape[:-1], data.shape[-1]/decimation_factor).

Return type:

data_decimated

dingo.gw.domains.time_domain module

class dingo.gw.domains.time_domain.TimeDomain(time_duration: float, sampling_rate: float)

Bases: Domain

Defines the physical time domain on which the data of interest live.

The time bins are assumed to be uniform between [0, duration] with spacing 1 / sampling_rate.

property delta_t: float

The size of the time bins

property domain_dict

Enables to rebuild the domain via calling build_domain(domain_dict).

property duration: float

Waveform duration in seconds.

property f_max: float

The maximum frequency [Hz] is typically set to half the sampling rate.

property max_idx: int
property min_idx: int
property noise_std: float

Standard deviation of the whitened noise distribution.

To have noise that comes from a multivariate unit normal distribution, you must divide by this factor. In practice, this means dividing the whitened waveforms by this.

In the continuum limit in time domain, the standard deviation of white noise would at each point go to infinity, hence the delta_t factor.

property sampling_rate: float

The sampling rate of the data [Hz].

time_translate_data(data, dt) → ndarray

Time translate strain data by dt seconds.

dingo.gw.domains.uniform_frequency_domain module

class dingo.gw.domains.uniform_frequency_domain.UniformFrequencyDomain(f_min: float, f_max: float, delta_f: float)

Bases: BaseFrequencyDomain

Defines the physical domain on which the data of interest live.

The frequency bins are assumed to be uniform between [0, f_max] with spacing delta_f.

Given a finite length of time domain data, the Fourier domain data starts at a frequency f_min and is zero below this frequency.

window_kwargs specify windowing used for FFT to obtain FD data from TD data in practice.

Parameters:

  • f_min (float)

  • f_max (float)

  • delta_f (float)

property delta_f: float

The frequency spacing of the uniform grid [Hz].

property domain_dict

Enables to rebuild the domain via calling build_domain(domain_dict).

property duration: float

Waveform duration in seconds.

property f_max: float

The maximum frequency [Hz] is typically set to half the sampling rate.

property f_min: float

The minimum frequency [Hz].

property frequency_mask: ndarray

Mask which selects frequency bins greater than or equal to the starting frequency

property frequency_mask_length: int

Number of samples in the subdomain domain[frequency_mask].

get_sample_frequencies_astype(data: ndarray | Tensor) → ndarray | Tensor

Returns a 1D frequency array compatible with the last index of data array.

Decides whether array is numpy or torch tensor (and cuda vs cpu), and whether it contains the leading zeros below f_min.

Parameters:

data (Union[np.array, torch.Tensor]) – Sample data

Return type:

frequency array compatible with last index

property max_idx: int
property min_idx: int
property sample_frequencies: ndarray
property sampling_rate: float

The sampling rate of the data [Hz].

update(new_settings: dict)

Update the domain with new settings. This is only allowed if the new settings are “compatible” with the old ones. E.g., f_min should be larger than the existing f_min.

Parameters:

new_settings (dict) – Settings dictionary. Must contain a subset of the keys contained in domain_dict.

update_data(data: ndarray, axis: int = -1, low_value: float = 0.0)

Adjusts data to be compatible with the domain:

  • Below f_min, it sets the data to low_value (typically 0.0 for a waveform, but for a PSD this might be a large value).

  • Above f_max, it truncates the data array.

Parameters:

  • data (np.ndarray) – Data array

  • axis (int) – Which data axis to apply the adjustment along.

  • low_value (float) – Below f_min, set the data to this value.

Returns:

The new data array.

Return type:

np.ndarray

Module contents