# pycbc.strain package¶

## pycbc.strain.calibration module¶

Functions for adding calibration factors to waveform templates.

class pycbc.strain.calibration.CubicSpline(minimum_frequency, maximum_frequency, n_points, ifo_name)[source]
apply_calibration(strain)[source]

Apply calibration model

This applies cubic spline calibration to the strain.

Parameters: strain (FrequencySeries) – The strain to be recalibrated. strain_adjusted – The recalibrated strain. FrequencySeries
name = 'cubic_spline'
class pycbc.strain.calibration.Recalibrate(ifo_name)[source]

Bases: object

apply_calibration(strain)[source]

Apply calibration model

This method should be overwritten by subclasses

Parameters: strain (FrequencySeries) – The strain to be recalibrated. strain_adjusted – The recalibrated strain. FrequencySeries
classmethod from_config(cp, ifo, section)[source]

Read a config file to get calibration options and transfer functions which will be used to intialize the model.

Parameters: cp (WorkflowConfigParser) – An open config file. ifo (string) – The detector (H1, L1) for which the calibration model will be loaded. section (string) – The section name in the config file from which to retrieve the calibration options. An instance of the class. instance
map_to_adjust(strain, prefix='recalib_', **params)[source]

Map an input dictionary of sampling parameters to the adjust_strain function by filtering the dictionary for the calibration parameters, then calling adjust_strain.

Parameters: strain (FrequencySeries) – The strain to be recalibrated. prefix (str) – Prefix for calibration parameter names params (dict) – Dictionary of sampling parameters which includes calibration parameters. strain_adjusted – The recalibrated strain. FrequencySeries
name = None

## pycbc.strain.gate module¶

Functions for applying gates to data.

pycbc.strain.gate.add_gate_option_group(parser)[source]

Adds the options needed to apply gates to data.

Parameters: parser (object) – ArgumentParser instance.
pycbc.strain.gate.apply_gates_to_fd(stilde_dict, gates)[source]

Applies the given dictionary of gates to the given dictionary of strain in the frequency domain.

Gates are applied by IFFT-ing the strain data to the time domain, applying the gate, then FFT-ing back to the frequency domain.

Parameters: stilde_dict (dict) – Dictionary of frequency-domain strain, keyed by the ifos. gates (dict) – Dictionary of gates. Keys should be the ifo to apply the data to, values are a tuple giving the central time of the gate, the half duration, and the taper duration. Dictionary of frequency-domain strain with the gates applied. dict
pycbc.strain.gate.apply_gates_to_td(strain_dict, gates)[source]

Applies the given dictionary of gates to the given dictionary of strain.

Parameters: strain_dict (dict) – Dictionary of time-domain strain, keyed by the ifos. gates (dict) – Dictionary of gates. Keys should be the ifo to apply the data to, values are a tuple giving the central time of the gate, the half duration, and the taper duration. Dictionary of time-domain strain with the gates applied. dict
pycbc.strain.gate.gate_and_paint(data, lindex, rindex, invpsd, copy=True)[source]

Gates and in-paints data.

Parameters: data (TimeSeries) – The data to gate. lindex (int) – The start index of the gate. rindex (int) – The end index of the gate. invpsd (FrequencySeries) – The inverse of the PSD. copy (bool, optional) – Copy the data before applying the gate. Otherwise, the gate will be applied in-place. Default is True. The gated and in-painted time series. TimeSeries
pycbc.strain.gate.gates_from_cli(opts)[source]

Parses the –gate option into something understandable by strain.gate_data.

pycbc.strain.gate.psd_gates_from_cli(opts)[source]

Parses the –psd-gate option into something understandable by strain.gate_data.

## pycbc.strain.lines module¶

Functions for removing frequency lines from real data.

pycbc.strain.lines.avg_inner_product(data1, data2, bin_size)[source]

Calculate the time-domain inner product averaged over bins.

