Repository: scikit-hep/pyhf

Issue:
Harmonize docstring for test_stat between AsymptoticCalculator and ToyCalculator
# Description

In `v0.6.0` docs, the `AsymptoticCalculator` API has a [nicely formatted docstring for the `test_stat` arg](https://pyhf.readthedocs.io/en/v0.6.0/_generated/pyhf.infer.calculators.AsymptoticCalculator.html)

https://github.com/scikit-hep/pyhf/blob/8de7566a2b6dc4a5278e0b0da9c0a45a2e5a752d/src/pyhf/infer/calculators.py#L199-L208

but the [`ToyCalculator`](https://pyhf.readthedocs.io/en/v0.6.0/_generated/pyhf.infer.calculators.ToyCalculator.html) API didn't have these changes applied to them (seems @matthewfeickert forgot to propagate these in PR #993)

https://github.com/scikit-hep/pyhf/blob/8de7566a2b6dc4a5278e0b0da9c0a45a2e5a752d/src/pyhf/infer/calculators.py#L625-L632

The `ToyCalculator` docstring should be updated to match.


Discussion:
Similarly, need to update the warning for `qmu` to be using `qmu_tilde` with the more appropriate suggestion.
@matthewfeickert can I take this up? @kratsg could you please elaborate a bit more on the warning updates?
@matthewfeickert @kratsg not to disturb you again, but any updates on this?
The warning updates were already done. As for documentation, why not just submit the PR? But unless you know the statistics content, we'd recommend not just rewriting without knowing what the content itself is.
> But unless you know the statistics content, we'd recommend not just rewriting without knowing what the content itself is.

Yeah, I was envisioning a small rewrite of this when I opened the Issue. My advice would be to only work on a PR for this if you feel comfortable with the frequentist statistics being discussed, else we'll probably have to request multiple revisions.
Oh oh, my bad, I thought this required only formatting of the documentation. Thanks for letting me know!

Resolving patch:
diff --git a/src/pyhf/infer/calculators.py b/src/pyhf/infer/calculators.py
--- a/src/pyhf/infer/calculators.py
+++ b/src/pyhf/infer/calculators.py
@@ -688,12 +688,14 @@ def __init__(
                 value during minimization.
             test_stat (:obj:`str`): The test statistic to use as a numerical summary of the
               data: ``'qtilde'``, ``'q'``, or ``'q0'``.
-              ``'qtilde'`` (default) performs the calculation using the alternative test statistic,
-              :math:`\tilde{q}_{\mu}`, as defined under the Wald approximation in Equation (62)
-              of :xref:`arXiv:1007.1727` (:func:`~pyhf.infer.test_statistics.qmu_tilde`), ``'q'``
-              performs the calculation using the test statistic :math:`q_{\mu}`
-              (:func:`~pyhf.infer.test_statistics.qmu`), and ``'q0'`` performs the calculation using
-              the discovery test statistic :math:`q_{0}` (:func:`~pyhf.infer.test_statistics.q0`).
+
+              * ``'qtilde'``: (default) performs the calculation using the alternative test statistic,
+                :math:`\tilde{q}_{\mu}`, as defined under the Wald approximation in Equation (62)
+                of :xref:`arXiv:1007.1727` (:func:`~pyhf.infer.test_statistics.qmu_tilde`).
+              * ``'q'``: performs the calculation using the test statistic :math:`q_{\mu}`
+                (:func:`~pyhf.infer.test_statistics.qmu`).
+              * ``'q0'``: performs the calculation using the discovery test statistic
+                :math:`q_{0}` (:func:`~pyhf.infer.test_statistics.q0`).
             ntoys (:obj:`int`): Number of toys to use (how many times to sample the underlying distributions).
             track_progress (:obj:`bool`): Whether to display the `tqdm` progress bar or not (outputs to `stderr`).
 


Test patch: