pycbc.events package

Submodules

pycbc.events.coinc module

This modules contains functions for calculating and manipulating coincident triggers.

class pycbc.events.coinc.CoincExpireBuffer(expiration, ifos, initial_size=1048576, dtype=<type 'numpy.float32'>)

Bases: object

Unordered dynamic sized buffer that handles multiple expiration vectors.

add(values, times, ifos)

Add values to the internal buffer

Parameters:

• values (numpy.ndarray) – Array of elements to add to the internal buffer.
• times (dict of arrays) – The current time to use for each element being added.
• ifos (list of strs) – The set of timers to be incremented.

data

Return the array of elements

increment(ifos)

Increment without adding triggers

nbytes

num_greater(value)

Return the number of elements larger than ‘value’

remove(num)

Remove the the last ‘num’ elements from the buffer

class pycbc.events.coinc.LiveCoincTimeslideBackgroundEstimator(num_templates, analysis_block, background_statistic, stat_files, ifos, ifar_limit=100, timeslide_interval=0.035, coinc_threshold=0.002, return_background=False)

Bases: object

Rolling buffer background estimation.

add_singles(results)

Add singles to the bacckground estimate and find candidates

Parameters:results (dict of arrays) – Dictionary of dictionaries indexed by ifo and keys such as ‘snr’, ‘chisq’, etc. The specific format it determined by the LiveBatchMatchedFilter class. Returns:coinc_results – A dictionary of arrays containing the coincident results. Return type:dict of arrays

background_time

Return the amount of background time that the buffers contain

backout_last(updated_singles, num_coincs)

Remove the recently added singles and coincs

Parameters:

• updated_singles (dict of numpy.ndarrays) – Array of indices that have been just updated in the internal buffers of single detector triggers.
• num_coincs (int) – The number of coincs that were just added to the internal buffer of coincident triggers

classmethod from_cli(args, num_templates, analysis_chunk, ifos)

ifar(coinc_stat)

Return the far that would be associated with the coincident given.

static insert_args(parser)

classmethod pick_best_coinc(coinc_results)

Choose the best two-ifo coinc by ifar first, then statistic if needed.

This function picks which of the available double-ifo coincs to use. It chooses the best (highest) ifar. The ranking statistic is used as a tie-breaker. A trials factor is applied if multiple types of coincs are possible at this time given the active ifos.

Parameters:coinc_results (list of coinc result dicts) – Dictionary by detector pair of coinc result dicts. Returns:best – If there is a coinc, this will contain the ‘best’ one. Otherwise it will return the provided dict. Return type:coinc results dict

static restore_state(filename)

Restore state of the background buffers from a file

save_state(filename)

Save the current state of the background buffers

set_singles_buffer(results)

Create the singles buffer

This creates the singles buffer for each ifo. The dtype is determined by a representative sample of the single triggers in the results.

Parameters:restuls (dict of dict) – Dict indexed by ifo and then trigger column.

class pycbc.events.coinc.MultiRingBuffer(num_rings, max_time, dtype)

Bases: object

Dynamic size n-dimensional ring buffer that can expire elements.

add(indices, values)

Add triggers in ‘values’ to the buffers indicated by the indices

advance_time()

Advance the internal time increment by 1, expiring any triggers that are now too old.

data(buffer_index)

Return the data vector for a given ring buffer

discard_last(indices)

Discard the triggers added in the latest update

expire_vector(buffer_index)

Return the expiration vector of a given ring buffer

filled_time

nbytes

num_elements()

pycbc.events.coinc.background_bin_from_string(background_bins, data)

Return template ids for each bin as defined by the format string

Parameters:

• bins (list of strings) – List of strings which define how a background bin is taken from the list of templates.
• data (dict of numpy.ndarrays) – Dict with parameter key values and numpy.ndarray values which define the parameters of the template bank to bin up.

Returns:

bins – Dictionary of location indices indexed by a bin name

Return type:

dict

pycbc.events.coinc.calculate_n_louder(bstat, fstat, dec, skip_background=False)

Calculate for each foreground event the number of background events that are louder than it.

Parameters:

• bstat (numpy.ndarray) – Array of the background statistic values
• fstat (numpy.ndarray or scalar) – Array of the foreground statistic values or single value
• dec (numpy.ndarray) – Array of the decimation factors for the background statistics
• skip_background (optional, {boolean, False}) – Skip calculating cumulative numbers for background triggers

Returns:

• cum_back_num (numpy.ndarray) – The cumulative array of background triggers. Does not return this argument if skip_background == True
• fore_n_louder (numpy.ndarray) – The number of background triggers above each foreground trigger

pycbc.events.coinc.cluster_coincs(stat, time1, time2, timeslide_id, slide, window, argmax=<function argmax>)

Cluster coincident events for each timeslide separately, across templates, based on the ranking statistic

Parameters:

• stat (numpy.ndarray) – vector of ranking values to maximize
• time1 (numpy.ndarray) – first time vector
• time2 (numpy.ndarray) – second time vector
• timeslide_id (numpy.ndarray) – vector that determines the timeslide offset
• slide (float) – length of the timeslides offset interval
• window (float) – length to cluster over

Returns:

cindex – The set of indices corresponding to the surviving coincidences.

Return type:

numpy.ndarray

pycbc.events.coinc.cluster_coincs_multiifo(stat, time_coincs, timeslide_id, slide, window, argmax=<function argmax>)

Cluster coincident events for each timeslide separately, across templates, based on the ranking statistic

Parameters:

• stat (numpy.ndarray) – vector of ranking values to maximize
• time_coincs (tuple of numpy.ndarrays) – trigger times for each ifo, or -1 if an ifo does not participate in a coinc
• timeslide_id (numpy.ndarray) – vector that determines the timeslide offset
• slide (float) – length of the timeslides offset interval
• window (float) – duration of clustering window in seconds

Returns:

cindex – The set of indices corresponding to the surviving coincidences

Return type:

numpy.ndarray

pycbc.events.coinc.cluster_over_time(stat, time, window, argmax=<function argmax>)

Cluster generalized transient events over time via maximum stat over a symmetric sliding window

Parameters:

• stat (numpy.ndarray) – vector of ranking values to maximize
• time (numpy.ndarray) – time to use for clustering
• window (float) – length to cluster over
• argmax (function) – the function used to calculate the maximum value

