Generalize inheritance and composition of model classes

[michaelosthege]

This PR refactors the model classes such ultimately code duplication is reduced.

The full reasoning behind this inheritance/composition design is described in a new documentation page.

Changes

Docs (done with #14)

• Sphinx was configured to also render Markdown pages.
• A Markdown document explaining the model classes, inheritance and distribution/noisemodel mixins was added.

Utils (done with #14)

• The HAS_PYMC constant is now exposed as calibr8.HAS_PYMC. And the pm module may be accessed via calibr8.utils.pm.

Generalization of noise model (see #16)

• Implement calibr8.core.DistributionMixin and a few calibr8.*Noise classes.
• Update inheritance of existing contrib models to use mixins.
• Refactor BaseModelT.loglikelihood to be distribution-agnostic.
• Move BaseModelT.loglikelihood → CalibrationModel.loglikelihood.
• Refactor (log)likelihood to slice correctly independent of ndim(x).

Inference type and dimensionality

• Split InferenceResult into subclasses.
• Introduce ContinuousUnivariateModel and ContinuousMultivariateModel model subclasses with infer_independent implementations.
• Update contrib models to inherit from model subclasses.

Tests (see #17)

• Close multiple tests coverage gaps & fix some bugs in the test code.
• Reorganize the test suite to correspond to the class hierarchy.
• Add x- & y-parameterized shape broadcasting tests for the log-likelihood implementation. (deferred to Standardize the loglikelihood and likelihood shape broadcasting #15)

Addition of examples (deferred to follow-up)

• Univariate, continuous with Laplace noise
• Univariate, discrete with Poisson noise
• Bivarite, continuous with Normal noise

[codecov-commenter]

Codecov Report

Merging #12 (70a26c6) into master (7d1b7a4) will increase coverage by 3.14%.
The diff coverage is 99.33%.

@@            Coverage Diff             @@
##           master      #12      +/-   ##
==========================================
+ Coverage   93.67%   96.81%   +3.14%     
==========================================
  Files           5        6       +1     
  Lines         664      723      +59     
==========================================
+ Hits          622      700      +78     
+ Misses         42       23      -19     

Impacted Files	Coverage Δ
calibr8/core.py	99.71% <98.88%> (+3.99%)	⬆️
calibr8/__init__.py	100.00% <100.00%> (+33.33%)	⬆️
calibr8/contrib/base.py	100.00% <100.00%> (+3.88%)	⬆️
calibr8/contrib/noise.py	100.00% <100.00%> (ø)
calibr8/utils.py	90.47% <100.00%> (+0.06%)	⬆️

---

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 7d1b7a4...70a26c6. Read the comment docs.

[lhelleckes]

I think a good point to split would be the noise refactoring, which is a big enough change to stand for itself. I would for sure split the docs etc. because they need to be changed when everything else is done.

I added two comment here already, I hope that doesn't confuse you. For a detailed review, I would split it in three smaller PRs:

Noise-related, InferenceResult-related and documentation-related changes.

[lhelleckes]

You also asked for weaknesses: except for the (probably) unnecessary subclass that I commented on above, I think we should clarify how the distributions would work in the discrete case. I think it's okay that this is not implemented for the first publication, but it should be clarified at least (that is also a nice outlook for the paper).

[lhelleckes]

OK