prompt: We are currently solving the following issue within our repository. Here is the issue text:
  --- BEGIN ISSUE ---
  Documentation: meaning of value for return_fitted_val=True
  # Description
  
  In this code snippet from the documentation 
  
  ```python
  >>> pyhf.infer.mle.fixed_poi_fit(test_poi, data, model, return_fitted_val=True)
  (array([1.        , 0.97224597, 0.87553894]), array([28.92218013]))
  ```
  
  it isn't clear what the meaning of `array([28.92218013])` is. Is it likelihood, log likelihood, -log likelihood, -2 log likelihood?
  It is the latter, but that is not clear.
  
  Applies to 
  
  https://scikit-hep.org/pyhf/_generated/pyhf.infer.mle.fixed_poi_fit.html
  or
  https://scikit-hep.org/pyhf/_generated/pyhf.infer.mle.fit.html
  
  ## Is your feature request related to a problem? Please describe.
  
  I wasn't sure, so I had to try a few things to figure it out.
  
  ### Describe the solution you'd like
  
  Add a note to the documentation for the convention.
  
  ### Describe alternatives you've considered
  
  banging my head against the wall.
  
  # Relevant Issues and Pull Requests
  
  
  
  --- END ISSUE ---
  
  Below are some code segments, each from a relevant file. One or more of these files may contain bugs.
  --- BEGIN FILES ---
  Path: `src/pyhf/infer/mle.py`
  Content:
  ```
  1 """Module for Maximum Likelihood Estimation."""
  2 from .. import get_backend
  3 from ..exceptions import UnspecifiedPOI
  4 
  5 
  6 def twice_nll(pars, data, pdf):
  7     """
  8     Twice the negative Log-Likelihood.
  9 
  10     Args:
  11         data (`tensor`): The data
  12         pdf (~pyhf.pdf.Model): The statistical model adhering to the schema model.json
  13 
  14     Returns:
  15         Twice the negative log likelihood.
  16 
  17     """
  18     return -2 * pdf.logpdf(pars, data)
  19 
  20 
  21 def fit(data, pdf, init_pars=None, par_bounds=None, **kwargs):
  22     """
  23     Run a unconstrained maximum likelihood fit.
  24 
  25     Example:
  26         >>> import pyhf
  27         >>> pyhf.set_backend("numpy")
  28         >>> model = pyhf.simplemodels.hepdata_like(
  29         ...     signal_data=[12.0, 11.0], bkg_data=[50.0, 52.0], bkg_uncerts=[3.0, 7.0]
  30         ... )
  31         >>> observations = [51, 48]
  32         >>> data = pyhf.tensorlib.astensor(observations + model.config.auxdata)
  33         >>> pyhf.infer.mle.fit(data, model, return_fitted_val=True)
  34         (array([0.        , 1.0030512 , 0.96266961]), array([24.98393521]))
  35 
  36     Args:
  37         data (`tensor`): The data
  38         pdf (~pyhf.pdf.Model): The statistical model adhering to the schema model.json
  39         init_pars (`list`): Values to initialize the model parameters at for the fit
  40         par_bounds (`list` of `list`\s or `tuple`\s): The extrema of values the model parameters are allowed to reach in the fit
  41         kwargs: Keyword arguments passed through to the optimizer API
  42 
  43     Returns:
  44         See optimizer API
  45 
  46     """
  47     _, opt = get_backend()
  48     init_pars = init_pars or pdf.config.suggested_init()
  49     par_bounds = par_bounds or pdf.config.suggested_bounds()
  50     return opt.minimize(twice_nll, data, pdf, init_pars, par_bounds, **kwargs)
  51 
  52 
  53 def fixed_poi_fit(poi_val, data, pdf, init_pars=None, par_bounds=None, **kwargs):
  54     """
  55     Run a maximum likelihood fit with the POI value fixed.
  56 
  57     Example:
  58         >>> import pyhf
  59         >>> pyhf.set_backend("numpy")
  60         >>> model = pyhf.simplemodels.hepdata_like(
  61         ...     signal_data=[12.0, 11.0], bkg_data=[50.0, 52.0], bkg_uncerts=[3.0, 7.0]
  62         ... )
  63         >>> observations = [51, 48]
  64         >>> data = pyhf.tensorlib.astensor(observations + model.config.auxdata)
  65         >>> test_poi = 1.0
  66         >>> pyhf.infer.mle.fixed_poi_fit(test_poi, data, model, return_fitted_val=True)
  67         (array([1.        , 0.97224597, 0.87553894]), array([28.92218013]))
  68 
  69     Args:
  70         data: The data
  71         pdf (~pyhf.pdf.Model): The statistical model adhering to the schema model.json
  72         init_pars (`list`): Values to initialize the model parameters at for the fit
  73         par_bounds (`list` of `list`\s or `tuple`\s): The extrema of values the model parameters are allowed to reach in the fit
  74         kwargs: Keyword arguments passed through to the optimizer API
  75 
  76     Returns:
  77         See optimizer API
  78 
  79     """
  80     if pdf.config.poi_index is None:
  81         raise UnspecifiedPOI(
  82             'No POI is defined. A POI is required to fit with a fixed POI.'
  83         )
  84     _, opt = get_backend()
  85     init_pars = init_pars or pdf.config.suggested_init()
  86     par_bounds = par_bounds or pdf.config.suggested_bounds()
  87     return opt.minimize(
  88         twice_nll,
  89         data,
  90         pdf,
  91         init_pars,
  92         par_bounds,
  93         [(pdf.config.poi_index, poi_val)],
  94         **kwargs,
  95     )
  96
  ```
  --- END FILES ---
  
  Please first localize the bug based on the issue statement, and then generate a patch according to the `git diff` format fenced by three backticks.
  
  Here is an example:
  
  ```diff
  diff --git a/examples/server_async.py b/examples/server_async.py
  --- a/examples/server_async.py
  +++ b/examples/server_async.py
  @@ -313,4 +313,4 @@
   
   
   if __name__ == "__main__":
  -    asyncio.run(run_async_server("."), debug=True)
  +    asyncio.run(run_async_server(), debug=True)
  diff --git a/examples/server_sync.py b/examples/server_sync.py
  --- a/examples/server_sync.py
  +++ b/examples/server_sync.py
  @@ -313,5 +313,5 @@
   
   
   if __name__ == "__main__":
  -    server = run_sync_server(".")
  +    server = run_sync_server()
       server.shutdown()
  
  ```
  
