Observing Scenarios Injection Tool (bayestar-inject)

Rough-cut injection tool.

The idea is to efficiently sample events, uniformly in “sensitive volume” (differential comoving volume divided by 1 + z), and from a distribution of masses and spins, such that later detection cuts will not reject an excessive number of events.

This occurs in two steps. First, we divide the intrinsic parameter space into a very coarse 10x10x10x10 grid and calculate the maximum horizon distance in each grid cell. Second, we directly sample injections jointly from the mass and spin distribution and a uniform and isotropic spatial distribution with a redshift cutoff that is piecewise constant in the masses and spins.

usage: bayestar-inject [-h] [--seed SEED] [--version]
                       [--cosmology {Planck18_arXiv_v2,Planck15,Planck13,WMAP9,WMAP7,WMAP5}]
                       --reference-psd PSD.xml[.gz] [--f-low F_LOW]
                       [--min-snr MIN_SNR] [--waveform WAVEFORM]
                       [--nsamples NSAMPLES] [-o INJ.xml[.gz]] [-j [JOBS]]

Named Arguments


show program’s version number and exit

-l, --loglevel

Default: INFO


Possible choices: Planck18_arXiv_v2, Planck15, Planck13, WMAP9, WMAP7, WMAP5

Cosmological model

Default: “Planck15”


Possible choices: bns_astro, bns_broad, nsbh_astro, nsbh_broad, bbh_astro, bbh_broad


PSD file


Low frequency cutoff in Hz

Default: 25.0


Minimum decisive SNR of injections given the reference PSDs

Default: 4.0


Waveform approximant

Default: “o2-uberbank”


Output this many injections

Default: 100000

-o, --output

Output file, optionally gzip-compressed

Default: -

-j, --jobs

Number of threads

Default: 1

random number generator options

Options that affect the Numpy pseudo-random number genrator


Pseudo-random number generator seed [default: initialized from /dev/urandom or clock]

Python helper functions

ligo.skymap.tool.bayestar_inject.get_decisive_snr(snrs)[source] [edit on github]

Return the SNR for the trigger that decides if an event is detectable.

If there are two or more detectors, then the decisive SNR is the SNR of the second loudest detector (since a coincidence of two or more events is required). If there is only one detector, then the decisive SNR is just the SNR of that detector. If there are no detectors, then 0 is returned.


List of SNRs (floats).

ligo.skymap.tool.bayestar_inject.z_at_snr(cosmo, psds, waveform, f_low, snr, mass1, mass2, spin1z, spin2z)[source] [edit on github]

Get redshift at which a waveform attains a given SNR.


The cosmological model.


List of lal.REAL8FrequencySeries objects.


Waveform approximant name.


Low-frequency cutoff for template.


Target SNR.


List of waveform parameters: mass1, mass2, spin1z, spin2z.


Comoving distance in Mpc.

ligo.skymap.tool.bayestar_inject.sensitive_volume(cosmo, z)[source] [edit on github]

Sensitive volume \(V(z)\) out to redshift \(z\).

Given a population of events that occur at a constant rate density \(R\) per unit comoving volume per unit proper time, the number of observed events out to a redshift \(N(z)\) over an observation time \(T\) is \(N(z) = R T V(z)\).

ligo.skymap.tool.bayestar_inject.sensitive_distance(cosmo, z)[source] [edit on github]

Sensitive distance as a function of redshift \(z\).

The sensitive distance is the distance \(d_s(z)\) defined such that \(V(z) = 4/3\pi {d_s(z)}^3\), where \(V(z)\) is the sensitive volume.

ligo.skymap.tool.bayestar_inject.cell_max(values)[source] [edit on github]

Find pairwise max of consecutive elements across all axes of an array.


An input array of \(n\) dimensions, \((m_0, m_1, \dots, m_{n-1})\).


An input array of \(n\) dimensions, each with a length 1 less than the input array, \((m_0 - 1, m_1 - 1, \dots, m_{n-1} - 1)\).