Major docs update

docs/analyse.rst

@@ -18,13 +18,15 @@ On this page we continue with analysis methods using same example::
     names = ["a", "b", "c"]
     mn = MultiNorm(mean, covariance, names)
 
+.. _analyse-scipy:
+
 Scipy
 -----
 
-For most computations, `Multinorm` uses `scipy`_. The :meth:`~MultiNorm.scipy`
-property is a frozen `scipy.stats.multivariate_normal`_ object. It is cached,
+For most computations, `MultiNorm` uses `scipy`_. The `MultiNorm.scipy`
+property is a frozen `scipy.stats.multivariate_normal` object. It is cached,
 accessing it multiple times doesn't incur any extra computations.
-Note that `scipy.stats.multivariate_normal`_ has a ``cov_info`` object,
+Note that `scipy.stats.multivariate_normal` has a ``cov_info`` object,
 which contains a covariance matrix decomposition which is computed once and
 cached. It is at this time undocumented, but it is a public property
 and is what powers most computations in the scipy and in this class.
@@ -37,9 +39,9 @@ and is what powers most computations in the scipy and in this class.
 
 
 To present a consistent and complete API, `MultiNorm` re-exposes the functionality
-of `scipy.stats.multivariate_normal`_, it is a wrapper.
+of `scipy.stats.multivariate_normal`, it is a wrapper.
 
-Draw random samples from the distribution using :meth:`~MultiNorm.sample`::
+Draw random samples from the distribution using `MultiNorm.sample`::
 
     >>> points = mn.sample(size=2, random_state=0)
     >>> points
@@ -48,19 +50,21 @@ Draw random samples from the distribution using :meth:`~MultiNorm.sample`::
 
 Points are always given as arrays with shape ``(n_dim, n_points)``.
 
-Evaluate the probability density function (PDF), call :meth:`~MultiNorm.pdf`::
+Evaluate the probability density function (PDF), call `MultiNorm.pdf`::
 
     >>> mn.pdf(points)
     array([1.27661616e-03, 9.31966590e-05])
 
-For ``log(pdf)`` (natural logarithm), call :meth:`~MultiNorm.logpdf`::
+For ``log(pdf)`` (natural logarithm), call `MultiNorm.logpdf`::
 
     >>> mn.logpdf(points)
     array([-6.66354232, -9.28079868])
 
 There is also a ``cdf`` and ``logcdf`` method for the cumulative distribution function,
 as well as ``entropy``. Since these are rarely needed, we didn't wrap them. But you
-can still access them via the :meth:`~MultiNorm.scipy` property.
+can still access them via the `MultiNorm.scipy` property.
+
+.. _analyse-marginal:
 
 Marginal
 --------
@@ -72,18 +76,18 @@ TODO: marginal
 Conditional
 -----------
 
-TODO: conditional
-
-.. _analyse-scipy:
+TODO: document `MultiNorm.conditional`
 
+.. _analyse-error:
 
 Error propagation
 -----------------
 
-TODO: to_uncertainties, to_soerp, to_mcerp
+TODO: document `MultiNorm.to_uncertainties`
 
+.. _analyse-sigma:
 
 Sigmas
 ------
 
-TODO: sigma_distance
+TODO: document `MultiNorm.sigma_distance`

docs/changes.rst

@@ -21,9 +21,9 @@ at https://pypi.org/project/multinorm/
 
 - Released Oct 26, 2018
 - API now mostly uses pandas objects, pandas is now a core dependency
-- `MultiNorm` is now full of cached properties, must be used read-only
+- ``MultiNorm`` is now full of cached properties, must be used read-only
 - Many methods added and improved, more tests and docs
-- Added a tutorial notebook `multinorm.ipynb`
+- Added a tutorial notebook ``multinorm.ipynb``
 - Dropped Python 2 support, require Python 3.6 or later
 
 .. _v0.1:

docs/conf.py

@@ -170,14 +170,20 @@
 intersphinx_mapping = {
     "https://docs.python.org/": None,
     "https://docs.scipy.org/doc/numpy/": None,
+    "https://docs.scipy.org/doc/scipy/reference/": None,
+    "https://dev.pandas.io/docs/": None,
+    "http://xarray.pydata.org/en/stable/": None,
+    "https://matplotlib.org/": None,
 }
 
 # This is to get rid of incorrect Sphinx warnings from classmethods
 # See https://stackoverflow.com/questions/12206334
-numpydoc_show_class_members = False
+# numpydoc_show_class_members = False
 
+# https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html#configuration
+napoleon_google_docstring = False
 napoleon_use_rtype = False
 
 html_show_sphinx = False
-
 nitpicky = True
+default_role = "py:obj"

docs/contribute.rst

@@ -13,7 +13,7 @@ Please give feedback to help make it better!
 Github
 ------
 
-Contributions to `multinorm` are welcome any time
+Contributions to ``multinorm`` are welcome any time
 on Github: https://github.com/cdeil/multinorm
 
 - If you find an issue, please file a bug report.