golden_diff: 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
  @@ -22,6 +22,10 @@
       """
       Run a unconstrained maximum likelihood fit.
   
  +    .. note::
  +
  +        :func:`twice_nll` is the objective function.
  +
       Example:
           >>> import pyhf
           >>> pyhf.set_backend("numpy")
  @@ -54,6 +58,10 @@
       """
       Run a maximum likelihood fit with the POI value fixed.
   
  +    .. note::
  +
  +        :func:`twice_nll` is the objective function.
  +
       Example:
           >>> import pyhf
           >>> pyhf.set_backend("numpy")
  
verification_info: {"golden_diff": "diff --git a/src/pyhf/infer/mle.py b/src/pyhf/infer/mle.py\n--- a/src/pyhf/infer/mle.py\n+++ b/src/pyhf/infer/mle.py\n@@ -22,6 +22,10 @@\n     \"\"\"\n     Run a unconstrained maximum likelihood fit.\n \n+    .. note::\n+\n+        :func:`twice_nll` is the objective function.\n+\n     Example:\n         >>> import pyhf\n         >>> pyhf.set_backend(\"numpy\")\n@@ -54,6 +58,10 @@\n     \"\"\"\n     Run a maximum likelihood fit with the POI value fixed.\n \n+    .. note::\n+\n+        :func:`twice_nll` is the objective function.\n+\n     Example:\n         >>> import pyhf\n         >>> pyhf.set_backend(\"numpy\")\n", "issue": "Documentation: meaning of value for return_fitted_val=True\n# Description\r\n\r\nIn this code snippet from the documentation \r\n\r\n```python\r\n>>> pyhf.infer.mle.fixed_poi_fit(test_poi, data, model, return_fitted_val=True)\r\n(array([1.        , 0.97224597, 0.87553894]), array([28.92218013]))\r\n```\r\n\r\nit isn't clear what the meaning of `array([28.92218013])` is. Is it likelihood, log likelihood, -log likelihood, -2 log likelihood?\r\nIt is the latter, but that is not clear.\r\n\r\nApplies to \r\n\r\nhttps://scikit-hep.org/pyhf/_generated/pyhf.infer.mle.fixed_poi_fit.html\r\nor\r\nhttps://scikit-hep.org/pyhf/_generated/pyhf.infer.mle.fit.html\r\n\r\n## Is your feature request related to a problem? Please describe.\r\n\r\nI wasn't sure, so I had to try a few things to figure it out.\r\n\r\n### Describe the solution you'd like\r\n\r\nAdd a note to the documentation for the convention.\r\n\r\n### Describe alternatives you've considered\r\n\r\nbanging my head against the wall.\r\n\r\n# Relevant Issues and Pull Requests\r\n\r\n\n", "before_files": [{"content": "\"\"\"Module for Maximum Likelihood Estimation.\"\"\"\nfrom .. import get_backend\nfrom ..exceptions import UnspecifiedPOI\n\n\ndef twice_nll(pars, data, pdf):\n    \"\"\"\n    Twice the negative Log-Likelihood.\n\n    Args:\n        data (`tensor`): The data\n        pdf (~pyhf.pdf.Model): The statistical model adhering to the schema model.json\n\n    Returns:\n        Twice the negative log likelihood.\n\n    \"\"\"\n    return -2 * pdf.logpdf(pars, data)\n\n\ndef fit(data, pdf, init_pars=None, par_bounds=None, **kwargs):\n    \"\"\"\n    Run a unconstrained maximum likelihood fit.\n\n    Example:\n        >>> import pyhf\n        >>> pyhf.set_backend(\"numpy\")\n        >>> model = pyhf.simplemodels.hepdata_like(\n        ...     signal_data=[12.0, 11.0], bkg_data=[50.0, 52.0], bkg_uncerts=[3.0, 7.0]\n        ... )\n        >>> observations = [51, 48]\n        >>> data = pyhf.tensorlib.astensor(observations + model.config.auxdata)\n        >>> pyhf.infer.mle.fit(data, model, return_fitted_val=True)\n        (array([0.        , 1.0030512 , 0.96266961]), array([24.98393521]))\n\n    Args:\n        data (`tensor`): The data\n        pdf (~pyhf.pdf.Model): The statistical model adhering to the schema model.json\n        init_pars (`list`): Values to initialize the model parameters at for the fit\n        par_bounds (`list` of `list`\\s or `tuple`\\s): The extrema of values the model parameters are allowed to reach in the fit\n        kwargs: Keyword arguments passed through to the optimizer API\n\n    Returns:\n        See optimizer API\n\n    \"\"\"\n    _, opt = get_backend()\n    init_pars = init_pars or pdf.config.suggested_init()\n    par_bounds = par_bounds or pdf.config.suggested_bounds()\n    return opt.minimize(twice_nll, data, pdf, init_pars, par_bounds, **kwargs)\n\n\ndef fixed_poi_fit(poi_val, data, pdf, init_pars=None, par_bounds=None, **kwargs):\n    \"\"\"\n    Run a maximum likelihood fit with the POI value fixed.\n\n    Example:\n        >>> import pyhf\n        >>> pyhf.set_backend(\"numpy\")\n        >>> model = pyhf.simplemodels.hepdata_like(\n        ...     signal_data=[12.0, 11.0], bkg_data=[50.0, 52.0], bkg_uncerts=[3.0, 7.0]\n        ... )\n        >>> observations = [51, 48]\n        >>> data = pyhf.tensorlib.astensor(observations + model.config.auxdata)\n        >>> test_poi = 1.0\n        >>> pyhf.infer.mle.fixed_poi_fit(test_poi, data, model, return_fitted_val=True)\n        (array([1.        , 0.97224597, 0.87553894]), array([28.92218013]))\n\n    Args:\n        data: The data\n        pdf (~pyhf.pdf.Model): The statistical model adhering to the schema model.json\n        init_pars (`list`): Values to initialize the model parameters at for the fit\n        par_bounds (`list` of `list`\\s or `tuple`\\s): The extrema of values the model parameters are allowed to reach in the fit\n        kwargs: Keyword arguments passed through to the optimizer API\n\n    Returns:\n        See optimizer API\n\n    \"\"\"\n    if pdf.config.poi_index is None:\n        raise UnspecifiedPOI(\n            'No POI is defined. A POI is required to fit with a fixed POI.'\n        )\n    _, opt = get_backend()\n    init_pars = init_pars or pdf.config.suggested_init()\n    par_bounds = par_bounds or pdf.config.suggested_bounds()\n    return opt.minimize(\n        twice_nll,\n        data,\n        pdf,\n        init_pars,\n        par_bounds,\n        [(pdf.config.poi_index, poi_val)],\n        **kwargs,\n    )\n", "path": "src/pyhf/infer/mle.py"}], "after_files": [{"content": "\"\"\"Module for Maximum Likelihood Estimation.\"\"\"\nfrom .. import get_backend\nfrom ..exceptions import UnspecifiedPOI\n\n\ndef twice_nll(pars, data, pdf):\n    \"\"\"\n    Twice the negative Log-Likelihood.\n\n    Args:\n        data (`tensor`): The data\n        pdf (~pyhf.pdf.Model): The statistical model adhering to the schema model.json\n\n    Returns:\n        Twice the negative log likelihood.\n\n    \"\"\"\n    return -2 * pdf.logpdf(pars, data)\n\n\ndef fit(data, pdf, init_pars=None, par_bounds=None, **kwargs):\n    \"\"\"\n    Run a unconstrained maximum likelihood fit.\n\n    .. note::\n\n        :func:`twice_nll` is the objective function.\n\n    Example:\n        >>> import pyhf\n        >>> pyhf.set_backend(\"numpy\")\n        >>> model = pyhf.simplemodels.hepdata_like(\n        ...     signal_data=[12.0, 11.0], bkg_data=[50.0, 52.0], bkg_uncerts=[3.0, 7.0]\n        ... )\n        >>> observations = [51, 48]\n        >>> data = pyhf.tensorlib.astensor(observations + model.config.auxdata)\n        >>> pyhf.infer.mle.fit(data, model, return_fitted_val=True)\n        (array([0.        , 1.0030512 , 0.96266961]), array([24.98393521]))\n\n    Args:\n        data (`tensor`): The data\n        pdf (~pyhf.pdf.Model): The statistical model adhering to the schema model.json\n        init_pars (`list`): Values to initialize the model parameters at for the fit\n        par_bounds (`list` of `list`\\s or `tuple`\\s): The extrema of values the model parameters are allowed to reach in the fit\n        kwargs: Keyword arguments passed through to the optimizer API\n\n    Returns:\n        See optimizer API\n\n    \"\"\"\n    _, opt = get_backend()\n    init_pars = init_pars or pdf.config.suggested_init()\n    par_bounds = par_bounds or pdf.config.suggested_bounds()\n    return opt.minimize(twice_nll, data, pdf, init_pars, par_bounds, **kwargs)\n\n\ndef fixed_poi_fit(poi_val, data, pdf, init_pars=None, par_bounds=None, **kwargs):\n    \"\"\"\n    Run a maximum likelihood fit with the POI value fixed.\n\n    .. note::\n\n        :func:`twice_nll` is the objective function.\n\n    Example:\n        >>> import pyhf\n        >>> pyhf.set_backend(\"numpy\")\n        >>> model = pyhf.simplemodels.hepdata_like(\n        ...     signal_data=[12.0, 11.0], bkg_data=[50.0, 52.0], bkg_uncerts=[3.0, 7.0]\n        ... )\n        >>> observations = [51, 48]\n        >>> data = pyhf.tensorlib.astensor(observations + model.config.auxdata)\n        >>> test_poi = 1.0\n        >>> pyhf.infer.mle.fixed_poi_fit(test_poi, data, model, return_fitted_val=True)\n        (array([1.        , 0.97224597, 0.87553894]), array([28.92218013]))\n\n    Args:\n        data: The data\n        pdf (~pyhf.pdf.Model): The statistical model adhering to the schema model.json\n        init_pars (`list`): Values to initialize the model parameters at for the fit\n        par_bounds (`list` of `list`\\s or `tuple`\\s): The extrema of values the model parameters are allowed to reach in the fit\n        kwargs: Keyword arguments passed through to the optimizer API\n\n    Returns:\n        See optimizer API\n\n    \"\"\"\n    if pdf.config.poi_index is None:\n        raise UnspecifiedPOI(\n            'No POI is defined. A POI is required to fit with a fixed POI.'\n        )\n    _, opt = get_backend()\n    init_pars = init_pars or pdf.config.suggested_init()\n    par_bounds = par_bounds or pdf.config.suggested_bounds()\n    return opt.minimize(\n        twice_nll,\n        data,\n        pdf,\n        init_pars,\n        par_bounds,\n        [(pdf.config.poi_index, poi_val)],\n        **kwargs,\n    )\n", "path": "src/pyhf/infer/mle.py"}]}