pycbc.population package

Submodules

pycbc.population.fgmc_functions module

A set of helper functions for evaluating event rates, densities etc.

See https://dcc.ligo.org/LIGO-T2100060/public for technical explanations

class pycbc.population.fgmc_functions.BackgroundEventRate(args, coinc_times, coinc_types=None, bin_param='mchirp', bin_lo=None, bin_hi=None)

Bases: EventRate

add_background(full_file)

eval_pdf(chunk, ctime, ctype, statvals)

get_norms()

plot_bg()

class pycbc.population.fgmc_functions.EventRate(args, coinc_times, coinc_types=None, bin_param='mchirp', bin_lo=None, bin_hi=None)

Bases: object

add_bank(bank_file)

filter_templates()

calculate array of Booleans in template id order to filter events

get_ctypes(tdict)

get_livetimes(fi)

in_coinc_time_excl(f, cstring, test_times)

filter to all times where exactly the ifos in cstring are observing

make_bins(maxval, choice='bg')

moreifotimes(ctstring)

class pycbc.population.fgmc_functions.ForegroundEvents(args, coinc_times, coinc_types=None, bin_param='mchirp', bin_lo=None, bin_hi=None)

Bases: EventRate

add_zerolag(full_file)

get_bg_pdf(bg_rate)

get_sg_pdf(sg_rate)

class pycbc.population.fgmc_functions.SignalEventRate(args, coinc_times, coinc_types=None, bin_param='mchirp', bin_lo=None, bin_hi=None)

Bases: EventRate

add_injections(inj_file, fg_file)

eval_pdf(chunk, ctime, ctype, statvals)

get_norms()

make_all_bins()

plot_inj()

pycbc.population.fgmc_functions.alltimes(ifos, mincount=1)

pycbc.population.fgmc_functions.filter_bin_lo_hi(values, lo, hi)

pycbc.population.fgmc_functions.filter_tmplt_mchirp(bankf, lo_mchirp, hi_mchirp)

pycbc.population.fgmc_functions.get_start_dur(path)

pycbc.population.fgmc_functions.ifos_from_combo(ct)

pycbc.population.fgmc_functions.in_coinc_time_incl(f, cstring, test_times)

filter to all times where coincs of type given by cstring exist

pycbc.population.fgmc_functions.log_rho_bg(trigs, counts, bins)

trigs: zerolag event statistic values counts: background histogram bins: bin edges of the background histogram

Returns: log of background PDF at the zerolag statistic values, fractional uncertainty due to Poisson count (set to 100% for empty bins)

pycbc.population.fgmc_functions.log_rho_fg(trigs, injstats, bins)

trigs: zerolag event statistic values injstats: injection event statistic values bins: histogram bins

Returns: log of signal PDF at the zerolag statistic values, fractional uncertainty from Poisson count

pycbc.population.fgmc_functions.log_rho_fg_analytic(trigs, rhomin)

pycbc.population.fgmc_functions.read_full_data(fullf, rhomin, tmplt_filter=None)

Read the zero- and time-lagged triggers identified by a specific set of templates.

Parameters:

• fullf – File that stores zerolag and slide triggers

• bankf – File with template mass/spin information

• rhomin (float) – Ranking statistic threshold

• tmplt_filter (array of Booleans) – Filter over the array of templates stored in bankf

Returns:

containing foreground triggers and background information

Return type:

dictionary

pycbc.population.fgmc_functions.read_full_data_mchirp(fullf, bankf, rhomin, mc_lo, mc_hi)

pycbc.population.fgmc_functions.type_in_time(ct, cty)

pycbc.population.fgmc_laguerre module

Based ultimately on code used for O1 rate calculations, see https://git.ligo.org/RatesAndPopulations/lvc-rates-and-pop/-/blob/master/bin/O1_scripts/lvc_rates_calc_posterior and technical documentation at https://dcc.ligo.org/LIGO-T1700029/public

class pycbc.population.fgmc_laguerre.augmented_rv_continuous(unit='dimensionless', texunit='\\mbox{dimensionless}', texsymb='x', **kwargs)

Bases: rv_continuous

hpd_interval(alpha)

Confidence interval of highest probability density.

Parameters:

alpha (array_like of float) – Probability that an rv will be drawn from the returned range. Each value should be in the range [0, 1].

Returns:

a, b – end-points of range that contain 100 * alpha % of the rv’s possible values.

Return type:

ndarray of float

class pycbc.population.fgmc_laguerre.count_posterior(logbf, laguerre_n, Lambda0, prior=-0.5, name='count posterior', unit='signals/experiment', texunit='\\mathrm{signals}/\\mathrm{experiment}', texsymb='\\Lambda_1')

Bases: augmented_rv_continuous

Count posterior distribution.

expect(func)

Calculate expected value of a function with respect to the

distribution.

The expected value of a function f(x) with respect to a distribution dist is defined as:

E[x] = Integral(f(x) * dist.pdf(x))

Parameters:

func (callable) – Function for which integral is calculated. Takes only one argument.

Returns:

expect – The calculated expected value.

Return type:

float

p_bg(logbf)

Calculate the false alarm probabilities of the events.

Parameters:

logbf (array_like) – Logs of foreground over background probability ratios of events.

pycbc.population.fgmc_plots module

pycbc.population.fgmc_plots.dist_summary(args, rv, plot_styles=('linear', 'loglog', 'semilogx'), plot_extensions=None, middle=None, credible_intervals=None)

pycbc.population.fgmc_plots.odds_summary(args, rankstats, ifars, p_b, ntop, times=None, mchirps=None, name='events', plot_extensions=None)

pycbc.population.fgmc_plots.plotdist(rv, plot_lim=None, middle=None, credible_intervals=None, style='linear')

pycbc.population.live_pastro module

pycbc.population.live_pastro.check_template_param_bin_data(spec_json)

Parameters:

spec_json (JSON dictionary-like object) – Result of parsing json file containing static data

Returns:

spec_json

Return type:

dictionary

pycbc.population.live_pastro.noise_density_from_far(far, exp_fac)

Exponential model of noise rate density per time per (reweighted) SNR b(rho) ~ k exp(-alpha * rho), where alpha is the ‘index’, yields the relation b(rho) = alpha * FAR(rho), where FAR is the integral of b(rho) from rho to infinity. E.g. fits to single-ifo noise typically yield alpha ~ 6

pycbc.population.live_pastro.read_template_bank_param(spec_d, bankf)

Parameters:

• spec_d (dictionary) – Prerequisite data for p astro calc

• bankf (string) – Path to HDF5 template bank file

Returns:

bank_data – Template counts binned over specified param

Return type:

dictionary

pycbc.population.live_pastro.signal_pdf_from_snr(netsnr, thresh)

FGMC approximate signal distribution ~ SNR ** -4

pycbc.population.live_pastro.signal_rate_rescale(horizons, ref_dhor)

Compute a factor proportional to the rate of signals with given network SNR to account for network sensitivity variation relative to a reference state

pycbc.population.live_pastro.signal_rate_trig_type(horizons, sens_ifos, trig_ifos)

Compute a factor accounting for the fraction of signals seen as a given trigger type

pycbc.population.live_pastro.template_param_bin_pa(padata, trdata, horizons)

Parameters:

• padata (PAstroData instance) – Static information on p astro calculation

• trdata (dictionary) – Trigger properties

• horizons (dictionary) – BNS horizon distances keyed on ifo

Returns:

p_astro, p_terr

Return type:

tuple of floats

pycbc.population.live_pastro.template_param_bin_types_farlim_pa(padata, trdata, horizons)

Parameters:

• padata (PAstroData instance) – Static information on p astro calculation

• trdata (dictionary) – Trigger properties

• horizons (dictionary) – BNS horizon distances keyed on ifo

Returns:

p_astro, p_terr

Return type:

tuple of floats

pycbc.population.live_pastro.template_param_bin_types_pa(padata, trdata, horizons)

Parameters:

• padata (PAstroData instance) – Static information on p astro calculation

• trdata (dictionary) – Trigger properties

• horizons (dictionary) – BNS horizon distances keyed on ifo

Returns:

p_astro, p_terr

Return type:

tuple of floats

pycbc.population.live_pastro_utils module

class pycbc.population.live_pastro_utils.PAstroData(specfile, bank)

Bases: object

Class for managing live p_astro calculation persistent info

apply_significance_limits(trigger_data)

If the network SNR and FAR indicate saturation of the FAR estimate, set them to the fixed values given in the specification.

do_pastro_calc(trigger_data, horizons)

No-op, or call the despatch dictionary to evaluate p_astro

pycbc.population.live_pastro_utils.insert_live_pastro_option_group(parser)

Add low-latency p astro options to the argparser object.

Parameters:

parser (object) – ArgumentParser instance.

Returns:

Argument group object

Return type:

live_pastro_group

pycbc.population.population_models module

This module provides functions for star formation rate models, time delay models, merger rate density, and population models of BBH/BNS/NSBH.

pycbc.population.population_models.average_time_between_signals(z_array, merger_rate)

This function calculates the average time interval

of a certain type of CBC source.

Parameters:

• z_array (numpy.array) – The array of redshift.

• merger_rate (scipy.interpolate.interp1d or function) – The coalescence rate. Provided by users or calculated by the coalescence_rate function.

Returns:

average_time – The average time interval (s).

Return type:

float

pycbc.population.population_models.coalescence_rate(rate_den, maxz=10.0, npoints=10000, z_array=None, **kwargs)

This function calculates the coalescence(merger) rate at the redshift z.

Parameters:

• rate_den (function or scipy.interpolate.interp1d) – The merger rate density as a function of redshift. In the unit of “Mpc^-3yr^-1”. Use merger_rate_density function to calculate.

• maxz (float) – The max redshift. The default value is 10.

• npoints (int) – The number of points used in the interpolation. The default value is 10000.

• z_array (numpy.array or list) – The redshift range. The default value is None.

• **kwargs – All other keyword args are passed to get_cosmology() to select a cosmology. If none provided, will use DEFAULT_COSMOLOGY.

Returns:

coalescence_rate_interp – The coalescence rate.

Return type:

scipy.interpolate.interp1d

Notes

Pease see Eq.(1) in <arXiv:2011.02717v3> for more details.

pycbc.population.population_models.diff_lookback_time(z, **kwargs)

The derivative of lookback time t(z)

with respect to redshit z.

Parameters:

z (float) – The redshift.

Returns:

• dt_dz (float) – The value of dt/dz at the redshift z.

• **kwargs – All other keyword args are passed to get_cosmology() to select a cosmology. If none provided, will use DEFAULT_COSMOLOGY.

Notes

Pease see Eq.(A3) in <arXiv:2011.02717v3> for more details.

pycbc.population.population_models.distance_from_rate(total_rate, merger_rate, maxz=10, npoints=10000, **kwargs)

Returns the luminosity distance from the given total rate value.

Parameters:

• total_rate (float) – The total rate.

• merger_rate (scipy.interpolate.interp1d or function) – The coalescence rate. Provided by users or calculated by the coalescence_rate function.

• maxz (float) – The max redshift in the interpolation, the default value is 10. Please use the same maxz as in merger_rate.

• npoints (int) – The number of points used in the interpolation, the default value is 10000.

• **kwargs – All other keyword args are passed to get_cosmology() to select a cosmology. If none provided, will use DEFAULT_COSMOLOGY.

Returns:

dl – The luminosity distance at the given total rate value. In the unit of “Mpc”.

Return type:

float

Notes

This can be used in a population-informed prior for redshift and luminosity distance of CBC sources. When this used in high redshift range, please first use the total_rate_upto_redshift function to plot the curve and find the point where the curve starts to stay almost horizontal, then set maxz to the corresponding value and change npoints to a reasonable value.

pycbc.population.population_models.merger_rate_density(sfr_func, td_model, rho_local, maxz=10.0, npoints=10000, z_array=None, **kwargs)

This function uses the symbolic integral to calculate

the merger rate density of CBC sources. This function converts the convolution of the star formation rate SFR(tau) and the time delay probability P(tau) on the time delay ‘tau’ into the convolution on the redshift ‘z’. This function relies on convolution_trans.

Parameters:

• sfr_func (function) – The star formation rate function used in the convolution.

• td_model (str) – The name of time delay model.

• rho_local (float) – The local merger rate of a certain type of CBC source. In the unit of “Mpc^-3yr^-1”.

• maxz (float) – The max redshift. The default value is 10.