Parameters: data1 (pycbc.types.TimeSeries) – First data set. data2 (pycbc.types.TimeSeries) – Second data set, with same duration and sample rate as data1. bin_size (float) – Duration of the bins the data will be divided into to calculate the inner product. inner_prod (list) – The (complex) inner product of data1 and data2 obtained in each bin. amp (float) – The absolute value of the median of the inner product. phi (float) – The angle of the median of the inner product.
pycbc.strain.lines.calibration_lines(freqs, data, tref=None)[source]

Extract the calibration lines from strain data.

Parameters: freqs (list) – List containing the frequencies of the calibration lines. data (pycbc.types.TimeSeries) – Strain data to extract the calibration lines from. tref ({None, float}, optional) – Reference time for the line. If None, will use data.start_time. data – The strain data with the calibration lines removed. pycbc.types.TimeSeries
pycbc.strain.lines.clean_data(freqs, data, chunk, avg_bin)[source]

Extract time-varying (wandering) lines from strain data.

Parameters: freqs (list) – List containing the frequencies of the wandering lines. data (pycbc.types.TimeSeries) – Strain data to extract the wandering lines from. chunk (float) – Duration of the chunks the data will be divided into to account for the time variation of the wandering lines. Should be smaller than data.duration, and allow for at least a few chunks. avg_bin (float) – Duration of the bins each chunk will be divided into for averaging the inner product when measuring the parameters of the line. Should be smaller than chunk. data – The strain data with the wandering lines removed. pycbc.types.TimeSeries
pycbc.strain.lines.complex_median(complex_list)[source]

Get the median value of a list of complex numbers.

Parameters: complex_list (list) – List of complex numbers to calculate the median. a + 1.j*b – The median of the real and imaginary parts. complex number
pycbc.strain.lines.line_model(freq, data, tref, amp=1, phi=0)[source]

Simple time-domain model for a frequency line.

Parameters: freq (float) – Frequency of the line. data (pycbc.types.TimeSeries) – Reference data, to get delta_t, start_time, duration and sample_times. tref (float) – Reference time for the line model. amp ({1., float}, optional) – Amplitude of the frequency line. phi ({0. float}, optional) – Phase of the frequency line (radians). freq_line – A timeseries of the line model with frequency ‘freq’. The returned data are complex to allow measuring the amplitude and phase of the corresponding frequency line in the strain data. For extraction, use only the real part of the data. pycbc.types.TimeSeries
pycbc.strain.lines.matching_line(freq, data, tref, bin_size=1)[source]

Find the parameter of the line with frequency ‘freq’ in the data.

Parameters: freq (float) – Frequency of the line to find in the data. data (pycbc.types.TimeSeries) – Data from which the line wants to be measured. tref (float) – Reference time for the frequency line. bin_size ({1, float}, optional) – Duration of the bins the data will be divided into for averaging. line_model – A timeseries containing the frequency line with the amplitude and phase measured from the data. pycbc.types.TimeSeries

## pycbc.strain.recalibrate module¶

Classes and functions for adjusting strain data.

class pycbc.strain.recalibrate.CubicSpline(minimum_frequency, maximum_frequency, n_points, ifo_name)[source]

Cubic spline recalibration

This assumes the spline points follow np.logspace(np.log(minimum_frequency), np.log(maximum_frequency), n_points)

Parameters: minimum_frequency (float) – frequency of spline points (maximum) – maximum_frequency (float) – frequency of spline points – n_points (int) – of spline points (number) –
apply_calibration(strain)[source]

Apply calibration model

This applies cubic spline calibration to the strain.

Parameters: strain (FrequencySeries) – The strain to be recalibrated. strain_adjusted – The recalibrated strain. FrequencySeries
name = 'cubic_spline'
class pycbc.strain.recalibrate.PhysicalModel(freq=None, fc0=None, c0=None, d0=None, a_tst0=None, a_pu0=None, fs0=None, qinv0=None)[source]

Bases: object

Class for adjusting time-varying calibration parameters of given strain data.

name

The name of this calibration model.

Type: ‘physical_model’
Parameters: strain (FrequencySeries) – The strain to be adjusted. freq (array) – The frequencies corresponding to the values of c0, d0, a0 in Hertz. fc0 (float) – Coupled-cavity (CC) pole at time t0, when c0=c(t0) and a0=a(t0) are measured. c0 (array) – Initial sensing function at t0 for the frequencies. d0 (array) – Digital filter for the frequencies. a_tst0 (array) – Initial actuation function for the test mass at t0 for the frequencies. a_pu0 (array) – Initial actuation function for the penultimate mass at t0 for the frequencies. fs0 (float) – Initial spring frequency at t0 for the signal recycling cavity. qinv0 (float) – Initial inverse quality factor at t0 for the signal recycling cavity.
adjust_strain(strain, delta_fs=None, delta_qinv=None, delta_fc=None, kappa_c=1.0, kappa_tst_re=1.0, kappa_tst_im=0.0, kappa_pu_re=1.0, kappa_pu_im=0.0)[source]

Adjust the FrequencySeries strain by changing the time-dependent calibration parameters kappa_c(t), kappa_a(t), f_c(t), fs, and qinv.

Parameters: strain (FrequencySeries) – The strain data to be adjusted. delta_fc (float) – Change in coupled-cavity (CC) pole at time t. kappa_c (float) – Scalar correction factor for sensing function c0 at time t. kappa_tst_re (float) – Real part of scalar correction factor for actuation function A_{tst0} at time t. kappa_tst_im (float) – Imaginary part of scalar correction factor for actuation function A_tst0 at time t. kappa_pu_re (float) – Real part of scalar correction factor for actuation function A_{pu0} at time t. kappa_pu_im (float) – Imaginary part of scalar correction factor for actuation function A_{pu0} at time t. fs (float) – Spring frequency for signal recycling cavity. qinv (float) – Inverse quality factor for signal recycling cavity. strain_adjusted – The adjusted strain. FrequencySeries
classmethod from_config(cp, ifo, section)[source]

Read a config file to get calibration options and transfer functions which will be used to intialize the model.

Parameters: cp (WorkflowConfigParser) – An open config file. ifo (string) – The detector (H1, L1) for which the calibration model will be loaded. section (string) – The section name in the config file from which to retrieve the calibration options. An instance of the Recalibrate class. instance
map_to_adjust(strain, **params)[source]

Map an input dictionary of sampling parameters to the adjust_strain function by filtering the dictionary for the calibration parameters, then calling adjust_strain.

Parameters: strain (FrequencySeries) – The strain to be recalibrated. params (dict) – Dictionary of sampling parameters which includes calibration parameters. strain_adjusted – The recalibrated strain. FrequencySeries
name = 'physical_model'
classmethod tf_from_file(path, delimiter=' ')[source]

Convert the contents of a file with the columns [freq, real(h), imag(h)] to a numpy.array with columns [freq, real(h)+j*imag(h)].

Parameters: path (string) – delimiter ({" ", string}) – numpy.array
update_c(fs=None, qinv=None, fc=None, kappa_c=1.0)[source]

Calculate the sensing function c(f,t) given the new parameters kappa_c(t), kappa_a(t), f_c(t), fs, and qinv.

Parameters: fc (float) – Coupled-cavity (CC) pole at time t. kappa_c (float) – Scalar correction factor for sensing function at time t. fs (float) – Spring frequency for signal recycling cavity. qinv (float) – Inverse quality factor for signal recycling cavity. c – The new sensing function c(f,t). numpy.array
update_g(fs=None, qinv=None, fc=None, kappa_tst_re=1.0, kappa_tst_im=0.0, kappa_pu_re=1.0, kappa_pu_im=0.0, kappa_c=1.0)[source]

Calculate the open loop gain g(f,t) given the new parameters kappa_c(t), kappa_a(t), f_c(t), fs, and qinv.

