update docstring

src/spey/hypothesis_testing/asymptotic_calculator.py

@@ -16,16 +16,33 @@ def compute_asymptotic_confidence_level(
     sqrt_qmuA: float, delta_test_statistic: float, test_stat: Text = "qtilde"
 ) -> Tuple[List[float], List[float]]:
     r"""
-    Compute confidence limits i.e. :math:`CL_{s+b}`, :math:`CL_b` and :math:`CL_s`
-
-    .. note::
-
-        see :func:`~spey.hypothesis_testing.test_statistics.compute_teststatistics` for
-        details regarding the arguments.
+    Compute p values i.e. :math:`p_{s+b}`, :math:`p_b` and :math:`p_s`
+        
+    .. math::
+    
+        p_{s+b}&=& \int_{-\infty}^{-\sqrt{q_{\mu,A}} - \Delta q_\mu} \mathcal{N}(x| 0, 1) dx \\
+        p_{b}&=& \int_{-\infty}^{-\Delta q_\mu} \mathcal{N}(x| 0, 1) dx \\
+        p_{s} &=& p_{s+b}/ p_{b}
+
+    where :math:`q_\mu` stands for the test statistic and A stands for Assimov.
+    
+    .. math::
+        
+        \Delta q_\mu = \begin{cases} 
+        \sqrt{q_{\mu}} - \sqrt{q_{\mu,A}}, &  \text{if}\ \sqrt{q_{\mu}} \leq \sqrt{q_{\mu,A}} \\
+        \frac{\sqrt{q_{\mu}} - \sqrt{q_{\mu,A}}}{2\ \sqrt{q_{\mu,A}}}, & \text{otherwise} 
+        \end{cases}
+
+    Note that the CDF has a cutoff at :math:`-\sqrt{q_{\mu,A}}`, hence if 
+    :math:`p_{s\ {\rm or}\ s+b} < -\sqrt{q_{\mu,A}}` p-value will not be computed.
+
+    .. seealso::
+    
+        eq. 66 of :xref:`1007.1727`
 
     Args:
         sqrt_qmuA (``float``): test statistic for Asimov data :math:`\sqrt{q_{\mu,A}}`.
-        delta_test_statistic (``float``): :math:`\Delta{\sqrt{q_{\mu}},\sqrt{q_{\mu,A}}}`
+        delta_test_statistic (``float``): :math:`\Delta q_\mu`
         test_stat (``Text``, default ``"qtilde"``): test statistics.
 
           * ``'qtilde'``: (default) performs the calculation using the alternative test statistic,
@@ -48,6 +65,12 @@ def compute_asymptotic_confidence_level(
     Returns:
         ``Tuple[List[float], List[float]]``:
         returns p-values and expected p-values.
+        
+    .. seealso::
+
+        :func:`~spey.hypothesis_testing.test_statistics.compute_teststatistics`, 
+        :func:`~spey.hypothesis_testing.utils.pvalues`,
+        :func:`~spey.hypothesis_testing.utils.expected_pvalues`
     """
     cutoff = -sqrt_qmuA  # use clipped normal -> normal will mean -np.inf
     # gives more stable result for cases that \hat\mu > \mu : see eq 14, 16 :xref:`1007.1727`