• npoints (int) – The number of points used in the interpolation. The default value is 10000.

• z_array (numpy.array) – The array of redshift. The default value is None.

• **kwargs – All other keyword args are passed to get_cosmology() to select a cosmology. If none provided, will use DEFAULT_COSMOLOGY.

Returns:

rho_z – The merger rate density.

Return type:

scipy.interpolate.interp1d

Notes

Pease see Eq.(A1), Eq.(A2) in <arXiv:2011.02717v3> for more details.

pycbc.population.population_models.norm_redshift_distribution(z_array, merger_rate)

This function calculates the normalized redshift distribution

of a certain type of CBC source.

Parameters:

• z_array (numpy.array) – The array of redshift.

• merger_rate (scipy.interpolate.interp1d or function) – The coalescence rate. Provided by users or calculated by the coalescence_rate function.

Returns:

norm_coalescence_rate – The normalized redshift distribution.

Return type:

numpy.array

Notes

The can be used as a population-informed prior for redshift and luminosity distance of CBC sources.

pycbc.population.population_models.p_tau(tau, td_model='inverse')

The probability distribution of the time delay.

Parameters:

• tau (float) – The merger delay time from the formation of the binary system and the orbital decay timescale through gravitational wave radiation.

• td_model (str) – The time delay model.

Returns:

p_t – The probability at time delay tau.

Return type:

float

Notes

Pease see the Appendix in <arXiv:2011.02717v3> for more details.

pycbc.population.population_models.sfr_grb_2008(z)

The star formation rate (SFR) calibrated by high-z GRBs data.

Parameters:

z (float) – The redshift.

Returns:

rho_z – The SFR at redshift z, in unit of “Msolar/Mpc^3/yr”.

Return type:

float

Note

Please see Eq.(5) in <arXiv:0804.4008> for more details.

pycbc.population.population_models.sfr_madau_dickinson_2014(z)

The madau-dickinson 2014 star formation rate (SFR).

Parameters:

z (float) – The redshift.

Returns:

rho_z – The SFR at redshift z, in unit of “Msolar/Mpc^3/yr”.

Return type:

float

Notes

Pease see Eq.(15) in <arXiv:1403.0007> for more details.

pycbc.population.population_models.sfr_madau_fragos_2017(z, k_imf=0.66, mode='high')

The madau-fragos 2017 star formation rate (SFR),

which updates madau-dickinson 2014 SFR by better reproducing a number of recent 4 < z < 10 results.

Parameters:

• z (float) – The redshift.

• k_imf (float) – The correction factor KIMF adjusts the SFR for the assumed IMF, for the Salpeter IMF, k_imf=1.0, for the three component broken power-law Kroupa IMF, k_imf=0.66, here we choose Kroupa IMF as default.

• model (string) – The model of SFR, choose from ‘high’ and ‘low’. Default to ‘high’.

Returns:

rho_z – The SFR at redshift z, in unit of “Msolar/Mpc^3/yr”.

Return type:

float

Notes

Pease see <arXiv:1606.07887> and <arXiv:1706.07053> for more details.

pycbc.population.population_models.total_rate_upto_redshift(z, merger_rate)

Total rate of occurrences out to some redshift.

Parameters:

• z (int, float, tuple, numpy.ndarray or list) – The redshift.

• merger_rate (scipy.interpolate.interp1d or function) – The merger or coalescence rate. Function should take the redshift as a single argument. Provided by users or calculated by the coalescence_rate function.

Returns:

rate – The total rate of occurrences out to some redshift. In the unit of “yr^-1”.

Return type:

float or list

pycbc.population.rates_functions module

A set of helper functions for evaluating rates.

pycbc.population.rates_functions.draw_flat_samples(**kwargs)

Draw samples for uniform in mass

Parameters:

**kwargs (string) – Keyword arguments as model parameters and number of samples

Returns:

• array – The first mass

• array – The second mass

pycbc.population.rates_functions.draw_imf_samples(**kwargs)

Draw samples for power-law model

Parameters:

**kwargs (string) – Keyword arguments as model parameters and number of samples

Returns:

• array – The first mass

• array – The second mass

pycbc.population.rates_functions.draw_lnm_samples(**kwargs)

Draw samples for uniform-in-log model

Parameters:

