cogwheel.data.EventData

class cogwheel.data.EventData(eventname, frequencies, strain, wht_filter, detector_names, tgps, tcoarse, injection=None)

Bases: JSONMixin

Class to save an event’s frequency-domain strain data and whitening filter for multiple detectors.

Parameters:

eventnamestr

Event name, e.g. 'GW150914'.

frequencies1-d array

Frequencies (Hz), as in numpy.fft.rfftfreq(), uniform and starting at 0.

strainarray of shape (ndet, nfreq)

Frequency-domain strain data (1/Hz).

wht_filterarray of shape (ndet, nfreq)

Frequency-domain whitening filter. It is important that entries are 0 below some minimum frequency so waveforms don’t need to be queried at arbitrarily low frequency.

detector_namessequence of str

E.g. 'HLV' or ('H', 'L', 'V') for Hanford-Livingston-Virgo.

tgpsfloat

GPS time of the event (s).

tcoarsefloat

Time of event relative to beginning of data.

injectiondict, optional

For bookkeeping, not actually used.

Methods

from_npz	Load a .npz file previously saved with to_npz().
from_timeseries
gaussian_noise	Constructor that generates stationary colored Gaussian noise.
get_filename	Return npz filename to save/load class instance.
get_init_dict	Return dictionary with keyword arguments to __init__.
get_module_name	Name of the module that defines the instance's class.
get_whitened_td	Whiten and convert to time-domain.
heterodyne	Return data heterodyned against with a reference phase.
inject_signal	Add a signal to the data.
inpaint	Inpaint segments of data, useful to mitigate glitches.
reinstantiate	Return a new instance of the class, possibly updating init_kwargs.
specgram	Plot a spectrogram of the whitened data.
suggest_inpaint_times	Identify time intervals to inpaint in each detector.
to_json	Write class instance to json file.
to_npz	Save class as .npz file (by default in DATADIR).

Attributes

df	Frequency resolution (Hz).
nfft	Number of time-domain samples.
subclass_registry
times	Times of the data, starting at 0 (s) (event is at tcoarse).

property df

Frequency resolution (Hz).

classmethod from_npz(eventname=None, *, filename=None)

Load a .npz file previously saved with to_npz().

classmethod from_timeseries(filenames, eventname, detector_names, tgps, t_before=16.0, t_after=16.0, wht_filter_duration=32.0, fmin=15.0, df_taper=1.0, fmax=1024.0, **kwargs)

Parameters:

filenameslist of paths

Paths pointing to gwpy.timeseries.Timeseries objects, containing data for each detector.

eventnamestr

Name of the event, e.g. 'GW150914'.

detector_namessequence of str

E.g. 'HLV' or ('H', 'L', 'V') for Hanford-Livingston-Virgo.

tgpsfloat

GPS time of the event (s).

t_before, t_afterfloat

Number of seconds of valid data (i.e. without edge effects) to keep before/after tgps. The total segment of data will have extra duration of wht_filter_duration / 2 seconds to either side.

wht_filter_durationfloat

Desired impulse response length of the whitening filter (s), will be wht_filter_duration / 2 seconds to either side. Note: the whitening filter will only be approximately FIR. This is also the duration of each chunk in which the individual PSDs are measured for Welch, and the extent of the tapering in time-domain (s).

fminfloat or sequence of floats

Minimum frequency at which the whitening filter will have support (Hz). Multiple values can be passed, one for each detector.

df_taperfloat

Whitening filter is highpassed. See highpass_filter.

fmaxfloat

Desired Nyquist frequency (Hz), half the sampling frequency.

**kwargs

Keyword arguments to gwpy.timeseries.TimeSeries.read.

Returns:

EventData instance.

See also

download_timeseries

classmethod gaussian_noise(eventname, duration, detector_names, asd_funcs, tgps, tcoarse=None, fmin=15.0, df_taper=1.0, fmax=1024.0, seed=None)

Constructor that generates stationary colored Gaussian noise.

Note: the data will be periodic.

Parameters:

eventnamestr

Name of event.

durationfloat

Number of seconds of data.

detector_namessequence of str

E.g. 'HLV' or ('H', 'L', 'V') for Hanford-Livingston-Virgo.

asd_funcssequence of callables or strings

Functions that return the noise amplitude spectral density (1/Hz), of the same length as detector_names. See make_asd_func to construct an interpolator. Alternatively, a string that is a key in ASDS can be passed to use a predefined ASD (e.g. ‘asd_H_O3’).

tgpsfloat

GPS time of event.

tcoarsefloat

Time of event relative to beginning of data. Defaults to duration / 2, the center of the segment.

fminfloat

Minimum frequency at which the whitening filter will have support (Hz). It is important for performance.

df_taperfloat

Whitening filter is highpassed. See highpass_filter.

fmaxfloat

Desired Nyquist frequency (Hz), half the sampling frequency.

seedint, optional

Use some fixed value for reproducibility.

