pygwb.detector.Interferometer

class pygwb.detector.Interferometer(*args, **kwargs)

Bases: Interferometer

__init__(*args, **kwargs)

Instantiate an Interferometer class

Parameters:

• *args (arguments passed to the (parent) bilby's Interferometer class.) –

• **kwargs (keyword arguments passed to the (parent) bilby's Interferometer class.) –

• name (str) – Interferometer name, e.g. H1 for LIGO Hanford.

• power_spectral_density (bilby.gw.detector.PowerSpectralDensity) – Power spectral density determining the sensitivity of the detector.

• minimum_frequency (float) – Minimum frequency to analyse for detector.

• maximum_frequency (float) – Maximum frequency to analyse for detector.

• length (float) – Length of the interferometer in km.

• latitude (float) – Latitude North in degrees (South is negative).

• longitude (float) – Longitude East in degrees (West is negative).

• elevation (float) – Height above surface in metres.

• xarm_azimuth (float) – Orientation of the x arm in degrees North of East.

• yarm_azimuth (float) – Orientation of the y arm in degrees North of East.

• xarm_tilt (float, optional) – Tilt of the x arm in radians above the horizontal defined by ellipsoid earth model in LIGO-T980044-08.

• yarm_tilt (float, optional) – Tilt of the y arm in radians above the horizontal.

• calibration_model (Recalibration) – Calibration model, this applies the calibration correction to the template, the default model applies no correction.

• timeseries (gwpy.timeseries.TimeSeries) – TimeSeries object with resampling/high-pass filter applied. This is an additional attribute of the class.

• psd_spectrogram (gwpy.spectrogram.Spectrogram) – gwpy Spectrogram of power spectral density. This is an additional attribute of the class.

• gates (gwpy.segments.SegmentList) – List of segments that have been gated, not including any additional padding. This is an additional attribute of the class.

• gate_pad (float) – Duration of padding used when applying gates. This is an additional attribute of the class.

See also

bilby.gw.detector.Interferometer

Test

gwpy.segments.SegmentList

More information here.

__call__(*args, **kwargs)

Call self as a function.

Methods

__init__(*args, **kwargs)	Instantiate an Interferometer class
antenna_response(ra, dec, time, psi, mode)	Calculate the antenna response function for a given sky location
apply_gates_from_file(loaded_object, index, ...)	Load gates from a pygwb output file and apply them to the Interferometer object.
check_signal_duration(parameters[, raise_error])	Check that the signal with the given parameters fits in the data
from_parameters(name, parameters)	A class method to get an Interferometer class from a given argparser object.
from_pickle([filename])	Loads in an Interferometer object from a pickle file
gate_data_apply(**kwargs)	Self-gate the gwpy.timeseries associated with this timeseries.
get_detector_response(...[, frequencies])	Get the detector response for a particular waveform
get_empty_interferometer(name)	A class method to get an Interferometer class object from a given ifo name.
inject_signal(parameters[, ...])	General signal injection method.
inject_signal_from_waveform_generator(...)	Inject a signal using a waveform generator and a set of parameters.
inject_signal_from_waveform_polarizations(...)	Inject a signal into the detector from a dict of waveform polarizations.
inner_product(signal)	Parameters:
matched_filter_snr(signal)	Parameters:
optimal_snr_squared(signal)	Parameters:
plot_data([signal, outdir, label])
plot_time_domain_data([outdir, label, ...])	Plots the strain data in the time domain
save_data(outdir[, label])	Creates save files for interferometer data in plain text format.
set_average_psd([N_average_segments])	Set average_psd attribute from the existing raw PSD.
set_psd_spectrogram(frequency_resolution[, ...])	Set psd_spectrogram attribute from given spectrum-related information.
set_strain_data_from_channel_name(channel, ...)	Set the Interferometer.strain_data by fetching from given channel using strain_data.set_from_channel_name()
set_strain_data_from_csv(filename)	Set the Interferometer.strain_data from a csv file
set_strain_data_from_frame_file(frame_file, ...)	Set the Interferometer.strain_data from a frame file
set_strain_data_from_frequency_domain_strain(...)	Set the Interferometer.strain_data from a numpy array
set_strain_data_from_gwpy_timeseries(time_series)	Set the Interferometer.strain_data from a gwpy TimeSeries
set_strain_data_from_power_spectral_density(...)	Set the Interferometer.strain_data from a power spectal density
set_strain_data_from_zero_noise(...[, ...])	Set the Interferometer.strain_data to zero noise
set_timeseries_from_channel_name(channel, ...)	Set a timeseries attribute from a given channel name.
set_timeseries_from_gwpy_timeseries(...)	Set a timeseries attribute from a given gwpy.timeseries object.
set_timeseries_from_timeseries_array(...)	Set a timeseries attribute from a given numpy array.
time_delay_from_geocenter(ra, dec, time)	Calculate the time delay from the geocenter for the interferometer.
to_pickle([outdir, label])	Save the object to a pickle file
unit_vector_along_arm(arm)
vertex_position_geocentric()	Calculate the position of the IFO vertex in geocentric coordinates in meters.

Attributes

amplitude_spectral_density_array	Returns the amplitude spectral density (ASD) given we know a power spectral density (PSD)
power_spectral_density_array	Returns the power spectral density (PSD)
whitened_frequency_domain_strain	Calculates the whitened data by dividing the frequency domain data by ((amplitude spectral density) * (duration / 4) ** 0.5).

property amplitude_spectral_density_array

Returns the amplitude spectral density (ASD) given we know a power spectral density (PSD)

Returns:

array_like: An array representation of the ASD

antenna_response(ra, dec, time, psi, mode)

Calculate the antenna response function for a given sky location

See Nishizawa et al. (2009) arXiv:0903.0528 for definitions of the polarisation tensors. [u, v, w] represent the Earth-frame [m, n, omega] represent the wave-frame Note: there is a typo in the definition of the wave-frame in Nishizawa et al.

Parameters:

ra: float

right ascension in radians

dec: float

declination in radians

time: float

geocentric GPS time

psi: float

binary polarisation angle counter-clockwise about the direction of propagation

mode: str

polarisation mode (e.g. ‘plus’, ‘cross’) or the name of a specific detector. If mode == self.name, return 1

Returns:

float: The antenna response for the specified mode and time/location

apply_gates_from_file(loaded_object, index, **kwargs)

Load gates from a pygwb output file and apply them to the Interferometer object. The gated times are stored as a property of the object.

Parameters:

• loaded_object – Object that represents the data in the output file, e.g. a loaded npz-object.

• index (int) – Integer representing the correct Interferometer object in the baseline.

• gate_tpad (float) – Half-width time duration (in seconds) in which the Planck window is tapered.

See also

pygwb.preprocessing.self_gate_data

check_signal_duration(parameters, raise_error=True)

Check that the signal with the given parameters fits in the data

Parameters:

parameters: dict

A dictionary of the injection parameters

raise_error: bool

If True, raise an error in the signal does not fit. Otherwise, print a warning message.

classmethod from_parameters(name, parameters)

A class method to get an Interferometer class from a given argparser object.

Parameters:

• name (str) – Interferometer name, e.g. H1 for LIGO Hanford.

• parameters (argparser object) – This contains attributes defined for command line options.

Returns:

interferometer: pygwb.Interferometer

Instance of the pygwb interferometer object.

classmethod from_pickle(filename=None)

Loads in an Interferometer object from a pickle file

Parameters:

filename: str

If given, try to load from this filename

gate_data_apply(**kwargs)

Self-gate the gwpy.timeseries associated with this timeseries. The list of times gated and the padding applied are stored as properties of the Interferometer.

Parameters:

• gate_tzero (float) – Half-width time duration (seconds) in which the timeseries is set to zero.

• gate_tpad (float) – Half-width time duration (seconds) in which the Planck window is tapered.

• gate_threshold (float) – Amplitude threshold, if the data exceeds this value a gating window will be placed.

• cluster_window (float) – Time duration (seconds) over which gating points will be clustered.

• gate_whiten (bool) – If True, data will be whitened before gating points are discovered, use of this option is highly recommended.

See also

pygwb.preprocessing.self_gate_data

gwpy.timeseries.TimeSeries.gate

the function used for the gating of the data itself.

get_detector_response(waveform_polarizations, parameters, frequencies=None)

Get the detector response for a particular waveform

Parameters:

waveform_polarizations: dict

polarizations of the waveform

parameters: dict

parameters describing position and time of arrival of the signal

frequencies: array-like, optional

The frequency values to evaluate the response at. If

not provided, the response is computed using

:code:`self.frequency_array`. If the frequencies are

specified, no frequency masking is performed.

Returns

=======

array_like: A 3x3 array representation of the detector response (signal observed in the interferometer)

classmethod get_empty_interferometer(name)

A class method to get an Interferometer class object from a given ifo name. Empty means no data has been read into this object.

Parameters:

name (str) – Interferometer name, e.g. H1 for LIGO Hanford.

Returns:

interferometer: pygwb.Interferometer

Interferometer instance of pygwb.

inject_signal(parameters, injection_polarizations=None, waveform_generator=None, raise_error=True)

General signal injection method. Provide the injection parameters and either the injection polarizations or the waveform generator to inject a signal into the detector. Defaults to the injection polarizations is both are given.

Parameters:

parameters: dict

Parameters of the injection.

injection_polarizations: dict, optional

Polarizations of waveform to inject, output of waveform_generator.frequency_domain_strain(). If waveform_generator is also given, the injection_polarizations will be calculated directly and this argument can be ignored.

waveform_generator: bilby.gw.waveform_generator.WaveformGenerator, optional

A WaveformGenerator instance using the source model to inject. If injection_polarizations is given, this will be ignored.

raise_error: bool

If true, raise an error if the injected signal has a duration longer than the data duration. If False, a warning will be printed instead.

Returns:

injection_polarizations: dict

The injected polarizations. This is the same as the injection_polarizations parameters if it was passed in. Otherwise it is the return value of waveform_generator.frequency_domain_strain().

Notes

if your signal takes a substantial amount of time to generate, or you experience buggy behaviour. It is preferable to provide the injection_polarizations directly.

inject_signal_from_waveform_generator(parameters, waveform_generator)

Inject a signal using a waveform generator and a set of parameters. Alternative to inject_signal and inject_signal_from_waveform_polarizations

Parameters:

parameters: dict

Parameters of the injection.

waveform_generator: bilby.gw.waveform_generator.WaveformGenerator

A WaveformGenerator instance using the source model to inject.

Returns:

injection_polarizations: dict

The internally generated injection parameters

Notes

if your signal takes a substantial amount of time to generate, or you experience buggy behaviour. It is preferable to use the inject_signal_from_waveform_polarizations() method.

inject_signal_from_waveform_polarizations(parameters, injection_polarizations)

Inject a signal into the detector from a dict of waveform polarizations. Alternative to inject_signal and inject_signal_from_waveform_generator.

Parameters:

parameters: dict

Parameters of the injection.

injection_polarizations: dict

Polarizations of waveform to inject, output of waveform_generator.frequency_domain_strain().

inner_product(signal)

Parameters:

signal: array_like

Array containing the signal

Returns:

float: The optimal signal to noise ratio possible squared

matched_filter_snr(signal)

Parameters:

signal: array_like

Array containing the signal

Returns:

float: The matched filter signal to noise ratio squared

optimal_snr_squared(signal)

Parameters:

signal: array_like

Array containing the signal

Returns:

float: The optimal signal to noise ratio possible squared

plot_time_domain_data(outdir='.', label=None, bandpass_frequencies=(50, 250), notches=None, start_end=None, t0=None)

Plots the strain data in the time domain

Parameters:

outdir, label: str

Used in setting the saved filename.

bandpass: tuple, optional

A tuple of the (low, high) frequencies to use when bandpassing the data, if None no bandpass is applied.

notches: list, optional

A list of frequencies specifying any lines to notch

start_end: tuple

A tuple of the (start, end) range of GPS times to plot

t0: float

If given, the reference time to subtract from the time series before plotting.

property power_spectral_density_array

Returns the power spectral density (PSD)

This accounts for whether the data in the interferometer has been windowed.

Returns:

array_like: An array representation of the PSD

save_data(outdir, label=None)

Creates save files for interferometer data in plain text format.

Saves two files: the frequency domain strain data with three columns [f, real part of h(f), imaginary part of h(f)], and the amplitude spectral density with two columns [f, ASD(f)].

Note that in v1.3.0 and below, the ASD was saved in a file called *_psd.dat.

Parameters:

outdir: str

The output directory in which the data is supposed to be saved

label: str

The name of the output files

set_average_psd(N_average_segments=2)

Set average_psd attribute from the existing raw PSD.

Parameters:

N_average_segments (int, optional) – Number of segments used for PSD averaging (from both sides of the segment of interest). N_avg_segs should be even and >= 2.

See also

pygwb.spectral.before_after_average

set_psd_spectrogram(frequency_resolution, coarse_grain=False, overlap_factor=0.5, window_fftgram_dict={'window_fftgram': 'hann'}, overlap_factor_welch=0.5)

Set psd_spectrogram attribute from given spectrum-related information.

Parameters:

• frequency_resolution (float) – Frequency resolution of the final PSDs. This sets the time duration over which FFTs are calculated in the pwelch method.

• coarse_grain (bool) – Coarse-graining flag. If True, PSD will be estimated via coarse-graining, as opposed to Welch-averaging. Default is False.

• overlap_factor (float, optional) – Amount of overlap between adjacent segments (ranges between 0 and 1). This factor should be same as the one used for cross_spectral_density (default 0, no overlap).

• window_fftgram_dict (dictionary, optional) – Dictionary containing name and parameters describing which window to use when producing fftgrams for psd estimation. Default is “hann”.

• overlap_factor_welch (float, optional) – Overlap factor to use when using Welch’s method to estimate the PSD (NOT coarsegraining). For “hann” window use 0.5 overlap_factor and for “boxcar” window use 0 overlap_factor. Default is 0.5 (50% overlap), which is optimal when using Welch’s method with a “hann” window.

See also

pygwb.spectral.power_spectral_density

set_strain_data_from_channel_name(channel, sampling_frequency, duration, start_time=0)

Set the Interferometer.strain_data by fetching from given channel using strain_data.set_from_channel_name()

Parameters:

channel: str

Channel to look for using gwpy in the format IFO:Channel

sampling_frequency: float

The sampling frequency (in Hz)

duration: float

The data duration (in s)

start_time: float

The GPS start-time of the data

set_strain_data_from_csv(filename)

Set the Interferometer.strain_data from a csv file

Parameters:

filename: str

The path to the file to read in

set_strain_data_from_frame_file(frame_file, sampling_frequency, duration, start_time=0, channel=None, buffer_time=1)

Set the Interferometer.strain_data from a frame file

Parameters:

frame_file: str

File from which to load data.

channel: str

Channel to read from frame.

sampling_frequency: float

The sampling frequency (in Hz)

duration: float

The data duration (in s)

start_time: float

The GPS start-time of the data

buffer_time: float

Read in data with start_time-buffer_time and start_time+duration+buffer_time

set_strain_data_from_frequency_domain_strain(frequency_domain_strain, sampling_frequency=None, duration=None, start_time=0, frequency_array=None)

Set the Interferometer.strain_data from a numpy array

Parameters:

frequency_domain_strain: array_like

The data to set.

sampling_frequency: float

The sampling frequency (in Hz).

duration: float

The data duration (in s).

start_time: float

The GPS start-time of the data.

frequency_array: array_like

The array of frequencies, if sampling_frequency and duration not given.

set_strain_data_from_gwpy_timeseries(time_series)

Set the Interferometer.strain_data from a gwpy TimeSeries

Parameters:

time_series: gwpy.timeseries.timeseries.TimeSeries

The data to set.

set_strain_data_from_power_spectral_density(sampling_frequency, duration, start_time=0)

Set the Interferometer.strain_data from a power spectal density

This uses the interferometer.power_spectral_density object to set the strain_data to a noise realization. See bilby.gw.detector.InterferometerStrainData for further information.

Parameters:

sampling_frequency: float

The sampling frequency (in Hz)

duration: float

The data duration (in s)

start_time: float

The GPS start-time of the data

set_strain_data_from_zero_noise(sampling_frequency, duration, start_time=0)

Set the Interferometer.strain_data to zero noise

Parameters:

sampling_frequency: float

The sampling frequency (in Hz)

duration: float

The data duration (in s)

start_time: float

The GPS start-time of the data

set_timeseries_from_channel_name(channel, **kwargs)

Set a timeseries attribute from a given channel name.

Parameters:

• channel (str) – Name of the channel (e.g.: “L1:GWOSC-4KHZ_R1_STRAIN”) from which to load the data.

• **kwargs (keyword arguments passed to preprocess module.) –

See also

pygwb.preprocessing.preprocessing_data_channel_name

set_timeseries_from_gwpy_timeseries(gwpy_timeseries, **kwargs)

Set a timeseries attribute from a given gwpy.timeseries object. More information on the gwpy.timeseries object can be found here.

Parameters:

• gwpy_timeseries (gwpy.timeseries.TimeSeries) – Timeseries strain data as gwpy.timeseries object.

• **kwargs (keyword arguments passed to preprocess module.) –

See also

pygwb.preprocessing.preprocessing_data_gwpy_timeseries

set_timeseries_from_timeseries_array(timeseries_array, sample_rate, **kwargs)

Set a timeseries attribute from a given numpy array.

Parameters:

• timeseries_array (np.ndarray) – Timeseries strain data as numpy array object

• sample_rate (int) – Sample rate of the timeseries in the array (in Hz)

• **kwargs (keyword arguments passed to preprocess module.) –

See also

pygwb.preprocessing.preprocessing_data_timeseries_array

time_delay_from_geocenter(ra, dec, time)

Calculate the time delay from the geocenter for the interferometer.

Use the time delay function from utils.

Parameters:

ra: float

right ascension of source in radians

dec: float

declination of source in radians

time: float

GPS time

Returns:

float: The time delay from geocenter in seconds

to_pickle(outdir='outdir', label=None)

Save the object to a pickle file

New in version 1.1.0.

Attributes:

outdir: str, optional

Output directory name of the file, defaults to ‘outdir’.

label: str, optional

Output file name, is self.name if not given otherwise.

vertex_position_geocentric()

Calculate the position of the IFO vertex in geocentric coordinates in meters.

Based on arXiv:gr-qc/0008066 Eqs. B11-B13 except for the typo in the definition of the local radius. See Section 2.1 of LIGO-T980044-10 for the correct expression

Returns:

array_like: A 3D array representation of the vertex

property whitened_frequency_domain_strain

Calculates the whitened data by dividing the frequency domain data by ((amplitude spectral density) * (duration / 4) ** 0.5). The resulting data will have unit variance.

Returns:

array_like: The whitened data