Skip to content

data

Data ¤

Bases: _Freezable, ABC

Base class for all data.

The time domain data are considered the primary entity; the frequency domain data are derived from an FFT after applying a window. The structure is set up so that td and fd are always Fourier conjugates of each other: the one-sided Fourier series is complete up to the Nyquist frequency.

Attributes:

Name Type Description
name str

Name of the data instance.

td Float[Array, n_time]

Time domain data array.

fd Complex[Array, n_time // 2 + 1]

Frequency domain data array.

start_time float

GPS start time of the data segment in seconds.

end_time float

Exclusive GPS end of the actual samples, derived from their start, count and time step.

trigger_time float

GPS time of the event trigger in seconds, the reference time of t_c. Defaults to 2 s before the end of the data.

delta_t FloatLike

Time step between samples.

window Float[Array, n_time]

Window function applied to data.

Methods:

Name Description
__bool__

Check if the data is empty.

__init__

Initialize empty data, the placeholder of a detector without data.

__iter__

Iterator over the time-domain data.

__len__

Returns the length of the time-domain data.

add_fd

Return a copy of the data with a frequency series added to fd.

fft

Compute the Fourier transform of the windowed time-domain data.

frequency_slice

Slice the data in the frequency domain.

from_fd

Create a Data object starting from (potentially incomplete)

from_file

Load data from a file.

from_gwosc

Pull data from GWOSC.

from_td

Create data from time domain samples.

normalize_fd

Validate a finite series on this grid and make real-FFT endpoints real.

set_tukey_window

Configure the Tukey window used when FFTing time-domain data.

to_file

Save the data to a file.

to_psd

Compute a Welch estimate of the power spectral density of the data.

duration: FloatLike property ¤

Gets duration of the data in seconds.

Returns:

Name Type Description
float FloatLike

Duration in seconds.

end_time: float property ¤

Exclusive GPS end of the segment, one time step after its last sample.

fd: Complex[Array, n_time // 2 + 1] property ¤

Gets the frequency-domain data.

Data built from frequency-domain arrays hold them with real DC and Nyquist components. Otherwise they are fft() of the time-domain data, computed on first use and kept, so the window can no longer change.

Returns:

Name Type Description
Array Complex[Array, n_time // 2 + 1]

frequency-domain data.

Raises:

Type Description
ValueError

If the data are empty.

frequencies: Float[Array, n_time // 2 + 1] property ¤

Gets frequencies of the data.

Returns:

Name Type Description
Array Float[Array, n_time // 2 + 1]

Array of frequencies in Hz.

frequency_bounds: tuple[float, float] property writable ¤

Gets the frequency range of the data.

Returns:

Name Type Description
tuple tuple[float, float]

The minimum and maximum frequency in Hz. The default, (0, inf), does not restrict the data.

frequency_mask: Bool[Array, n_freq] property ¤

Gets the mask of the frequencies inside the frequency range of the data.

Returns:

Name Type Description
Array Bool[Array, n_freq]

True for the frequencies from f_min to f_max.

has_fd: bool property ¤

Checks whether frequency-domain data have been computed or supplied.

Returns:

Name Type Description
bool bool

True if frequency-domain data are fixed, False otherwise.

is_empty: bool property ¤

Checks if the data is empty.

Returns:

Name Type Description
bool bool

True if data is empty, False otherwise.

n_freq: int property ¤

Gets number of frequency samples.

Returns:

Name Type Description
int int

Number of frequency domain samples.

n_time: int property ¤

Gets number of time samples.

Returns:

Name Type Description
int int

Number of time domain samples.

sampling_frequency: FloatLike property ¤

Gets sampling frequency of the data.

Returns:

Name Type Description
float FloatLike

Sampling frequency in Hz.

start_time: float property writable ¤

GPS start time of the segment, as a finite real scalar.

times: Float[Array, n_time] property ¤

Gets time points of the data.

Returns:

Name Type Description
Array Float[Array, n_time]

Array of time points in seconds.

trigger_time: float property writable ¤

Gets the GPS time of the event trigger, the reference time of t_c.

Returns:

Name Type Description
float float

The trigger time in seconds; unless it was set, 2 s before the end of the data.

Raises:

Type Description
ValueError

If the data are empty and no trigger time was set.

__bool__() -> bool ¤

Check if the data is empty.

__init__(*args: Never, **kwargs: Never) -> None ¤

Initialize empty data, the placeholder of a detector without data.

It takes no arguments: create data with from_td, from_fd, from_gwosc or from_file.

Raises:

Type Description
TypeError

If any argument is given.

__iter__() ¤

Iterator over the time-domain data.

Returns:

Name Type Description
iterator

Iterator over time domain data.

__len__() -> int ¤

Returns the length of the time-domain data.

Returns:

Name Type Description
int int

Length of time domain data array.

add_fd(frequency_series: Complex[Array, n_freq]) -> Self ¤

Return a copy of the data with a frequency series added to fd.

The copy keeps every other property of the data, such as the trigger time and the frequency range of the data, and has no window. Imaginary DC and even-length Nyquist components are discarded so the TD and FD arrays stay conjugate. The original data, including their FFT cache, are unchanged. The returned data are mutable even if the original data are frozen.

Parameters:

Name Type Description Default
frequency_series Complex[Array, n_freq]

Array to add, on the frequencies of the data.

required

Raises:

Type Description
ValueError

If frequency_series does not have the shape of fd or contains non-finite values.

fft(window: Optional[Float[Array, n_time]] = None) -> Complex[Array, n_freq] ¤

Compute the Fourier transform of the windowed time-domain data.

Parameters:

Name Type Description Default
window Optional[Float[Array, n_time]]

Window function to apply to the data before the transform (default: the window of the data).

None

Returns:

Name Type Description
Array Complex[Array, n_freq]

The Fourier transform, scaled by the time step.

frequency_slice(f_min: FloatLike, f_max: FloatLike) -> tuple[Float[Array, ' n_sample'], Complex[Array, ' n_sample']] ¤

Slice the data in the frequency domain. This is the main function which interacts with the likelihood.

Parameters:

Name Type Description Default
f_min FloatLike

Minimum frequency of the slice in Hz.

required
f_max FloatLike

Maximum frequency of the slice in Hz.

required

Returns:

Name Type Description
tuple tuple[Float[Array, ' n_sample'], Complex[Array, ' n_sample']]

The frequencies in the slice and the sliced data in the frequency domain.

from_fd(fd: Complex[Array, n_freq], frequencies: Float[Array, n_freq], *, start_time: float = 0.0, trigger_time: Optional[float] = None, name: str = '') -> Self classmethod ¤

Create a Data object starting from (potentially incomplete) frequency domain data. The frequencies must be consecutive points of a real-FFT grid, ending at the Nyquist frequency of an even-length segment. Imaginary DC and Nyquist components are discarded because real samples cannot represent them.

Parameters:

Name Type Description Default
fd Complex[Array, n_freq]

Frequency domain data array.

required
frequencies Float[Array, n_freq]

Frequencies of the data in Hz.

required
start_time float

GPS start time of the segment in seconds (default: 0).

0.0
trigger_time Optional[float]

GPS time of the event trigger in seconds (default: 2 s before the end of the data).

None
name str

Name of the data (default: '').

''

Returns:

Name Type Description
Data Self

Data object with the frequency and time domain data.

Raises:

Type Description
ValueError

If arrays differ in shape, contain non-finite values, or frequencies are not at least two nonnegative, strictly increasing, uniformly spaced points aligned with a real-FFT grid.

from_file(path: str, channel: Optional[str] = None, start_time: Optional[float] = None, end_time: Optional[float] = None) -> Self classmethod ¤

Load data from a file.

Supported formats:

  • .npz — NumPy archive containing td (time-domain strain), dt (time step in seconds), and start_time (GPS start time). It may also hold window, trigger_time, frequency_bounds and fd, which to_file writes; without them the data get the default Tukey window, trigger time and frequency range of the data.
  • .gwf / .gwf.gz — LIGO/Virgo Gravitational Wave Frame file. Requires gwpy. Specify channel (e.g. 'H1:GDS-CALIB_STRAIN'); if omitted, common preset channel names are tried automatically.
  • .hdf5 / .h5 / .hdf — HDF5 file readable by gwpy. channel names the dataset; it is required when the file contains several.
  • .csv — Two-column CSV time-series file (gwpy format). channel only names the data.

Parameters:

Name Type Description Default
path str

Path to the file.

required
channel Optional[str]

Channel name for frame or HDF5 files (e.g. 'H1:GDS-CALIB_STRAIN'). Ignored for .npz.

None
start_time Optional[float]

GPS start time to read (optional; for gwpy-backed formats).

None
end_time Optional[float]

GPS end time to read (optional; for gwpy-backed formats).

None

Returns:

Name Type Description
Data Self

Data object with the loaded time domain data.

from_gwosc(ifo: str, gps_start_time: float, gps_end_time: float, cache: bool = True, *, trigger_time: Optional[float] = None, **kws) -> Self classmethod ¤

Pull data from GWOSC.

The reference time of t_c defaults to two seconds before the requested end time. Detectors fetched for the same interval therefore share a reference, even if their sample timestamps are rounded differently. start_time and end_time describe the returned samples, using their epoch, time step and sample count rather than the requested boundaries.

Parameters:

Name Type Description Default
ifo str

Detector name.

required
gps_start_time float

Requested GPS start time of the data.

required
gps_end_time float

Requested GPS end time of the data.

required
cache bool

Whether to cache the data (default: True).

True
trigger_time Optional[float]

GPS reference time of t_c. Defaults to two seconds before the requested end time.

None
**kws

Keyword arguments for gwpy.timeseries.TimeSeries.fetch_open_data.

{}

Returns:

Name Type Description
Data Self

Data object with the fetched time domain data.

Raises:

Type Description
ValueError

If requested times or an explicit trigger time are not finite real scalars, or the end time is not later than the start.

from_td(td: Float[Array, n_time], delta_t: FloatLike, *, start_time: float = 0.0, trigger_time: Optional[float] = None, name: str = '', window: Optional[Float[Array, n_time]] = None) -> Self classmethod ¤

Create data from time domain samples.

Parameters:

Name Type Description Default
td Float[Array, n_time]

Time domain data array.

required
delta_t FloatLike

Time step of the data in seconds.

required
start_time float

GPS start time of the segment in seconds (default: 0).

0.0
trigger_time Optional[float]

GPS time of the event trigger in seconds (default: 2 s before the end of the data).

None
name str

Name of the data (default: '').

''
window Optional[Float[Array, n_time]]

Window function to apply to the data before FFT (default: None).

None

Returns:

Name Type Description
Data Self

Data object with the time domain data.

Raises:

Type Description
ValueError

If samples or the window are not one-dimensional, real and finite, if the window shape differs from the data, if timing metadata are not finite scalars, or if non-empty data have a non-positive time step.

normalize_fd(frequency_series: Complex[Array, n_freq]) -> Complex[Array, n_freq] ¤

Validate a finite series on this grid and make real-FFT endpoints real.

DC is real; the final bin is also real for an even number of time samples. With an odd number of samples, the final bin keeps its complex phase.

set_tukey_window(alpha: Optional[float] = None, roll_off: Optional[float] = None) -> None ¤

Configure the Tukey window used when FFTing time-domain data.

This must be called before frequency-domain data are computed or supplied. Only one of alpha and roll_off may be provided.

Parameters:

Name Type Description Default
alpha Optional[float]

Shape parameter passed directly to the Tukey window. If supplied, it must be finite and between 0 and 1.

None
roll_off Optional[float]

Duration in seconds of the taper on each side. Defaults to 0.4 seconds. It must be finite and between 0 and half the data duration. The corresponding shape parameter is 2 * roll_off / duration.

None

Raises:

Type Description
ValueError

If the data are empty, both parameterizations are supplied, or a parameter is outside its valid range.

RuntimeError

If frequency-domain data have already been fixed.

to_file(path: str) -> None ¤

Save the data to a file.

Supported formats:

  • .npz — NumPy archive with keys td (time-domain strain), dt (time step in seconds), start_time (GPS), name, window, frequency_bounds and, if they were set, trigger_time and fd. It is the only format that keeps the window, the trigger time and the frequency range of the data.
  • .txt / .dat — Three-column whitespace-separated text file containing [f, real(h(f)), imag(h(f))] (frequency-domain strain).
  • .csv — Same as .txt but comma-separated.
  • .gwf — LIGO/Virgo Gravitational Wave Frame file (time-domain). Requires gwpy.
  • .hdf5 / .h5 — HDF5 file (time-domain). Requires gwpy.

Parameters:

Name Type Description Default
path str

Path to the output file (extension determines format).

required

Raises:

Type Description
ValueError

If the file extension is not supported.

to_psd(**kws) -> PowerSpectrum ¤

Compute a Welch estimate of the power spectral density of the data.

Parameters:

Name Type Description Default
**kws

Keyword arguments for scipy.signal.welch.

{}

Returns:

Name Type Description
PowerSpectrum PowerSpectrum

Power spectral density of the data.

PowerSpectrum ¤

Bases: _Freezable, ABC

Class representing a power spectral density.

Attributes:

Name Type Description
name str

Name of the power spectrum.

values Float[Array, n_freq]

Array of PSD values.

frequencies Float[Array, n_freq]

Array of frequencies corresponding to PSD values.

Methods:

Name Description
__bool__

Check if the power spectrum is empty.

__init__

Initialize PowerSpectrum.

frequency_slice

Slice the power spectrum to a frequency range.

from_file

Load a power spectrum from a file.

interpolate

Interpolate the power spectrum to new frequencies.

simulate_data

Simulate noise data based on the power spectrum.

to_file

Save the power spectrum to a file in .npz format.

delta_f: FloatScalar property ¤

Get the positive spacing of a uniform frequency grid, in any order.

Returns:

Name Type Description
float FloatScalar

Frequency resolution in Hz.

Raises:

Type Description
ValueError

If fewer than two frequencies are present or the grid is not uniformly spaced.

delta_t: FloatScalar property ¤

Gets time resolution.

Returns:

Name Type Description
float FloatScalar

Time resolution in seconds.

duration: FloatScalar property ¤

Gets duration of the data.

Returns:

Name Type Description
float FloatScalar

Duration in seconds.

is_empty: bool property ¤

Checks if the data is empty.

Returns:

Name Type Description
bool bool

True if data is empty, False otherwise.

n_freq: int property ¤

Gets number of frequency samples.

Returns:

Name Type Description
int int

Number of frequency samples.

sampling_frequency: FloatScalar property ¤

Gets sampling frequency.

Returns:

Name Type Description
float FloatScalar

Sampling frequency in Hz.

__bool__() -> bool ¤

Check if the power spectrum is empty.

Returns:

Name Type Description
bool bool

True if power spectrum contains data, False otherwise.

__init__(values: Float[Array, n_freq] = _EMPTY_ARRAY, frequencies: Float[Array, n_freq] = _EMPTY_ARRAY, name: Optional[str] = None) -> None ¤

Initialize PowerSpectrum.

Parameters:

Name Type Description Default
values Float[Array, n_freq]

Array of PSD values. Defaults to empty array.

_EMPTY_ARRAY
frequencies Float[Array, n_freq]

Array of frequencies in Hz. Defaults to empty array.

_EMPTY_ARRAY
name Optional[str]

Name of the power spectrum. Defaults to None.

None

Raises:

Type Description
ValueError

If arrays are not one-dimensional real numeric arrays of the same shape, or frequencies are not finite, nonnegative and unique. Frequency ordering need not be monotonic.

frequency_slice(f_min: float, f_max: float) -> tuple[Float[Array, ' n_sample'], Float[Array, ' n_sample']] ¤

Slice the power spectrum to a frequency range.

Parameters:

Name Type Description Default
f_min float

Minimum frequency of the slice in Hz.

required
f_max float

Maximum frequency of the slice in Hz.

required

Returns:

Name Type Description
tuple tuple[Float[Array, ' n_sample'], Float[Array, ' n_sample']]

Contains: - frequencies: Frequencies in the slice - values: Sliced PSD values

from_file(path: str, is_asd: bool = False) -> Self classmethod ¤

Load a power spectrum from a file.

Supported formats:

  • .npz — NumPy archive containing values and frequencies arrays (to_file writes PSD values).
  • .txt / .dat — two-column whitespace-separated text file (frequency, value).
  • .csv — same two-column format as .txt/.dat but comma-separated.

In every format the values are a PSD in \(\mathrm{Hz}^{-1}\), unless is_asd is set.

Parameters:

Name Type Description Default
path str

Path to the PSD file.

required
is_asd bool

If True, the values in the file are an amplitude spectral density in \(\mathrm{Hz}^{-1/2}\) and are squared to obtain the PSD. Applies to every format. Defaults to False.

False

Returns:

Name Type Description
PowerSpectrum Self

Loaded power spectrum.

interpolate(frequencies: Float[Array, ' n_sample'], kind: str = 'linear', **kws) -> PowerSpectrum ¤

Interpolate the power spectrum to new frequencies.

Parameters:

Name Type Description Default
f

Frequencies to interpolate to.

required
kind str

Interpolation method. Defaults to 'linear'.

'linear'
**kws

Additional keyword arguments for scipy.interpolate.interp1d.

{}

Returns:

Name Type Description
PowerSpectrum PowerSpectrum

New power spectrum with interpolated values.

simulate_data(key: Key[Array, '']) -> Complex[Array, ' n_sample'] ¤

Simulate noise data based on the power spectrum.

Parameters:

Name Type Description Default
key Key[Array, '']

JAX PRNG key for random number generation.

required

Returns:

Type Description
Complex[Array, ' n_sample']

Complex frequency series of simulated noise data.

Raises:

Type Description
ValueError

If the frequencies do not form a uniform grid, any PSD value is not finite and positive, or the resulting variance cannot be represented as a finite positive number.

to_file(path: str) ¤

Save the power spectrum to a file in .npz format.

Parameters:

Name Type Description Default
path str

Path to save the .npz file.

required