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.
- class pycbc.vetoes.bank_chisq.SingleDetSkyMaxBankVeto(*args, **kwds)[source]
Bases:
SingleDetBankVeto
Stub for precessing bank veto if anyone ever wants to code it up.
- 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:
filters (list of FrequencySeries) – The list of bank veto templates filters.
stilde (FrequencySeries) – The current segment of data.
psd (FrequencySeries)
low_frequency_cutoff (float)
- 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:
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)[source]
Bases:
object
Class that handles precomputation and memory management for efficiently running the power chisq in a single detector inspiral analysis.
- 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.
- 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.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:
- 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:
- 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:
- 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:
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.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
- 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: