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

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

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)

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)

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)

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)

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

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)

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:

complex: The matched filter signal to noise ratio

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

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

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()

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

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