waveformtools.waveformtools

This module contains a set of tools to handle data from numerical relativity simulations and gravitational waves. It consists of a bunch of functions that were frequently used for handling NR data.

Notes: 1. Some functions here display plots. If you intend to use these on the cluster and if xterm is not adequately setup, you may have to either comment the plot codes or use the`Agg` mode for plotting and save the figures instead of showing by changing the appropriate lines in the code. 2. These is a module consisting of functions, not completely optimized for speed. This will happen in future. 3. These functions are not defined in classes as they mostly use and operate on the objects of pycbc’s builtin classes. 4. Any suggestions, comments, critisism invited to vaishak@gmail.com!

Functions

addzeros(data, zeros)	Append zeros to an array without tapering.
apxstartend(data[, tol])	Identify the Approximate start and endpoints of the data.
bintp(xdata, func_x, width, order[, to_plot])	Function to bin the data and interpolate it at specified width and order.
center(wvp[, wvc, delta_t])	Center a waveform (wvp, wvc) at the peak of the complex modulous sqrt(wvp**2 + wvc**2).
cleandata(data[, toldt, bridge, k])	Check the data (time,datar,datai) for repetetive rows and remove them.
coalignwfs(tsdata1, tsdata2[, delta_t])	Coalign two timeseries.
coalignwfs2(tsdata1, tsdata2[, delta_t])	Coalign two waveforms function 2.
compute_chi_eff_from_masses_and_spins(spin1, ...)	Compute the effective z-spin parameter \(\chi_{eff}\)
compute_chi_prec_from_masses_and_spins(...)	Compute the effective spin-precession parameter \(\chi_{prec}\)
compute_chirp_mass(a2_param)	Compute the chirpmass from a2, the coefficient of time of the Finn-Chernoff waform model.
compute_chirp_mass_from_mass_ratio_and_total_mass(...)
compute_chirp_mass_from_masses(m1, m2)
compute_frequencies(t_coal, t_val, chirp_mass)	Compute the Newtonian instantaneous frequency of strain waveform from coalescence time and chirp mass, from the Finn-Chernoff model.
compute_masses_from_mass_ratio_and_chirp_mass(...)
compute_masses_from_mass_ratio_and_total_mass(...)	Compute the individual masses from mass-ratio and total mass
compute_total_mass_from_mass_ratio_and_chirp_mass(...)
differentiate(data[, delta_t, TS])	Differentiate a timeseries in time domain using the Simple Euler method
fill_gaps_in_data(data[, k])	Fill gaps in data by interpolation
find_maxloc_and_time(times, amp)
flatten_3l(nflist)	Flatten a (3rd order) list of list of lists.
flatten_l(nflist)	Flatten a (3rd order) list of list of lists.
get_centered_taxis(time_ax, amps)	Get the time axis of the waveform centered at its maximum absolute amplitude.
get_nr_frame_angles_from_lal(inclination, ...)	Convert the lalframe angles (inclination, phi_ref) to NR frame (theta, phi/psi, alpha)
get_starting_angular_frequency(waveform, delta_t)	Get the approximate starting frequency of the input data by averaging over the first npoints number of points.
get_val_at_t_ref(time_axis, val_axis, time)	Interpolate and get the value at the requested time
get_waveform_angular_frequency(waveform, delta_t)	Get the angular frequency of the waveform given the complex waveform time step.
integrate_first_order(data[, t_start, ...])	Integrate a timeseries using first order method.
interp_resam_wfs(wavf_data, old_taxis, new_taxis)	Wrapper function for interpolation and resampling.
interpolate_wfs(ts_data, interp_func[, delta_t])	Function to interpolate a list of timeseries data using the user specified interp_func function and the keyword arguments.
iscontinuous(time_axis[, delta_t, toldt])	Check if the data has discontinuities.
lengtheq(data_a, data_b[, delta_t, is_ts])	Equalize the length of two timeseries/array by appending zeros at the end of the array.
load_obj(name[, obj_dir])	A function to load python objects from the disk using pickle.
low_cut_filter(utilde, freqs[, order, omega0])	Apply low frequency cut filter using a butterworth filter.
massratio(chirp_mass)	Compute the mass ratio from chirpmass.
match_wfs(all_time_axes, all_waveforms[, ...])	Match two waveforms and return the time shift, phase shift, normalized waveforms and match coefficient.
match_wfs_pycbc(all_time_axes, all_waveforms)	Match two waveforms using pycbc subroutines and return the time shift, phase shift, normalized waveforms and match coefficient.
mavg(func_x, width)	Function to smoothen data.
message(*args[, message_verbosity, ...])	The print function with verbosity levels and logging facility.
norm(hdat[, psd])	Calculate the norm of a vector.
olap(data1, data2[, psd])	Calcuate the overlap between two data vectors weighted by the given psd.
plot(xdata, func_x[, save])	A Basic plotting function.
pmmatch_wfs(waveforms[, offset, crop])	Match function for post merger waveforms.
progressbar(present_count, total_counts[, ...])	Display the progress bar to std out from present_count and total_count.
removeNans(xdata, ydata)	Remove Nans from (xdata,ydata) data pair.
remove_repetitive_rows(data[, delta_t, toldt])	Remove repeated rows in the data
removezeros(data, delta_t)	Remove zeros from the input waveform from either sides.
resample(interp_data, new_delta_t, epoch, length)	Function to generate timeseries out of the given interpolated data function, epoch,sampling frequency, length(duration).
resample_wfs(both_time_axes, both_waveforms)	Resample the waveform pairs.
roll(tsdata, i_roll[, is_ts])	Roll the data circularly.
save_obj(obj, name[, obj_dir, protocol])	A function to save python objects to disk using pickle.
shiftmatched(hdat, ind[, delta_t, is_ts])	Timeshift an array.
shorten(tsdata, start, end[, delta_t])	Shorten an array given the start and end points.
simplematch_wfs_old(waveforms[, delta_t])	Simple match the given waveforms.
smoothen(func_x, win, order[, xdata, to_plot])	Use the Savitzky-Golay Filter to smoothen the data.
sort_data(data)	Sort the data according to its time axis.
startend(data)	Identify the start and endpoints of the data.
stat_mode(a_list)	Find the mode of a list
taper(data[, delta_t, zeros])	A method to taper and append additional zeros at either ends, using the taper function of the pycbc TimeSeries object.
taper_tanh(waveform[, time_axis, delta_t, ...])	Taper a waveform with a \(tanh\) function at either ends
taperlengtheq(data_a, data_b[, delta_t])	Taper and equalize the lengths of two arrays.
totalmass(mass_ratio, chirp_mass)	Find total mass from mass ratio and chirpmass.
unsort(sorted_array, args_order)
unwrap_phase(phi0)	Unwrap the phase by finding turning points in phi0.
xtract_camp(tsdata_p, tsdata_x[, to_plot])	Given real and imaginary parts of a complex timeseries, extract the amplitude of the complex data vector : (tsdata_p + i * tsdata_x)
xtract_camp_phase(tsdata_1, tsdata_2)	Wrapper for extracting the amplitude
xtract_cphase(tsdata_p, tsdata_x[, delta_t, ...])	Given real and imaginary parts of a complex timeseries, extract the phase of the waveform :arctan_(Img(data)/Re(data))

