Design an Injection Population¶
Question: Which sources are recovered, and which are missed?
Prepare the inputs in Working with Signals. population.yaml places four
150-Hz signals at separated times with source amplitudes
1e-23, 3e-22, 6e-22 and 1e-21 in the same noise interval.
The weak source lets you inspect missed-event accounting alongside loud
recoveries; determine the actual recovered set from the output.
Run and match to truth¶
pycwb run tutorial-work/population.yaml \
--work-dir tutorial-work/runs/population
pycwb simulation-summary --work-dir tutorial-work/runs/population
pycwb match-simulations tutorial-work/runs/population/catalog/catalog.parquet \
tutorial-work/runs/population/catalog/simulations.parquet \
--how right --output tutorial-work/matched_population.parquet
import pandas as pd
truth = pd.read_parquet("tutorial-work/runs/population/catalog/simulations.parquet")
matched = pd.read_parquet("tutorial-work/matched_population.parquet")
print(truth.columns.tolist())
print(truth)
print(matched.columns.tolist())
print(matched[["sim_sim_idx", "sim_hrss", "id", "rho"]])
print("Unmatched sources:", matched.loc[matched["id"].isna(), "sim_sim_idx"].tolist())
A right match retains all scheduled simulations, including those without a trigger. The matcher resolves competing candidates into unique associations. See Match triggers to simulations for the output columns and join choices, and Detection Efficiency for eligibility and recovery rules.
In this example, the right match retained all four sources: three had a
recovered trigger and the weakest had an empty id.
Change one population choice¶
Copy the YAML into a new input and change one dimension: amplitude, frequency, sky position or noise seed. Use a fresh output directory. Four signals are enough to inspect the workflow but not to fit a reliable efficiency curve. Repeat across independent trials before following Run Ranking and Efficiency on a Study with your own study catalogs.
For larger populations, use parameters_from_python with explicit
sky_distribution and time_distribution settings. The scheduling
reference in Injection Infrastructure covers rate/Poisson timing,
repeated trials, real-data injection and supported sky distributions.
The examples/multiple_injection directory retains the earlier parameter-list
example.
Amplitude and time support¶
Fixed hrss controls source waveform amplitude according to the generator’s
convention. CBC distance is a waveform-model parameter. target_snr
requests normalization against detector noise; these are different experiments.
When switching the population to target SNR, remove conflicting amplitude
normalization choices and follow Step by Step Injection Search for the supported
resampling convention. Keep target-SNR and fixed-hrss sources in separate
trials when using the cWB-compatible path.
t_start and t_end bound the waveform relative to its reference epoch.
Do not shorten them to force a long signal into a job. As a boundary exercise,
move one signal close to a segment edge and inspect its simulation-summary
eligibility and recovered waveform. analyze_injection_only is a simulation
shortcut, not a way to estimate unbiased background exposure.
Waveform families and stored signals¶
Use examples/sine_gaussian_injection and examples/white_noise_burst_injection
for burst families, and the CBC examples for parameterized binary waveforms.
Injections with Customized Waveform Generation shows the generator contract and how to use
stored detector strain. Adapt a Search to Signal Morphology explains which search
settings must be revisited when signal duration or bandwidth changes.
Result to keep: a table of scheduled sources, eligibility, recovery and selected statistics, including every missed source.