pycbc.vetoes package

Submodules

pycbc.vetoes.autochisq module

class pycbc.vetoes.autochisq.SingleDetAutoChisq(stride, num_points, onesided=None, twophase=False, reverse_template=False, take_maximum_value=False, maximal_value_dof=None)

Bases: object

Class that handles precomputation and memory management for efficiently running the auto chisq in a single detector inspiral analysis.

classmethod from_cli(args)

Create the auto-chisq from the options of insert_option_group.

static insert_option_group(parser)

Add the auto-chisq options to an argument parser.

values(sn, indices, template, psd, norm, stilde=None, low_frequency_cutoff=None, high_frequency_cutoff=None)

Calculate the auto-chisq at the specified indices.

Parameters:

• sn (Array[complex]) – SNR time series of the template for which auto-chisq is being computed. Provided unnormalized.

• indices (Array[int]) – List of points at which to calculate auto-chisq

• template (Pycbc template object) – The template for which we are calculating auto-chisq

• psd (Pycbc psd object) – The PSD of the data being analysed

• norm (float) – The normalization factor to apply to sn

• stilde (Pycbc data object, needed if using reverse-template) – The data being analysed. Only needed if using reverse-template, otherwise ignored

• low_frequency_cutoff (float) – The lower frequency to consider in matched-filters

• high_frequency_cutoff (float) – The upper frequency to consider in matched-filters

Returns:

• achi_list (TimeSeries of auto veto values - if indices)

• is None then evaluated at all time samples, if not then only at

• requested sample indices

• dof (int, approx number of statistical degrees of freedom)

class pycbc.vetoes.autochisq.SingleDetSkyMaxAutoChisq(*args, **kwds)

Bases: SingleDetAutoChisq

Stub for precessing auto chisq if anyone ever wants to code it up.

values(*args, **kwargs)

Calculate the auto-chisq at the specified indices.

Parameters:

• sn (Array[complex]) – SNR time series of the template for which auto-chisq is being computed. Provided unnormalized.

• indices (Array[int]) – List of points at which to calculate auto-chisq

• template (Pycbc template object) – The template for which we are calculating auto-chisq

• psd (Pycbc psd object) – The PSD of the data being analysed

• norm (float) – The normalization factor to apply to sn

• stilde (Pycbc data object, needed if using reverse-template) – The data being analysed. Only needed if using reverse-template, otherwise ignored

• low_frequency_cutoff (float) – The lower frequency to consider in matched-filters

• high_frequency_cutoff (float) – The upper frequency to consider in matched-filters

Returns:

• achi_list (TimeSeries of auto veto values - if indices)

• is None then evaluated at all time samples, if not then only at

• requested sample indices

• dof (int, approx number of statistical degrees of freedom)

pycbc.vetoes.autochisq.autochisq_from_precomputed(sn, corr_sn, hautocorr, indices, stride=1, num_points=None, oneside=None, twophase=True, maxvalued=False)

Compute correlation (two sided) between template and data and compares with autocorrelation of the template: C(t) = IFFT(A*A/S(f))

Parameters:

• sn (Array[complex]) – normalized (!) array of complex snr for the template that produced the trigger(s) being tested

• corr_sn (Array[complex]) – normalized (!) array of complex snr for the template that you want to produce a correlation chisq test for. In the [common] case that sn and corr_sn are the same, you are computing auto-correlation chisq.

• hautocorr (Array[complex]) – time domain autocorrelation for the template

• indices (Array[int]) – compute correlation chisquare at the points specified in this array,

• num_points ([int, optional; default=None]) – Number of points used for autochisq on each side, if None all points are used.

• stride ([int, optional; default = 1]) – stride for points selection for autochisq total length <= 2*num_points*stride

• oneside ([str, optional; default=None]) – whether to use one or two sided autochisquare. If None (or not provided) twosided chi-squared will be used. If given, options are ‘left’ or ‘right’, to do one-sided chi-squared on the left or right.

• twophase (Boolean, optional; default=True) – If True calculate the auto-chisq using both phases of the filter. If False only use the phase of the obtained trigger(s).

• maxvalued (Boolean, optional; default=False) – Return the largest auto-chisq at any of the points tested if True. If False, return the sum of auto-chisq at all points tested.

