feat: Add autoscan for upper limit using TOMS Algorithm 748 (#1274)

* Add pyhf.infer.intervals and pyhf.infer.intervals.upper_limits modules.
* Migrate pyhf.infer.intervals.upperlimit to pyhf.infer.intervals.upper_limits.upper_limit.
* Add pyhf.infer.intervals.upper_limits.toms748_scan to API which implements the SciPy TOMS748
  root finding method to scan for the upper limit.
* Add pyhf.infer.intervals.upper_limits.linear_grid_scan to preserve the linear scan of the
  old pyhf.infer.intervals.upperlimit API in a specific API.
* Use pyhf.infer.intervals.upper_limits.toms748_scan as the default method of scanning for
  and upper limit in pyhf.infer.intervals.upper_limits.upper_limit.
* Update lower bound of the supported scipy versions to v1.2.0 to use scipy.optimize.toms748.
* Add tests for the pyhf.infer.intervals.upper_limits.toms748_scan API and the behavior 
  changes in pyhf.infer.intervals.upper_limits.upper_limit.
* Add 'Confidence Intervals' section to the API docs and move the pyhf.infer.intervals.upper_limits
  APIs there.
* Add a deprecation warning to pyhf.infer.intervals.upperlimit and note it is scheduled
  for removal in pyhf v0.9.0.
* Add Beojan Stanislaus to contributors list.

Co-authored-by: Matthew Feickert <matthew.feickert@cern.ch>

docs/api.rst

@@ -157,9 +157,19 @@ Fits and Tests
    mle.fit
    mle.fixed_poi_fit
    hypotest
-   intervals.upperlimit
    utils.all_pois_floating
 
+Confidence Intervals
+~~~~~~~~~~~~~~~~~~~~
+
+.. autosummary::
+   :toctree: _generated/
+   :nosignatures:
+
+   intervals.upper_limits.upper_limit
+   intervals.upper_limits.toms748_scan
+   intervals.upper_limits.linear_grid_scan
+   intervals.upperlimit
 
 Schema
 ------

docs/contributors.rst

@@ -29,3 +29,4 @@ Contributors include:
 - Aryan Roy
 - Jerry Ling
 - Nathan Simpson
+- Beojan Stanislaus

docs/examples/notebooks/ShapeFactor.ipynb

@@ -176,7 +176,11 @@
     }
    ],
    "source": [
-    "obs_limit, exp_limits, (poi_tests, tests) = pyhf.infer.intervals.upperlimit(\n",
+    "(\n",
+    "    obs_limit,\n",
+    "    exp_limits,\n",
+    "    (poi_tests, tests),\n",
+    ") = pyhf.infer.intervals.upper_limits.upper_limit(\n",
     "    data, pdf, np.linspace(0, 5, 61), level=0.05, return_results=True\n",
     ")"
    ]

docs/examples/notebooks/binderexample/StatisticalAnalysis.ipynb

@@ -2295,7 +2295,11 @@
    "outputs": [],
    "source": [
     "mu_tests = np.linspace(0, 1, 16)\n",
-    "obs_limit, exp_limits, (poi_tests, tests) = pyhf.infer.intervals.upperlimit(\n",
+    "(\n",
+    "    obs_limit,\n",
+    "    exp_limits,\n",
+    "    (poi_tests, tests),\n",
+    ") = pyhf.infer.intervals.upper_limits.upper_limit(\n",
     "    data, pdf, mu_tests, level=0.05, return_results=True\n",
     ")"
    ]

docs/examples/notebooks/multiBinPois.ipynb

@@ -94,7 +94,11 @@
     "init_pars = model.config.suggested_init()\n",
     "par_bounds = model.config.suggested_bounds()\n",
     "\n",
-    "obs_limit, exp_limits, (poi_tests, tests) = pyhf.infer.intervals.upperlimit(\n",
+    "(\n",
+    "    obs_limit,\n",
+    "    exp_limits,\n",
+    "    (poi_tests, tests),\n",
+    ") = pyhf.infer.intervals.upper_limits.upper_limit(\n",
     "    data, model, np.linspace(0, 5, 61), level=0.05, return_results=True\n",
     ")"
    ]

setup.cfg

@@ -35,7 +35,7 @@ package_dir =
 include_package_data = True
 python_requires = >=3.7
 install_requires =
-    scipy>=1.1.0 # requires numpy, which is required by pyhf and tensorflow
+    scipy>=1.2.0 # requires numpy, which is required by pyhf and tensorflow
     click>=8.0.0  # for console scripts
     tqdm>=4.56.0  # for readxml
     jsonschema>=4.15.0  # for utils

src/pyhf/infer/intervals/__init__.py

@@ -0,0 +1,30 @@
+"""Interval estimation"""
+import pyhf.infer.intervals.upper_limits
+
+__all__ = ["upper_limits.upper_limit"]
+
+
+def __dir__():
+    return __all__
+
+
+def upperlimit(
+    data, model, scan=None, level=0.05, return_results=False, **hypotest_kwargs
+):
+    """
+    .. deprecated:: 0.7.0
+       Use :func:`~pyhf.infer.intervals.upper_limits.upper_limit` instead.
+    .. warning:: :func:`~pyhf.infer.intervals.upperlimit` will be removed in
+     ``pyhf`` ``v0.9.0``.
+    """
+    from pyhf.exceptions import _deprecated_api_warning
+
+    _deprecated_api_warning(
+        "pyhf.infer.intervals.upperlimit",
+        "pyhf.infer.intervals.upper_limits.upper_limit",
+        "0.7.0",
+        "0.9.0",
+    )
+    return pyhf.infer.intervals.upper_limits.upper_limit(
+        data, model, scan, level, return_results, **hypotest_kwargs
+    )