waveformtools.waveformtools.addzeros(data, zeros)

Append zeros to an array without tapering.

Parameters:

data1d array or a pycbc TimeSeries

The waveform data as list or numpy array or pycbc timeseries.

zerosint

The number of zeros to be added.

Returns:

data1darray

data with zeros number of zeros concatenated at the end as numpy 1d array

waveformtools.waveformtools.apxstartend(data, tol=1e-05)

Identify the Approximate start and endpoints of the data.

Parameters:

data1d array or a pycbc TimeSeries object

The input waveform whose start and end points need to be identified based on a given tolerance value.

tolfloat

The tolerance value below which the signal is assumed to be absent.

Returns:

loc_pairint (2)

The pair of indices denoting the start and end points of an array

Notes

The starting and ending index of the peak tol (default 1e-5) part of the data is the identification criterion. Requires the data to fall off to tol*peak absolute value outside a certain range.

waveformtools.waveformtools.bintp(xdata, func_x, width, order, to_plot=True)

Function to bin the data and interpolate it at specified width and order.

Parameters:

xdata1d array

1D list or numpy array.

func_x1d array

The y axis.

widthint

Window size for smoothening,

orderint

Order of the polynomial used for interpolation.

to_plotbool

True or False. To plot or not plot the results.

Returns:

histlist

[binloc, yvals], The location of the bins and

the y values associated with the bins.