Returns:

• dof (int) – number of degrees of freedom

• autochisq (Array[float]) – autochisq values corresponding to the time instances defined by indices

pycbc.vetoes.bank_chisq module

class pycbc.vetoes.bank_chisq.SingleDetBankVeto(bank_file, flen=None, delta_f=None, f_low=None, cdtype=None, approximant=None, **kwds)

Bases: object

This class reads in a template bank file for a bank veto, handles the memory management of its filters internally, and calculates the bank veto TimeSeries.

cache_overlaps(template, psd)

cache_segment_snrs(stilde, psd, overwhitened=True)

classmethod from_cli(args)

static insert_option_group(parser)

values(template, psd, stilde, snrv, norm, indices, overwhitened=True)

Returns:

• bank_chisq_from_filters (TimeSeries of bank veto values - if indices)

• is None then evaluated at all time samples, if not then only at

• requested sample indices

• bank_chisq_dof (int, approx number of statistical degrees of freedom)

class pycbc.vetoes.bank_chisq.SingleDetSkyMaxBankVeto(*args, **kwds)

Bases: SingleDetBankVeto

Stub for precessing bank veto if anyone ever wants to code it up.

values(*args, **kwargs)

Returns:

• bank_chisq_from_filters (TimeSeries of bank veto values - if indices)

• is None then evaluated at all time samples, if not then only at

• requested sample indices

• bank_chisq_dof (int, approx number of statistical degrees of freedom)

pycbc.vetoes.bank_chisq.bank_chisq_from_filters(tmplt_snr, tmplt_norm, bank_snrs, bank_norms, tmplt_bank_matches, indices=None)

This function calculates and returns a TimeSeries object containing the bank veto calculated over a segment.

Parameters:

• tmplt_snr (TimeSeries) – The SNR time series from filtering the segment against the current search template

• tmplt_norm (float) – The normalization factor for the search template

• bank_snrs (list of TimeSeries) – The precomputed list of SNR time series between each of the bank veto templates and the segment

• bank_norms (list of floats) – The normalization factors for the list of bank veto templates (usually this will be the same for all bank veto templates)

• tmplt_bank_matches (list of floats) – The complex overlap between the search template and each of the bank templates

• indices ({None, Array}, optional) – Array of indices into the snr time series. If given, the bank chisq will only be calculated at these values.

Returns:

bank_chisq

Return type:

TimeSeries of the bank vetos

pycbc.vetoes.bank_chisq.segment_snrs(filters, stilde, psd, low_frequency_cutoff, overwhitened=True)

This functions calculates the snr of each bank veto template against the segment

Parameters:

• filters (list of FrequencySeries) – The list of bank veto templates filters.

• stilde (FrequencySeries) – The current segment of data.

• psd (FrequencySeries)

• low_frequency_cutoff (float)

• overwhitened (bool, optional) – Whether stilde is already divided by the PSD.

Returns:

• snr (list) (List of snr time series.)

• norm (list) (List of normalizations factors for the snr time series.)

pycbc.vetoes.bank_chisq.template_overlaps(bank_filters, template, psd, low_frequency_cutoff)

This functions calculates the overlaps between the template and the bank veto templates.

Parameters:

• bank_filters (List of FrequencySeries)

• template (FrequencySeries)

• psd (FrequencySeries)

• low_frequency_cutoff (float)

Returns:

overlaps

Return type:

List of complex overlap values.

pycbc.vetoes.chisq module

class pycbc.vetoes.chisq.SingleDetPowerChisq(num_bins=0, snr_threshold=None)

Bases: object

Class that handles precomputation and memory management for efficiently running the power chisq in a single detector inspiral analysis.

Each bin is weighted by the template power it contains, so that the chisq does not depend on how evenly the bins divide that power; see power_chisq_bin_weights.

cached_chisq_bins_and_weights(template, psd)

Returns the chisq bin edges for this template and psd and the weight of each bin, computing them only once for each pair.

classmethod from_cli(args)

Create the power chisq from the options of insert_option_group.

static insert_option_group(parser)

Add the power chisq options to an argument parser.

static parse_option(row, arg)

values(corr, snrv, snr_norm, psd, indices, template)

Calculate the chisq at points given by indices.

Returns:

