feat: Update model and inference defaults (#1114)

* Use the same defaults across the Python and CLI API
   - Use interpolation code4 and code4p in default modifier settings for models
   - Use qtilde as the default test stat for inference
* Link to test stat functions in docstrings
   - Migrate mention of approximation of test stat distributions to AsymptoticCalculator.distributions

src/pyhf/cli/infer.py

@@ -105,10 +105,6 @@ def fit(
     model = ws.model(
         measurement_name=measurement,
         patches=patches,
-        modifier_settings={
-            "normsys": {"interpcode": "code4"},
-            "histosys": {"interpcode": "code4p"},
-        },
     )
     data = ws.data(model)
 

src/pyhf/infer/__init__.py

@@ -11,7 +11,7 @@ def hypotest(
     init_pars=None,
     par_bounds=None,
     fixed_params=None,
-    qtilde=False,
+    qtilde=True,
     **kwargs,
 ):
     r"""
@@ -41,9 +41,9 @@ def hypotest(
         init_pars (:obj:`tensor`): The initial parameter values to be used for minimization
         par_bounds (:obj:`tensor`): The parameter value bounds to be used for minimization
         fixed_params (:obj:`tensor`): Whether to fix the parameter to the init_pars value during minimization
-        qtilde (:obj:`bool`): When ``True`` perform 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`.
+        qtilde (:obj:`bool`): When ``True`` use :func:`~pyhf.infer.test_statistics.qmu_tilde`
+         as the test statistic.
+         When ``False`` use :func:`~pyhf.infer.test_statistics.qmu`.
 
     Keyword Args:
         return_tail_probs (bool): Bool for returning :math:`\mathrm{CL}_{s+b}` and :math:`\mathrm{CL}_{b}`

src/pyhf/infer/calculators.py

@@ -128,7 +128,7 @@ def __init__(
         init_pars=None,
         par_bounds=None,
         fixed_params=None,
-        qtilde=False,
+        qtilde=True,
     ):
         """
         Asymptotic Calculator.
@@ -139,7 +139,9 @@ def __init__(
             init_pars (:obj:`tensor`): The initial parameter values to be used for fitting.
             par_bounds (:obj:`tensor`): The parameter value bounds to be used for fitting.
             fixed_params (:obj:`tensor`): Whether to fix the parameter to the init_pars value during minimization
-            qtilde (:obj:`bool`): Whether to use qtilde as the test statistic.
+            qtilde (:obj:`bool`): When ``True`` use :func:`~pyhf.infer.test_statistics.qmu_tilde`
+             as the test statistic.
+             When ``False`` use :func:`~pyhf.infer.test_statistics.qmu`.
 
         Returns:
             ~pyhf.infer.calculators.AsymptoticCalculator: The calculator for asymptotic quantities.
@@ -156,7 +158,9 @@ def __init__(
 
     def distributions(self, poi_test):
         """
-        Probability Distributions of the test statistic value under the signal + background and and background-only hypothesis.
+        Probability distributions of the test statistic, as defined in
+        :math:`\S` 3 of :xref:`arXiv:1007.1727` under the Wald approximation,
+        under the signal + background and background-only hypotheses.
 
         Args:
             poi_test: The value for the parameter of interest.

src/pyhf/infer/test_statistics.py

@@ -113,8 +113,8 @@ def qmu(mu, data, pdf, init_pars, par_bounds, fixed_params):
 
 def qmu_tilde(mu, data, pdf, init_pars, par_bounds, fixed_params):
     r"""
-    The test statistic, :math:`\tilde{q}_{\mu}`, for establishing an upper
-    limit on the strength parameter, :math:`\mu`, for models with
+    The "alternative" test statistic, :math:`\tilde{q}_{\mu}`, for establishing
+    an upper limit on the strength parameter, :math:`\mu`, for models with
     bounded POI, as defiend in Equation (16) in :xref:`arXiv:1007.1727`
 
     .. math::

src/pyhf/pdf.py

@@ -224,7 +224,11 @@ def __init__(self, spec, **config_kwargs):
         )
         poi_name = config_kwargs.pop('poi_name', 'mu')
 
-        default_modifier_settings = {'normsys': {'interpcode': 'code1'}}
+        default_modifier_settings = {
+            'normsys': {'interpcode': 'code4'},
+            'histosys': {'interpcode': 'code4p'},
+        }
+
         self.modifier_settings = config_kwargs.pop(
             'modifier_settings', default_modifier_settings
         )

tests/test_validation.py

@@ -635,7 +635,9 @@ def test_validation(setup_and_tolerance):
     setup, tolerance = setup_and_tolerance
     source = setup['source']
 
-    pdf = pyhf.Model(setup['spec'])
+    pdf = pyhf.Model(
+        setup['spec'], modifier_settings={'normsys': {'interpcode': 'code1'}}
+    )
 
     if 'channels' in source:
         data = []