spey.backends.default_pdf.third_moment.third_moment_expansion

spey.backends.default_pdf.third_moment.third_moment_expansion#

spey.backends.default_pdf.third_moment.third_moment_expansion(expectation_value: ndarray, covariance_matrix: ndarray, third_moment: ndarray | None = None, return_correlation_matrix: bool = False) → Tuple[source]#

Compute the \(A\), \(B\), \(C\) coefficients and optional modified correlation matrix for the third-moment expansion of the simplified likelihood.

Given the background expectation values \(m^{(1)}_i\), covariance matrix \(\Sigma_{ij}\), and diagonal third moments \(m^{(3)}_i\), the function implements eqs. 2.9–2.12 of [arXiv:1809.05548]:

\[\begin{split}C_i &= -\mathrm{sign}(m^{(3)}_i)\,\sqrt{2\,\Sigma_{ii}} \cos\!\left(\frac{4\pi}{3} + \frac{1}{3}\arctan\!\sqrt{\frac{8\,\Sigma_{ii}^3}{(m^{(3)}_i)^2} - 1} \right), \\[4pt] B_i &= \sqrt{\Sigma_{ii} - 2C_i^2}, \\[4pt] A_i &= m^{(1)}_i - C_i.\end{split}\]

When return_correlation_matrix=True, the modified inter-bin correlation matrix is also computed (eq. 2.12):

\[\rho_{ij} = \frac{1}{4C_i C_j} \left(\sqrt{(B_i B_j)^2 + 8\,C_i C_j\,\Sigma_{ij}} - B_i B_j\right).\]

A small regularisation \(\varepsilon = 10^{-5}\) is added to \(C_i\) in the denominator to avoid division by zero when \(C_i = 0\).

Attention

The expansion requires \(8\,\Sigma_{ii}^3 \geq (m^{(3)}_i)^2\) for every bin. Bins that violate this condition produce NaN values for \(C_i\), which are silently replaced by zero, effectively reverting to the standard simplified likelihood (\(\lambda_i = \mu n^s_i + n^b_i + B_i\,\theta_i\)) for those bins. A warning is emitted when this occurs.

Parameters:

  • expectation_value (np.ndarray) – Per-bin background expectation values \(\{m^{(1)}_i\}\) (shape \(N\)).

  • covariance_matrix (np.ndarray) – \(N \times N\) background covariance matrix \(\Sigma\).

  • third_moment (np.ndarray) – Diagonal elements of the third-moment tensor \(\{m^{(3)}_i\}\) (shape \(N\)).

  • return_correlation_matrix (bool, default False) – If True, also compute and return the modified correlation matrix \(\rho\).

Returns:

The triple \((A, B, C)\) (each of shape \(N\)), and additionally \(\rho\) (shape \(N \times N\)) when return_correlation_matrix=True.

Return type:

Tuple[np.ndarray, np.ndarray, np.ndarray] | Tuple[np.ndarray, np.ndarray, np.ndarray, np.ndarray]