Parameters: fc (float) – Coupled-cavity (CC) pole at time t. kappa_c (float) – Scalar correction factor for sensing function c at time t. kappa_tst_re (float) – Real part of scalar correction factor for actuation function a_tst0 at time t. kappa_pu_re (float) – Real part of scalar correction factor for actuation function a_pu0 at time t. kappa_tst_im (float) – Imaginary part of scalar correction factor for actuation function a_tst0 at time t. kappa_pu_im (float) – Imaginary part of scalar correction factor for actuation function a_pu0 at time t. fs (float) – Spring frequency for signal recycling cavity. qinv (float) – Inverse quality factor for signal recycling cavity. g – The new open loop gain g(f,t). numpy.array
update_r(fs=None, qinv=None, fc=None, kappa_c=1.0, kappa_tst_re=1.0, kappa_tst_im=0.0, kappa_pu_re=1.0, kappa_pu_im=0.0)[source]

Calculate the response function R(f,t) given the new parameters kappa_c(t), kappa_a(t), f_c(t), fs, and qinv.

Parameters: fc (float) – Coupled-cavity (CC) pole at time t. kappa_c (float) – Scalar correction factor for sensing function c at time t. kappa_tst_re (float) – Real part of scalar correction factor for actuation function a_tst0 at time t. kappa_pu_re (float) – Real part of scalar correction factor for actuation function a_pu0 at time t. kappa_tst_im (float) – Imaginary part of scalar correction factor for actuation function a_tst0 at time t. kappa_pu_im (float) – Imaginary part of scalar correction factor for actuation function a_pu0 at time t. fs (float) – Spring frequency for signal recycling cavity. qinv (float) – Inverse quality factor for signal recycling cavity. r – The new response function r(f,t). numpy.array
class pycbc.strain.recalibrate.Recalibrate(ifo_name)[source]

Bases: object

Base class for modifying calibration

apply_calibration(strain)[source]

Apply calibration model

This method should be overwritten by subclasses

Parameters: strain (FrequencySeries) – The strain to be recalibrated. strain_adjusted – The recalibrated strain. FrequencySeries
classmethod from_config(cp, ifo, section)[source]

Read a config file to get calibration options and transfer functions which will be used to intialize the model.

Parameters: cp (WorkflowConfigParser) – An open config file. ifo (string) – The detector (H1, L1) for which the calibration model will be loaded. section (string) – The section name in the config file from which to retrieve the calibration options. An instance of the class. instance
map_to_adjust(strain, prefix='recalib_', **params)[source]

Map an input dictionary of sampling parameters to the adjust_strain function by filtering the dictionary for the calibration parameters, then calling adjust_strain.

Parameters: strain (FrequencySeries) – The strain to be recalibrated. prefix (str) – Prefix for calibration parameter names params (dict) – Dictionary of sampling parameters which includes calibration parameters. strain_adjusted – The recalibrated strain. FrequencySeries
name = None

## pycbc.strain.strain module¶

This modules contains functions reading, generating, and segmenting strain data

class pycbc.strain.strain.StrainBuffer(frame_src, channel_name, start_time, max_buffer=512, sample_rate=4096, low_frequency_cutoff=20, highpass_frequency=15.0, highpass_reduction=200.0, highpass_bandwidth=5.0, psd_samples=30, psd_segment_length=4, psd_inverse_length=3.5, trim_padding=0.25, autogating_threshold=None, autogating_cluster=None, autogating_pad=None, autogating_width=None, autogating_taper=None, state_channel=None, data_quality_channel=None, dyn_range_fac=5.902958103587057e+20, psd_abort_difference=None, psd_recalculate_difference=None, force_update_cache=True, increment_update_cache=None, analyze_flags=None, data_quality_flags=None, dq_padding=0)[source]

Bases: pycbc.frame.frame.DataBuffer

add_hard_count()[source]

Reset the countdown timer, so that we don’t analyze data long enough to generate a new PSD.

advance(blocksize, timeout=10)[source]

Add blocksize seconds more to the buffer, push blocksize seconds from the beginning.

Parameters: blocksize (int) – The number of seconds to attempt to read from the channel status – Returns True if this block is analyzable. boolean
end_time

