# 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]
[-l CRITICAL|ERROR|WARNING|INFO|DEBUG|NOTSET]
[--cosmology {Planck18_arXiv_v2,Planck15,Planck13,WMAP9,WMAP7,WMAP5}]
--distribution
--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¶

--version

show program’s version number and exit

-l, --loglevel

Default: INFO

--cosmology

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

Cosmological model

Default: “Planck15”

--distribution

--reference-psd

PSD file

--f-low

Low frequency cutoff in Hz

Default: 25.0

--min-snr

Minimum decisive SNR of injections given the reference PSDs

Default: 4.0

--waveform

Waveform approximant

Default: “o2-uberbank”

--nsamples

Output this many injections

Default: 100000

-o, --output

Output file, optionally gzip-compressed

Default: -

-j, --jobs

Default: 1

## random number generator options¶

Options that affect the Numpy pseudo-random number genrator

--seed

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.

Parameters
snrslist

List of SNRs (floats).

Returns
decisive_snrfloat
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.

Parameters
cosmoastropy.cosmology.FLRW

The cosmological model.

psdslist

List of lal.REAL8FrequencySeries objects.

waveformstr

Waveform approximant name.

f_lowfloat

Low-frequency cutoff for template.

snrfloat

Target SNR.

paramslist

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

Returns
comoving_distancefloat

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.

Parameters
valuesnumpy.ndarray

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

Returns
maximanumpy.ndarray

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)$$.