feat: Add AsymptoticCalculator

[lukasheinrich]

Description

Another in the series of #709 .

This introduces the AsymptoticCalculator

Checklist Before Requesting Reviewer

• Tests are passing
• "WIP" removed from the title of the pull request
• Selected an Assignee for the PR to be responsible for the log summary

Before Merging

For the PR Assignees:

• Summarize commit messages into a comprehensive review of the PR

* Add an 'infer.calculators' API giving an asymptotic calculator and asymptotic test stat distribution
* Move calculator functions from 'infer.utils' to 'infer.calculators'

[lgtm-com]

This pull request introduces 2 alerts when merging f8e6bda into a508732 - view on LGTM.com

new alerts:

• 2 for Unused local variable

[codecov]

Codecov Report

Merging #750 into master will increase coverage by <.01%.
The diff coverage is 98.41%.

@@            Coverage Diff             @@
##           master     #750      +/-   ##
==========================================
+ Coverage   95.33%   95.33%   +<.01%     
==========================================
  Files          54       54              
  Lines        2982     3004      +22     
  Branches      425      426       +1     
==========================================
+ Hits         2843     2864      +21     
- Misses         94       95       +1     
  Partials       45       45

Flag	Coverage Δ
#unittests	95.33% <98.41%> (ø)	⬆️

Impacted Files	Coverage Δ
src/pyhf/infer/__init__.py	100% <100%> (ø)	⬆️
src/pyhf/infer/calculators.py	97.95% <97.95%> (ø)

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update e3f0eb3...2f828d3. Read the comment docs.

[matthewfeickert]

I think overall this is really nice, so thanks! No functional issues with the code from me, but it would be nice if the docstrings could be improved to match the style of the existing docs like the tensor backends. In addition to formatting changes it would also help if examples were added. I would offer to make these changes that I'm asking for, but I realistically won't get to them until after my talk is written (which will be Wednesday).

[lukasheinrich]

@matthewfeickert if you can push your changes that'd be nice

[matthewfeickert]

While trying to get the docs to show the full signatures and docstrings:

.. autosummary::
   :toctree: _generated/
   :nosignatures:
   :template: modifierclass.rst

I'm getting the following warnings (which we treat as errors) when I try to build the docs:

WARNING: error while formatting arguments for pyhf.infer.calculators.generate_asimov_data: 'function' object has no attribute '__mro__'
WARNING: error while formatting arguments for pyhf.infer.hypotest: 'function' object has no attribute '__mro__'
WARNING: error while formatting arguments for pyhf.infer.mle.fit: 'function' object has no attribute '__mro__'
WARNING: error while formatting arguments for pyhf.infer.mle.fixed_poi_fit: 'function' object has no attribute '__mro__'
WARNING: error while formatting arguments for pyhf.infer.mle.twice_nll: 'function' object has no attribute '__mro__'
WARNING: error while formatting arguments for pyhf.infer.test_statistics.qmu: 'function' object has no attribute '__mro__'

which I believe is happening as __mro__ only exists on the class, and these functions exist in the source code outside of a class definition. Thoughts on how to avoid/fix this?

[lgtm-com]

This pull request introduces 1 alert and fixes 1 when merging ca360aa into 7c3ba2e - view on LGTM.com

new alerts:

• 1 for Module imports itself

fixed alerts:

• 1 for Module imports itself

[lgtm-com]

This pull request introduces 1 alert and fixes 1 when merging 09cd082 into aa25803 - view on LGTM.com

new alerts:

• 1 for Module imports itself

fixed alerts:

• 1 for Module imports itself

[lgtm-com]

This pull request introduces 1 alert and fixes 1 when merging 68d6a3c into aa25803 - view on LGTM.com

new alerts:

• 1 for Module imports itself

fixed alerts:

• 1 for Module imports itself

[matthewfeickert]

I think since the problem with the docs is roughly documented in Issue #761 that we can just go ahead and review this.

[matthewfeickert]

This LGTM now. Thanks @lukasheinrich for both the useful PR and for your extreme patience with how long this took to review again.

[kratsg]

Overall, I like the refactoring. There's still more to digest here and clean-up.

[lgtm-com]

This pull request introduces 1 alert and fixes 1 when merging 9a9d6ef into e3f0eb3 - view on LGTM.com

new alerts:

• 1 for Module imports itself

fixed alerts:

• 1 for Module imports itself

[lgtm-com]

This pull request introduces 1 alert and fixes 1 when merging 9c69fb5 into e3f0eb3 - view on LGTM.com

new alerts:

• 1 for Module imports itself

fixed alerts:

• 1 for Module imports itself

[lgtm-com]

This pull request introduces 1 alert and fixes 1 when merging 2f828d3 into e3f0eb3 - view on LGTM.com

new alerts:

• 1 for Module imports itself

fixed alerts:

• 1 for Module imports itself