bilby.gw.detector.interferometer.Interferometer

class bilby.gw.detector.interferometer.Interferometer(name, power_spectral_density, minimum_frequency, maximum_frequency, length, latitude, longitude, elevation, xarm_azimuth, yarm_azimuth, xarm_tilt=0.0, yarm_tilt=0.0, calibration_model=Recalibrate(prefix='recalib_'))[source]

Bases: object

Class for the Interferometer

__init__(name, power_spectral_density, minimum_frequency, maximum_frequency, length, latitude, longitude, elevation, xarm_azimuth, yarm_azimuth, xarm_tilt=0.0, yarm_tilt=0.0, calibration_model=Recalibrate(prefix='recalib_'))[source]

Instantiate an Interferometer object.

Parameters:
name: str

Interferometer name, e.g., H1.

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.

__call__(*args, **kwargs)

Call self as a function.

Methods

__init__(name, power_spectral_density, ...)

Instantiate an Interferometer object.

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

Calculate the antenna response function for a given sky location

check_signal_duration(parameters[, raise_error])

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

from_pickle([filename])

Loads in an Interferometer object from a pickle file

get_detector_response(...[, frequencies])

Get the detector response for a particular waveform

get_whitened_time_series_from_whitened_frequency_series(...)

Gets the whitened time series from a whitened frequency series.

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_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

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.

whiten_frequency_series(frequency_series)

Whitens a frequency series with the noise properties of the detector

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

Whitens the frequency domain data by dividing through by ASD, with appropriate normalization.

whitened_time_domain_strain

Calculates the whitened time domain strain by iffting the whitened frequency domain strain, with the appropriate normalization.

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)[source]

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
check_signal_duration(parameters, raise_error=True)[source]

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_pickle(filename=None)[source]

Loads in an Interferometer object from a pickle file

Parameters:
filename: str

If given, try to load from this filename

get_detector_response(waveform_polarizations, parameters, frequencies=None)[source]

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)
get_whitened_time_series_from_whitened_frequency_series(whitened_frequency_series: array) array[source]

Gets the whitened time series from a whitened frequency series.

This ifft’s and also applies a windowing factor, since when f_min and f_max are set bilby applies a mask to the series.

Per 6.2a-b in https://arxiv.org/pdf/gr-qc/0509116 since our window is just a band pass, this coefficient is \(w/W\) where

\[W = \frac{1}{N} \sum_{k=0}^N w^2[j]\]

Since our window \(w\) is simply 1 or 0, depending on the mask, we get

\[W = \frac{1}{N} \sum_{k=0}^N \Theta(f_{max} - f_k)\Theta(f_k - f_{min})}\]

and accordingly the termwise window factor is

\[w = \sqrt{N W} = \sqrt{\sum_{k=0}^N \Theta(f_{max} - f_k)\Theta(f_k - f_{min})}}\]
inject_signal(parameters, injection_polarizations=None, waveform_generator=None, raise_error=True)[source]

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)[source]

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)[source]

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)[source]
Parameters:
signal: array_like

Array containing the signal

Returns:
float: The optimal signal to noise ratio possible squared
matched_filter_snr(signal)[source]
Parameters:
signal: array_like

Array containing the signal

Returns:
complex: The matched filter signal to noise ratio
optimal_snr_squared(signal)[source]
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)[source]

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)[source]

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_strain_data_from_channel_name(channel, sampling_frequency, duration, start_time=0)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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

time_delay_from_geocenter(ra, dec, time)[source]

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)[source]

Save the object to a pickle file

Added 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()[source]

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
whiten_frequency_series(frequency_series: array) array[source]

Whitens a frequency series with the noise properties of the detector

\[\tilde{a}_w(f) = \tilde{a}(f) \sqrt{\frac{4}{T S_n(f)}}\]

Such that

\[Var(n) = \frac{1}{N} \sum_k=0^N n_W(f_k)n_W^*(f_k) = 2\]

Where the factor of two is due to the independent real and imaginary components.

Parameters:
frequency_seriesnp.array

The frequency series, whitened by the ASD

property whitened_frequency_domain_strain

Whitens the frequency domain data by dividing through by ASD, with appropriate normalization.

See whiten_frequency_series() for details.

Returns:
array_like: The whitened data
property whitened_time_domain_strain: array

Calculates the whitened time domain strain by iffting the whitened frequency domain strain, with the appropriate normalization.

See get_whitened_time_series_from_whitened_frequency_series() for details

Returns:
array_like

The whitened data in the time domain