Returns:

cindex – The set of indices corresponding to the surviving coincidences.

Return type:

numpy.ndarray

pycbc.events.coinc.mean_if_greater_than_zero(vals)

Calculate mean over numerical values, ignoring values less than zero. E.g. used for mean time over coincident triggers when timestamps are set to -1 for ifos not included in the coincidence.

Parameters:vals (iterator of numerical values) – values to be mean averaged Returns:

• mean (float) – The mean of the values in the original vector which are greater than zero
• num_above_zero (int) – The number of entries in the vector which are above zero

pycbc.events.coinc.time_coincidence(t1, t2, window, slide_step=0)

Find coincidences by time window

Parameters:

• t1 (numpy.ndarray) – Array of trigger times from the first detector
• t2 (numpy.ndarray) – Array of trigger times from the second detector
• window (float) – Coincidence window maximum time difference, arbitrary units (usually s)
• slide_step (float (default 0)) – If calculating background coincidences, the interval between background slides, arbitrary units (usually s)

Returns:

• idx1 (numpy.ndarray) – Array of indices into the t1 array for coincident triggers
• idx2 (numpy.ndarray) – Array of indices into the t2 array
• slide (numpy.ndarray) – Array of slide ids

pycbc.events.coinc.time_multi_coincidence(times, slide_step=0, slop=0.003, pivot='H1', fixed='L1')

Find multi detector coincidences.

Parameters:

• times (dict of numpy.ndarrays) – Dictionary keyed by ifo of single ifo trigger times
• slide_step (float) – Interval between time slides
• slop (float) – The amount of time to add to the TOF between detectors for coincidence
• pivot (str) – The ifo to which time shifts are applied in first stage coincidence
• fixed (str) – The other ifo used in first stage coincidence, subsequently used as a time reference for additional ifos. All other ifos are not time shifted relative to this ifo

Returns:

• ids (dict of arrays of int) – Dictionary keyed by ifo with ids of trigger times forming coincidences. Coincidence is tested for every pair of ifos that can be formed from the input dict: only those tuples of times passing all tests are recorded
• slide (array of int) – Slide ids of coincident triggers in pivot ifo

pycbc.events.coinc.timeslide_durations(start1, start2, end1, end2, timeslide_offsets)

Find the coincident time for each timeslide.

Find the coincident time for each timeslide, where the first time vector is slid to the right by the offset in the given timeslide_offsets vector.

Parameters:

• start1 (numpy.ndarray) – Array of the start of valid analyzed times for detector 1
• start2 (numpy.ndarray) – Array of the start of valid analyzed times for detector 2
• end1 (numpy.ndarray) – Array of the end of valid analyzed times for detector 1
• end2 (numpy.ndarray) – Array of the end of valid analyzed times for detector 2
• timseslide_offset (numpy.ndarray) – Array of offsets (in seconds) for each timeslide

Returns:

durations – Array of coincident time for each timeslide in the offset array

Return type:

numpy.ndarray

pycbc.events.coinc_rate module

This module contains functions for calculating expected rates of noise and signal coincidences.

pycbc.events.coinc_rate.combination_noise_lograte(log_rates, slop)

Calculate the expected rate of noise coincidences for a combination of detectors given log of single detector noise rates

Parameters:

• log_rates (dict) – Key: ifo string, Value: sequence of log single-detector trigger rates, units assumed to be Hz
• slop (float) – time added to maximum time-of-flight between detectors to account for timing error

Returns:

Expected log coincidence rate in the combination, units Hz

Return type:

numpy array

pycbc.events.coinc_rate.combination_noise_rate(rates, slop)

Calculate the expected rate of noise coincidences for a combination of detectors WARNING: for high stat values, numerical underflow can occur

Parameters:

• rates (dict) – Key: ifo string, Value: sequence of single-detector trigger rates, units assumed to be Hz
• slop (float) – time added to maximum time-of-flight between detectors to account for timing error

Returns:

Expected coincidence rate in the combination, units Hz

Return type:

numpy array

pycbc.events.coinc_rate.multiifo_noise_coincident_area(ifos, slop)

Calculate the total extent of time offset between 2 detectors, or area of the 2d space of time offsets for 3 detectors, for which a coincidence can be generated Cannot yet handle more than 3 detectors.

Parameters:

• ifos (list of strings) – list of interferometers
• slop (float) – extra time to add to maximum time-of-flight for timing error

Returns:

allowed_area – area in units of seconds^(n_ifos-1) that coincident values can fall in

Return type:

float

pycbc.events.coinc_rate.multiifo_noise_lograte(log_rates, slop)

Calculate the expected rate of noise coincidences for multiple combinations of detectors

Parameters:

• log_rates (dict) – Key: ifo string, Value: sequence of log single-detector trigger rates, units assumed to be Hz
• slop (float) – time added to maximum time-of-flight between detectors to account for timing error

Returns:

expected_log_rates – Key: ifo combination string Value: expected log coincidence rate in the combination, units log Hz

Return type:

dict

pycbc.events.coinc_rate.multiifo_signal_coincident_area(ifos)

Calculate the area in which signal time differences are physically allowed

Parameters:ifos (list of strings) – list of interferometers Returns:allowed_area – area in units of seconds^(n_ifos-1) that coincident signals will occupy Return type:float

pycbc.events.eventmgr module

This modules defines functions for clustering and thresholding timeseries to produces event triggers

pycbc.events.eventmgr.threshold_and_cluster(series, threshold, window)

Return list of values and indices values over threshold in series.

pycbc.events.eventmgr.findchirp_cluster_over_window(times, values, window_length)

Reduce the events by clustering over a window using the FindChirp clustering algorithm

Parameters:

• indices (Array) – The list of indices of the SNR values
• snr (Array) – The list of SNR value
• window_size (int) – The size of the window in integer samples. Must be positive.

Returns:

indices – The reduced list of indices of the SNR values

Return type:

Array

pycbc.events.eventmgr.threshold(series, value)

Return list of values and indices values over threshold in series.

pycbc.events.eventmgr.cluster_reduce(idx, snr, window_size)

Reduce the events by clustering over a window

Parameters:

• indices (Array) – The list of indices of the SNR values
• snr (Array) – The list of SNR value
• window_size (int) – The size of the window in integer samples.

Returns:

• indices (Array) – The list of indices of the SNR values
• snr (Array) – The list of SNR values

class pycbc.events.eventmgr.ThresholdCluster

Bases: object

Create a threshold and cluster engine

Parameters:series (complex64) – Input pycbc.types.Array (or subclass); it will be searched for points above threshold that are then clustered

pycbc.events.eventmgr.threshold_real_numpy(series, value)

pycbc.events.eventmgr.threshold_only(series, value)

Return list of values and indices whose values in series are larger (in absolute value) than value

class pycbc.events.eventmgr.EventManager(opt, column, column_types, **kwds)

Bases: object

add_template_events(columns, vectors)

Add a vector indexed

add_template_params(**kwds)

chisq_threshold(value, num_bins, delta=0)

cluster_template_events(tcolumn, column, window_size)

Cluster the internal events over the named column

consolidate_events(opt, gwstrain=None)

finalize_events()

finalize_template_events()

classmethod from_multi_ifo_interface(opt, ifo, column, column_types, **kwds)

To use this for a single ifo from the multi ifo interface requires some small fixing of the opt structure. This does that. As we edit the opt structure the process_params table will not be correct.

keep_loudest_in_interval(window, num_keep, statname='newsnr', log_chirp_width=None)

keep_near_injection(window, injections)

make_output_dir(outname)

new_template(**kwds)

newsnr_threshold(threshold)

Remove events with newsnr smaller than given threshold

save_performance(ncores, nfilters, ntemplates, run_time, setup_time)

Calls variables from pycbc_inspiral to be used in a timing calculation

write_events(outname)

Write the found events to a sngl inspiral table

write_to_hdf(outname)

class pycbc.events.eventmgr.EventManagerMultiDet(opt, ifos, column, column_types, psd=None, **kwargs)

Bases: pycbc.events.eventmgr.EventManagerMultiDetBase

cluster_template_events_single_ifo(tcolumn, column, window_size, ifo)

Cluster the internal events over the named column

finalize_template_events(perform_coincidence=True, coinc_window=0.0)

write_events(outname)

Write the found events to a sngl inspiral table

write_to_hdf(outname)

class pycbc.events.eventmgr.EventManagerCoherent(opt, ifos, column, column_types, network_column, network_column_types, psd=None, **kwargs)

Bases: pycbc.events.eventmgr.EventManagerMultiDetBase

add_template_events_to_network(columns, vectors)

Add a vector indexed

add_template_network_events(columns, vectors)

Add a vector indexed

cluster_template_network_events(tcolumn, column, window_size)

Cluster the internal events over the named column

finalize_template_events()

write_to_hdf(outname)

pycbc.events.eventmgr_cython module

pycbc.events.eventmgr_cython.findchirp_cluster_over_window_cython

pycbc.events.ranking module

This module contains functions for calculating single-ifo ranking statistic values

pycbc.events.ranking.effsnr(snr, reduced_x2, fac=250.0)

Calculate the effective SNR statistic. See (S5y1 paper) for definition.

pycbc.events.ranking.get_newsnr(trigs)

Calculate newsnr (‘reweighted SNR’) for a trigs object

Parameters:trigs (dict of numpy.ndarrays, h5py group (or similar dict-like object)) – Dictionary-like object holding single detector trigger information. ‘chisq_dof’, ‘snr’, and ‘chisq’ are required keys Returns:Array of newsnr values Return type:numpy.ndarray

pycbc.events.ranking.get_newsnr_sgveto(trigs)

Calculate newsnr re-weigthed by the sine-gaussian veto

Parameters:trigs (dict of numpy.ndarrays, h5py group (or similar dict-like object)) – Dictionary-like object holding single detector trigger information. ‘chisq_dof’, ‘snr’, ‘sg_chisq’ and ‘chisq’ are required keys Returns:Array of newsnr values Return type:numpy.ndarray

pycbc.events.ranking.get_newsnr_sgveto_psdvar(trigs)

Calculate newsnr re-weighted by the sine-gaussian veto and psd variation statistic with a threshold at 1.2

Parameters:

• trigs (dict of numpy.ndarrays) – Dictionary holding single detector trigger information.
• 'snr', 'chisq' and 'psd_var_val' are required keys ('chisq_dof',) –

Returns:

Array of newsnr values

Return type:

numpy.ndarray

pycbc.events.ranking.get_newsnr_sgveto_psdvar_scaled(trigs)

Calculate newsnr re-weighted by the sine-gaussian veto and scaled psd variation statistic

Parameters:

• trigs (dict of numpy.ndarrays) – Dictionary holding single detector trigger information.
• 'snr', 'chisq' and 'psd_var_val' are required keys ('chisq_dof',) –

Returns:

Array of newsnr values

Return type:

numpy.ndarray

pycbc.events.ranking.get_newsnr_sgveto_psdvar_scaled_threshold(trigs)

Calculate newsnr re-weighted by the sine-gaussian veto and scaled psd variation statistic. A futher threshold is applied to the reduced chisq.

Parameters:

• trigs (dict of numpy.ndarrays) – Dictionary holding single detector trigger information.
• 'snr', 'chisq' and 'psd_var_val' are required keys ('chisq_dof',) –

Returns:

Array of newsnr values

Return type:

numpy.ndarray

pycbc.events.ranking.newsnr(snr, reduced_x2, q=6.0, n=2.0)

Calculate the re-weighted SNR statistic (‘newSNR’) from given SNR and reduced chi-squared values. See http://arxiv.org/abs/1208.3491 for definition. Previous implementation in glue/ligolw/lsctables.py

pycbc.events.ranking.newsnr_sgveto(snr, bchisq, sgchisq)

Combined SNR derived from NewSNR and Sine-Gaussian Chisq

pycbc.events.ranking.newsnr_sgveto_psdvar(snr, bchisq, sgchisq, psd_var_val)

Combined SNR derived from NewSNR, Sine-Gaussian Chisq and PSD variation statistic with a threshold at 1.2

pycbc.events.ranking.newsnr_sgveto_psdvar_scaled(snr, bchisq, sgchisq, psd_var_val, scaling=0.33)

Combined SNR derived from NewSNR, Sine-Gaussian Chisq and scaled PSD variation statistic.

pycbc.events.ranking.newsnr_sgveto_psdvar_scaled_threshold(snr, bchisq, sgchisq, psd_var_val, threshold=2.0)

