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

Bases: object

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

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

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

Bases: SingleDetAutoChisq

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

values(*args, **kwargs)[source]

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

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, delta_f, f_low, cdtype, approximant=None, **kwds)[source]

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)[source]
cache_segment_snrs(stilde, psd)[source]
values(template, psd, stilde, snrv, norm, indices)[source]
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)[source]

Bases: SingleDetBankVeto

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

values(*args, **kwargs)[source]
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)[source]

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

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

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

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

Parameters:
Returns:

overlaps

Return type:

List of complex overlap values.

pycbc.vetoes.chisq module

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

Bases: object

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

cached_chisq_bins(template, psd)[source]
static parse_option(row, arg)[source]
values(corr, snrv, snr_norm, psd, indices, template)[source]

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

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(template, psd)[source]

Obtain the chisq bins for this template and PSD.

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

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)[source]
pycbc.vetoes.chisq.fastest_power_chisq_at_points(corr, snr, snrv, snr_norm, bins, indices)[source]

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

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

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

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.

Returns:

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

Return type:

Array

pycbc.vetoes.chisq.power_chisq_bins(htilde, num_bins, psd, low_frequency_cutoff=None, high_frequency_cutoff=None)[source]

Returns bins of equal power for use with the chisq functions

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 – A list of the edges of the chisq bins is returned.

Return type:

List of ints

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

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

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.

Returns:

chisq

Return type:

TimeSeries

pycbc.vetoes.chisq.shift_sum(v1, shifts, bins)[source]

Calculate the time shifted sum of the FrequencySeries

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)
pycbc.vetoes.chisq_cpu.shift_sum(v1, shifts, bins)

pycbc.vetoes.chisq_cupy module

pycbc.vetoes.chisq_cupy.chisq_accum_bin(chisq, q)[source]
pycbc.vetoes.chisq_cupy.get_cached_bin_layout(bins)[source]
pycbc.vetoes.chisq_cupy.get_cached_pow2(N)[source]
pycbc.vetoes.chisq_cupy.get_pchisq_fn(np, fuse_correlate=False)[source]
pycbc.vetoes.chisq_cupy.get_pchisq_fn_pow2(np, fuse_correlate=False)[source]
pycbc.vetoes.chisq_cupy.shift_sum(corr, points, bins)[source]
pycbc.vetoes.chisq_cupy.shift_sum_points(num, N, arg_tuple)[source]
pycbc.vetoes.chisq_cupy.shift_sum_points_pow2(num, arg_tuple)[source]

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

Bases: SingleDetPowerChisq

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

classmethod from_cli(args, bank, chisq_bins)[source]
static insert_option_group(parser)[source]
returns = {'sg_chisq': <class 'numpy.float32'>}
values(stilde, template, psd, snrv, snr_norm, bchisq, bchisq_dof, indices)[source]

Calculate sine-Gaussian chisq

Parameters:

  • stilde (pycbc.types.Frequencyseries) – The overwhitened strain

  • 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) – The Bruce Allen power chisq values for these triggers

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

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

Returns:

chisq – Chisq values, one for each sample index

Return type:

Array

Module contents