docs(backport): Correct fixed_params type to tuple or list (#2428)

matthewfeickert · web-flow · commit 1edf68e23f30 · 2024-01-05T10:29:04.000-06:00
* Backport PR #2420 * `fixed_params` is an iterable that is of type tuple or list. Though operations on it may support tensor types, not all operations will necessarily be supported and so the docs should not list it as being a tensor.
diff --git a/src/pyhf/infer/__init__.py b/src/pyhf/infer/__init__.py
@@ -61,8 +61,8 @@ def hypotest(
         par_bounds (:obj:`tensor`): The extrema of values the model parameters
             are allowed to reach in the fit.
             The shape should be ``(n, 2)`` for ``n`` model parameters.
-        fixed_params (:obj:`tensor` of :obj:`bool`): The flag to set a parameter constant to its starting
-            value during minimization.
+        fixed_params (:obj:`tuple` or :obj:`list` of :obj:`bool`): The flag to set a parameter
+            constant to its starting value during minimization.
         calctype (:obj:`str`): The calculator to create. Choose either 'asymptotics' (default) or 'toybased'.
         return_tail_probs (:obj:`bool`): Bool for returning :math:`\mathrm{CL}_{s+b}` and :math:`\mathrm{CL}_{b}`
         return_expected (:obj:`bool`): Bool for returning :math:`\mathrm{CL}_{\mathrm{exp}}`
diff --git a/src/pyhf/infer/calculators.py b/src/pyhf/infer/calculators.py
@@ -61,8 +61,8 @@ def generate_asimov_data(
         par_bounds (:obj:`tensor`): The extrema of values the model parameters
             are allowed to reach in the fit.
             The shape should be ``(n, 2)`` for ``n`` model parameters.
-        fixed_params (:obj:`tensor` of :obj:`bool`): The flag to set a parameter constant to its starting
-            value during minimization.
+        fixed_params (:obj:`tuple` or :obj:`list` of :obj:`bool`): The flag to set a parameter
+            constant to its starting value during minimization.
         return_fitted_pars (:obj:`bool`): Return the best-fit parameter values for the given ``asimov_mu``.
 
 
@@ -241,8 +241,8 @@ def __init__(
             par_bounds (:obj:`tensor`): The extrema of values the model parameters
                 are allowed to reach in the fit.
                 The shape should be ``(n, 2)`` for ``n`` model parameters.
-            fixed_params (:obj:`tensor` of :obj:`bool`): The flag to set a parameter constant to its starting
-                value during minimization.
+            fixed_params (:obj:`tuple` or :obj:`list` of :obj:`bool`): The flag to set a parameter
+                constant to its starting value during minimization.
             test_stat (:obj:`str`): The test statistic to use as a numerical summary of the
               data: ``'qtilde'``, ``'q'``, or ``'q0'``.
 
@@ -685,8 +685,8 @@ def __init__(
             par_bounds (:obj:`tensor`): The extrema of values the model parameters
                 are allowed to reach in the fit.
                 The shape should be ``(n, 2)`` for ``n`` model parameters.
-            fixed_params (:obj:`tensor` of :obj:`bool`): The flag to set a parameter constant to its starting
-                value during minimization.
+            fixed_params (:obj:`tuple` or :obj:`list` of :obj:`bool`): The flag to set a parameter
+                constant to its starting value during minimization.
             test_stat (:obj:`str`): The test statistic to use as a numerical summary of the
               data: ``'qtilde'``, ``'q'``, or ``'q0'``.
 
diff --git a/src/pyhf/infer/mle.py b/src/pyhf/infer/mle.py
@@ -106,8 +106,8 @@ def fit(data, pdf, init_pars=None, par_bounds=None, fixed_params=None, **kwargs)
         par_bounds (:obj:`list` of :obj:`list`/:obj:`tuple`): The extrema of values the model parameters
             are allowed to reach in the fit.
             The shape should be ``(n, 2)`` for ``n`` model parameters.
-        fixed_params (:obj:`list` of :obj:`bool`): The flag to set a parameter constant to its starting
-            value during minimization.
+        fixed_params (:obj:`tuple` or :obj:`list` of :obj:`bool`): The flag to set a parameter
+            constant to its starting value during minimization.
         kwargs: Keyword arguments passed through to the optimizer API
 
     Returns:
@@ -180,8 +180,8 @@ def fixed_poi_fit(
         par_bounds (:obj:`list` of :obj:`list`/:obj:`tuple`): The extrema of values the model parameters
             are allowed to reach in the fit.
             The shape should be ``(n, 2)`` for ``n`` model parameters.
-        fixed_params (:obj:`list` of :obj:`bool`): The flag to set a parameter constant to its starting
-            value during minimization.
+        fixed_params (:obj:`tuple` or :obj:`list` of :obj:`bool`): The flag to set a parameter
+            constant to its starting value during minimization.
         kwargs: Keyword arguments passed through to the optimizer API
 
     Returns:
diff --git a/src/pyhf/infer/test_statistics.py b/src/pyhf/infer/test_statistics.py
@@ -112,8 +112,8 @@ def qmu(mu, data, pdf, init_pars, par_bounds, fixed_params, return_fitted_pars=F
         par_bounds (:obj:`list` of :obj:`list`/:obj:`tuple`): The extrema of values the model parameters
             are allowed to reach in the fit.
             The shape should be ``(n, 2)`` for ``n`` model parameters.
-        fixed_params (:obj:`list` of :obj:`bool`): The flag to set a parameter constant to its starting
-            value during minimization.
+        fixed_params (:obj:`tuple` or :obj:`list` of :obj:`bool`): The flag to set a parameter
+            constant to its starting value during minimization.
         return_fitted_pars (:obj:`bool`): Return the best-fit parameter tensors
             the fixed-POI and unconstrained fits have converged on
             (i.e. :math:`\mu, \hat{\hat{\theta}}` and :math:`\hat{\mu}, \hat{\theta}`)
@@ -207,8 +207,8 @@ def qmu_tilde(
         par_bounds (:obj:`list` of :obj:`list`/:obj:`tuple`): The extrema of values the model parameters
             are allowed to reach in the fit.
             The shape should be ``(n, 2)`` for ``n`` model parameters.
-        fixed_params (:obj:`list` of :obj:`bool`): The flag to set a parameter constant to its starting
-            value during minimization.
+        fixed_params (:obj:`tuple` or :obj:`list` of :obj:`bool`): The flag to set a parameter
+            constant to its starting value during minimization.
         return_fitted_pars (:obj:`bool`): Return the best-fit parameter tensors
             the fixed-POI and unconstrained fits have converged on
             (i.e. :math:`\mu, \hat{\hat{\theta}}` and :math:`\hat{\mu}, \hat{\theta}`)
@@ -290,8 +290,8 @@ def tmu(mu, data, pdf, init_pars, par_bounds, fixed_params, return_fitted_pars=F
         par_bounds (:obj:`list` of :obj:`list`/:obj:`tuple`): The extrema of values the model parameters
             are allowed to reach in the fit.
             The shape should be ``(n, 2)`` for ``n`` model parameters.
-        fixed_params (:obj:`list` of :obj:`bool`): The flag to set a parameter constant to its starting
-            value during minimization.
+        fixed_params (:obj:`tuple` or :obj:`list` of :obj:`bool`): The flag to set a parameter
+            constant to its starting value during minimization.
         return_fitted_pars (:obj:`bool`): Return the best-fit parameter tensors
             the fixed-POI and unconstrained fits have converged on
             (i.e. :math:`\mu, \hat{\hat{\theta}}` and :math:`\hat{\mu}, \hat{\theta}`)
@@ -380,8 +380,8 @@ def tmu_tilde(
         par_bounds (:obj:`list` of :obj:`list`/:obj:`tuple`): The extrema of values the model parameters
             are allowed to reach in the fit.
             The shape should be ``(n, 2)`` for ``n`` model parameters.
-        fixed_params (:obj:`list` of :obj:`bool`): The flag to set a parameter constant to its starting
-            value during minimization.
+        fixed_params (:obj:`tuple` or :obj:`list` of :obj:`bool`): The flag to set a parameter
+            constant to its starting value during minimization.
         return_fitted_pars (:obj:`bool`): Return the best-fit parameter tensors
             the fixed-POI and unconstrained fits have converged on
             (i.e. :math:`\mu, \hat{\hat{\theta}}` and :math:`\hat{\mu}, \hat{\theta}`)
@@ -458,8 +458,8 @@ def q0(mu, data, pdf, init_pars, par_bounds, fixed_params, return_fitted_pars=Fa
         par_bounds (:obj:`list` of :obj:`list`/:obj:`tuple`): The extrema of values the model parameters
             are allowed to reach in the fit.
             The shape should be ``(n, 2)`` for ``n`` model parameters.
-        fixed_params (:obj:`list` of :obj:`bool`): The flag to set a parameter constant to its starting
-            value during minimization.
+        fixed_params (:obj:`tuple` or :obj:`list` of :obj:`bool`): The flag to set a parameter
+            constant to its starting value during minimization.
         return_fitted_pars (:obj:`bool`): Return the best-fit parameter tensors
             the fixed-POI and unconstrained fits have converged on
             (i.e. :math:`\mu, \hat{\hat{\theta}}` and :math:`\hat{\mu}, \hat{\theta}`)
diff --git a/src/pyhf/infer/utils.py b/src/pyhf/infer/utils.py
@@ -22,7 +22,7 @@ def all_pois_floating(pdf, fixed_params):
     Args:
         pdf (~pyhf.pdf.Model): The statistical model adhering to the schema
          ``model.json``.
-        fixed_params (:obj:`list` or `tensor` of :obj:`bool`): Array of
+        fixed_params (:obj:`tuple` or :obj:`list` of :obj:`bool`): Array of
          :obj:`bool` indicating if model parameters are fixed.
 
     Returns:
