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 |
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 |
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, |
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 |
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 |
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 containingtd(time-domain strain),dt(time step in seconds), andstart_time(GPS start time). It may also holdwindow,trigger_time,frequency_boundsandfd, whichto_filewrites; 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. Requiresgwpy. 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. |
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 |
None
|
**kws
|
Keyword arguments for |
{}
|
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
|
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 keystd(time-domain strain),dt(time step in seconds),start_time(GPS),name,window,frequency_boundsand, if they were set,trigger_timeandfd. 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.txtbut comma-separated..gwf— LIGO/Virgo Gravitational Wave Frame file (time-domain). Requiresgwpy..hdf5/.h5— HDF5 file (time-domain). Requiresgwpy.
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 |
{}
|
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 containingvaluesandfrequenciesarrays (to_filewrites PSD values)..txt/.dat— two-column whitespace-separated text file(frequency, value)..csv— same two-column format as.txt/.datbut 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 |
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 |