Likelihood¶
This guide describes pycWB’s likelihood framework—the mathematical core that assigns a ranking statistic to each candidate event. It covers the Dominant Polarization Frame, sky scan, SNR definitions, regularization, and the configurable parameters that control likelihood evaluation.
Why this matters¶
The likelihood is the mathematical core that separates signals from noise.
Most users only need to set netRHO, netCC, and healpix. The
other parameters (\(\delta\), cfg_gamma, precision) are for
expert tuning and can degrade performance if set incorrectly.
Overview¶
The pycWB likelihood pipeline follows the cWB 2G likelihood WP algorithm. For each supercluster (candidate event), the algorithm:
Projects the multi-detector time-frequency data onto the Dominant Polarization Frame (DPF) for each sky direction.
Scans the sky to find the best-fit direction.
Computes coherent statistics: SNR (\(\rho\)), network correlation (\(cc\)), null energy, and \(\chi^2\).
Applies regularization to handle degenerate configurations (e.g., 2-detector networks).
Populates per-pixel detection statistics and extracts waveform reconstructions.
The production code lives in pycwb.modules.likelihoodWP, with the
sky scan in sky_scan and statistics
computation in sky_statistics.
In the cWB-2G stage flow, likelihood reads each surviving supercluster, loads
time-delay amplitudes for its pixels, evaluates likelihood2G or
likelihoodWP, reconstructs event parameters, and optionally produces a
Coherent Event Display. pycWB performs the same algorithmic role but writes
structured trigger data, reconstructed waveforms, plots, and postproduction
inputs through the Python workflow.
Dominant Polarization Frame (DPF)¶
The DPF formalism determines the optimal polarization basis for each sky direction. For a given sky direction, the antenna response functions \(F_+\) and \(F_\times\) determine how each detector responds to the two gravitational-wave polarizations.
Noise-weighted antenna patterns (per sky direction, per pixel, per detector \(i\)):
where \(\sigma_i\) is the noise RMS of detector \(i\) at the pixel’s
time-frequency location (from the conditioning nRMS maps), so that
\(\sum_i w_i^2 = 1\).
Optimal polarization angle \(\psi\):
Effective plus-polarization response:
After the rotation by \(\psi\), the cross vector is made orthogonal to the
plus vector, \(F \leftarrow F - f\,(f\cdot F)/|f_+|^2\), and
\(|f_\times|^2 = F\cdot F\). In the DPF the \(+\) response is maximal
and the \(\times\) response is orthogonal to it. Both components enter the
signal reconstruction; the \(\times\) component is regulated (see
REG[1] below and the sky-scan projection).
Network index. Per pixel \(\nu = \sum_k f_k^4 / |f_+|^4\), and per sky direction
DPF regulator REG[1]
(pycwb.modules.likelihoodWP.dpf.compute_dpf_regulator()). The
threshold is
(\(\gamma\) = cfg_gamma; its sign does not enter here), and the
regulator is a single number per cluster:
where \(N_{sky}\) is the number of unmasked sky directions and
\(n_{valid}\) is the number of those with \(NI > \gamma_{reg}\).
REG[1] grows when few directions have appreciable \(\times\)
sensitivity, and it suppresses the \(\times\) component of the
reconstructed signal in every direction. It does not act as a per-direction
sky penalty.
Sky Scan¶
The sky scan (pycwb.modules.likelihoodWP.sky_scan.scan_sky())
is the computational core of the likelihood pipeline. It visits every
unmasked HEALPix direction (see sky_mask). Directions whose integer
detector delays are identical are grouped; the Numba prange runs over
these groups, and the delayed-data load is shared within a group. For each
direction:
Apply time delay: each pixel carries, per detector and per quadrature (0° and 90°), a vector of \(2K+1\) time-delayed WDM amplitudes \(TD_i\). For sky direction \(l\), detector \(i\) uses
\[x_i = TD_i\left[K + ml[i, l]\right], \qquad ml[i, l] = \mathrm{rint}\left(\frac{(\vec R_i - \vec R_{ref})\cdot\hat n_l}{c}\, \mathrm{TDRate}\right) \in [-K, K]\]with \(\mathrm{TDRate} = \texttt{rateANA} \cdot \texttt{upTDF}\) and \(K = \max(\texttt{TDSize}\cdot\texttt{upTDF},\ \lfloor \tau_{max}\, \mathrm{TDRate} \rfloor + 1)\), where \(\tau_{max}\) is the maximum network light-travel delay. Delays are relative to
refIFO.Select and project onto the DPF (
pycwb.modules.likelihoodWP.sky_kernels.project_signal_packet()). Only pixels with network energy \(E_p = \sum_i (x_{i,0}^2 + x_{i,90}^2) > E_{th}\) are used.With \(a_+ = |x\cdot f|^2\) and \(a_\times = |x\cdot F|^2\) (summed over both quadratures), the regulated amplitudes are
\[\begin{split}u &= \frac{x\cdot f}{\max\left(|f_+|^2,\ \mathrm{REG}[0]\sqrt{\nu\,a_+/E_p}\right)} \\[4pt] v &= \frac{x\cdot F}{\max\left(|f_\times|^2,\ R\,\sqrt{a_\times}/|u|\right)}, \qquad R = 0.1 + \frac{\mathrm{REG}[1]}{E_p}\end{split}\]and the reconstructed detector response is \(s_i = f_i\,u + F_i\,v\).
Orthogonalize the 0° and 90° quadrature signal vectors of each pixel (a per-pixel rotation between the two quadratures).
Compute coherent statistics. Per pixel: signal energy \(\ell = |s|^2\), residual \(r = |s - x|^2\), a Gaussian-noise term \(g\), and the coherent energy (signal energy with the single-detector terms removed, per quadrature)
\[e_c = |s|^2 \left(1 - \frac{\sum_i (s_i x_i)^2}{\left(\sum_i s_i x_i\right)^2}\right)\]Summing over pixels gives \(E_c = \sum e_c\), the null energy \(N = \tfrac12\sum (r + g)\), the data energy \(E = \tfrac12 \sum E_p\), and the likelihood \(L = E - N\). With \(M\) the number of selected pixels:
\[\begin{split}C_r &= \frac{2\sum \ell\, c}{\sum \ell}, \qquad c = \frac{e_c}{2|e_c| + r + g} \\[4pt] ch &= \frac{N}{n_{IFO} M + \sqrt{M}}, \qquad C_o = \frac{E_c}{E_c + N \max(ch, 1) - M (n_{IFO} - 1)}\end{split}\]Directions with reduced correlation \(C_r <\)
netCCare skipped.
The selected direction \(l_{max}\) maximizes the sky statistic \(AA = L \cdot C_o\) over the unmasked directions (on ties the last index wins). A cluster whose maximum \(AA\) is not positive is rejected.
SNR Definitions¶
At \(l_{max}\),
compute_statistics_at_sky_position()
rebuilds the data and signal packets with cross-talk corrections and computes:
\(E_c\): core coherent energy — the sum of \(e_c\) over core pixels, divided by \(\mathrm{norm} = \max\left(1, (E_o - E_h)/E_m\right)\), where \(E_o\) is the total data energy, \(E_h\) the satellite (halo) energy and \(E_m\) the cross-talk-corrected packet data energy.
\(R_c\): the fraction of coherent energy kept after the per-pixel Gaussian-noise correction, \(R_c = \sum e_c / \max(1, g/2) \,/\, \sum e_c\).
\(\chi^2\) (see below).
pycWB supports two SNR definitions, selectable via xgb_rho_mode:
cWB 2G SNR (\(\rho\), xgb_rho_mode: false):
The reported rho[0] is \(\rho / \sqrt{\max(\chi^2_w, 1)}\), using the
waveform-domain \(\chi^2_w\) defined below.
XGBoost \(\rho_0\) (xgb_rho_mode: true, the cWB XGB.rho0
convention):
It is reported unchanged as rho[0]; rho[1] then holds the 2G value
\(\sqrt{E_c R_c/2}\,/\sqrt{\max(\chi^2_w, 1)}\). Setting netRHO < 0 is
the deprecated way to enable this mode.
Selection cuts
(get_likelihood_rejection_reason()).
A cluster is rejected if \(L_m \le 0\), \(E_o - E_h \le 0\),
\(N_{eff} < 1\), or
2G: \(E_c R_c / \max(\chi^2, 1) < 2\,\texttt{netRHO}^2\)
XGB: \(\rho_0 < |\texttt{netRHO}|\)
where \(L_m = E_m - N_p - G_n\) is the packet signal energy.
Network Correlation (\(cc\)):
The fraction of coherent energy relative to coherent plus null energy:
where \(D_c\) is the signal-packet coherent energy minus \(E_c\)
(same normalization) and \(N_w\) is the waveform-domain null energy.
netcc[1] uses the same expression with \((D_c + N_w + G_n)\)
multiplied by \(1 + 2(\chi^2_w - 1)(1 - R_c)\) when \(\chi^2_w > 1\).
The netCC threshold (default 0.5) is applied during the sky scan to
\(C_r\), not to the final netcc.
Chi-squared (\(\chi^2\)):
where \(N_p\) is the cross-talk-corrected null packet energy, \(G_n\)
is the Gaussian-noise correction, \(N_{eff}\) is the effective number of
pixels per detector (minus one), and \(n_{IFO}\) is the number of
interferometers. This pixel-domain \(\chi^2\) is used for \(\rho_0\)
and for the selection cut. The waveform-domain
\(\chi^2_w = (N_w + G_n)/(N_{eff}\, n_{IFO})\) is used for the reported
2G rho. The reported penalty is \((N_w + G_n)\) divided by
\(n_{IFO} N_{eff}\) (by \(n_{IFO}\) times the number of core pixels
when pattern = 0). \(\chi^2 \sim 1\) for well-modeled signals and
\(\chi^2 > 1\) for glitches or poorly modeled events.
Regularization¶
\(\delta\) Regulator (Amplitude)¶
Prevents degenerate sky locations in 2-detector networks where the polarization angle is unconstrained:
If \(\delta = 0\), it is stored as \(0.00001\) to avoid a truly degenerate regulator. The amplitude regularization term is:
It enters the denominator of the \(+\) projection
(see the sky scan); larger \(|\delta|\)
regularizes more strongly, saturating at \(\sqrt 2\) for
\(|\delta| \ge 1\). The sign of \(\delta\) does not change
REG[0]: \(\delta < 0\) only makes the sky-localization probability use
\(L\) instead of \(L \cdot C_o\); the selected direction is unchanged.
cfg_gamma Regulator (Sky Location):
Regulates the \(\times\) component through REG[1] (see the DPF
regulator above), via the threshold \(\gamma_{reg} = \tfrac23\gamma^2\).
\(\gamma = 0\) effectively disables it (REG[1] \(\approx 0\) when
every direction has \(NI > 0\)). \(\gamma < 0\) additionally applies
an antenna-pattern prior to the sky-localization probability. Range
\([-1, 1]\), default 0.5.
Detection Statistics¶
After the selection cuts, detection statistics are populated per pixel and per
cluster via
pycwb.modules.likelihoodWP.detection_statistics.populate_detection_statistics():
Core flags: pixels whose network energy exceeds \(E_{th} = 2 A_{core}^2 n_{IFO}\) and that are accepted by the projection at \(l_{max}\)
Per-pixel arrays: \(+\) and \(\times\) quadrature energies, cross-talk-corrected likelihood and null, and the data and signal packet amplitudes
Subnetwork statistic: with \(S_i\) the per-detector signal SNR,
\[E_0 = \sum_i S_i - \max_i S_i, \qquad E_{sub} = E_0 \left(1 + 2 R_c \frac{E_0}{\max_i S_i}\right)\]and the stored statistic is
\[\texttt{netcc[2]} = \frac{E_{sub}}{E_{sub} + N_{max}}, \qquad N_{max} = G_n + N_p - N_{eff}(n_{IFO} - 1)\]Multi-resolution analysis (MRA) waveform: whitened and strain-unit detector waveforms are synthesized from the packets to obtain the waveform-domain signal, data and null energies per detector, the time/frequency centroids, and the physical signal energy used for \(h_{rss}\)
The MRA/XTalk catalog used here is not the WDM transform itself. WDM defines the time-frequency basis; the catalog stores sparse overlaps between pixels at different WDM resolutions and quadratures. The likelihood/reconstruction path uses those overlaps to remove duplicated support between resolutions before synthesizing the final detector waveforms.
Chirp Mass: the chirp mass
is estimated from the time-frequency track for eligible MRA searches:
optim is false and cfg_search is one of i e c r p b l s g.
Original-2G rho uses
pycwb.modules.likelihoodWP.chirp_hough.update_chirp_mass_statistics(),
including fitted mass, merger time, uncertainties and morphology. XGB rho uses
pycwb.modules.likelihoodWP.chirp_micropixel.estimate_chirp() when
Search is CBC, BBH or IMBHB. Ineligible searches reset chirp
metadata. Both estimators use the run seed; no additional estimator switch is
needed. Original-2G pattern zero preserves unscaled rho; other patterns use
\(\texttt{rho[1]} = \texttt{rho[0]}\cdot\epsilon_{chirp}\sqrt{E_{frac}}\).
See Native calculation conventions.
Sky localization
(populate_sky_localization()):
the sky probability over directions with \(S_l > 0\) is
where \(S\) is the \(L \cdot C_o\) sky map (\(L\) when
\(\delta < 0\)) and \(\sigma\) is set by the waveform normalization,
\(R_c\), the number of core pixels and \(ch\) at \(l_{max}\).
When cfg_gamma \(< 0\), \(p_l\) is multiplied by
\((A_l / A_{max})^4\), where \(A\) is the energy-weighted antenna
sensitivity \(\sqrt{|f_+|^2 + |f_\times|^2}\). The square roots of the
10 %–90 % credible-region areas are stored as the error regions.
Big Cluster Optimization¶
When a supercluster contains a large number of pixels, the full-resolution sky
scan becomes expensive. The precision parameter enables a coarse-grid
scan:
If \(\text{csize} > 0\), \(n_{pixels} > nRES \times \text{csize}\)
(counted after the BATCH pixel limit), and coarse-grid sky arrays were
passed to
prepare_likelihood_inputs()
(ml_big, FP_big, FX_big and big_cluster_healpix_order), the
whole sky scan runs on that coarser HEALPix grid instead of the full grid.
There is no refinement pass. The native job-segment workflow does not
currently build these coarse arrays, so production runs always scan the
full-resolution grid. precision defaults to 0 (disabled).
Config.get_precision(csize, order) returns
\(\text{csize} + 65536 \cdot \text{order}\), but likelihoodWP does not
decode the order part.
Usage Guidance¶
For standard users¶
The three parameters you should set:
netRHO: coherent SNR threshold. Lower = more triggers, more background. Typical range: 3.5–5.0 for bursts.netCC: network correlation threshold, applied to the reduced correlation \(C_r\) of each sky direction during the scan. Lower = more triggers, more glitches. Typical: 0.4–0.6.healpix: sky resolution. Higher = better localization but slower. Typical: 6–8.
Everything else should be left at defaults unless you have a specific reason to change them.
For advanced users¶
Tune these only with caution—they can degrade performance if set incorrectly:
delta: 2-detector sky regulator. \(|\delta|\) setsREG[0]; larger \(|\delta|\) gives stronger regularization of the \(+\) projection, saturating at \(|\delta| = 1\). A negative value also switches the sky-localization statistic from \(L \cdot C_o\) to \(L\). Default 0.5.cfg_gamma: sets \(\gamma_{reg} = \tfrac23\gamma^2\) forREG[1], which suppresses the \(\times\) component when few sky directions have network index above \(\gamma_{reg}\). A negative value also applies an antenna-pattern prior to the sky-localization probability.precision: big-cluster coarse-grid scan (csize = |precision| % 65536). It only takes effect when coarse-grid sky arrays are supplied, which the native workflow does not currently do.xgb_rho_mode: use \(\rho_0\) (cWB XGB.rho0 convention) instead of the 2G \(\rho\); the SNR cut becomes \(\rho_0 \ge |\texttt{netRHO}|\). Set totruefor XGBoost-ranked searches. It replaces the deprecatednetRHO < 0convention.Search:CBC/BBH/IMBHBis one of the conditions for the micropixel chirp-mass estimate (together withxgb_rho_mode,optim: falseandcfg_search).
Developer notes¶
Implementation detail
The likelihood pipeline is the most computationally intensive part of pycWB. Key implementation details:
The sky scan is a Numba
@njit(parallel=True)kernel.prangeruns over groups of sky directions that share the same integer delay tuple; theexecution_profileoptionsky_delay_reuse: falseuses one direction per group.DPF projection and coherent statistics are recomputed for every direction from the delay indices
mland the antenna patternsFP/FX, which are built once per job segment.JAX device buffers must be explicitly freed after each lag to prevent memory leaks—this is a known pitfall.
Big-cluster mode (
bBB) replaces the full sky grid with a coarse grid for the whole scan; there is no refinement step, and it is inactive unless coarse-grid arrays are passed toprepare_likelihood_inputs.
Config Quick Reference¶
Parameter |
Default |
Description |
|---|---|---|
|
\(\sqrt{2}\) |
Core pixel threshold; pixel network energy must exceed \(2 A_{core}^2 n_{IFO}\) |
|
4.0 |
Coherent network SNR threshold |
|
0.5 |
Network correlation threshold (applied to \(C_r\) in the sky scan) |
|
0.5 |
2-detector sky location regulator \(\in [-1, 1]\); \(\mathrm{REG}[0] = \min(|\delta|,1)\sqrt2\); \(\delta < 0\) uses \(L\) for the sky probability |
|
0.5 |
\(\times\)-component regulator threshold \(\gamma_{reg} = \tfrac23\gamma^2\), \(\gamma \in [-1, 1]\); \(\gamma < 0\) adds an antenna prior to the sky probability |
|
false |
Use \(\rho_0 = \sqrt{E_c / (1 + \chi^2(\max(1,\chi^2) - 1))}\) instead of \(\rho = \sqrt{E_c R_c / 2}\) |
|
7 |
Sky map HEALPix resolution (\(12 \times 4^7\) pixels) |
|
4 |
Upsample factor for the time-delay filter rate:
|
|
12 |
Time-delay filter half-size in analysis-rate samples (max 20); extended if needed to cover the maximum network delay |
|
|
|
|
false |
cWB optimal-resolution switch; in likelihoodWP it only disables the
native chirp estimator and controls whether the event |
|
0 (disabled) |
Big-cluster coarse-grid scan: |
|
(none) |
Restrict sky scan region (see Targeted Search) |
Likelihood Pipeline Flow¶
prepare_likelihood_inputs() ← once per job segment: delays ml,
│ FP/FX, thresholds, sky mask
▼
per lag: coherence → supercluster → fragment_cluster.clusters
│
└── for each cluster with cluster_status <= 0:
evaluate_cluster_likelihood()
├── select_likelihood_pixels() ← keep loudest BATCH pixels
├── compute_dpf_regulator() ← REG[1] from network index
├── scan_sky() ← Numba scan over delay groups
│ ├── time-delay lookup (ml)
│ ├── DPF + regulated projection
│ └── netCC gate on C_r, AA = L·C_o → l_max
├── compute_statistics_at_sky_position() ← Ec, Rc, χ², ρ at l_max
├── get_likelihood_rejection_reason() ← Lm, Eo−Eh, ρ vs netRHO, N_eff cuts
├── populate_detection_statistics() ← per-pixel stats, MRA waveform
│ energies, netcc, rho
├── chirp update ← chirp_hough / chirp_micropixel
└── populate_sky_localization() ← sky probability, error regions
│
▼
workflow output: Event.output_py() → save_trigger() → Catalog.add_triggers()
evaluate_fragment_clusters()
is a convenience wrapper for interactive use: it calls
prepare_likelihood_inputs itself and then
evaluate_cluster_likelihood()
for every surviving cluster of every lag.
This is the Python workflow analogue of the cWB-2G cluster loop:
read surviving supercluster
│
├── attach time-delay amplitudes to pixels
├── run coherent likelihood / sky scan
├── reconstruct waveform and event statistics
└── write trigger and postproduction inputs
Inspect reconstructed candidates¶
Use the catalog’s ranking, correlation and sky quantities together with the reconstructed waveforms to understand which candidates passed the configured cuts.
To study a regulator or search-mode change, compare the same background and injection population under both settings. Inspect which candidates pass the cuts, how their sky estimates change and which signals are recovered. See Compare Runs with a Controlled Change for a worked comparison.
See also: Clustering Algorithm · Pipeline Lifecycle · Background Estimation
Next: Event Output — what the search writes for each trigger