Merge pull request #221 from elfi-dev/dev

vuolleko · web-flow · commit 3d4fe94475f8 · 2017-08-03T15:11:58.000+03:00
Fix issue #216, add arXiv info
diff --git a/Makefile b/Makefile
@@ -73,19 +73,19 @@ CONTENT_URL := http://research.cs.aalto.fi/pml/software/elfi/docs/0.6.1/
 
 notebook-docs: ## Conver notebooks to rst docs. Assumes you have them in `notebooks` directory.
 	jupyter nbconvert --to rst ../notebooks/quickstart.ipynb --output-dir docs
-	sed -i 's|\(quickstart_files/quickstart.*\.\)|'${CONTENT_URL}'\1|g' docs/quickstart.rst
+	sed -i '' 's|\(quickstart_files/quickstart.*\.\)|'${CONTENT_URL}'\1|g' docs/quickstart.rst
 
 	jupyter nbconvert --to rst ../notebooks/tutorial.ipynb --output-dir docs/usage
-	sed -i 's|\(tutorial_files/tutorial.*\.\)|'${CONTENT_URL}usage/'\1|g' docs/usage/tutorial.rst
+	sed -i '' 's|\(tutorial_files/tutorial.*\.\)|'${CONTENT_URL}usage/'\1|g' docs/usage/tutorial.rst
 
 	jupyter nbconvert --to rst ../notebooks/BOLFI.ipynb --output-dir docs/usage
-	sed -i 's|\(BOLFI_files/BOLFI.*\.\)|'${CONTENT_URL}usage/'\1|g' docs/usage/BOLFI.rst
+	sed -i '' 's|\(BOLFI_files/BOLFI.*\.\)|'${CONTENT_URL}usage/'\1|g' docs/usage/BOLFI.rst
 
 	jupyter nbconvert --to rst ../notebooks/parallelization.ipynb --output-dir docs/usage
-	sed -i 's|\(parallelization_files/parallelization.*\.\)|'${CONTENT_URL}usage/'\1|g' docs/usage/parallelization.rst
+	sed -i '' 's|\(parallelization_files/parallelization.*\.\)|'${CONTENT_URL}usage/'\1|g' docs/usage/parallelization.rst
 
 	jupyter nbconvert --to rst ../notebooks/non_python_operations.ipynb --output-dir docs/usage --output=external
-	sed -i 's|\(external_files/external.*\.\)|'${CONTENT_URL}usage/'\1|g' docs/usage/external.rst
+	sed -i '' 's|\(external_files/external.*\.\)|'${CONTENT_URL}usage/'\1|g' docs/usage/external.rst
 
 # release: clean ## package and upload a release
 # 	python setup.py sdist upload
diff --git a/README.md b/README.md
@@ -79,3 +79,18 @@ Resolving these may sometimes go wrong:
 - On OS X with Anaconda virtual environment say `conda install python.app` and then use 
 `pythonw` instead of `python`.
 - Note that ELFI requires Python 3.5 or greater so try `pip3 install elfi`.