**kwargs (string) – Keyword arguments as model parameters and number of samples

Returns:

• array – The first mass

• array – The second mass

pycbc.population.rates_functions.fgmc(log_fg_ratios, mu_log_vt, sigma_log_vt, Rf, maxfg)

Function to fit the likelihood Fixme

pycbc.population.rates_functions.fit(R)

Fit skew - lognormal to the rate samples achived from a prior analysis :param R: Rate samples :type R: array

Returns:

• ff[0] (float) – The skewness

• ff[1] (float) – The mean

• ff[2] (float) – The standard deviation

pycbc.population.rates_functions.log_rho_fgmc(t, injstats, bins)

pycbc.population.rates_functions.mchirp_sampler_flat(**kwargs)

Draw chirp mass samples for flat in mass model

Parameters:

**kwargs (string) – Keyword arguments as model parameters and number of samples

Returns:

mchirp-astro – The chirp mass samples for the population

Return type:

array

pycbc.population.rates_functions.mchirp_sampler_imf(**kwargs)

Draw chirp mass samples for power-law model

Parameters:

**kwargs (string) – Keyword arguments as model parameters and number of samples

Returns:

mchirp-astro – The chirp mass samples for the population

Return type:

array

pycbc.population.rates_functions.mchirp_sampler_lnm(**kwargs)

Draw chirp mass samples for uniform-in-log model

Parameters:

**kwargs (string) – Keyword arguments as model parameters and number of samples

Returns:

mchirp-astro – The chirp mass samples for the population

Return type:

array

pycbc.population.rates_functions.prob_flat(m1, m2, s1z, s2z, **kwargs)

Return probability density for uniform in component mass :param m1: Component masses 1 :type m1: array :param m2: Component masses 2 :type m2: array :param s1z: Aligned spin 1 (not in use currently) :type s1z: array :param s2z: Aligned spin 2 (not in use currently) :param **kwargs: Keyword arguments as model parameters :type **kwargs: string

Returns:

p_m1_m2 – the probability density for m1, m2 pair

Return type:

array

pycbc.population.rates_functions.prob_imf(m1, m2, s1z, s2z, **kwargs)

Return probability density for power-law :param m1: Component masses 1 :type m1: array :param m2: Component masses 2 :type m2: array :param s1z: Aligned spin 1(Not in use currently) :type s1z: array :param s2z: Aligned spin 2(Not in use currently) :param **kwargs: Keyword arguments as model parameters :type **kwargs: string

Returns:

p_m1_m2 – the probability density for m1, m2 pair

Return type:

array

pycbc.population.rates_functions.prob_lnm(m1, m2, s1z, s2z, **kwargs)

Return probability density for uniform in log :param m1: Component masses 1 :type m1: array :param m2: Component masses 2 :type m2: array :param s1z: Aligned spin 1(Not in use currently) :type s1z: array :param s2z: Aligned spin 2(Not in use currently) :param **kwargs: Keyword arguments as model parameters :type **kwargs: string

Returns:

p_m1_m2 – The probability density for m1, m2 pair

Return type:

array

pycbc.population.rates_functions.process_full_data(fname, rhomin, mass1, mass2, lo_mchirp, hi_mchirp)

Read the zero-lag and time-lag triggers identified by templates in a specified range of chirp mass.

Parameters:

• hdfile – File that stores all the triggers

• rhomin (float) – Minimum value of SNR threhold (will need including ifar)

• mass1 (array) – First mass of the waveform in the template bank

• mass2 (array) – Second mass of the waveform in the template bank

• lo_mchirp (float) – Minimum chirp mass for the template

• hi_mchirp (float) – Maximum chirp mass for the template

Returns:

containing foreground triggers and background information

Return type:

dictionary

pycbc.population.rates_functions.save_bkg_falloff(fname_statmap, fname_bank, path, rhomin, lo_mchirp, hi_mchirp)

Read the STATMAP files to derive snr falloff for the background events. Save the output to a txt file Bank file is also provided to restrict triggers to BBH templates.

Parameters:

• fname_statmap (string) – STATMAP file containing trigger information

• fname_bank (string) – File name of the template bank

• path (string) – Destination where txt file is saved

• rhomin (float) – Minimum value of SNR threhold (will need including ifar)

