feat: Add contrib module (#694)

* Add pyhf.contrib
* Add pyhf.contrib.viz.brazil for POI scan "Brazil band" plots

Author: lukasheinrich

.github/workflows/ci.yml

@@ -41,7 +41,11 @@ jobs:
         check-manifest
     - name: Test with pytest
       run: |
-        python -m pytest -r sx --ignore tests/benchmarks/ --ignore tests/test_notebooks.py
+        python -m pytest -r sx --ignore tests/benchmarks/ --ignore tests/contrib --ignore tests/test_notebooks.py
+    - name: Test Contrib
+      if: matrix.python-version != 2.7
+      run: |
+        python -m pytest -r sx tests/contrib --mpl --mpl-baseline-path tests/contrib/baseline
     - name: Report coverage with Codecov
       if: github.event_name == 'push' && matrix.python-version == 3.7 && matrix.os == 'ubuntu-latest'
       uses: codecov/codecov-action@v1.0.4

CONTRIBUTING.md

@@ -30,7 +30,7 @@ We recommend first reading the "[Developing](https://scikit-hep.org/pyhf/develop
 You can install the development environment (which includes a number of extra) libraries and all others needed to run the tests via `pip`:
 
 ```
-pip install --ignore-installed -U -e .[complete]
+python -m pip install --ignore-installed -U -e .[complete]
 ```
 
 To make the PR process much smoother we also strongly recommend that you setup the Git pre-commit hook for [Black](https://github.com/psf/black) by running
@@ -46,16 +46,24 @@ This will run `black` over your code each time you attempt to make a commit and
 You can run the unit tests (which should be fast!) via the following command.
 
 ```
-pytest --ignore=tests/test_notebooks.py
+python -m pytest --ignore=tests/test_notebooks.py
 ```
 
 Note: This ignores the notebook tests (which are run via [papermill](https://github.com/nteract/papermill) which run somewhat slow.
 Make sure to run the complete suite before submitting a PR
 
 ```
-pytest
+python -m pytest
 ```
 
 ## Making a pull request
 
 We try to follow [Conventional Commit](https://www.conventionalcommits.org/) for commit messages and PR titles. Since we merge PR's using squash commits, it's fine if the final commit messages (proposed in the PR body) follow this convention.
+
+## Generating Reference Visuals
+
+New baseline visuals can be generated using this command:
+
+```
+python -m pytest tests/contrib/test_viz.py --mpl-generate-path=tests/contrib/baseline
+```

docs/examples/notebooks/Recast.ipynb

@@ -21,18 +21,21 @@
         + extras_require['minuit']
     )
 )
+extras_require['contrib'] = sorted(set(['matplotlib']))
 
 extras_require['test'] = sorted(
     set(
         extras_require['backends']
         + extras_require['xmlio']
+        + extras_require['contrib']
         + [
             'pyflakes',
             'pytest~=3.5',
             'pytest-cov>=2.5.1',
             'pytest-mock',
             'pytest-benchmark[histogram]',
             'pytest-console-scripts',
+            'pytest-mpl',
             'pydocstyle',
             'coverage>=4.0',  # coveralls
             'papermill~=1.0',

setup.py

@@ -0,0 +1,15 @@
+import numpy as np
+
+
+def plot_results(ax, mutests, tests, test_size=0.05):
+    cls_obs = np.array([test[0] for test in tests]).flatten()
+    cls_exp = [np.array([test[1][i] for test in tests]).flatten() for i in range(5)]
+    ax.plot(mutests, cls_obs, c='black')
+    for idx, color in zip(range(5), 5 * ['black']):
+        ax.plot(
+            mutests, cls_exp[idx], c=color, linestyle='dotted' if idx != 2 else 'dashed'
+        )
+    ax.fill_between(mutests, cls_exp[0], cls_exp[-1], facecolor='yellow')
+    ax.fill_between(mutests, cls_exp[1], cls_exp[-2], facecolor='green')
+    ax.plot(mutests, [test_size] * len(mutests), c='red')
+    ax.set_ylim(0, 1)

src/pyhf/contrib/__init__.py

@@ -0,0 +1 @@
+{"testmus": [0.0, 0.10204081632653061, 0.20408163265306123, 0.30612244897959184, 0.40816326530612246, 0.5102040816326531, 0.6122448979591837, 0.7142857142857143, 0.8163265306122449, 0.9183673469387755, 1.0204081632653061, 1.1224489795918369, 1.2244897959183674, 1.3265306122448979, 1.4285714285714286, 1.5306122448979593, 1.6326530612244898, 1.7346938775510203, 1.836734693877551, 1.9387755102040818, 2.0408163265306123, 2.142857142857143, 2.2448979591836737, 2.3469387755102042, 2.4489795918367347, 2.5510204081632653, 2.6530612244897958, 2.7551020408163267, 2.857142857142857, 2.9591836734693877, 3.0612244897959187, 3.163265306122449, 3.2653061224489797, 3.36734693877551, 3.4693877551020407, 3.5714285714285716, 3.673469387755102, 3.7755102040816326, 3.8775510204081636, 3.979591836734694, 4.081632653061225, 4.183673469387755, 4.285714285714286, 4.387755102040816, 4.4897959183673475, 4.591836734693878, 4.6938775510204085, 4.795918367346939, 4.8979591836734695, 5.0], "results": [[[1.0], [[1.0], [1.0], [1.0], [1.0], [1.0]]], [[0.9198048796027511], [[0.8003523766783294], [0.8657880813773585], [0.926500181496301], [0.9722472257361765], [0.9944112824414663]]], [[0.839100236039747], [[0.6362840632800341], [0.7448633382365591], [0.8538943429856678], [0.9421898843604899], [0.9877751824407214]]], [[0.7606196387599321], [[0.5024873104445834], [0.636782112242942], [0.7827699523208475], [0.909919271128208], [0.9799665144370904]]], [[0.6853439815973553], [[0.3942041873353143], [0.5409455217406552], [0.7136723054183196], [0.8755703375481869], [0.9708602114272193]]], [[0.6138817549208604], [[0.3072260710327589], [0.45663167885281464], [0.6470918402063681], [0.8393201200694193], [0.9603345105978371]]], [[0.5466520191208533], [[0.2378784124718112], [0.38302924193596943], [0.5834548849065089], [0.8013851091832367], [0.9482745624221375]]], [[0.48393854921668633], [[0.18299207886208488], [0.31926897681080985], [0.5231169298527711], [0.7620171889976247], [0.9345762654941722]]], [[0.4259129951575223], [[0.13986547982094094], [0.2644524618105127], [0.4663585482264142], [0.7214982740466017], [0.9191501826101015]]], [[0.3726492974103388], [[0.10622126569122098], [0.21767760055616822], [0.4133842991235831], [0.6801341188872082], [0.9019254929889814]]], [[0.324134968440125], [[0.0801598207718221], [0.17805956847572404], [0.36432342061761336], [0.6382467929422038], [0.8828535159466979]]], [[0.2802826370010205], [[0.06011303743570278], [0.14474849551794217], [0.31923361022331365], [0.5961672556054145], [0.8619110821713235]]], [[0.24094129458876343], [[0.044799203968964564], [0.11694269839261567], [0.2781062808126321], [0.554227459792468], [0.839103268190989]]], [[0.20590762526465403], [[0.03318060147343553], [0.09389796817961733], [0.24087302780230613], [0.5127522224511009], [0.8144652230085557]]], [[0.17493740383079923], [[0.024424968565718866], [0.07493391202774118], [0.20741391307720602], [0.4720522490535773], [0.7880635643815863]]], [[0.14775646808403214], [[0.017870763750423062], [0.05943682476153367], [0.177565750586129], [0.432417188404156], [0.7599965112906026]]], [[0.12407086541355851], [[0.012996765359831016], [0.04686022994211607], [0.15113094295981705], [0.3941098832017428], [0.7303931936507014]]], [[0.10357617371973486], [[0.009395813271700262], [0.036723340912297585], [0.12788616499544864], [0.3573616510935654], [0.6994119514819113]]], [[0.08596569270375912], [[0.006752496844131013], [0.02860795800326225], [0.10759064325288482], [0.3223687654330649], [0.6672376867319805]]], [[0.0709374216394394], [[0.00482446744164985], [0.022154244489946354], [0.08999378816812222], [0.2892901915247313], [0.6340783480160386]]], [[0.058199773032195874], [[0.003426994895083505], [0.017055773555718756], [0.074841997024345], [0.25824657007000956], [0.6001606640018293]]], [[0.04747604727364194], [[0.002420364375345894], [0.013054182906446518], [0.06188451459272328], [0.22932039417100172], [0.5657252835183778]]], [[0.03850771803030073], [[0.0016997122016359349], [0.009933711214571046], [0.05087829297665413], [0.20255727356333936], [0.5310215022328496]]], [[0.03105664481410004], [[0.00118692083072342], [0.007515834855271883], [0.04159185839058891], [0.1779681814257332], [0.4963018290001926]]], [[0.02490627119916336], [[0.000824220651464575], [0.0056541436264246295], [0.033808139135974996], [0.15553228882784403], [0.4618162675902134]]], [[0.019862101748736594], [[0.000569199867370171], [0.004229617346688932], [0.027326526178190758], [0.13520073732229348], [0.4278072694464786]]], [[0.01575140805686649], [[0.00039093951947880614], [0.003146304413200575], [0.02196400555193567], [0.11690048999628666], [0.3945046049800572]]], [[0.012422447143851966], [[0.0002670555938279746], [0.0023274842855307], [0.01755565546170874], [0.10053855227881175], [0.362120969813859]]], [[0.009743273637234796], [[0.00018145328237073458], [0.0017123013275989515], [0.013954554632715678], [0.08600621292199703], [0.33084821302085293]]], [[0.00760027656199083], [[0.00012263731319204978], [0.0012528590110264595], [0.011031229687760503], [0.07318318330467101], [0.3008543236759697]]], [[0.005896547447072741], [[8.24514971752238e-05], [0.0009117462783394886], [0.008672752749700292], [0.06194150902423138], [0.2722812366107402]]], [[0.004550169506102278], [[5.514624090971646e-05], [0.0006599588365318749], [0.00678159108485563], [0.05214915444399073], [0.24524348077869182]]], [[0.003492500512234848], [[3.6694240736866264e-05], [0.0004751732958366533], [0.0052742985892608365], [0.043673188280370534], [0.2198276577852224]]], [[0.00266650555608078], [[2.4292238547835243e-05], [0.00034033044946228755], [0.004080125478446557], [0.03638252488064445], [0.19609270569579706]]], [[0.002025180833799833], [[1.600101946691112e-05], [0.00024248475852828156], [0.0031396086822460686], [0.030150200274013036], [0.1740708755490746]]], [[0.0015300963708547715], [[1.0487233189895942e-05], [0.00017187952959158592], [0.0024031919853666037], [0.024855183538312765], [0.15376932633857215]]], [[0.0011500743611148592], [[6.839586378255383e-06], [0.00012121073853978906], [0.0018299124611080803], [0.020383741810117033], [0.1351722288366443]]], [[0.0008600106495896109], [[4.4389136204515726e-06], [8.504648287251544e-05], [0.0013861786280161537], [0.016630391184628373], [0.11824325988281767]]], [[0.0006398397298317391], [[2.866972945097033e-06], [5.9373266440080945e-05], [0.001044656227874989], [0.013498475751348918], [0.10292836623111547]]], [[0.0004736382856648849], [[1.8428604240826888e-06], [4.124447285040656e-05], [0.0007832696599424016], [0.010900423351399248], [0.08915868032101311]]], [[0.0003488586838408561], [[1.1789764184315034e-06], [2.8510297478967586e-05], [0.0005843210315402952], [0.008757731481870704], [0.07685348928911641]]], [[0.0002556807812834516], [[7.507284830334185e-07], [1.9611888621817164e-05], [0.0004337229907957642], [0.007000725156380685], [0.06592310103181603]]], [[0.0001864710166233493], [[4.7582490265229354e-07], [1.3425776599915986e-05], [0.00032034116364441906], [0.005568159404360973], [0.05627165587182177]]], [[0.0001353343750084471], [[3.002057703012116e-07], [9.147073838729912e-06], [0.00023543502100253894], [0.004406684138062113], [0.04779965648672459]]], [[9.774785355062994e-05], [[1.8854689423100252e-07], [6.2025179028550665e-06], [0.00017218924860468084], [0.0034702322077145033], [0.040406276759163674]]], [[7.026311780295228e-05], [[1.1788780511789333e-07], [4.186172290469588e-06], [0.00012532458571138945], [0.002719358725828326], [0.03399137475697942]]], [[5.026751146919708e-05], [[7.33817374779526e-08], [2.8122207451169707e-06], [9.077795831886747e-05], [0.0021205624274258745], [0.02845719810232286]]], [[3.579363233151248e-05], [[4.547753868303434e-08], [1.8805496464357448e-06], [6.544206547534791e-05], [0.0016456128601341745], [0.023709777349454543]]], [[2.536887092754408e-05], [[2.8061817254111096e-08], [1.2518231332945299e-06], [4.695529295488039e-05], [0.0012709017172559528], [0.019660014769259153]]], [[1.7897483033223352e-05], [[1.7241074143798466e-08], [8.295516626664989e-07], [3.353370443387253e-05], [0.000976831665501647], [0.01622448564522934]]]]}

src/pyhf/contrib/viz/__init__.py

@@ -0,0 +1,15 @@
+import pytest
+import json
+import pyhf.contrib.viz.brazil as brazil
+import matplotlib.pyplot as plt
+import numpy as np
+from matplotlib.testing.decorators import image_comparison
+
+
+@pytest.mark.mpl_image_compare
+def test_brazil():
+    data = json.load(open('tests/contrib/hypotestresults.json'))
+    fig, ax = plt.subplots(1, 1)
+    testmus = np.linspace(0, 5)
+    brazil.plot_results(ax, data['testmus'], data['results'], test_size=0.05)
+    return fig