docs/create.rst

@@ -21,15 +21,15 @@ On this page, we look at the most common scenarios.
 
 .. _create_from_fit:
 
-From fit
---------
+Create from fit
+---------------
 
-TODO: show example using scipy.optimise.curve_fit`
+TODO: show example using `scipy.optimize.curve_fit`
 
 To use ``multinorm``, we first need to fit some parameterised model
 to obtain a best-fit parameter vector and covariance matrix.
 
-Let's use `scipy.optimize_curve_fit`_ to fit some data.
+Let's use `scipy.optimize.curve_fit` to fit some data.
 
 TODO: show example using iminuit
 
@@ -39,10 +39,18 @@ https://lmfit.github.io
 https://iminuit.readthedocs.io
 https://sherpa.readthedocs.io
 
+.. _create_from_pub:
+
+Create from publication
+-----------------------
+
+TODO: show example how to take covar (or par errors) from a
+publication or blog post, i.e. as inputs.
+
 .. _create_from_samples:
 
-From samples
-------------
+Create from samples
+-------------------
 
 A common way to analyse likelihood or in Bayesian analyses the
 posterior probability distributions is to use MCMC methods that
@@ -53,8 +61,8 @@ Estimating the multivariate normal distribution from samples well
 can be difficult, there are many methods with different trade-offs.
 We recommend using a different package for this task, e.g. `sklearn.covariance`_.
 
-That said, there is a method :meth:`MultiNorm.from_samples` that calls :func:`numpy.std`
-to compute the mean vector, and :func:`numpy.cov` to compute what's sometimes called
+That said, there is a method `MultiNorm.from_samples` that calls `numpy.std`
+to compute the mean vector, and `numpy.cov` to compute what's sometimes called
 the "empirical" multivariate normal estimate.
 
 Samples should always be given as 2-dimensional arrays with shape ``(n_dim, n_samples)``.
@@ -70,31 +78,23 @@ Samples should always be given as 2-dimensional arrays with shape ``(n_dim, n_sa
     b     20.212505  1.973948
     c     30.301562  3.093609
 
-.. _create_from_pub:
-
-From publication
-----------------
-
-TODO: show example how to take covar (or par errors) from a
-publication or blog post, i.e. as inputs.
-
 .. _create_from_stack:
 
 From stack
 ----------
 
-TODO: document :meth:`MultiNorm.from_stack`
+TODO: document `MultiNorm.from_stack`
 
 .. _create_from_product:
 
 From product
 ------------
 
-TODO: document :meth:`MultiNorm.from_product`
+TODO: document `MultiNorm.from_product`
 
 .. _create_make_example:
 
 Make example
 ------------
 
-TODO: document :meth:`MultiNorm.make_example`
+TODO: document `MultiNorm.make_example`

docs/install.rst

@@ -22,7 +22,7 @@ This will install the required dependencies if you don't have them already:
 
 There are some built-in methods for plotting using `matplotlib`_.
 That optionally dependency has to be installed separately,
-`pip install multinorm` will not install matplotlib.
+``pip install multinorm`` will not install matplotlib.
 
 This package consists of a single Python file `multinorm.py`_.
 Most users will not care about this implementation detail,

docs/quickstart.rst

@@ -14,7 +14,7 @@ Getting started
 Import
 ------
 
-The `multinorm` package offers a single class :class:`MultiNorm`,
+The ``multinorm`` package offers a single class `MultiNorm`,
 so you always start like this::
 
     from multinorm import MultiNorm
@@ -40,7 +40,7 @@ and you would define them in Python code as shown here, or read them from a file
 However, often you obtain these values as the result of a fit of a parametrised
 model to data, or estimate them in some other way.
 
-Further examples to create :class:`MultiNorm` objects are here: :ref:`create`
+Further examples to create `MultiNorm` objects are here: :ref:`create`
 
 Read only
 ---------
@@ -56,7 +56,7 @@ TODO: make read-only as much as possible, the document remaining caveats!
 Analyse
 -------
 
-Once you have a :class:`MultiNorm` object representing a multivariate normal distribution,
+Once you have a `MultiNorm` object representing a multivariate normal distribution,
 you can access the following properties and methods to analyse it.
 
 The object repr only shows the number of dimensions (number of parameters)
@@ -106,19 +106,19 @@ The ``mean`` is a 1-dimensional array, and ``cov`` is a 2-dimensional array:
     >>> mn.cov.shape
     (3, 3)
 
-Parameter error vector :meth:`~MultiNorm.err`::
+Parameter error vector `MultiNorm.err`::
 
     >>> mn.err
     array([1., 2., 3.])
 
-Precision matrix (the inverse covariance) :meth:`~MultiNorm.precision`:
+Precision matrix (the inverse covariance) `MultiNorm.precision`:
 
     >>> mn.precision
     array([[1.        , 0.        , 0.        ],
            [0.        , 0.25      , 0.        ],
            [0.        , 0.        , 0.11111111]])
 
-Correlation matrix :meth:`~MultiNorm.correlation`:
+Correlation matrix `MultiNorm.correlation`:
 
     >>> mn.correlation
     array([[1., 0., 0.],
@@ -128,20 +128,20 @@ Correlation matrix :meth:`~MultiNorm.correlation`:
 These are just the basic attributes and properties.
 
 We continue with this example on the :ref:`analyse` page and show
-how to really do some analysis with :class:`MultiNorm` objects and methods.
+how to really do some analysis with `MultiNorm` objects and methods.
 
 .. _gs_plot:
 
 Plot
 ----
 
-Plot ellipse using :meth:`~MultiNorm.to_matplotlib_ellipse`::
+Plot ellipse using `MultiNorm.to_matplotlib_ellipse`::
 
     import matplotlib.pyplot as plt
     mn2 = mn.marginal()
     mn2.plot()
 
-Further examples to plot :class:`MultiNorm` objects are here: :ref:`plot`
+Further examples to plot `MultiNorm` objects are here: :ref:`plot`
 
 What next?
 ----------
@@ -150,7 +150,7 @@ The :ref:`create`, :ref:`analyse` and :ref:`plot` tutorial pages contain
 further examples. The :ref:`theory` and :ref:`ref` pages contain background
 information and definitions, as well as links to other documents and codes.
 
-The full API documentation is here: :class:`MultiNorm`.
+The full API documentation is here: `MultiNorm`.
 Note that you can click on "source" on the right for any method or property,
 and read the implementation to see what exactly it does.
 It's usually a few lines of straightforward code using Python and Numpy,

docs/reference.rst

@@ -32,10 +32,8 @@ Codes
 Other codes related to multivariate normal distributions:
 
 - `Wolfram MultinormalDistribution`_
-- `numpy.random.multivariate_normal`_
-- `scipy.stats.multivariate_normal`_
+- `numpy.random.Generator.multivariate_normal`
+- `scipy.stats.multivariate_normal`
 - `sklearn.covariance`_
 - `uncertainties`_
 - `statsmodels`_
-
-

docs/references.txt

@@ -7,10 +7,7 @@
 .. _conditional distribution: https://en.wikipedia.org/wiki/Conditional_probability_distribution
 .. _stats book: https://press.princeton.edu/titles/10159.html
 .. _numpy: https://docs.scipy.org/doc/numpy/reference/
-.. _numpy.random.multivariate_normal: https://docs.scipy.org/doc/numpy/reference/generated/numpy.random.multivariate_normal.html
 .. _scipy: https://docs.scipy.org/doc/scipy/reference/
-.. _scipy.stats.multivariate_normal: https://docs.scipy.org/doc/scipy/reference/generated/scipy.stats.multivariate_normal.html
-.. _scipy.optimize_curve_fit: https://docs.scipy.org/doc/scipy/reference/generated/scipy.optimize.curve_fit.html
 .. _pandas: https://pandas.pydata.org/
 .. _matplotlib.patches.Ellipse: https://matplotlib.org/api/_as_gen/matplotlib.patches.Ellipse.html
 .. _sklearn.covariance: http://scikit-learn.org/stable/modules/covariance.html

docs/theory.rst

@@ -118,7 +118,7 @@ via the inverse Hessian:
 Marginal distribution
 ---------------------
 
-The marginal distribution can be obtained with the :meth:`~MultiNorm.marginal` method.
+The marginal distribution can be obtained with the `MultiNorm.marginal` method.
 
 You can think of the `marginal distribution`_ as the distribution obtained
 by simply ignoring some of the parameters, or by "projecting" the :math:`N`-dimensional
@@ -136,7 +136,7 @@ See `here <https://en.wikipedia.org/wiki/Multivariate_normal_distribution#Margin
 Conditional distribution
 ------------------------
 
-The conditional distribution can be obtained with the :meth:`~MultiNorm.conditional` method.
+The conditional distribution can be obtained with the `MultiNorm.conditional` method.
 
 The `conditional distribution`_ is given by the "slice" in the :math:`N`-dimensional
 distribution when fixing some of the parameters.
@@ -158,7 +158,7 @@ Fix parameters
 This method is used e.g. in MINUIT, see Section 1.3.1 here:
 http://lmu.web.psi.ch/docu/manuals/software_manuals/minuit2/mnerror.pdf
 
-As far as I can tell, it gives the same results as conditional (see `test_conditional_vs_fix`).
+As far as I can tell, it gives the same results as conditional (see ``test_conditional_vs_fix``).
 
 TODO: work out the math of why that is the case and document it here.
 
@@ -171,7 +171,7 @@ TODO: document and make example in the analyse section using iminuit.
 Stacked distribution
 --------------------
 
-TODO: document :meth:`MultiNorm.from_stack`
+TODO: document `MultiNorm.from_stack`
 
 .. _theory_product: