Repository: scikit-hep/pyhf

Issue:
pyhf.infer.mle.fit docstring missing arguments
# Description

`pyhf.infer.mle.fit`'s docstring currently only includes `data`, `pdf` and `kwargs` and does not list the other arguments. It should be updated to include all arguments and also have `pydocstyle` run over it.


Discussion:

Resolving patch:
diff --git a/src/pyhf/infer/__init__.py b/src/pyhf/infer/__init__.py
--- a/src/pyhf/infer/__init__.py
+++ b/src/pyhf/infer/__init__.py
@@ -11,6 +11,27 @@ def hypotest(
     r"""
     Compute :math:`p`-values and test statistics for a single value of the parameter of interest.
 
+    Example:
+        >>> import pyhf
+        >>> pyhf.set_backend("numpy")
+        >>> model = pyhf.simplemodels.hepdata_like(
+        ...     signal_data=[12.0, 11.0], bkg_data=[50.0, 52.0], bkg_uncerts=[3.0, 7.0]
+        ... )
+        >>> observations = [51, 48]
+        >>> data = pyhf.tensorlib.astensor(observations + model.config.auxdata)
+        >>> test_poi = 1.0
+        >>> CLs_obs, CLs_exp_band = pyhf.infer.hypotest(
+        ...     test_poi, data, model, qtilde=True, return_expected_set=True
+        ... )
+        >>> print(CLs_obs)
+        [0.05251554]
+        >>> print(CLs_exp_band)
+        [[0.00260641]
+         [0.01382066]
+         [0.06445521]
+         [0.23526104]
+         [0.57304182]]
+
     Args:
         poi_test (Number or Tensor): The value of the parameter of interest (POI)
         data (Number or Tensor): The root of the calculated test statistic given the Asimov data, :math:`\sqrt{q_{\mu,A}}`
diff --git a/src/pyhf/infer/mle.py b/src/pyhf/infer/mle.py
--- a/src/pyhf/infer/mle.py
+++ b/src/pyhf/infer/mle.py
@@ -7,7 +7,7 @@ def twice_nll(pars, data, pdf):
     Twice the negative Log-Likelihood.
 
     Args:
-        data (`tensor`): the data
+        data (`tensor`): The data
         pdf (~pyhf.pdf.Model): The statistical model adhering to the schema model.json
 
     Returns:
@@ -21,13 +21,26 @@ def fit(data, pdf, init_pars=None, par_bounds=None, **kwargs):
     """
     Run a unconstrained maximum likelihood fit.
 
+    Example:
+        >>> import pyhf
+        >>> pyhf.set_backend("numpy")
+        >>> model = pyhf.simplemodels.hepdata_like(
+        ...     signal_data=[12.0, 11.0], bkg_data=[50.0, 52.0], bkg_uncerts=[3.0, 7.0]
+        ... )
+        >>> observations = [51, 48]
+        >>> data = pyhf.tensorlib.astensor(observations + model.config.auxdata)
+        >>> pyhf.infer.mle.fit(data, model, return_fitted_val=True)
+        (array([0.        , 1.0030512 , 0.96266961]), 24.98393521454011)
+
     Args:
-        data (`tensor`): the data
+        data (`tensor`): The data
         pdf (~pyhf.pdf.Model): The statistical model adhering to the schema model.json
-        kwargs: keyword arguments passed through to the optimizer API
+        init_pars (`list`): Values to initialize the model parameters at for the fit
+        par_bounds (`list` of `list`\s or `tuple`\s): The extrema of values the model parameters are allowed to reach in the fit
+        kwargs: Keyword arguments passed through to the optimizer API
 
     Returns:
-        see optimizer API
+        See optimizer API
 
     """
     _, opt = get_backend()
@@ -38,15 +51,29 @@ def fit(data, pdf, init_pars=None, par_bounds=None, **kwargs):
 
 def fixed_poi_fit(poi_val, data, pdf, init_pars=None, par_bounds=None, **kwargs):
     """
-    Run a maximum likelihood fit with the POI value fixzed.
+    Run a maximum likelihood fit with the POI value fixed.
+
+    Example:
+        >>> import pyhf
+        >>> pyhf.set_backend("numpy")
+        >>> model = pyhf.simplemodels.hepdata_like(
+        ...     signal_data=[12.0, 11.0], bkg_data=[50.0, 52.0], bkg_uncerts=[3.0, 7.0]
+        ... )
+        >>> observations = [51, 48]
+        >>> data = pyhf.tensorlib.astensor(observations + model.config.auxdata)
+        >>> test_poi = 1.0
+        >>> pyhf.infer.mle.fixed_poi_fit(test_poi, data, model, return_fitted_val=True)
+        (array([1.        , 0.97224597, 0.87553894]), 28.92218013492061)
 
     Args:
-        data: the data
+        data: The data
         pdf (~pyhf.pdf.Model): The statistical model adhering to the schema model.json
-        kwargs: keyword arguments passed through to the optimizer API
+        init_pars (`list`): Values to initialize the model parameters at for the fit
+        par_bounds (`list` of `list`\s or `tuple`\s): The extrema of values the model parameters are allowed to reach in the fit
+        kwargs: Keyword arguments passed through to the optimizer API
 
     Returns:
-        see optimizer API
+        See optimizer API
 
     """
     _, opt = get_backend()


Test patch:
diff --git a/src/pyhf/infer/test_statistics.py b/src/pyhf/infer/test_statistics.py
--- a/src/pyhf/infer/test_statistics.py
+++ b/src/pyhf/infer/test_statistics.py
@@ -18,13 +18,26 @@ def qmu(mu, data, pdf, init_pars, par_bounds):
           \end{array}\right.
         \end{equation}
 
+    Example:
+        >>> import pyhf
+        >>> pyhf.set_backend("numpy")
+        >>> model = pyhf.simplemodels.hepdata_like(
+        ...     signal_data=[12.0, 11.0], bkg_data=[50.0, 52.0], bkg_uncerts=[3.0, 7.0]
+        ... )
+        >>> observations = [51, 48]
+        >>> data = pyhf.tensorlib.astensor(observations + model.config.auxdata)
+        >>> test_mu = 1.0
+        >>> init_pars = model.config.suggested_init()
+        >>> par_bounds = model.config.suggested_bounds()
+        >>> pyhf.infer.test_statistics.qmu(test_mu, data, model, init_pars, par_bounds)
+        3.938244920380498
 
     Args:
         mu (Number or Tensor): The signal strength parameter
         data (Tensor): The data to be considered
         pdf (~pyhf.pdf.Model): The HistFactory statistical model used in the likelihood ratio calculation
-        init_pars (Tensor): The initial parameters
-        par_bounds(Tensor): The bounds on the paramter values
+        init_pars (`list`): Values to initialize the model parameters at for the fit
+        par_bounds (`list` of `list`\s or `tuple`\s): The extrema of values the model parameters are allowed to reach in the fit
 
     Returns:
         Float: The calculated test statistic, :math:`q_{\mu}`