waveformtools.waveformtools.center(wvp, wvc=None, delta_t=None)

Center a waveform (wvp, wvc) at the peak of the complex modulous sqrt(wvp**2 + wvc**2).

Parameters:

wvp, wvc1d array or a pycbc TimeSeries object

The one/two components of the waveforms as 1d list or numpy arrays or pycbc timeseries.

delta_tfloat

The timestepping delta_t.

Returns:

centered_wfa pycbc TimeSeries object

The two 1d centered waveform(s) as individual pycbc timeseries.

waveformtools.waveformtools.cleandata(data, toldt=0.001, bridge=False, k=5)

Check the data (time,datar,datai) for repetetive rows and remove them.

Parameters:

data: list

Input as a list of 1d arrays [time, data1, data2, …]. All the data share the common time axis time

toldt: float

The tolerance for error in checking. defaluts to toldt=1e-3.

bridge: bool

A bridge flag to decide whether or not to interpolate and resample to fill in jump discontinuities.

k: int, optional

The interpolation order. Defaults to 5

Returns:

cleaned_data: list

The cleaned data array with repetitive rows and gaps (if bridge=True) removed.

waveformtools.waveformtools.coalignwfs(tsdata1, tsdata2, delta_t=None)

Coalign two timeseries. Wrapper and modification around pycbc functions with some additional functionalities.

Parameters:

tsdata1, tsdata2list, 1d array or a pycbc TimeSeries

The two data vectors as 1d lists or numpy arrays or pycbc TimeSeries

delta_tfloat

The time stepping.

Returns:

ctsdata1, tsdata2a pycbc TimeSeries

A pair of pycbc TimeSeries objects the aligned first waveform and the second.

Notes

The first waveform is changed.

waveformtools.waveformtools.coalignwfs2(tsdata1, tsdata2, delta_t=None)

Coalign two waveforms function 2.

Parameters:

tsdata1, tsdata21d array or a pycbc TimeSeries

two data vectors as 1d lists or numpy arrays or pycbc timeseries.

Returns:

aligned_waveformslist

The aligned waveforms in the format [aligned_wf1, aligned_wf2, [norm1, norm2, location of maximum]].

Notes

See coalignwfs for more description. This algorithm does not use the builtin coalign function from pycbc. This involves normalization of the data vectors explicitly and identifiies the timeshift by computing the complex SNR and finding the maximum element.

waveformtools.waveformtools.compute_chi_eff_from_masses_and_spins(spin1, spin2, larger_mass_ratio)

Compute the effective z-spin parameter \(\chi_{eff}\)

Parameters:

spin1,spin2: tuple of floats

The spin vector of the two black holes

larger_mass_ratio: float, >1

The SpEC convention mass-ratio \(\dfrac{M_1}{M_2}\)

waveformtools.waveformtools.compute_chi_prec_from_masses_and_spins(spin1, spin2, larger_mass_ratio)

Compute the effective spin-precession parameter \(\chi_{prec}\)

Parameters:

spin1,spin2: tuple of floats

The spin vector of the two black holes

larger_mass_ratio: float,

The SpEC convention mass-ratio, usually greater than 1

waveformtools.waveformtools.compute_chirp_mass(a2_param)

Compute the chirpmass from a2, the coefficient of time of the Finn-Chernoff waform model.

Parameters:

a2_param: 1d array float

The a2 parameter in the Finn Chernoff model.

Returns:

chirp_mass: float

The chirp mass

waveformtools.waveformtools.compute_chirp_mass_from_mass_ratio_and_total_mass(mass_ratio, M=1)

waveformtools.waveformtools.compute_chirp_mass_from_masses(m1, m2)

waveformtools.waveformtools.compute_frequencies(t_coal, t_val, chirp_mass)

Compute the Newtonian instantaneous frequency of strain waveform from coalescence time and chirp mass, from the Finn-Chernoff model.

Parameters:

t_coal: float

The coalescence time,

t_val: 1d array

The time,

chirp_mass: float

The chirpmass.

Returns:

freqs: float

The instantaneous frequency of the strain waveform.

waveformtools.waveformtools.compute_masses_from_mass_ratio_and_chirp_mass(mass_ratio, chirp_mass)

waveformtools.waveformtools.compute_masses_from_mass_ratio_and_total_mass(mass_ratio, M=1)

Compute the individual masses from mass-ratio and total mass

waveformtools.waveformtools.compute_total_mass_from_mass_ratio_and_chirp_mass(mass_ratio, chirp_mass)

waveformtools.waveformtools.differentiate(data, delta_t=None, TS=False)

Differentiate a timeseries in time domain using the Simple Euler method

Parameters:

data: 1d array

a pycbc TimeSeries object The time series to be differentiated.

delta_t: float

The grid spacing delta_t. Supplying delta_t overrides the delta_t attribute of TimeSeries.

Returns:

ddt_data: pycbc TimeSeries object

The differentiated 1d data as pycbc TimeSeries

waveformtools.waveformtools.fill_gaps_in_data(data, k=5)

Fill gaps in data by interpolation

Parameters:

data: list

Input as a list of 1d arrays [time, data1, data2, …]. All the data share the common time axis time

k: int, optional

The interpolation order. Defaults to 5

Returns:

cleaned_data: list

The cleaned data array with repetitive rows and gaps (if bridge=True) removed.

See also

scipy.interpolate.InterpolatedUnivariateSpline

waveformtools.waveformtools.find_maxloc_and_time(times, amp)

waveformtools.waveformtools.flatten_3l(nflist)

Flatten a (3rd order) list of list of lists. i.e. a three tier list [[[],[]], [[],[]] —> []. This is useful e.g. when combining the data from the list output of multiple MPI ranks.

Parameters:

nflista third tier list

A list of list of lists (a list of depth three).

Returns:

flattened_lista list

The flattened list i.e. a tier one list.

waveformtools.waveformtools.flatten_l(nflist)

Flatten a (3rd order) list of list of lists. i.e. a three tier list [[[],[]], [[],[]] —> []. This is useful e.g. when combining the data from the list output of multiple MPI ranks.

Parameters:

nflista third tier list

A list of list of lists (a list of depth three).

Returns:

flattened_lista list

The flattened list i.e. a tier one list.

waveformtools.waveformtools.get_centered_taxis(time_ax, amps)

Get the time axis of the waveform centered at its maximum absolute amplitude.

Parameters:

time_ax1d array

The 1d array containg the original (uncentered)time axis of the wveform.

amps1d array

The amplitude of the waveform.

Returns:

time_centered1d array

The centered time axis of the waveform. The maximum amplitude timestamp will be at \(t=0\).

waveformtools.waveformtools.get_nr_frame_angles_from_lal(inclination, phi_ref, tol=0.001)

Convert the lalframe angles (inclination, phi_ref) to NR frame (theta, phi/psi, alpha)

waveformtools.waveformtools.get_starting_angular_frequency(waveform, delta_t, npoints=400)

Get the approximate starting frequency of the input data by averaging over the first npoints number of points.

Parameters:

waveform: 1d array

The 1d complex array of the input waveform.

delta_t: float

The time step.

npoints: int

The number of points to average over.

Returns:

omega0: float

The approximate starting angular frequency.

Notes

Please suppy a conditioned input waveform that is neatly clipped, and not tapered.

waveformtools.waveformtools.get_val_at_t_ref(time_axis, val_axis, time)

Interpolate and get the value at the requested time

waveformtools.waveformtools.get_waveform_angular_frequency(waveform, delta_t, timeaxis=None, method='FD')

Get the angular frequency of the waveform given the complex waveform time step. The phase is extracted and is differentiated using one of the available methods to compute the angular frequency.

Parameters:

waveform: 1d array

The 1d complex array of the input waveform.

delta_t: float

The time step.

timeaxis: 1d array, optional

The time axis of the waveform. Recommended especially when the sampling is non-uniform and Chebyshev method is chosen.

method: str

The method for computing the derivative. Can be FD or CS. See below for more information.

Returns:

omega: 1d array

The real instantaneous frequency of the waveform.

Notes

Available methods

Chebyshev series (CS): The phase is expanded in

a Chebyshev series and

Finite Differencing (FD): A 11 point finite difference

scheme is used to differentiate the phase, and is then smoothened using the Savgol filter.

waveformtools.waveformtools.integrate_first_order(data, t_start=None, t_end=None, delta_t=None, to_taper=False, TS=False)

Integrate a timeseries using first order method.

Parameters:

data1d array or a pycbc TimeSeries object

The input function to be integrated.

delta_tfloat

The grid spacing delta_t,

to_taperbool

True or False. Whether or not to taper the input series.

Returns:

int_dataa pycbc TimeSeries object

TimeSeries of the time integrated data

Notes

Capabilities

Simple Euler integrator, option to taper the ends.

waveformtools.waveformtools.interp_resam_wfs(wavf_data, old_taxis, new_taxis, kind='cubic', k=None)

Wrapper function for interpolation and resampling.

Parameters:

wavf_data1d array

The yaxis to be interpolated,

old_taxis, new_taxis1darray

Old and New time axis.

Returns:

resam_wf_data1d array

Interpolated and resampled data.

waveformtools.waveformtools.interpolate_wfs(ts_data, interp_func, delta_t=None, **kwargs)

Function to interpolate a list of timeseries data using the user specified interp_func function and the keyword arguments.

Parameters:

ts_data: list

The 1d data. A list of waveforms as a list or numpy array or pycbc TimeSeries.

interp_fun: function

An interpolating function.

delta_t: float

Timestep.

``**kwargs``: keyword arguments

additional arguments to the user specified interp_func.

Returns:

interp_data: list

A list containing interpolated data.

waveformtools.waveformtools.iscontinuous(time_axis, delta_t=None, toldt=0.001)

Check if the data has discontinuities. This checks for repetitive time rows and jumps.

Parameters:

data: list

Input as a list of 1d arrays [time, data1, data2, …]. All the data share the common time axis time

delta_t: float

The time stepping.

toldt: float

The tolerance for error in checking. defaluts to toldt=1e-3.

Returns:

discontinuity_details: list.

It contains:

1. A list. details of discontinuity. index location of original array, the corresponding discinbtinuity type.

2. A float. the global discontinuity type.

Notes

Types of discontunuities

0: Continuous. 1: Repetitive rows. 2: Jumps in timeaxis.

waveformtools.waveformtools.lengtheq(data_a, data_b, delta_t=None, is_ts=False)

Equalize the length of two timeseries/array by appending zeros at the end of the array. No tapering.

Parameters:

data_a: list

The input waveform A

data_b: list

The input waveform B.

delta_t: float

The time steping. Defaults to None.

is_ts: bool

To determine whether the given data is a pycbc TimeSeries.

Returns

——-

equalized_signals: list

The Tapered, length equalized waveforms data_a and data_b, and a flag denoting which waveform was changed, a or b.

Notes

Recommended usage:

Change length of waveform a to match with that of waveform b.

waveformtools.waveformtools.load_obj(name, obj_dir='./')

A function to load python objects from the disk using pickle.

Parameters:

name: string

The filename.

obj_dir: string

The path to directory in which file exists. Defaults to PWD.

Returns:

obj: object

A python object with the contents of the file.

waveformtools.waveformtools.low_cut_filter(utilde, freqs, order=2, omega0=0.03)

Apply low frequency cut filter using a butterworth filter.

Parameters:

utilde1d array

The frequency domain data.

freqs1d array

The frequencies.

orderint

The order of the butterworth filter.

omega0float

The cutoff frequency of the butterworth filter.

Returns:

utilde_lc1d array

The filtered data.

waveformtools.waveformtools.massratio(chirp_mass)

Compute the mass ratio from chirpmass. Assumes total mass to be 1.

Parameters:

mchirp: float

The chirp mass of the system.

Returns:

mass_ratio: float

The Mass ratio of the system

waveformtools.waveformtools.match_wfs(all_time_axes, all_waveforms, delta_t='auto')

Match two waveforms and return the time shift, phase shift, normalized waveforms and match coefficient.

Parameters:

time_axeslist

A list containing the time axes of the two waveforms

waveformslist

A list of two waveforms. Each is a 1d array.

delta_tfloat, string, optional

The time step of the resampled arrays. Can be A, B, auto or any float value.

Returns:

match_detailsdict

A dictionary containing the i). match coeffient ii). time_shift iii). phase shift in radians iv). normalized, resampled, waveforms