Returns:

Instance of EventData.

See also

make_asd_func

EventData.inject_signal

static get_filename(eventname=None)

Return npz filename to save/load class instance.

get_init_dict(**kwargs)

Return dictionary with keyword arguments to __init__.

Only works if the class stores its init parameters as attributes with the same names. Otherwise, the subclass should override this method.

Parameters:

**kwargs

Allows to manually override some keys. The remaining ones will be read from the instance’s attributes. All keywords must be in the __init__ signature. It’s mostly here to facilitate overriding by subclasses.

get_module_name()

Name of the module that defines the instance’s class.

get_whitened_td(strain_f=None)

Whiten and convert to time-domain.

Take a frequency-domain strain defined on the FFT grid self.frequencies and return a whitened time domain strain defined on self.times.

Parameters:

strain_f(n_det, n_rfftfreq) complex array

A strain signal in the frequency domain. Defaults to the data.

Returns:

(n_det, n_times) real arrayWhitened time-domain signal.

heterodyne(ref_phase)

Return data heterodyned against with a reference phase.

Useful e.g. for visualizing long faint signals and for assessing by eye the quality of a fit.

Parameters:

ref_phase(n_det?, n_freq_slice) float array

Phase (rad) evaluated on self.frequencies[self.fslice].

Returns:

EventData

inject_signal(par_dic, approximant)

Add a signal to the data.

Injection parameters will be stored as a dictionary in the injection attribute. The inner product ⟨h|h⟩ at each detector (ignoring ASD-drift correction) is also stored. The signal is computed only at frequencies where the whitening filter has support.

Parameters:

par_dicdict

Parameter values, keys should match waveform.WaveformGenerator.params. Note: par_dic['t_geocenter'] is relative to self.tgps, and should be << 1 in practice.

approximantstr

Name of approximant.

inpaint(inpaint_times_by_det: dict)

Inpaint segments of data, useful to mitigate glitches.

Parameters:

inpaint_times_by_detdict

Dictionary with times to inpaint by detector. Keys are detector names, values are lists of tuples, each with a pair (t_start, t_end), e.g.: {‘H’: [(t_start_0, t_end_0), (t_start_1, t_end_1)]} Times are expressed in seconds from .tgps. See EventData.suggest_inpaint_times to generate automatically.

Returns:

EventDataInstance containing the inpainted data.

See also

EventData.suggest_inpaint_times

property nfft

Number of time-domain samples.

reinstantiate(**new_init_kwargs)

Return a new instance of the class, possibly updating init_kwargs.

Values not passed will be taken from the current instance.

specgram(xlim=None, nfft=64, noverlap=None, vmax=25.0)

Plot a spectrogram of the whitened data.

The colorbar is in units of the expected power from Gaussian noise.

Parameters:

xlim(float, float)

Optional, time range to plot relative to time of the event.

nfftint

Number of samples to use in each spectrum computation. Sets the frequency resolution.

noverlapint

How many samples to overlap between adjacent spectra. Defaults to nfft / 2.

vmaxfloat

Upper limit for the color scale.

suggest_inpaint_times(nfft=64, noverlap=None, vmax=20.0, exclude=(-0.5, 0.1), power_drop=10.0, plot=True)

Identify time intervals to inpaint in each detector.

Inpaint times are identified based on excess power in a spectrogram of whitened data. The parameters to this function control the spectrogram. Note that different glitches may be better captured by different spectrogram configurations. The first output inpaint_times can be (edited and) passed to inpaint().

Parameters:

nfftint, optional

Number of samples per FFT segment. Defines the STFT frequency resolution. Default is 64.

noverlapint or None, optional

Number of samples to overlap between consecutive FFT windows. Defaults to nfft // 2.

vmaxfloat, optional

Maximum allowed peak power in the whitened spectrogram, in units of variance.

excludetuple of float

Two-element tuple (t_min, t_max) specifying a time interval relative to self.tcoarse that is not to be inpainted (to preserve the actual GW signal).

power_dropfloat

We seek outliers iteratively, to prevent the whitening filter from corrupting a lot of data if there is a very loud glitch. At each iteration only data with power within a factor 1/power_drop of the global maximum are flagged and inpainted.

plotbool

If True (default), display diagnostic spectrograms before and after suggested inpainting, with segments to inpaint marked.

Returns:

inpaint_times_by_detdict

Dictionary mapping detector names to lists of time segments [t_start, t_end] (relative to tgps) that can be passed to inpaint().

event_dataEventData

Data with the suggested inpainting applied.

See also

EventData.inpaint

EventData.specgram

property times

Times of the data, starting at 0 (s) (event is at tcoarse).

to_json(dirname, basename=None, *, dir_permissions=493, file_permissions=420, overwrite=False)

Write class instance to json file.

It can then be loaded with read_json.

to_npz(*, filename=None, overwrite=False, permissions=420)

Save class as .npz file (by default in DATADIR).