Return the end time of the current valid segment of data

classmethod from_cli(ifo, args, maxlen)[source]

Initialize a StrainBuffer object (data reader) for a particular detector.

invalidate_psd()[source]

Make the current PSD invalid. A new one will be generated when it is next required

near_hwinj()[source]

Check that the current set of triggers could be influenced by a hardware injection.

null_advance_strain(blocksize)[source]

Parameters: blocksize (int) – The number of seconds to attempt to read from the channel
overwhitened_data(delta_f)[source]

Return overwhitened data

Parameters: delta_f (float) – The sample step to generate overwhitened frequency domain data for htilde – Overwhited strain data FrequencySeries
recalculate_psd()[source]

Recalculate the psd

start_time

Return the start time of the current valid segment of data

class pycbc.strain.strain.StrainSegments(strain, segment_length=None, segment_start_pad=0, segment_end_pad=0, trigger_start=None, trigger_end=None, filter_inj_only=False, injection_window=None, allow_zero_padding=False)[source]

Bases: object

Class for managing manipulation of strain data for the purpose of matched filtering. This includes methods for segmenting and conditioning.

fourier_segments()[source]

Return a list of the FFT’d segments. Return the list of FrequencySeries. Additional properties are added that describe the strain segment. The property ‘analyze’ is a slice corresponding to the portion of the time domain equivalent of the segment to analyze for triggers. The value ‘cumulative_index’ indexes from the beginning of the original strain series.

classmethod from_cli(opt, strain)[source]

Calculate the segmentation of the strain data for analysis from the command line options.

classmethod from_cli_multi_ifos(opt, strain_dict, ifos)[source]

Calculate the segmentation of the strain data for analysis from the command line options.

classmethod from_cli_single_ifo(opt, strain, ifo)[source]

Calculate the segmentation of the strain data for analysis from the command line options.

classmethod insert_segment_option_group(parser)[source]
classmethod insert_segment_option_group_multi_ifo(parser)[source]
required_opts_list = ['--segment-length', '--segment-start-pad', '--segment-end-pad']
classmethod verify_segment_options(opt, parser)[source]
classmethod verify_segment_options_multi_ifo(opt, parser, ifos)[source]
pycbc.strain.strain.detect_loud_glitches(strain, psd_duration=4.0, psd_stride=2.0, psd_avg_method='median', low_freq_cutoff=30.0, threshold=50.0, cluster_window=5.0, corrupt_time=4.0, high_freq_cutoff=None, output_intermediates=False)[source]

Automatic identification of loud transients for gating purposes.

This function first estimates the PSD of the input time series using the FindChirp Welch method. Then it whitens the time series using that estimate. Finally, it computes the magnitude of the whitened series, thresholds it and applies the FindChirp clustering over time to the surviving samples.

Parameters: strain (TimeSeries) – Input strain time series to detect glitches over. psd_duration ({float, 4}) – Duration of the segments for PSD estimation in seconds. psd_stride ({float, 2}) – Separation between PSD estimation segments in seconds. psd_avg_method ({string, 'median'}) – Method for averaging PSD estimation segments. low_freq_cutoff ({float, 30}) – Minimum frequency to include in the whitened strain. threshold ({float, 50}) – Minimum magnitude of whitened strain for considering a transient to be present. cluster_window ({float, 5}) – Length of time window to cluster surviving samples over, in seconds. corrupt_time ({float, 4}) – Amount of time to be discarded at the beginning and end of the input time series. high_frequency_cutoff ({float, None}) – Maximum frequency to include in the whitened strain. If given, the input series is downsampled accordingly. If omitted, the Nyquist frequency is used. output_intermediates ({bool, False}) – Save intermediate time series for debugging.
pycbc.strain.strain.from_cli(opt, dyn_range_fac=1, precision='single', inj_filter_rejector=None)[source]

Parses the CLI options related to strain data reading and conditioning.