+
+
+Citation
+--------
+
+If you wish to cite ELFI, please use the paper in [arXiv](https://arxiv.org/abs/1708.00707):
+
+```
+@misc{1708.00707,
+Author = {Jarno Lintusaari and Henri Vuollekoski and Antti Kangasrääsiö and Kusti Skytén and Marko Järvenpää and Michael Gutmann and Aki Vehtari and Jukka Corander and Samuel Kaski},
+Title = {ELFI: Engine for Likelihood Free Inference},
+Year = {2017},
+Eprint = {arXiv:1708.00707},
+}
+```
diff --git a/docs/description.rst b/docs/description.rst
@@ -1,7 +1,9 @@
 ELFI is a statistical software package for likelihood-free inference (LFI) such as
 Approximate Bayesian Computation (ABC_). The term LFI refers to a family of inference
 methods that replace the use of the likelihood function with a data generating simulator
-function. ELFI features an easy to use generative modeling syntax and supports
-parallelized inference out of the box.
+function. Other names or related approaches to LFI include simulator-based inference,
+approximate Bayesian inference, indirect inference, etc.
+
+ELFI features an easy to use syntax and supports parallelized inference out of the box.
 
 .. _ABC: https://en.wikipedia.org/wiki/Approximate_Bayesian_computation
diff --git a/docs/index.rst b/docs/index.rst
@@ -70,7 +70,18 @@ ELFI also has the following non LFI methods:
 ..    developer/extensions
 
 
+Citation
+--------
 
+If you wish to cite ELFI, please use the paper in arXiv_:
 
-Other names or related approaches to LFI include simulator-based inference, approximate
-Bayesian inference, indirect inference, etc.
+.. _arXiv: https://arxiv.org/abs/1708.00707
+
+.. code-block:: console
+
+    @misc{1708.00707,
+    Author = {Jarno Lintusaari and Henri Vuollekoski and Antti Kangasrääsiö and Kusti Skytén and Marko Järvenpää and Michael Gutmann and Aki Vehtari and Jukka Corander and Samuel Kaski},
+    Title = {ELFI: Engine for Likelihood Free Inference},
+    Year = {2017},
+    Eprint = {arXiv:1708.00707},
+    }
diff --git a/docs/installation.rst b/docs/installation.rst
@@ -38,7 +38,7 @@ Optional dependencies
 
 We recommend to install:
 
-* ``graphviz`` for drawing graphical models (``pip install graphviz`` requires Graphviz_ binaries which are already available in many unix-like OS).
+* ``graphviz`` for drawing graphical models (``pip install graphviz`` requires Graphviz_ binaries).
 
 .. _Graphviz: http://www.graphviz.org
 
@@ -52,6 +52,7 @@ Resolving these may sometimes go wrong:
 * If you receive an error about `yaml.load`, install ``pyyaml``.
 * On OS X with Anaconda virtual environment say `conda install python.app` and then use `pythonw` instead of `python`.
 * Note that ELFI requires Python 3.5 or greater
+* In some environments ``pip`` refers to Python 2.x, and you have to use ``pip3`` to use the Python 3.x version
 
 Developer installation from sources
 -----------------------------------
diff --git a/docs/usage/external.rst b/docs/usage/external.rst
@@ -16,7 +16,7 @@ briefly demonstrates how to do this in three common scenarios:
 
 Let's begin by importing some libraries that we will be using:
 
-.. code:: python
+.. code:: ipython3
 
     import os
     import numpy as np
@@ -45,7 +45,7 @@ use ``elfi.tools.external_operation`` tool to wrap executables as a
 Python callables (function). Let's first investigate how it works with a
 simple shell ``echo`` command:
 
-.. code:: python
+.. code:: ipython3
 
     # Make an external command. {0} {1} are positional arguments and {seed} a keyword argument `seed`.
     command = 'echo {0} {1} {seed}'
@@ -70,7 +70,7 @@ Currently ``echo_sim`` only accepts scalar arguments. In order to work
 in ELFI, ``echo_sim`` needs to be vectorized so that we can pass to it a
 vector of arguments. ELFI provides a handy tool for this as well:
 
-.. code:: python
+.. code:: ipython3
 
     # Vectorize it with elfi tools
     echo_sim_vec = elfi.tools.vectorize(echo_sim)
@@ -88,9 +88,9 @@ vector of arguments. ELFI provides a handy tool for this as well:
 
 .. parsed-literal::
 
-    array([[  4.16252911e-01,   0.00000000e+00,   3.08758378e+08],
-           [  9.83011677e-01,   0.00000000e+00,   3.08758378e+08],
-           [  8.22756066e-01,   0.00000000e+00,   3.08758378e+08]])
+    array([[  1.93678222e+00,   0.00000000e+00,   7.43529055e+08],
+           [  9.43846120e-01,   0.00000000e+00,   7.43529055e+08],
+           [  2.67626618e-01,   0.00000000e+00,   7.43529055e+08]])
 
 
 
@@ -143,7 +143,7 @@ efficiently. We will now reproduce Figure 6(a) in `*Lintusaari at al
 2016* <https://doi.org/10.1093/sysbio/syw077>`__ *[2]* with ELFI. Let's
 start by defining some constants:
 
-.. code:: python
+.. code:: ipython3
 
     # Fixed model parameters
     delta = 0
@@ -156,7 +156,7 @@ start by defining some constants:
 Let's build the beginning of a new model for the birth rate
 :math:`\alpha` as the only unknown
 
-.. code:: python
+.. code:: ipython3
 
     m = elfi.ElfiModel(name='bdm')
     elfi.Prior('uniform', .005, 2, model=m, name='alpha')
@@ -170,29 +170,26 @@ Let's build the beginning of a new model for the birth rate
 
 
 
-.. code:: python
+.. code:: ipython3
 
     # Get the BDM source directory
     sources_path = elfi.examples.bdm.get_sources_path()
     
-    # Copy to resources folder and compile (unix-like systems)
-    !cp -r $sources_path resources
-    !make -C resources/cpp
+    # Compile (unix-like systems)
+    !make -C $sources_path
     
-    # Move the file in to the working directory
-    !mv ./resources/cpp/bdm .
+    # Move the executable in to the working directory
+    !mv $sources_path/bdm .
 
 
 .. parsed-literal::
 
-    make: Entering directory '/l/lintusj1/elfi-dev/notebooks/resources/cpp'
-    g++ bdm.cpp --std=c++0x -O -Wall -o bdm
-    make: Leaving directory '/l/lintusj1/elfi-dev/notebooks/resources/cpp'
+    g++ bdm.cpp --std=c++0x -O -Wall -o bdm
 
 
 .. note:: The source code for the BDM simulator comes with ELFI. You can get the directory with `elfi.examples.bdm.get_source_directory()`. Under unix-like systems it can be compiled with just typing `make` to console in the source directory. For windows systems, you need to have some C++ compiler available to compile it.
 
-.. code:: python
+.. code:: ipython3
 
     # Test the executable (assuming we have the executable `bdm` in the working directory)
     sim = elfi.tools.external_operation('./bdm {0} {1} {2} {3} --seed {seed} --mode 1')
@@ -220,7 +217,7 @@ efficient would be to write a native Python module with C++ but it's
 beyond the scope of this article. So let's work through files which is a
 fairly common situation especially with existing software.
 
-.. code:: python
+.. code:: ipython3
 
     # Assuming we have the executable `bdm` in the working directory
     command = './bdm {filename} --seed {seed} --mode 1 > {output_filename}'
@@ -272,7 +269,7 @@ informative filenames, we ask ELFI to provide the operation some meta
 information. That will be available under the ``meta`` keyword (see the
 ``prepare_inputs`` function above):
 
-.. code:: python
+.. code:: ipython3
 
     # Create the simulator
     bdm_node = elfi.Simulator(bdm, m['alpha'], delta, tau, N, observed=y_obs, name='sim')
@@ -290,7 +287,7 @@ information. That will be available under the ``meta`` keyword (see the
 
 
 
-.. code:: python
+.. code:: ipython3
 
     # Test it
     data = bdm_node.generate(3)
@@ -299,9 +296,9 @@ information. That will be available under the ``meta`` keyword (see the
 
 .. parsed-literal::
 
-    [[ 8  3  1  1  1  1  1  2  1  1  0  0  0  0  0  0  0  0  0  0]
-     [ 8  1  1  1  1  1  1  3  1  1  1  0  0  0  0  0  0  0  0  0]
-     [14  2  1  1  2  0  0  0  0  0  0  0  0  0  0  0  0  0  0  0]]
+    [[13  1  4  1  1  0  0  0  0  0  0  0  0  0  0  0  0  0  0  0]
+     [19  1  0  0  0  0  0  0  0  0  0  0  0  0  0  0  0  0  0  0]
+     [14  3  2  1  0  0  0  0  0  0  0  0  0  0  0  0  0  0  0  0]]
 
 
 Completing the BDM model
@@ -312,7 +309,7 @@ We are now ready to finish up the BDM model. To reproduce Figure 6(a) in
 *[2]*, let's add different summaries and discrepancies to the model and
 run the inference for each of them:
 
-.. code:: python
+.. code:: ipython3
 
     def T1(clusters):
         clusters = np.atleast_2d(clusters)
@@ -340,7 +337,7 @@ run the inference for each of them:
 
 
 
-.. code:: python
+.. code:: ipython3
 
     elfi.draw(m)
 
@@ -351,7 +348,7 @@ run the inference for each of them:
 
 
 
-.. code:: python
+.. code:: ipython3
 
     # Save parameter and simulation results in memory to speed up the later inference
     pool = elfi.OutputPool(['alpha', 'sim'])
@@ -370,15 +367,15 @@ run the inference for each of them:
 
 .. parsed-literal::
 
-    CPU times: user 3.86 s, sys: 52 ms, total: 3.92 s
-    Wall time: 4.81 s
-    CPU times: user 32 ms, sys: 4 ms, total: 36 ms
-    Wall time: 36.4 ms
-    CPU times: user 40 ms, sys: 0 ns, total: 40 ms
-    Wall time: 36.9 ms
+    CPU times: user 3.11 s, sys: 143 ms, total: 3.26 s
+    Wall time: 5.56 s
+    CPU times: user 29.9 ms, sys: 1.45 ms, total: 31.3 ms
+    Wall time: 31.2 ms
+    CPU times: user 33.8 ms, sys: 500 µs, total: 34.3 ms
+    Wall time: 34 ms
 
 
-.. code:: python
+.. code:: ipython3
 
     # Load a precomputed posterior based on an analytic solution (see Lintusaari et al 2016)
     matdata = sio.loadmat('./resources/bdm.mat')
@@ -426,7 +423,7 @@ Here we demonstrate how to calculate the summary statistics used in the
 ELFI tutorial (autocovariances) using R's ``acf`` function for the MA2
 model.
 
-.. code:: python
+.. code:: ipython3
 
     import rpy2.robjects as robj
     from rpy2.robjects import numpy2ri as np2ri
@@ -441,7 +438,7 @@ model.
 Let's create a Python function that wraps the R commands (please see the
 documentation of `rpy2 <http://rpy2.readthedocs.io>`__ for details):
 
-.. code:: python
+.. code:: ipython3
 
     robj.r('''
         # create a function `f`
@@ -459,7 +456,7 @@ documentation of `rpy2 <http://rpy2.readthedocs.io>`__ for details):
         ans = apply(x, 1, f, lag=lag)
         return np.atleast_1d(ans)
 
-.. code:: python
+.. code:: ipython3
 
     # Test it
     autocovR(np.array([[1,2,3,4], [4,5,6,7]]), 1)
@@ -475,7 +472,7 @@ documentation of `rpy2 <http://rpy2.readthedocs.io>`__ for details):
 
 Load a ready made MA2 model:
 
-.. code:: python
+.. code:: ipython3
 
     ma2 = elfi.examples.ma2.get_model(seed_obs=4)
     elfi.draw(ma2)
@@ -489,7 +486,7 @@ Load a ready made MA2 model:
 
 Replace the summaries S1 and S2 with our R autocovariance function.
 
-.. code:: python
+.. code:: ipython3
 
     # Replace with R autocov
     S1 = elfi.Summary(autocovR, ma2['MA2'], 1)
@@ -523,20 +520,20 @@ MATLAB function using the official `MATLAB Python cd
 API <http://www.mathworks.com/help/matlab/matlab-engine-for-python.html>`__.
 (Tested with MATLAB 2016b.)
 
-.. code:: python
+.. code:: ipython3
 
     import matlab.engine
 
 A MATLAB session needs to be started (and stopped) separately:
 
-.. code:: python
+.. code:: ipython3
 
     eng = matlab.engine.start_matlab()  # takes a while...
 
 Similarly as with R, we have to write a piece of code to interface
 between MATLAB and Python:
 
-.. code:: python
+.. code:: ipython3
 
     def euclidean_M(x, y):
         # MATLAB array initialized with Python's list
@@ -549,7 +546,7 @@ between MATLAB and Python:
         d = np.atleast_1d(dM).reshape(-1)
         return d
 
-.. code:: python
+.. code:: ipython3
 
     # Test it
     euclidean_M(np.array([[1,2,3], [6,7,8], [2,2,3]]), np.array([2,2,2]))
@@ -565,7 +562,7 @@ between MATLAB and Python:
 
 Load a ready made MA2 model:
 
-.. code:: python
+.. code:: ipython3
 
     ma2M = elfi.examples.ma2.get_model(seed_obs=4)
     elfi.draw(ma2M)
@@ -579,7 +576,7 @@ Load a ready made MA2 model:
 
 Replace the summaries S1 and S2 with our R autocovariance function.
 
-.. code:: python
+.. code:: ipython3
 
     # Replace with Matlab distance implementation
     d = elfi.Distance(euclidean_M, ma2M['S1'], ma2M['S2'])
@@ -604,7 +601,7 @@ Replace the summaries S1 and S2 with our R autocovariance function.
 
 Finally, don't forget to quit the MATLAB session:
 
-.. code:: python
+.. code:: ipython3
 
     eng.quit()
 