Combined SNR derived from NewSNR and Sine-Gaussian Chisq, and scaled psd variation.

pycbc.events.simd_threshold_cython module

pycbc.events.simd_threshold_cython.parallel_thresh_cluster()

pycbc.events.simd_threshold_cython.parallel_threshold()

pycbc.events.single module

utilities for assigning FAR to single detector triggers

class pycbc.events.single.LiveSingle(ifo, newsnr_threshold=10.0, reduced_chisq_threshold=5, duration_threshold=0, fit_file=None, sngl_ifar_est_dist=None, fixed_ifar=None)

Bases: object

calculate_ifar(newsnr, duration)

check(trigs, data_reader)

Look for a single detector trigger that passes the thresholds in the current data.

classmethod from_cli(args, ifo)

static insert_args(parser)

pycbc.events.stat module

This module contains functions for calculating coincident ranking statistic values.

class pycbc.events.stat.ExpFitCombinedSNR(files=None, ifos=None, **kwargs)

Bases: pycbc.events.stat.ExpFitStatistic

Reworking of ExpFitStatistic designed to resemble network SNR

Use a monotonic function of the negative log noise rate density which approximates combined (new)snr for coincs with similar newsnr in each ifo

coinc(s0, s1, slide, step)

Calculate the final coinc ranking statistic

coinc_multiifo(s, slide, step, to_shift, **kwargs)

Calculate the coincident detection statistic.

Parameters:

• s (list) – List of (ifo, single detector statistic) tuples
• slide ((unused in this statistic)) –
• step ((unused in this statistic)) –
• to_shift (list) – List of integers indicating what multiples of the time shift will
• applied (unused in this statistic) (be) –

Returns:

Array of coincident ranking statistic values

Return type:

numpy.ndarray

single(trigs)

Single-detector statistic, here just equal to the log noise rate

use_alphamax()

class pycbc.events.stat.ExpFitSGBgRateStatistic(files=None, ifos=None, benchmark_lograte=-14.6, **kwargs)

Bases: pycbc.events.stat.ExpFitStatistic

Detection statistic using an exponential falloff noise model.

Statistic calculates the log noise coinc rate for each template over single-ifo newsnr values.

coinc_multiifo(s, slide, step, to_shift, **kwargs)

Calculate the coincident detection statistic.

Parameters:

• s (list) – List of (ifo, single detector statistic) tuples
• slide ((unused in this statistic)) –
• step ((unused in this statistic)) –
• to_shift (list) – List of integers indicating what multiples of the time shift will
• applied (unused in this statistic) (be) –

Returns:

Array of coincident ranking statistic values

Return type:

numpy.ndarray

reassign_rate(ifo)

class pycbc.events.stat.ExpFitSGCombinedSNR(files=None, ifos=None, **kwargs)

Bases: pycbc.events.stat.ExpFitCombinedSNR

ExpFitCombinedSNR but with sine-Gaussian veto added to the single

detector ranking

class pycbc.events.stat.ExpFitSGFgBgRateNewStatistic(files=None, ifos=None, **kwargs)

Bases: pycbc.events.stat.PhaseTDNewStatistic, pycbc.events.stat.ExpFitSGBgRateStatistic

assign_median_sigma(ifo)

coinc_multiifo(s, slide, step, to_shift, **kwargs)

Calculate the coincident detection statistic.

Parameters:

• s (list) – List of (ifo, single detector statistic) tuples
• slide ((unused in this statistic)) –
• step ((unused in this statistic)) –
• to_shift (list) – List of integers indicating what multiples of the time shift will
• applied (unused in this statistic) (be) –

Returns:

Array of coincident ranking statistic values

Return type:

numpy.ndarray

single(trigs)

Calculate the single detector statistic & assemble other parameters

Parameters:

• trigs (dict of numpy.ndarrays, h5py group or similar dict-like object) – Object holding single detector trigger information. ‘snr’, ‘chisq’,
• 'coa_phase', 'end_time', and 'sigmasq' are required keys. ('chisq_dof',) –

Returns:

Array of single detector parameter values

Return type:

numpy.ndarray

class pycbc.events.stat.ExpFitSGFgBgRateStatistic(files=None, ifos=None, **kwargs)

Bases: pycbc.events.stat.PhaseTDStatistic, pycbc.events.stat.ExpFitSGBgRateStatistic

assign_median_sigma(ifo)

coinc_multiifo(s, slide, step, to_shift, **kwargs)

Calculate the coincident detection statistic.

Parameters:

• s (list) – List of (ifo, single detector statistic) tuples
• slide ((unused in this statistic)) –
• step ((unused in this statistic)) –
• to_shift (list) – List of integers indicating what multiples of the time shift will
• applied (unused in this statistic) (be) –

Returns:

Array of coincident ranking statistic values

Return type:

numpy.ndarray

single(trigs)

Calculate the single detector statistic & assemble other parameters

Parameters:

• trigs (dict of numpy.ndarrays, h5py group or similar dict-like object) – Object holding single detector trigger information. ‘snr’, ‘chisq’,
• 'coa_phase', 'end_time', and 'sigmasq' are required keys. ('chisq_dof',) –

Returns:

Array of single detector parameter values

Return type:

numpy.ndarray

class pycbc.events.stat.ExpFitSGPSDCombinedSNR(files=None, ifos=None, **kwargs)

Bases: pycbc.events.stat.ExpFitCombinedSNR

ExpFitCombinedSNR but with sine-Gaussian veto and PSD variation added to

the single detector ranking

class pycbc.events.stat.ExpFitStatistic(files=None, ifos=None, **kwargs)

Bases: pycbc.events.stat.NewSNRStatistic

Detection statistic using an exponential falloff noise model.

Statistic approximates the negative log noise coinc rate density per template over single-ifo newsnr values.

assign_fits(ifo)

coinc(s0, s1, slide, step)

Calculate the final coinc ranking statistic

find_fits(trigs)

Get fit coeffs for a specific ifo and template id(s)

get_ref_vals(ifo)

lognoiserate(trigs)

Calculate the log noise rate density over single-ifo newsnr

Read in single trigger information, make the newsnr statistic and rescale by the fitted coefficients alpha and rate

single(trigs)

Single-detector statistic, here just equal to the log noise rate