• lo_mchirp (float) – Minimum chirp mass for the template

• hi_mchirp (float) – Maximum chirp mass for template

pycbc.population.rates_functions.skew_lognormal_samples(alpha, mu, sigma, minrp, maxrp)

Returns a large number of Skew lognormal samples :param alpha: Skewness of the distribution :type alpha: float :param mu: Mean of the distribution :type mu: float :param sigma: Scale of the distribution :type sigma: float :param minrp: Minimum value for the samples :type minrp: float :param maxrp: Maximum value for the samples :type maxrp: float

Returns:

Rfs – Large number of samples (may need fixing)

Return type:

array

pycbc.population.scale_injections module

pycbc.population.scale_injections.astro_redshifts(min_z, max_z, nsamples)

Sample the redshifts for sources, with redshift

independent rate, using standard cosmology

Parameters:

• min_z (float) – Minimum redshift

• max_z (float) – Maximum redshift

• nsamples (int) – Number of samples

Returns:

z_astro – nsamples of redshift, between min_z, max_z, by standard cosmology

Return type:

array

pycbc.population.scale_injections.contracted_dVdc(z)

pycbc.population.scale_injections.dlum_to_z(dl)

Get the redshift for a luminosity distance

Parameters:

dl (array) – The array of luminosity distances

Returns:

The redshift values corresponding to the luminosity distances

Return type:

array

pycbc.population.scale_injections.estimate_vt(injections, mchirp_sampler, model_pdf, **kwargs)

Based on injection strategy and the desired astro model estimate the injected volume. Scale injections and estimate sensitive volume.

Parameters:

• injections (dictionary) – Dictionary obtained after reading injections from read_injections

• mchirp_sampler (function) – Sampler for producing chirp mass samples for the astro model.

• model_pdf (function) – The PDF for astro model in mass1-mass2-spin1z-spin2z space. This is easily extendible to include precession

• kwargs (key words) – Inputs for thresholds and astrophysical models

Returns:

injection_chunks – The input dictionary with VT and VT error included with the injections

Return type:

dictionary

pycbc.population.scale_injections.inj_distance_pdf(key, distance, low_dist, high_dist, mchirp=1)

Estimate the probability density of the injections for the distance distribution.

Parameters:

• key (string) – Injections strategy

• distance (array) – Array of distances

• low_dist (float) – Lower value of distance used in the injection strategy

• high_dist (float) – Higher value of distance used in the injection strategy

pycbc.population.scale_injections.inj_mass_pdf(key, mass1, mass2, lomass, himass, lomass_2=0, himass_2=0)

Estimate the probability density based on the injection strategy

Parameters:

• key (string) – Injection strategy

• mass1 (array) – First mass of the injections

• mass2 (array) – Second mass of the injections

• lomass (float) – Lower value of the mass distributions

• himass (float) – higher value of the mass distribution

Returns:

pdf – Probability density of the injections

Return type:

array

pycbc.population.scale_injections.inj_spin_pdf(key, high_spin, spinz)

Estimate the probability density of the

injections for the spin distribution.

Parameters:

• key (string) – Injections strategy

• high_spin (float) – Maximum spin used in the strategy

• spinz (array) – Spin of the injections (for one component)

pycbc.population.scale_injections.pdf_z_astro(z, V_min, V_max)

Get the probability density for the rate of events at a redshift assuming standard cosmology

pycbc.population.scale_injections.process_injections(hdffile)

Function to read in the injection file and extract the found injections and all injections

Parameters:

hdffile (hdf file) – File for which injections are to be processed

Returns:

data – Dictionary containing injection read from the input file

Return type:

dictionary

pycbc.population.scale_injections.read_injections(sim_files, m_dist, s_dist, d_dist)

Read all the injections from the files in the provided folder. The files must belong to individual set i.e. no files that combine all the injections in a run. Identify injection strategies and finds parameter boundaries. Collect injection according to GPS.

Parameters:

• sim_files (list) – List containign names of the simulation files

• m_dist (list) – The mass distribution used in the simulation runs

• s_dist (list) – The spin distribution used in the simulation runs

• d_dist (list) – The distance distribution used in the simulation runs

Returns:

injections – Contains the organized information about the injections

Return type:

dictionary

Module contents