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: pycbc.population.fgmc_functions.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: pycbc.population.fgmc_functions.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: pycbc.population.fgmc_functions.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: scipy.stats._distn_infrastructure.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: pycbc.population.fgmc_laguerre.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.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