refactor: Create infer subpackage to hold our statistics code (#531)

* Create a pyhf.infer subpackage
* Move cli.stats to cli.infer
* Bump version: 0.2.2 → 0.3.0

Author: kratsg

.bumpversion.cfg

@@ -1,5 +1,5 @@
 [bumpversion]
-current_version = 0.2.2
+current_version = 0.3.0
 commit = True
 tag = True
 

README.md

@@ -32,7 +32,7 @@ This repo is a pure-python implementation of that statistical model for multi-bi
 ```python
 >>> import pyhf
 >>> pdf = pyhf.simplemodels.hepdata_like(signal_data=[12.0, 11.0], bkg_data=[50.0, 52.0], bkg_uncerts=[3.0, 7.0])
->>> CLs_obs, CLs_exp = pyhf.utils.hypotest(1.0, [51, 48] + pdf.config.auxdata, pdf, return_expected=True)
+>>> CLs_obs, CLs_exp = pyhf.infer.hypotest(1.0, [51, 48] + pdf.config.auxdata, pdf, return_expected=True)
 >>> print('Observed: {}, Expected: {}'.format(CLs_obs, CLs_exp))
 Observed: [0.05290116], Expected: [0.06445521]
 

docs/api.rst

@@ -109,6 +109,19 @@ Interpolators
    code4
    code4p
 
+Statistics
+----------
+
+.. currentmodule:: pyhf.infer
+
+.. autosummary::
+   :toctree: _generated/
+
+   test_statistics.hypotest
+   test_statistics.qmu
+   utils.loglambdav
+   utils.generate_asimov_data
+
 Exceptions
 ----------
 
@@ -141,9 +154,5 @@ Utilities
 .. autosummary::
    :toctree: _generated/
 
-   generate_asimov_data
-   loglambdav
    pvals_from_teststat
    pvals_from_teststat_expected
-   qmu
-   hypotest

docs/conf.py

@@ -86,9 +86,9 @@ def setup(app):
 # built documents.
 #
 # The short X.Y version.
-version = u'0.2.2'
+version = u'0.3.0'
 # The full version, including alpha/beta/rc tags.
-release = u'0.2.2'
+release = u'0.3.0'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -162,7 +162,7 @@ def setup(app):
 # The name for this set of Sphinx documents.
 # "<project> v<release> documentation" by default.
 #
-# html_title = u'pyhf v0.2.2'
+# html_title = u'pyhf v0.3.0'
 
 # A shorter title for the navigation bar.  Default is the same as html_title.
 #

docs/examples/notebooks/ImpactPlot.ipynb

@@ -85,7 +85,7 @@
     "        pyhf.tensor.numpy_backend(), pyhf.optimize.minuit_optimizer(verbose=True)\n",
     "    )\n",
     "    minuit = pyhf.optimizer._make_minuit(\n",
-    "        pyhf.utils.loglambdav,\n",
+    "        pyhf.infer.utils.loglambdav,\n",
     "        data,\n",
     "        model,\n",
     "        model.config.suggested_init(),\n",

docs/examples/notebooks/Recast.ipynb

@@ -115,7 +115,7 @@
    "source": [
     "testmus = np.linspace(0,5)\n",
     "results = [\n",
-    "    pyhf.utils.hypotest(mu, data + original.config.auxdata, \n",
+    "    pyhf.infer.hypotest(mu, data + original.config.auxdata, \n",
     "                        original, original.config.suggested_init(), original.config.suggested_bounds(),\n",
     "                       return_expected_set=True)\n",
     "    for mu in testmus\n",
@@ -205,7 +205,7 @@
    "source": [
     "testmus = np.linspace(0,5)\n",
     "results = [\n",
-    "    pyhf.utils.hypotest(mu, data + recast.config.auxdata, \n",
+    "    pyhf.infer.hypotest(mu, data + recast.config.auxdata, \n",
     "                     recast, recast.config.suggested_init(), recast.config.suggested_bounds(),\n",
     "                    return_expected_set=True)\n",
     "    for mu in testmus\n",

docs/examples/notebooks/ShapeFactor.ipynb

@@ -181,7 +181,7 @@
    "source": [
     "print('initialization parameters: {}'.format(pdf.config.suggested_init()))\n",
     "\n",
-    "unconpars = pyhf.optimizer.unconstrained_bestfit(pyhf.utils.loglambdav, data, pdf,\n",
+    "unconpars = pyhf.optimizer.unconstrained_bestfit(pyhf.infer.utils.loglambdav, data, pdf,\n",
     "                                                 pdf.config.suggested_init(), pdf.config.suggested_bounds())\n",
     "print('parameters post unconstrained fit: {}'.format(unconpars))"
    ]
@@ -252,7 +252,7 @@
     "\n",
     "\n",
     "poi_tests = np.linspace(0, 5, 61)\n",
-    "tests = [pyhf.utils.hypotest(poi_test, data, pdf, init_pars, par_bounds, return_expected_set=True) \n",
+    "tests = [pyhf.infer.hypotest(poi_test, data, pdf, init_pars, par_bounds, return_expected_set=True) \n",
     "         for poi_test in poi_tests]\n",
     "cls_obs = np.array([test[0] for test in tests]).flatten()\n",
     "cls_exp = [np.array([test[1][i] for test in tests]).flatten() for i in range(5)]\n",

docs/examples/notebooks/binderexample/StatisticalAnalysis.ipynb

@@ -1073,7 +1073,7 @@
     "background_only = pdf.config.suggested_init()\n",
     "background_only[pdf.config.poi_index] = 0.0\n",
     "best_fit = pyhf.optimizer.unconstrained_bestfit(\n",
-    "    pyhf.utils.loglambdav, data, pdf, pdf.config.suggested_init(), pdf.config.suggested_bounds())"
+    "    pyhf.infer.utils.loglambdav, data, pdf, pdf.config.suggested_init(), pdf.config.suggested_bounds())"
    ]
   },
   {
@@ -2740,7 +2740,7 @@
    ],
    "source": [
     "mu_tests = np.linspace(0, 1, 16)\n",
-    "hypo_tests = [pyhf.utils.hypotest(mu, data, pdf, pdf.config.suggested_init(), pdf.config.suggested_bounds(),\n",
+    "hypo_tests = [pyhf.infer.hypotest(mu, data, pdf, pdf.config.suggested_init(), pdf.config.suggested_bounds(),\n",
     "                                 return_expected_set=True, return_test_statistics=True)\n",
     "              for mu in mu_tests]\n",
     "\n",