class pycbc.events.stat.MaxContTradNewSNRStatistic(files=None, ifos=None, **kwargs)

Bases: pycbc.events.stat.NewSNRStatistic

Combination of NewSNR with the power chisq and auto chisq

single(trigs)

Calculate the single detector statistic.

Parameters:trigs (dict of numpy.ndarrays, h5py group (or similar dict-like object)) – Dictionary-like object holding single detector trigger information. ‘snr’, ‘cont_chisq’, ‘cont_chisq_dof’, ‘chisq_dof’ and ‘chisq’ are required keys for this statistic. Returns:stat – The array of single detector values Return type:numpy.ndarray

class pycbc.events.stat.NetworkSNRStatistic(files=None, ifos=None, **kwargs)

Bases: pycbc.events.stat.NewSNRStatistic

Same as the NewSNR statistic, but just sum of squares of SNRs

single(trigs)

Calculate the single detector statistic, here equal to newsnr

Parameters:trigs (dict of numpy.ndarrays, h5py group (or similar dict-like object)) – Dictionary-like object holding single detector trigger information. Returns:The array of single detector values Return type:numpy.ndarray

class pycbc.events.stat.NewSNRCutStatistic(files=None, ifos=None, **kwargs)

Bases: pycbc.events.stat.NewSNRStatistic

Same as the NewSNR statistic, but demonstrates a cut of the triggers

coinc(s0, s1, slide, step)

Calculate the coincident detection statistic.

Parameters:

• s0 (numpy.ndarray) – Single detector ranking statistic for the first detector.
• s1 (numpy.ndarray) – Single detector ranking statistic for the second detector.
• slide ((unused in this statistic)) –
• step ((unused in this statistic)) –

Returns:

cstat – Array of coincident ranking statistic values

Return type:

numpy.ndarray

single(trigs)

Calculate the single detector statistic.

Parameters:trigs (dict of numpy.ndarrays, h5py group (or similar dict-like object)) – Dictionary-like object holding single detector trigger information. Returns:newsnr – Array of single detector values Return type:numpy.ndarray

class pycbc.events.stat.NewSNRSGPSDScaledStatistic(files=None, ifos=None, **kwargs)

Bases: pycbc.events.stat.NewSNRSGStatistic

Calculate the NewSNRSGPSD coincident detection statistic

single(trigs)

Calculate the single detector statistic, here equal to newsnr combined with sgveto and psdvar statistic

Parameters:trigs (dict of numpy.ndarrays) – Returns:The array of single detector values Return type:numpy.ndarray

class pycbc.events.stat.NewSNRSGPSDScaledThresholdStatistic(files=None, ifos=None, **kwargs)

Bases: pycbc.events.stat.NewSNRSGStatistic

Calculate the NewSNRSGPSD coincident detection statistic

single(trigs)

Calculate the single detector statistic, here equal to newsnr combined with sgveto and psdvar statistic

Parameters:trigs (dict of numpy.ndarrays) – Returns:The array of single detector values Return type:numpy.ndarray

class pycbc.events.stat.NewSNRSGPSDStatistic(files=None, ifos=None, **kwargs)

Bases: pycbc.events.stat.NewSNRSGStatistic

Calculate the NewSNRSGPSD coincident detection statistic

single(trigs)

Calculate the single detector statistic, here equal to newsnr combined with sgveto and psdvar statistic

Parameters:trigs (dict of numpy.ndarrays) – Returns:The array of single detector values Return type:numpy.ndarray

class pycbc.events.stat.NewSNRSGStatistic(files=None, ifos=None, **kwargs)

Bases: pycbc.events.stat.NewSNRStatistic

Calculate the NewSNRSG coincident detection statistic

single(trigs)

Calculate the single detector statistic, here equal to newsnr_sgveto

Parameters:trigs (dict of numpy.ndarrays, h5py group (or similar dict-like object)) – Dictionary-like object holding single detector trigger information. Returns:The array of single detector values Return type:numpy.ndarray

class pycbc.events.stat.NewSNRStatistic(files=None, ifos=None, **kwargs)

Bases: pycbc.events.stat.Stat

Calculate the NewSNR coincident detection statistic

coinc(s0, s1, slide, step)

Calculate the coincident detection statistic.

Parameters:

• s0 (numpy.ndarray) – Single detector ranking statistic for the first detector.
• s1 (numpy.ndarray) – Single detector ranking statistic for the second detector.
• slide ((unused in this statistic)) –
• step ((unused in this statistic)) –

Returns:

Array of coincident ranking statistic values

Return type:

numpy.ndarray

coinc_multiifo(s, slide, step, to_shift, **kwargs)

Calculate the coincident detection statistic.

Parameters:

• s (list) – List of (ifo, single detector statistic) tuples
• slide ((unused in this statistic)) –
• step ((unused in this statistic)) –
• to_shift (list) – List of integers indicating what multiples of the time shift will
• applied (unused in this statistic) (be) –

Returns:

Array of coincident ranking statistic values

Return type:

numpy.ndarray

single(trigs)

Calculate the single detector statistic, here equal to newsnr

Parameters:trigs (dict of numpy.ndarrays, h5py group (or similar dict-like object)) – Dictionary-like object holding single detector trigger information. Returns:The array of single detector values Return type:numpy.ndarray

class pycbc.events.stat.PhaseTDExpFitSGPSDScaledStatistic(files=None, ifos=None, **kwargs)

Bases: pycbc.events.stat.PhaseTDExpFitSGStatistic

Statistic combining exponential noise model with signal histogram PDF

adding the sine-Gaussian veto and PSD variation statistic to the single detector ranking

class pycbc.events.stat.PhaseTDExpFitSGPSDStatistic(files=None, ifos=None, **kwargs)

Bases: pycbc.events.stat.PhaseTDExpFitSGStatistic

Statistic combining exponential noise model with signal histogram PDF

adding the sine-Gaussian veto and PSD variation statistic to the single detector ranking

class pycbc.events.stat.PhaseTDExpFitSGStatistic(files=None, ifos=None, **kwargs)

Bases: pycbc.events.stat.PhaseTDExpFitStatistic

Statistic combining exponential noise model with signal histogram PDF

adding the sine-Gaussian veto to the single detector ranking

class pycbc.events.stat.PhaseTDExpFitStatistic(files=None, ifos=None, **kwargs)