and their time-axes.

waveformtools.waveformtools.match_wfs_pycbc(all_time_axes, all_waveforms)

Match two waveforms using pycbc subroutines and return the time shift, phase shift, normalized waveforms and match coefficient.

Parameters:

time_axeslist

A list containing the time axes of the two waveforms

waveformslist

A list of two waveforms. Each is a 1d array.

changeint

Which waveform to change, 1 or 2.

Returns:

match_detailsdict

A dictionary containing the i). match coeffient ii). time_shift iii). phase shift iv). normalized waveforms and their time-axes.

waveformtools.waveformtools.mavg(func_x, width)

Function to smoothen data. Moving average over the window width.

Parameters:

func_x1d array

A list or numpy array of y axis.

Widthint

The width of the moving average window.

Returns:

func_x_avgd1d array

1D array of moving averaged y axis.

waveformtools.waveformtools.message(*args, message_verbosity=2, print_verbosity=3, log_verbosity=1, **kwargs)

The print function with verbosity levels and logging facility.

Parameters:

``*args`: non-keyword arguments

same arguments as to that of the print functions,

message_verbosity: int

print_verbosity: int

log_verbosity: int

``**kwargs``: keyword arguments

Same as that of the print function.

Returns:

1: int

messages to stdout and logging of messages, while the function returns 1.

Notes

Verbosity choices:

• message_verbosity: Each message carries with it a verbosity level.

  More the verbosity less the priority. Default value is 2 i.e. informational.

• print_verbosity: prints all messages above this level of verbosity.

• log_verbosity: logs all messages above this level of verbosity.

Verbosity levels: * 0: Errors * 1: Warnings * 2: Information

waveformtools.waveformtools.norm(hdat, psd=1.0)

Calculate the norm of a vector.

Parameters:

hdat: 1d array or a pycbc TimeSeries object.

The input waveform.

psa: 1d array

The noise power spectral density of the inner product.

Returns:

norm_f: float

The norm with weighting by the psd.

waveformtools.waveformtools.olap(data1, data2, psd=1)

Calcuate the overlap between two data vectors weighted by the given psd.

Parameters:

data1, data2: 1d array or a pycbc RimeSeries object

The input waveforms

psd: 1d array

The power spectral density to weight.

Returns:

overlap: float

The overlap divided by the psd.

waveformtools.waveformtools.plot(xdata, func_x, save='no')

A Basic plotting function.

Parameters:

xdata1d array

The x axis of the function,

func_x1d array

The y axis of the function f(x),

savebool.

True or False. Whether the plot should be saved or not.

Returns:

1int

plotsfigures to stdout and disk

Displays the plot, and Saves with the filename provided.

waveformtools.waveformtools.pmmatch_wfs(waveforms, offset=25, crop=None)

Match function for post merger waveforms.

Parameters:

waveformsa list of pairs

The pairs of waveforms to match in the format [[wf1_pair1, wf2_pair2], [wf1_pair_2, wf2_pair2], …].

offsetint

Number of indices to shift the data.

cropstring

A string to decide how to crop the waveforms. The available Options are 1. signal 2. template 3. both.

Returns:

matchdeta list of dicts

A list of dictionaries. Each contains

1. the waveform pair,

2. the match score,

3. the shift index. to maximize the match.

waveformtools.waveformtools.progressbar(present_count, total_counts, normalize='yes')

Display the progress bar to std out from present_count and total_count.

Parameters:

present_countint

The present count state.

total_countsint

The final state.

Returns:

1int

The progress bar is messageed to stdout.

waveformtools.waveformtools.removeNans(xdata, ydata)

Remove Nans from (xdata,ydata) data pair. Removes Nans in xdata and ydata and the corresponding y and x entries.

Parameters:

xdata: 1d array

The x axis of the data.

ydata: 1d array

The y axis of the data.

Returns:

x_no_nan,y_no_nan: 1d,array

The data pair x,y with Nans removed.

waveformtools.waveformtools.remove_repetitive_rows(data, delta_t=1, toldt=0.001)

Remove repeated rows in the data

Parameters:

data: ndarray

Data array where the first axis refers to different columns of data. The zeroth column is time axis. The second axis refers to entries at different time steps.

delta_t: float

The tim stepping.

toldt: float

The tolerance for error in checking. Defaluts to toldt=1e-3.

Returns:

cleaned_data: list

The cleaned data array with repetitive rows removed.

waveformtools.waveformtools.removezeros(data, delta_t)

Remove zeros from the input waveform from either sides. Similar to startend but return the truncated array.

Parameters:

data1d array or a pycbc TimeSeries

The input waveform.

delta_tfloat, optional

The time stepping.

Returns:

short_tsa list

A list containing waveforms with zeros removed on either sides, the start and end indices in the format [short_ts, [start_index, end_index]]

waveformtools.waveformtools.resample(interp_data, new_delta_t, epoch, length, old_delta_t=None)

Function to generate timeseries out of the given interpolated data function, epoch,sampling frequency, length(duration).

Parameters:

interp_data1d array

The yaxis to be interpolated.

epochfloat

The starting point in time.

delta_tfloat

New grid spacing to be sampled at.

lengthint

The duration of x axis.

Returns:

datalist

A list containing resampled data as pycbc TimeSeries.

waveformtools.waveformtools.resample_wfs(both_time_axes, both_waveforms, delta_t='auto', Plot=False)

Resample the waveform pairs.

Parameters:

both_time_axeslist

A list containing two 1d arrays representing the time axes.

both_waveformslist

A list containing two 1d arrays respresenting the waveforms.

delta_tstring, float

The time step to resample at. Auto uses the finest of the two available. A float value can be provided by the user as well.

Returns:

both_time_axes_resam1d array

A 1d array representing the resampled time axes.

both_waveforms_resamlist

A list containing two 1d arrays respresenting the resampled waveforms.

waveformtools.waveformtools.roll(tsdata, i_roll, is_ts=False)

Roll the data circularly. Circular counterpart of shiftmatched function.

Parameters:

tsdata: 1d array or pycbc TimeSeries

1D data vector in the form of a list/ numpy array or timeseries.

i_roll: int

The number of indices to roll the array.

Returns:

rolled_waveform: 1d array or(pycbc TimeSeries object

The rolled wavefrom.

waveformtools.waveformtools.save_obj(obj, name, obj_dir='./', protocol=5)

A function to save python objects to disk using pickle.

Parameters:

obj: object

The python object to be saved.

name: string

The filename.

obj_dir: string

The path to directory to be saved in. Defaults to PWD

protocol: int

The protocol to be used to save. Default is binary.

Returns:

Nothing (other than saving the data to the disk).

Notes

Protocols:

• 0 : Text

• 5 : Binary

See the man page of pickle for more details.

waveformtools.waveformtools.shiftmatched(hdat, ind, delta_t=None, is_ts=False)

Timeshift an array. IMP: After timeshifting, the original length of the array is retained by clipping last(first) when ind > 0(ind <0) ind number of points!!. Make sure the input array already has number of zeros z > ind (z<ind) initially at the end.

Parameters:

hdat: 1d array or a pycbc TimeSeries object

The input waveform to be shifted in time.

ind: int

The numper of places to shift the input waveform.

delta_t: int

the grid spacing in time.

Returns:

shifted_wf: a pycbc TimeSeries object

The waveform array of same length timeshifted by ind units by prepending zeros.

waveformtools.waveformtools.shorten(tsdata, start, end, delta_t=None)

Shorten an array given the start and end points.

Parameters:

tsdata1d array or a pycbc TimeSeries object

The waveform data.

startint

The start index of the data.

endint

The end index of the data.

delta_tfloat, optional

The time stepping.

Returns:

short_tsa pycbc TimeSeries object

The shortened data, clipped before start and after end.

waveformtools.waveformtools.simplematch_wfs_old(waveforms, delta_t=None)

Simple match the given waveforms. Does not clip the waveforms at either ends.

Parameters:

waveformslist

A list of pairs [waveform A, waveform B] of waveforms.

delta_tfloat, optional

The time stepping.

Returns:

matchlist

A list of dicts [{ Aligned waveforms} , {match score (float), shift (number)}] containing the match information for all the input waveform pairs.

Notes

The time stepping delta_t is the same for each pair of waveforms in the list.

waveformtools.waveformtools.smoothen(func_x, win, order, xdata=None, to_plot=False)

Use the Savitzky-Golay Filter to smoothen the data.

Show the plots if plot=`yes`.

Parameters:

func_x: 1d array

The y axis.

win: int

Window for smoothening. Must be odd.

order: int

The order of the polynomial used for interpolation.

x: 1d array, optional.

The 1D list or numpy array, to plot the smoothened function. Only required if to_plot=True.

to_plot: bool

True or False. Whether or not to display the plot.

Returns:

ydata: 1d array

The Savgol filtered list.

waveformtools.waveformtools.sort_data(data)

Sort the data according to its time axis. The first axis is assumend to be the time axis.

Parameters:

data: ndarray

The data array with shape (naxis, time_steps) The first axis is assumed to be the time axis.

Returns:

sorted_data: ndarray

The sorted data array

waveformtools.waveformtools.startend(data)

Identify the start and endpoints of the data.

Parameters:

data1d array or a pycbc TimeSeries object

The input waveform.

Returns:

start_index, end_indexint (2)

The pair of indices denoting the start and end points of an array

Notes

The starting and ending index of the non-zero part of the data is the identification criterion. Requires the data to be exactly zero outside a certain domain.

waveformtools.waveformtools.stat_mode(a_list)

Find the mode of a list

Parameters:

a_list: list

The list whose mode is to be found

Returns:

list_mode: float

The mode of the list.

waveformtools.waveformtools.taper(data, delta_t=1, zeros=150)

A method to taper and append additional zeros at either ends, using the taper function of the pycbc TimeSeries object.

Parameters:

data1d array or a pycbc TimeSeries

The waveform data

delta_tfloat

The timestepping.

zerosint

The number of zeros to be added.

Returns:

tapered_data1d array or a pycbc TimeSeries

The waveform data tapered and zero padded.

Notes

See taper_timeseries from pycbc.waveform.utils for more details.

waveformtools.waveformtools.taper_tanh(waveform, time_axis=None, delta_t=None, duration=10, sides='both')

Taper a waveform with a \(tanh\) function at either ends

Parameters:

waveform1d array

A 1d array of waveform data.

delta_tfloat, optional

The time stepping delta_t. Optional if time_axis is given.

percentint, optional

The percent of data to taper. This is equally distributed on either sides of the array. Defaults to 10.

sidesstr

A string indicating which sides to taper. beg tapers the beginning, end tapers the end and both tapers both the ends.

Returns:

time_axis, waveform1d array

The timeaxis and the waveform data of the tapered waveform.

waveformtools.waveformtools.taperlengtheq(data_a, data_b, delta_t=None)

Taper and equalize the lengths of two arrays.

Parameters:

data_a: list

The input waveform A.

data_b: list

The input waveform B.

delta_t: float

The time steping.

Returns:

equalized_signals: list

The Tapered, length equalized waveforms data_a and data_b, and a flag denoting which waveform was changed, a or b.

waveformtools.waveformtools.totalmass(mass_ratio, chirp_mass)

Find total mass from mass ratio and chirpmass.

Parameters:

mass_ratio: float

The mass ratio of the system.

mchirp: float

The chirp mass of the system.

Returns:

total_mass: float

The total mass of the system.

waveformtools.waveformtools.unsort(sorted_array, args_order)

waveformtools.waveformtools.unwrap_phase(phi0)

Unwrap the phase by finding turning points in phi0. Finding turning points for unwrapping arctan2 function

Parameters:

phi0: 1darray

The wrapped phase which takes values in the range (0, 2pi).

Returns

——-

phic: 1darray

The unwrapped phase.

waveformtools.waveformtools.xtract_camp(tsdata_p, tsdata_x, to_plot=False)

Given real and imaginary parts of a complex timeseries, extract the amplitude of the complex data vector : (tsdata_p + i * tsdata_x)

Parameters:

tsdata_p, tsdata_x: pycbc TimeSeries/1darray

The plus and cross polarized components of the waveforms.

to_plot: bool

True or False. Whether to plot the data or not

Returns:

camp: 1d array

The 1d array of extracted amplitudes of the waveform.

waveformtools.waveformtools.xtract_camp_phase(tsdata_1, tsdata_2)

Wrapper for extracting the amplitude

and the phase of the complex vector.

Parameters:

tsdata_1, tsdata_2: 1d array or pycbc TimeSeries object

The two input waveforms as timeseries vectors, the plus and cross polarized components.

delta_t: float

The timestepping delta_t.

Returns:

amplitude: 1d array

A list containing complex amplitude (list) and phase (list).

waveformtools.waveformtools.xtract_cphase(tsdata_p, tsdata_x, delta_t=None, to_plot=False)

Given real and imaginary parts of a complex timeseries, extract the phase of the waveform :arctan_(Img(data)/Re(data))

Parameters:

tsdata_p, tsdata_x: 1d array / a pycbc TimeSeries

The plus and cross polarized components of the waveforms.

delta_t: float, optional

The time step. Overrides the timestep from pycbc TS object if given.

to_plot: bool, optional

True or False. Whether to plot the data or not

Returns:

phic: 1d array

The 1d array of the phase of the waveform.