add example in doc

.gitignore

@@ -2,6 +2,7 @@ MANIFEST
 dist/*
 doc/build/*
 doc/source/_autosummary/*
+doc/source/savefig/*
 */__pycache__/*
 *.egg-info
 other/*

doc/source/conf.py

@@ -11,13 +11,14 @@ author = 'Jean-Baptiste Delisle'
 needs_sphinx = '1.1'
 extensions = [
   'sphinx.ext.autodoc', 'sphinx.ext.autosummary', 'sphinx.ext.intersphinx',
-  'sphinx.ext.coverage', 'numpydoc'
+  'sphinx.ext.coverage', 'numpydoc',
+  'IPython.sphinxext.ipython_console_highlighting',
+  'IPython.sphinxext.ipython_directive'
 ]
 templates_path = ['_templates']
 exclude_patterns = []
 pygments_style = 'sphinx'
 autosummary_generate = True
-plot_include_source = True
 
 # -- Options for HTML output -------------------------------------------------
 html_theme_path = ['_theme']

doc/source/index.rst

@@ -2,7 +2,14 @@
 sam documentation
 =================
 
-Todo
+The sam package provides two samplers:
+
+- a Scaled Adaptive Metropolis algorithm (:doc:`_autosummary/sam.sam`), to robustly obtain samples from a target distribution,
+- a COVariance Importance Sampling algorithm (:doc:`_autosummary/sam.covis`), to efficiently compute the model evidence (or other integrals).
+
+It additionally includes tools (:doc:`_autosummary/sam.acf`)
+to assess the convergence of the sam sampler (ACF, IAT),
+and a few commonly used prior distributions (:doc:`_autosummary/sam.logprior`).
 
 Installation
 ------------
@@ -15,15 +22,66 @@ and upgraded with
 
 ``pip install --extra-index-url https://obswww.unige.ch/~delisle sam --upgrade``
 
-Usage
------
-
-Todo
-
 Example
 -------
 
-Todo
+Let us first define a simple log-probability function:
+
+.. ipython::
+
+   In [1]: import numpy as np
+      ...: import matplotlib.pyplot as plt
+      ...: from sam import sam, covis, acf
+      ...: from corner import corner
+      ...: np.random.seed(0)
+      ...:
+      ...: def logprob(x):
+      ...:     return(-0.5*(np.sum(x**2) + x.size*np.log(2*np.pi)))
+
+Then we run sam to sample this distribution:
+
+.. ipython::
+
+   In [2]: ndim = 10
+      ...: nsamples = 100000
+      ...: x0 = np.random.normal(0, 100, ndim)
+      ...:
+      ...: samples, sam_diagnos = sam(x0, logprob, nsamples=nsamples, print_level=0)
+      ...: samples = samples[nsamples//4:]
+
+Let us check that sam converged correctly using the ACF/IAT:
+
+.. ipython::
+
+   @savefig acf.png
+   In [3]: R = acf.acf(samples)
+      ...: tau = np.arange(samples.shape[0])
+      ...:
+      ...: plt.figure()
+      ...: plt.plot(tau[1:], R[1:])
+      ...: plt.xscale('log')
+      ...: plt.xlim(1, samples.shape[0])
+      ...: plt.xlabel('lag')
+      ...: plt.ylabel('ACF')
+      ...:
+      ...: iat = acf.iat(R=R)
+      ...: print('IAT:', iat.max())
+      ...: print('Effective number of samples:', samples.shape[0]/iat.max())
+
+Now we plot the corner plot of the parameter samples:
+
+.. ipython::
+
+   @savefig corner.png
+   In [4]: corner(samples);
+
+Finally we run covis to compute the log-evidence of the model:
+
+.. ipython::
+
+   In [5]: _, _, covis_diagnos = covis(sam_diagnos['mu'], sam_diagnos['cov'], logprob, nsamples=1000, print_level=0)
+      ...: # Should be close to 0 since the logprob is correctly normalized
+      ...: print('Log-evidence:', covis_diagnos['logevidence'])
 
 API Reference
 -------------

sam_env.yml

@@ -8,3 +8,6 @@ dependencies:
    - pytest
    - sphinx
    - numpydoc
+   - matplotlib
+   - ipython
+   - corner
\ No newline at end of file