Parameters: opt (object) – Result of parsing the CLI with OptionParser, or any object with the required attributes (gps-start-time, gps-end-time, strain-high-pass, pad-data, sample-rate, (frame-cache or frame-files), channel-name, fake-strain, fake-strain-seed, fake-strain-from-file, gating_file). dyn_range_fac ({float, 1}, optional) – A large constant to reduce the dynamic range of the strain. precision (string) – Precision of the returned strain (‘single’ or ‘double’). inj_filter_rejector (InjFilterRejector instance; optional, default=None) – If given send the InjFilterRejector instance to the inject module so that it can store a reduced representation of injections if necessary. strain – The time series containing the conditioned strain data. TimeSeries
pycbc.strain.strain.from_cli_multi_ifos(opt, ifos, inj_filter_rejector_dict=None, **kwargs)[source]

Get the strain for all ifos when using the multi-detector CLI

pycbc.strain.strain.from_cli_single_ifo(opt, ifo, inj_filter_rejector=None, **kwargs)[source]

Get the strain for a single ifo when using the multi-detector CLI

pycbc.strain.strain.gate_data(data, gate_params)[source]

Apply a set of gating windows to a time series.

Each gating window is defined by a central time, a given duration (centered on the given time) to zero out, and a given duration of smooth tapering on each side of the window. The window function used for tapering is a Tukey window.

Parameters: data (TimeSeries) – The time series to be gated. gate_params (list) – List of parameters for the gating windows. Each element should be a list or tuple with 3 elements: the central time of the gating window, the half-duration of the portion to zero out, and the duration of the Tukey tapering on each side. All times in seconds. The total duration of the data affected by one gating window is thus twice the second parameter plus twice the third parameter. data – The gated time series. TimeSeries
pycbc.strain.strain.insert_strain_option_group(parser, gps_times=True)[source]

Add strain-related options to the optparser object.

Adds the options used to call the pycbc.strain.from_cli function to an optparser as an OptionGroup. This should be used if you want to use these options in your code.

Parameters: parser (object) – OptionParser instance. gps_times (bool, optional) – Include --gps-start-time and --gps-end-time options. Default is True.
pycbc.strain.strain.insert_strain_option_group_multi_ifo(parser, gps_times=True)[source]

Adds the options used to call the pycbc.strain.from_cli function to an optparser as an OptionGroup. This should be used if you want to use these options in your code.

Parameters: parser (object) – OptionParser instance. gps_times (bool, optional) – Include --gps-start-time and --gps-end-time options. Default is True.
pycbc.strain.strain.next_power_of_2(n)[source]

Return the smallest integer power of 2 larger than the argument.

Parameters: n (int) – A positive integer. m – Smallest integer power of 2 larger than n. int
pycbc.strain.strain.verify_strain_options(opts, parser)[source]

Sanity check provided strain arguments.

Parses the strain data CLI options and verifies that they are consistent and reasonable.

Parameters: opt (object) – Result of parsing the CLI with OptionParser, or any object with the required attributes (gps-start-time, gps-end-time, strain-high-pass, pad-data, sample-rate, frame-cache, channel-name, fake-strain, fake-strain-seed). parser (object) – OptionParser instance.
pycbc.strain.strain.verify_strain_options_multi_ifo(opts, parser, ifos)[source]

Sanity check provided strain arguments.

Parses the strain data CLI options and verifies that they are consistent and reasonable.

Parameters: opt (object) – Result of parsing the CLI with OptionParser, or any object with the required attributes (gps-start-time, gps-end-time, strain-high-pass, pad-data, sample-rate, frame-cache, channel-name, fake-strain, fake-strain-seed). parser (object) – OptionParser instance. ifos (list of strings) – List of ifos for which to verify options for

## Module contents¶

pycbc.strain.read_model_from_config(cp, ifo, section='calibration')[source]

Returns an instance of the calibration model specified in the given configuration file.

Parameters: cp (WorflowConfigParser) – An open config file to read. ifo (string) – The detector (H1, L1) whose model will be loaded. section ({"calibration", string}) – Section name from which to retrieve the model. An instance of the calibration model class. instance