Merge pull request #336 from stan-dev/randommm-patch-1

Remove pystan.stan from README.rst and other places in documentation

Author: ariddell

README.rst

@@ -100,8 +100,8 @@ Example
                    'y': [28,  8, -3,  7, -1,  1, 18, 12],
                    'sigma': [15, 10, 16, 11,  9, 11, 10, 18]}
 
-    fit = pystan.stan(model_code=schools_code, data=schools_dat,
-                      iter=1000, chains=4)
+    sm = pystan.StanModel(model_code=schools_code)
+    fit = sm.sampling(data=schools_dat, iter=1000, chains=4)
 
     print(fit)
 
@@ -111,7 +111,7 @@ Example
     # if matplotlib is installed (optional, not required), a visual summary and
     # traceplot are available
     fit.plot()
-    plt.show() 
+    plt.show()
 
 .. |pypi| image:: https://badge.fury.io/py/pystan.png
     :target: https://badge.fury.io/py/pystan

doc/avoiding_recompilation.rst

@@ -11,7 +11,7 @@ whenever possible. If the same model is going to be used repeatedly, we would
 like to compile it just once. The following demonstrates how to reuse a model in
 different scripts and between interactive Python sessions.
 
-**Within sessions** you can avoid recompiling a model in two ways. The simplest
+**Within sessions** you can avoid recompiling a model in two ways. The first
 method is to reuse a fit object in the call to ``stan``. For example,
 
 .. code-block:: python
@@ -45,8 +45,10 @@ method is to reuse a fit object in the call to ``stan``. For example,
     fit2 = stan(fit=fit, data=new_data)
     print(fit2)
 
-Alternatively, we can compile the model once using the ``StanModel`` class and
-then sample from the model using the ``sampling`` method.
+However, calling ``pystan.stan`` is deprecated and will soon be removed from
+PyStan. The recommended method is to compile the model once using the
+``StanModel`` class and then sample from the model using the ``sampling``
+method.
 
 .. code-block:: python
 
@@ -114,7 +116,7 @@ available.
     import pickle
     from hashlib import md5
 
-    def stan_cache(model_code, model_name=None, **kwargs):
+    def StanModel_cache(model_code, model_name=None, **kwargs):
         """Use just as you would `stan`"""
         code_hash = md5(model_code.encode('ascii')).hexdigest()
         if model_name is None:
@@ -129,14 +131,16 @@ available.
                 pickle.dump(sm, f)
         else:
             print("Using cached StanModel")
-        return sm.sampling(**kwargs)
+        return sm
 
     # with same model_code as before
     data = dict(N=10, y=[0, 1, 0, 0, 0, 0, 0, 0, 0, 1])
-    fit = stan_cache(model_code=model_code, data=data)
+    sm = StanModel_cache(model_code=model_code)
+    fit = sm.sampling(data=data)
     print(fit)
 
     new_data = dict(N=6, y=[0, 0, 0, 0, 0, 1])
     # the cached copy of the model will be used
-    fit2 = stan_cache(model_code=model_code, data=new_data)
+    sm = StanModel_cache(model_code=model_code)
+    fit2 = sm.sampling(data=new_data)
     print(fit2)

doc/getting_started.rst

@@ -6,7 +6,8 @@
  Getting started
 =================
 
-PyStan is the `Python <http://python.org>`_ interface for `Stan <http://mc-stan.org/>`_.
+PyStan is the `Python <http://python.org>`_ interface for
+`Stan <http://mc-stan.org/>`_.
 
 Prerequisites
 =============
@@ -108,8 +109,8 @@ which studied coaching effects from eight schools.
                    'y': [28,  8, -3,  7, -1,  1, 18, 12],
                    'sigma': [15, 10, 16, 11,  9, 11, 10, 18]}
 
-    fit = pystan.stan(model_code=schools_code, data=schools_dat,
-                      iter=1000, chains=4)
+    sm = pystan.StanModel(model_code=schools_code)
+    fit = sm.sampling(data=schools_dat, iter=1000, chains=4)
 
 In this model, we let ``theta`` be transformed parameters of ``mu`` and ``eta``
 instead of directly declaring theta as parameters. By parameterizing this way,
@@ -121,17 +122,16 @@ our working directory and use the following call to ``stan`` instead:
 
 .. code-block:: python
 
-    fit1 = pystan.stan(file='8schools.stan', data=schools_dat, iter=1000, chains=4)
+    sm = pystan.StanModel(file='8schools.stan')
+    fit = sm.sampling(data=schools_dat, iter=1000, chains=4)
 
-Once a model is fitted, we can use the fitted result as an input to the model
-with other data or settings. This saves us time compiling the C++ code for the
-model. By specifying the parameter ``fit`` for the ``stan`` function, we can fit
-the model again. For example, if we want to sample more iterations, we proceed
-as follows:
+Once a model is compiled, we can use the StanModel object multiple times.
+This saves us time compiling the C++ code for the model. For example, if we
+want to sample more iterations, we proceed as follows:
 
 .. code-block:: python
 
-    fit2 = pystan.stan(fit=fit1, data=schools_dat, iter=10000, chains=4)
+    fit2 = sm.sampling(data=schools_dat, iter=10000, chains=4)
 
 The object ``fit``, returned from function ``stan`` stores samples from the
 posterior distribution. The ``fit`` object has a number of methods, including
@@ -154,7 +154,8 @@ parameters of interest, or just an array.
 
     print(fit)
 
-If `matplotlib <http://matplotlib.org/>`_ and `scipy <http://http://www.scipy.org/>`_ are installed, a visual summary may
+If `matplotlib <http://matplotlib.org/>`_ and
+`scipy <http://http://www.scipy.org/>`_ are installed, a visual summary may
 also be displayed using the ``plot()`` method.
 
 .. code-block:: python

doc/installation_beginner.rst

@@ -39,7 +39,7 @@ package manager (that also plays nicely with ``pip``) called ``conda``,
 and comes with many of the data analytics packages and dependencies
 pre-installed.
 
-Don't worry about Anaconda ruining your current Python installation, can
+Don't worry about Anaconda ruining your current Python installation, it
 can be easily uninstalled (described below).
 
 Anaconda is not a requirement