Bases: pycbc.events.stat.PhaseTDStatistic, pycbc.events.stat.ExpFitCombinedSNR

Statistic combining exponential noise model with signal histogram PDF

coinc(s0, s1, slide, step)

Calculate the coincident detection statistic.

Parameters:

• s0 (numpy.ndarray) – Single detector ranking statistic for the first detector.
• s1 (numpy.ndarray) – Single detector ranking statistic for the second detector.
• slide (numpy.ndarray) – Array of ints. These represent the multiple of the timeslide
• to bring a pair of single detector triggers into coincidence. (interval) –
• step (float) – The timeslide interval in seconds.

Returns:

coinc_stat – An array of the coincident ranking statistic values

Return type:

numpy.ndarray

single(trigs)

Calculate the single detector statistic & assemble other parameters

Parameters:

• trigs (dict of numpy.ndarrays, h5py group or similar dict-like object) – Object holding single detector trigger information. ‘snr’, ‘chisq’,
• 'coa_phase', 'end_time', and 'sigmasq' are required keys. ('chisq_dof',) –

Returns:

Array of single detector parameter values

Return type:

numpy.ndarray

class pycbc.events.stat.PhaseTDNewExpFitSGStatistic(files=None, ifos=None, **kwargs)

Bases: pycbc.events.stat.PhaseTDNewExpFitStatistic

Statistic combining exponential noise model with signal histogram PDF

adding the sine-Gaussian veto to the single detector ranking

class pycbc.events.stat.PhaseTDNewExpFitStatistic(files=None, ifos=None, **kwargs)

Bases: pycbc.events.stat.PhaseTDNewStatistic, pycbc.events.stat.ExpFitCombinedSNR

Statistic combining exponential noise model with signal histogram PDF

coinc(s0, s1, slide, step)

Calculate the coincident detection statistic.

Parameters:

• s0 (numpy.ndarray) – Single detector ranking statistic for the first detector.
• s1 (numpy.ndarray) – Single detector ranking statistic for the second detector.
• slide ((unused in this statistic)) –
• step ((unused in this statistic)) –

Returns:

Array of coincident ranking statistic values

Return type:

numpy.ndarray

single(trigs)

Calculate the single detector statistic & assemble other parameters

Parameters:

• trigs (dict of numpy.ndarrays, h5py group or similar dict-like object) – Object holding single detector trigger information. ‘snr’, ‘chisq’,
• 'coa_phase', 'end_time', and 'sigmasq' are required keys. ('chisq_dof',) –

Returns:

Array of single detector parameter values

Return type:

numpy.ndarray

class pycbc.events.stat.PhaseTDNewStatistic(files=None, ifos=None, **kwargs)

Bases: pycbc.events.stat.NewSNRStatistic

Statistic that re-weights combined newsnr using coinc parameters.

The weighting is based on the PDF of time delays, phase differences and amplitude ratios between triggers in different ifos.

get_hist(ifos=None)

Read in a signal density file for the ifo combination

logsignalrate(s0, s1, shift)

logsignalrate_multiifo(stats, shift, to_shift)

Calculate the normalized log rate density of signals via lookup

single(trigs)

Calculate the single detector statistic & assemble other parameters

Parameters:

• trigs (dict of numpy.ndarrays, h5py group or similar dict-like object) – Object holding single detector trigger information. ‘snr’, ‘chisq’,
• 'coa_phase', 'end_time', and 'sigmasq' are required keys. ('chisq_dof',) –

Returns:

Array of single detector parameter values

Return type:

numpy.ndarray

class pycbc.events.stat.PhaseTDSGStatistic(files=None, ifos=None, **kwargs)

Bases: pycbc.events.stat.PhaseTDStatistic

PhaseTDStatistic but with sine-Gaussian veto added to the

single-detector ranking

class pycbc.events.stat.PhaseTDStatistic(files=None, ifos=None, **kwargs)

Bases: pycbc.events.stat.NewSNRStatistic

Statistic that re-weights combined newsnr using coinc parameters.

The weighting is based on the PDF of time delays, phase differences and amplitude ratios between triggers in different ifos.

coinc(s0, s1, slide, step)

Calculate the coincident detection statistic.

Parameters:

• s0 (numpy.ndarray) – Single detector ranking statistic for the first detector.
• s1 (numpy.ndarray) – Single detector ranking statistic for the second detector.
• slide (numpy.ndarray) – Array of ints. These represent the multiple of the timeslide
• to bring a pair of single detector triggers into coincidence. (interval) –
• step (float) – The timeslide interval in seconds.

Returns:

coinc_stat – An array of the coincident ranking statistic values

Return type:

numpy.ndarray

get_hist(ifos=None, norm='max')

Read in a signal density file for the ifo combination

logsignalrate(s0, s1, shift)

Calculate the normalized log rate density of signals via lookup

logsignalrate_multiifo(s, shift, to_shift)

Parameters:

• s (list, length 2) – List of sets of single-ifo trigger parameter values
• shift (numpy.ndarray) – Array of floats giving the time shifts to be applied with
• given by to_shift (multiples) –
• to_shift (list, length 2) – List of time shift multiples

signal_hist(td, pd, sn0, sn1, rd)

single(trigs)

Calculate the single detector statistic & assemble other parameters

Parameters:

• trigs (dict of numpy.ndarrays, h5py group or similar dict-like object) – Object holding single detector trigger information. ‘snr’, ‘chisq’,
• 'coa_phase', 'end_time', and 'sigmasq' are required keys. ('chisq_dof',) –

Returns:

Array of single detector parameter values

Return type:

numpy.ndarray

slide_dt(singles, shift, slide_vec)

class pycbc.events.stat.Stat(files=None, ifos=None, **kwargs)

Bases: object

Base class which should be extended to provide a coincident statistic

class pycbc.events.stat.TwoOGCBBHStatistic(files=None, ifos=None, max_chirp_mass=None, **kwargs)

Bases: pycbc.events.stat.ExpFitSGFgBgRateNewStatistic

logsignalrate_multiifo(stats, shift, to_shift)

Calculate the normalized log rate density of signals via lookup

single(trigs)

Calculate the single detector statistic & assemble other parameters

Parameters:

• trigs (dict of numpy.ndarrays, h5py group or similar dict-like object) – Object holding single detector trigger information. ‘snr’, ‘chisq’,
• 'coa_phase', 'end_time', and 'sigmasq' are required keys. ('chisq_dof',) –

Returns:

Array of single detector parameter values

Return type:

numpy.ndarray

class pycbc.events.stat.TwoOGCStatistic(files=None, ifos=None, **kwargs)

Bases: pycbc.events.stat.ExpFitSGFgBgRateNewStatistic

pycbc.events.stat.get_sngl_statistic(stat)

Error-handling sugar around dict lookup for single-detector statistics

Parameters:stat (string) – Name of the single-detector statistic Returns:Subclass of Stat base class Return type:class Raises:RuntimeError – If the string is not recognized as corresponding to a Stat subclass

pycbc.events.stat.get_statistic(stat)

Error-handling sugar around dict lookup for coincident statistics

Parameters:stat (string) – Name of the coincident statistic Returns:Subclass of Stat base class Return type:class Raises:RuntimeError – If the string is not recognized as corresponding to a Stat subclass

pycbc.events.threshold_cpu module

class pycbc.events.threshold_cpu.CPUThresholdCluster(series)

Bases: pycbc.events.eventmgr._BaseThresholdCluster

threshold_and_cluster(threshold, window)

Threshold and cluster the memory specified at instantiation with the threshold and window size specified at creation.

Parameters:

• threshold (float32) – The minimum absolute value of the series given at object initialization to return when thresholding and clustering.
• window (uint32) – The size (in number of samples) of the window over which to cluster
• Returns –
• -------- –
• event_vals (complex64) – Numpy array, complex values of the clustered events
• event_locs (uint32) – Numpy array, indices into series of location of events

pycbc.events.threshold_cpu.threshold(series, value)

pycbc.events.threshold_cpu.threshold_inline(series, value)

pycbc.events.threshold_cpu.threshold_numpy(series, value)

pycbc.events.threshold_cpu.threshold_only(series, value)

pycbc.events.trigger_fits module

Tools for maximum likelihood fits to single trigger statistic values

For some set of values above a threshold, e.g. trigger SNRs, the functions in this module perform maximum likelihood fits with 1-sigma uncertainties to various simple functional forms of PDF, all normalized to 1. You can also obtain the fitted function and its (inverse) CDF and perform a Kolmogorov-Smirnov test.

Usage: # call the fit function directly if the threshold is known alpha, sigma_alpha = fit_exponential(snrs, 5.5)

# apply a threshold explicitly alpha, sigma_alpha = fit_above_thresh(‘exponential’, snrs, thresh=6.25)

# let the code work out the threshold from the smallest value via the default thresh=None alpha, sigma_alpha = fit_above_thresh(‘exponential’, snrs)

# or only fit the largest N values, i.e. tail fitting thresh = tail_threshold(snrs, N=500) alpha, sigma_alpha = fit_above_thresh(‘exponential’, snrs, thresh)

# obtain the fitted function directly xvals = numpy.xrange(5.5, 10.5, 20) exponential_fit = expfit(xvals, alpha, thresh)

# or access function by name exponential_fit_1 = fit_fn(‘exponential’, xvals, alpha, thresh)

# get the KS test statistic and p-value - see scipy.stats.kstest ks_stat, ks_pval = KS_test(‘exponential’, snrs, alpha, thresh)

pycbc.events.trigger_fits.KS_test(distr, vals, alpha, thresh=None)

Perform Kolmogorov-Smirnov test for fitted distribution

Compare the given set of discrete values above a given threshold to the fitted distribution function. If no threshold is specified, the minimum sample value will be used. Returns the KS test statistic and its p-value: lower p means less probable under the hypothesis of a perfect fit

Parameters:

• distr ({'exponential', 'rayleigh', 'power'}) – Name of distribution
• vals (sequence of floats) – Values to compare to fit
• alpha (float) – Fitted distribution parameter
• thresh (float) – Threshold to apply before fitting; if None, use min(vals)

Returns:

• D (float) – KS test statistic
• p-value (float) – p-value, assumed to be two-tailed

pycbc.events.trigger_fits.cum_fit(distr, xvals, alpha, thresh)

Integral of the fitted function above a given value (reverse CDF)

The fitted function is normalized to 1 above threshold

Parameters:

• xvals (sequence of floats) – Values where the function is to be evaluated
• alpha (float) – The fitted parameter
• thresh (float) – Threshold value applied to fitted values

Returns:

cum_fit – Reverse CDF of fitted function at the requested xvals

Return type:

array of floats

pycbc.events.trigger_fits.fit_above_thresh(distr, vals, thresh=None)

Maximum likelihood fit for the coefficient alpha

Fitting a distribution of discrete values above a given threshold. Exponential p(x) = alpha exp(-alpha (x-x_t)) Rayleigh p(x) = alpha x exp(-alpha (x**2-x_t**2)/2) Power p(x) = ((alpha-1)/x_t) (x/x_t)**-alpha Values below threshold will be discarded. If no threshold is specified the minimum sample value will be used.

Parameters:

• distr ({'exponential', 'rayleigh', 'power'}) – Name of distribution
• vals (sequence of floats) – Values to fit
• thresh (float) – Threshold to apply before fitting; if None, use min(vals)

Returns:

• alpha (float) – Fitted value
• sigma_alpha (float) – Standard error in fitted value

pycbc.events.trigger_fits.fit_fn(distr, xvals, alpha, thresh)

The fitted function normalized to 1 above threshold

To normalize to a given total count multiply by the count.

Parameters:

• xvals (sequence of floats) – Values where the function is to be evaluated
• alpha (float) – The fitted parameter
• thresh (float) – Threshold value applied to fitted values

Returns:

fit – Fitted function at the requested xvals

Return type:

array of floats

pycbc.events.trigger_fits.tail_threshold(vals, N=1000)

Determine a threshold above which there are N louder values

pycbc.events.trigger_fits.which_bin(par, minpar, maxpar, nbins, log=False)

Helper function

Returns bin index where a parameter value belongs (from 0 through nbins-1) when dividing the range between minpar and maxpar equally into bins.

Parameters:

• par (float) – Parameter value being binned
• minpar (float) – Minimum parameter value
• maxpar (float) – Maximum parameter value
• nbins (int) – Number of bins to use
• log (boolean) – If True, use log spaced bins

Returns:

binind – Bin index

Return type:

int

pycbc.events.triggers module

This modules contains functions for reading single and coincident triggers from the command line.

pycbc.events.triggers.bank_bins_from_cli(opts)

Parses the CLI options related to binning templates in the bank.

Parameters:

• opts (object) – Result of parsing the CLI with OptionParser.
• Results –
• ------- –
• bins_idx (dict) – A dict with bin names as key and an array of their indices as value.
• bank (dict) – A dict of the datasets from the bank file.

pycbc.events.triggers.get_found_param(injfile, bankfile, trigfile, param, ifo, args=None)

Translates some popular trigger parameters into functions that calculate them from an hdf found injection file

Parameters:

• injfile (hdf5 File object) – Injection file of format known to ANitz (DOCUMENTME)
• bankfile (hdf5 File object or None) – Template bank file
• trigfile (hdf5 File object or None) – Single-detector trigger file
• param (string) – Parameter to be calculated for the recovered triggers
• ifo (string or None) – Standard ifo name, ex. ‘L1’
• args (Namespace object returned from ArgumentParser instance) – Calling code command line options, used for f_lower value

Returns:

[return value] – The calculated parameter values and a Boolean mask indicating which injections were found in the given ifo (if supplied)

Return type:

NumPy array of floats, array of boolean

pycbc.events.triggers.get_inj_param(injfile, param, ifo, args=None)

Translates some popular injection parameters into functions that calculate them from an hdf found injection file

Parameters:

• injfile (hdf5 File object) – Injection file of format known to ANitz (DOCUMENTME)
• param (string) – Parameter to be calculated for the injected signals
• ifo (string) – Standard detector name, ex. ‘L1’
• args (Namespace object returned from ArgumentParser instance) – Calling code command line options, used for f_lower value

Returns:

[return value] – The calculated parameter values

Return type:

NumPy array of floats

pycbc.events.triggers.get_mass_spin(bank, tid)

Helper function

Parameters:

• bank (h5py File object) – Bank parameter file
• tid (integer or array of int) – Indices of the entries to be returned

Returns:

m1, m2, s1z, s2z – Parameter values of the bank entries

Return type:

tuple of floats or arrays of floats

pycbc.events.triggers.get_param(par, args, m1, m2, s1z, s2z)

Helper function

Parameters:

• par (string) – Name of parameter to calculate
• args (Namespace object returned from ArgumentParser instance) – Calling code command line options, used for f_lower value
• m1 (float or array of floats) – First binary component mass (etc.)

Returns:

parvals – Calculated parameter values

Return type:

float or array of floats

pycbc.events.triggers.insert_bank_bins_option_group(parser)

Add options to the optparser object for selecting templates in bins.

Parameters:parser (object) – OptionParser instance.

pycbc.events.triggers.insert_loudest_triggers_option_group(parser, coinc_options=True)

Add options to the optparser object for selecting templates in bins.

Parameters:parser (object) – OptionParser instance.

pycbc.events.triggers.loudest_triggers_from_cli(opts, coinc_parameters=None, sngl_parameters=None, bank_parameters=None)

Parses the CLI options related to find the loudest coincident or single detector triggers.

Parameters:

• opts (object) – Result of parsing the CLI with OptionParser.
• coinc_parameters (list) – List of datasets in statmap file to retrieve.
• sngl_parameters (list) – List of datasets in single-detector trigger files to retrieve.
• bank_parameters (list) – List of datasets in template bank file to retrieve.
• Results –
• ------- –
• bin_names (dict) – A list of bin names.
• bin_results (dict) – A list of dict holding trigger data data.

pycbc.events.veto module

This module contains utilities to manipulate trigger lists based on segment.

pycbc.events.veto.get_segment_definer_comments(xml_file, include_version=True)

Returns a dict with the comment column as the value for each segment

pycbc.events.veto.indices_outside_segments(times, segment_files, ifo=None, segment_name=None)

Return the list of indices that are outside the segments in the list of segment files.

Parameters:

• times (numpy.ndarray of integer type) – Array of gps start times
• segment_files (string or list of strings) – A string or list of strings that contain the path to xml files that contain a segment table
• ifo (string, optional) – The ifo to retrieve segments for from the segment files
• segment_name (str, optional) – name of segment

Returns:

• indices (numpy.ndarray) – The array of index values outside the segments
• segmentlist – The segment list corresponding to the selected time.

pycbc.events.veto.indices_outside_times(times, start, end)

Return an index array into times that like outside the durations defined by start end arrays

Parameters:

• times (numpy.ndarray) – Array of times
• start (numpy.ndarray) – Array of duration start times
• end (numpy.ndarray) – Array of duration end times

Returns:

indices – Array of indices into times

Return type:

numpy.ndarray

pycbc.events.veto.indices_within_segments(times, segment_files, ifo=None, segment_name=None)

Return the list of indices that should be vetoed by the segments in the list of veto_files.

Parameters:

• times (numpy.ndarray of integer type) – Array of gps start times
• segment_files (string or list of strings) – A string or list of strings that contain the path to xml files that contain a segment table
• ifo (string, optional) – The ifo to retrieve segments for from the segment files
• segment_name (str, optional) – name of segment

Returns:

• indices (numpy.ndarray) – The array of index values within the segments
• segmentlist – The segment list corresponding to the selected time.

pycbc.events.veto.indices_within_times(times, start, end)

Return an index array into times that lie within the durations defined by start end arrays

Parameters:

• times (numpy.ndarray) – Array of times
• start (numpy.ndarray) – Array of duration start times
• end (numpy.ndarray) – Array of duration end times

Returns:

indices – Array of indices into times

Return type:

numpy.ndarray

pycbc.events.veto.segments_to_start_end(segs)

pycbc.events.veto.select_segments_by_definer(segment_file, segment_name=None, ifo=None)

Return the list of segments that match the segment name

Parameters:

• segment_file (str) – path to segment xml file
• segment_name (str) – Name of segment
• ifo (str, optional) –

Returns:

seg

Return type:

list of segments

pycbc.events.veto.start_end_from_segments(segment_file)

Return the start and end time arrays from a segment file.

Parameters:segment_file (xml segment file) – Returns:

• start (numpy.ndarray)
• end (numpy.ndarray)

pycbc.events.veto.start_end_to_segments(start, end)

Module contents

This packages contains modules for clustering events