• chisq (Array) – Chisq values, one for each sample index, or zero for points below the specified SNR threshold

• chisq_dof (Array) – Number of statistical degrees of freedom for the chisq test in the given template, equal to 2 * num_bins - 2

class pycbc.vetoes.chisq.SingleDetSkyMaxPowerChisq(**kwds)

Bases: SingleDetPowerChisq

Class that handles precomputation and memory management for efficiently running the power chisq in a single detector inspiral analysis when maximizing analytically over sky location.

calculate_chisq_bins_and_weights(template, psd)

Obtain the chisq bins for this template and PSD, and their weights.

values(corr_plus, corr_cross, snrv, psd, indices, template_plus, template_cross, u_vals, hplus_cross_corr, hpnorm, hcnorm)

Calculate the chisq at points given by indices.

Returns:

• chisq (Array) – Chisq values, one for each sample index

• chisq_dof (Array) – Number of statistical degrees of freedom for the chisq test in the given template

pycbc.vetoes.chisq.chisq_accum_bin(chisq, q)

pycbc.vetoes.chisq.fastest_power_chisq_at_points(corr, snr, snrv, snr_norm, bins, indices, weights=None)

Calculate the chisq values for only selected points.

This function looks at the number of points to be evaluated and selects the fastest method (FFT, or direct time shift and sum). In either case, only the selected points are returned.

Parameters:

• corr (FrequencySeries) – The product of the template and data in the frequency domain.

• snr (Array) – The unnormalized snr

• snr_norm (float) – The snr normalization factor — EXPLAINME

• bins (List of integers) – The edges of the equal power bins

• indices (Array) – The indices where we will calculate the chisq. These must be relative to the given snr series.

Returns:

chisq – An array containing only the chisq at the selected points.

Return type:

Array

pycbc.vetoes.chisq.power_chisq(template, data, num_bins, psd, low_frequency_cutoff=None, high_frequency_cutoff=None, return_bins=False, return_bins_slice=None)

Calculate the chisq timeseries

Parameters:

• template (FrequencySeries or TimeSeries) – A time or frequency series that contains the filter template.

• data (FrequencySeries or TimeSeries) – A time or frequency series that contains the data to filter. The length must be commensurate with the template. (EXPLAINME - does this mean ‘the same as’ or something else?)

• num_bins (int) – The number of frequency bins used for chisq. The number of statistical degrees of freedom (‘dof’) is 2*num_bins-2.

• psd (FrequencySeries) – The psd of the data.

• low_frequency_cutoff ({None, float}, optional) – The low frequency cutoff for the filter

• high_frequency_cutoff ({None, float}, optional) – The high frequency cutoff for the filter

• return_bins ({boolean, False}, optional) – Return a list of the individual chisq bins

• return_bins_slice ({slice, None}, optional) – If provided and return_bins is True, returns numpy array slices of each bin’s SNR time series instead of full TimeSeries objects.

Returns:

chisq – TimeSeries containing the chisq values for all times.

Return type:

TimeSeries

pycbc.vetoes.chisq.power_chisq_at_points_from_precomputed(corr, snr, snr_norm, bins, indices, weights=None)

Calculate the chisq timeseries from precomputed values for only select points.

This function calculates the chisq at each point by explicitly time shifting and summing each bin. No FFT is involved.

Parameters:

• corr (FrequencySeries) – The product of the template and data in the frequency domain.

• snr (numpy.ndarray) – The unnormalized array of snr values at only the selected points in indices.

• snr_norm (float) – The normalization of the snr (EXPLAINME : refer to Findchirp paper?)

• bins (List of integers) – The edges of the equal power bins

• indices (Array) – The indices where we will calculate the chisq. These must be relative to the given corr series.

• weights (numpy.ndarray, optional) – The weight of each bin, as returned by power_chisq_bin_weights. If not given, each weight is the number of bins, which gives the standard chisq for bins of equal power.

Returns:

chisq – An array containing only the chisq at the selected points.

Return type:

Array

pycbc.vetoes.chisq.power_chisq_bin_weights(sigmasq_series, bins)

Remove the empty chisq bins, and calculate the weight of each remaining bin.

The chisq bins are placed so that each contains an equal share of the template’s power. Because the bin edges must fall on frequency samples, the shares are not exactly equal, and a bin that is only a few samples wide may contain no power at all. Each such empty bin is merged into the bin that follows it (an empty last bin, into the bin before it). Each remaining bin j is then given the weight:

w_j = (total template power) / (template power in bin j).

The chisq functions use these weights to compute:

chisq = sum_j w_j |z_j|^2 - |rho|^2,

where z_j is the SNR accumulated over the frequencies of bin j and rho, the sum of the z_j, is the SNR. For any bins this has 2p - 2 degrees of freedom, where p is the number of bins, and a signal that exactly matches the template does not increase it. If every bin contains the same power, every w_j is p and this is the standard power chisq.

Parameters:

• sigmasq_series (numpy.ndarray) – The cumulative template power: at each frequency sample, the sum of |h(f)|^2 / S(f) over that sample and all below it, as returned by pycbc.filter.sigmasq_series.

• bins (numpy.ndarray) – The bin edges, as indices into sigmasq_series. Bin j covers the samples from bins[j] up to, but not including, bins[j + 1].

Returns:

• bins (numpy.ndarray) – The edges of the remaining bins.

• weights (numpy.ndarray) – The weight w_j of each remaining bin.

pycbc.vetoes.chisq.power_chisq_bins_and_weights(htilde, num_bins, psd, low_frequency_cutoff=None, high_frequency_cutoff=None)

Returns the bins for use with the chisq functions and the weight of each bin: edges placed to divide the template’s power equally, with any bin that contains no power merged into the next (see power_chisq_bin_weights).

Parameters:

• htilde (FrequencySeries) – A frequency series containing the template waveform

• num_bins (int) – The number of chisq bins to calculate.

• psd (FrequencySeries) – A frequency series containing the psd. Its length must be commensurate with the template waveform.

• low_frequency_cutoff ({None, float}, optional) – The low frequency cutoff to apply

• high_frequency_cutoff ({None, float}, optional) – The high frequency cutoff to apply

Returns:

• bins (numpy.ndarray) – The edges of the chisq bins.

• weights (numpy.ndarray) – The weight of each bin.

pycbc.vetoes.chisq.power_chisq_bins_from_sigmasq_series(sigmasq_series, num_bins, kmin, kmax)

Returns bins of equal power for use with the chisq functions

Parameters:

• sigmasq_series (FrequencySeries) – A frequency series containing the cumulative power of a filter template preweighted by a psd.

• num_bins (int) – The number of chisq bins to calculate.

• kmin (int) – DOCUMENTME

• kmax (int) – DOCUMENTME

Returns:

bins – A list of the edges of the chisq bins is returned.

Return type:

List of ints

pycbc.vetoes.chisq.power_chisq_from_precomputed(corr, snr, snr_norm, bins, indices=None, return_bins=False, return_bins_slice=None, weights=None)

Calculate the chisq timeseries from precomputed values.

This function calculates the chisq at all times by performing an inverse FFT of each bin.

Parameters:

• corr (FrequencySeries) – The produce of the template and data in the frequency domain.

• snr (TimeSeries) – The unnormalized snr time series.

• snr_norm – The snr normalization factor (true snr = snr * snr_norm) EXPLAINME - define ‘true snr’?

• bins (List of integers) – The edges of the chisq bins.

• indices ({Array, None}, optional) – Index values into snr that indicate where to calculate chisq values. If none, calculate chisq for all possible indices.

• return_bins ({boolean, False}, optional) – Return a list of the SNRs for each chisq bin.

• return_bins_slice ({slice, None}, optional) – If provided, only slice the specified range for each bin and return as numpy arrays, avoiding full-length TimeSeries allocations.

• weights (numpy.ndarray, optional) – The weight of each bin, as returned by power_chisq_bin_weights. If not given, each weight is the number of bins, which gives the standard chisq for bins of equal power.

Returns:

chisq

Return type:

TimeSeries

pycbc.vetoes.chisq.shift_sum(v1, shifts, bins, weights=None)

Calculate the time shifted sum of the FrequencySeries: at each of the given shifts, the sum over bins of w_j |z_j|^2, where z_j is the sum of v1 over bin j shifted in time. Each w_j is 1 if weights is None.

pycbc.vetoes.chisq_cpu module

pycbc.vetoes.chisq_cpu.chisq_accum_bin(chisq, q)

pycbc.vetoes.chisq_cpu.chisq_accum_bin_cython(chisq, q, N)

pycbc.vetoes.chisq_cpu.chisq_accum_bin_numpy(chisq, q)

pycbc.vetoes.chisq_cpu.point_chisq_code(chisq, v1, n, slen, shifts, bins, blen, weights)

pycbc.vetoes.chisq_cpu.shift_sum(v1, shifts, bins, weights=None)

pycbc.vetoes.chisq_cuda module

pycbc.vetoes.chisq_cuda.chisq_accum_bin(chisq, q)

pycbc.vetoes.chisq_cuda.get_accum_diff_sq_kernel(dtype_x, dtype_z)

pycbc.vetoes.chisq_cuda.get_cached_bin_layout(bins)

pycbc.vetoes.chisq_cuda.get_cached_pow2(N)

pycbc.vetoes.chisq_cuda.get_pchisq_fn(np, fuse_correlate=False)

pycbc.vetoes.chisq_cuda.get_pchisq_fn_pow2(np, fuse_correlate=False)

pycbc.vetoes.chisq_cuda.shift_sum(corr, points, bins, weights=None)

pycbc.vetoes.chisq_cuda.shift_sum_points(num, N, arg_tuple)

pycbc.vetoes.chisq_cuda.shift_sum_points_pow2(num, arg_tuple)

pycbc.vetoes.chisq_cupy module

pycbc.vetoes.chisq_cupy.chisq_accum_bin(chisq, q)

pycbc.vetoes.chisq_cupy.get_cached_bin_layout(bins)

pycbc.vetoes.chisq_cupy.get_cached_pow2(N)

pycbc.vetoes.chisq_cupy.get_pchisq_fn(np, fuse_correlate=False)

pycbc.vetoes.chisq_cupy.get_pchisq_fn_pow2(np, fuse_correlate=False)

pycbc.vetoes.chisq_cupy.shift_sum(corr, points, bins, weights=None)

pycbc.vetoes.chisq_cupy.shift_sum_points(num, N, arg_tuple)

pycbc.vetoes.chisq_cupy.shift_sum_points_pow2(num, arg_tuple)

pycbc.vetoes.sgchisq module

Chisq based on sine-gaussian tiles. See https://arxiv.org/abs/1709.08974 for a discussion.

class pycbc.vetoes.sgchisq.SingleDetSGChisq(bank, num_bins=0, snr_threshold=None, chisq_locations=None)

Bases: SingleDetPowerChisq

Class that handles precomputation and memory management for efficiently running the sine-Gaussian chisq

cached_tiles(stilde, psd, template)

classmethod from_cli(args, bank=None, chisq_bins=None)

Create the power chisq from the options of insert_option_group.

static insert_option_group(parser)

Add the power chisq options to an argument parser.

peak_frequency(template, psd=None)

Estimate the maximum frequency up to which the waveform has power by approximating power per frequency as constant over the last 2 chisq bins. We cannot use the final chisq bin edge as it does not have to be where the waveform terminates.

returns = {'sg_chisq': <class 'numpy.float32'>}

values(stilde, template, psd, snrv, snr_norm, bchisq=None, bchisq_dof=None, indices=None, overwhitened=True)

Calculate sine-Gaussian chisq

Parameters:

• stilde (pycbc.types.FrequencySeries) – The data, divided by its PSD (overwhitened) unless overwhitened is False

• template (pycbc.types.FrequencySeries) – The waveform template being analyzed

• psd (pycbc.types.FrequencySeries) – The power spectral density of the data

• snrv (numpy.ndarray) – The peak unnormalized complex SNR values

• snr_norm (float) – The normalization factor for the snr

• bchisq (numpy.ndarray, optional) – The Bruce Allen power chisq values for these triggers

• bchisq_dof (numpy.ndarray, optional) – The degrees of freedom of the Bruce chisq

• indices (numpy.ndarray, optional) – The indices of the snr peaks.

• overwhitened (bool, optional) – Whether stilde is already divided by the PSD.

Returns:

chisq – Chisq values, one for each sample index

Return type:

Array

Module contents