Merge pull request #707 from stan-dev/docs/701-pathfinder

Docs/701 pathfinder

Author: WardBrian

cmdstanpy/model.py

@@ -1882,8 +1882,8 @@ def laplace_sample(
             either as a dictionary with entries matching the data variables,
             or as the path of a data file in JSON or Rdump format.
 
-        :param mode: The mode around which to place the approximation.
-            This can be:
+        :param mode: The mode around which to place the approximation, either
+
             * A :class:`CmdStanMLE` object
             * A path to a CSV file containing the output of an optimization run.
             * ``None`` - use default optimizer settings and/or any ``opt_args``.

cmdstanpy/stanfit/gq.py

@@ -566,7 +566,9 @@ def stan_variable(
         CmdStanGQ.stan_variables
         CmdStanMCMC.stan_variable
         CmdStanMLE.stan_variable
+        CmdStanPathfinder.stan_variable
         CmdStanVB.stan_variable
+        CmdStanLaplace.stan_variable
         """
         model_var_names = self.previous_fit._metadata.stan_vars.keys()
         gq_var_names = self._metadata.stan_vars.keys()
@@ -613,7 +615,9 @@ def stan_variables(self, inc_warmup: bool = False) -> Dict[str, np.ndarray]:
         CmdStanGQ.stan_variable
         CmdStanMCMC.stan_variables
         CmdStanMLE.stan_variables
+        CmdStanPathfinder.stan_variables
         CmdStanVB.stan_variables
+        CmdStanLaplace.stan_variables
         """
         result = {}
         sample_var_names = self.previous_fit._metadata.stan_vars.keys()

cmdstanpy/stanfit/laplace.py

@@ -82,6 +82,7 @@ def stan_variable(self, var: str) -> np.ndarray:
         --------
         CmdStanMLE.stan_variables
         CmdStanMCMC.stan_variable
+        CmdStanPathfinder.stan_variable
         CmdStanVB.stan_variable
         CmdStanGQ.stan_variable
         """
@@ -113,6 +114,7 @@ def stan_variables(self) -> Dict[str, np.ndarray]:
         CmdStanGQ.stan_variable
         CmdStanMCMC.stan_variables
         CmdStanMLE.stan_variables
+        CmdStanPathfinder.stan_variables
         CmdStanVB.stan_variables
         """
         result = {}
@@ -235,7 +237,9 @@ def mode(self) -> CmdStanMLE:
     @property
     def metadata(self) -> InferenceMetadata:
         """
-        Return the inference metadata as an :class:`InferenceMetadata` object.
+        Returns object which contains CmdStan configuration as well as
+        information about the names and structure of the inference method
+        and model output variables.
         """
         return self._metadata
 

cmdstanpy/stanfit/mcmc.py

@@ -748,8 +748,10 @@ def stan_variable(
         --------
         CmdStanMCMC.stan_variables
         CmdStanMLE.stan_variable
+        CmdStanPathfinder.stan_variable
         CmdStanVB.stan_variable
         CmdStanGQ.stan_variable
+        CmdStanLaplace.stan_variable
         """
         try:
             draws = self.draws(inc_warmup=inc_warmup, concat_chains=True)
@@ -774,8 +776,10 @@ def stan_variables(self) -> Dict[str, np.ndarray]:
         --------
         CmdStanMCMC.stan_variable
         CmdStanMLE.stan_variables
+        CmdStanPathfinder.stan_variables
         CmdStanVB.stan_variables
         CmdStanGQ.stan_variables
+        CmdStanLaplace.stan_variables
         """
         result = {}
         for name in self._metadata.stan_vars:

cmdstanpy/stanfit/mle.py

@@ -189,8 +189,10 @@ def stan_variable(
         --------
         CmdStanMLE.stan_variables
         CmdStanMCMC.stan_variable
+        CmdStanPathfinder.stan_variable
         CmdStanVB.stan_variable
         CmdStanGQ.stan_variable
+        CmdStanLaplace.stan_variable
         """
         if var not in self._metadata.stan_vars:
             raise ValueError(
@@ -241,8 +243,10 @@ def stan_variables(
         --------
         CmdStanMLE.stan_variable
         CmdStanMCMC.stan_variables
+        CmdStanPathfinder.stan_variables
         CmdStanVB.stan_variables
         CmdStanGQ.stan_variables
+        CmdStanLaplace.stan_variables
         """
         if not self.runset._check_retcodes():
             get_logger().warning(

cmdstanpy/stanfit/pathfinder.py

@@ -106,7 +106,8 @@ def stan_variable(self, var: str) -> np.ndarray:
 
         See Also
         --------
-        CmdStanMLE.stan_variables
+        CmdStanPathfinder.stan_variables
+        CmdStanMLE.stan_variable
         CmdStanMCMC.stan_variable
         CmdStanVB.stan_variable
         CmdStanGQ.stan_variable
@@ -133,10 +134,11 @@ def stan_variables(self) -> Dict[str, np.ndarray]:
 
         See Also
         --------
-        CmdStanGQ.stan_variable
+        CmdStanPathfinder.stan_variable
         CmdStanMCMC.stan_variables
         CmdStanMLE.stan_variables
         CmdStanVB.stan_variables
+        CmdStanGQ.stan_variables
         CmdStanLaplace.stan_variables
         """
         result = {}

cmdstanpy/stanfit/vb.py

@@ -140,7 +140,9 @@ def stan_variable(self, var: str) -> np.ndarray:
         CmdStanVB.stan_variables
         CmdStanMCMC.stan_variable
         CmdStanMLE.stan_variable
+        CmdStanPathfinder.stan_variable
         CmdStanGQ.stan_variable
+        CmdStanLaplace.stan_variable
         """
         try:
             out: np.ndarray = self._metadata.stan_vars[var].extract_reshape(
@@ -166,6 +168,8 @@ def stan_variables(self) -> Dict[str, np.ndarray]:
         CmdStanMCMC.stan_variables
         CmdStanMLE.stan_variables
         CmdStanGQ.stan_variables
+        CmdStanPathfinder.stan_variables
+        CmdStanLaplace.stan_variables
         """
         result = {}
         for name in self._metadata.stan_vars:

docsrc/api.rst

@@ -6,7 +6,8 @@ API Reference
 
 The following documents the public API of CmdStanPy. It is expected to be stable between versions,
 with backwards compatibility between minor versions and deprecation warnings preceding breaking changes.
-There is also the `internal API <internal_api.rst>`__, which is makes no such guarantees.
+The documentation for the `internal API <internal_api.rst>`_ is also provided, but the internal API
+does not guarantee either stability and backwards compatibility.
 
 .. toctree::
    :hidden:
@@ -25,15 +26,15 @@ A CmdStanModel object encapsulates the Stan program. It manages program compilat
 :meth:`~CmdStanModel.sample`
     runs the HMC-NUTS sampler to produce a set of draws from the posterior distribution.
 
-:meth:`~CmdStanModel.pathfinder`
-    runs the Pathfinder variational inference parameters to recieve approximate draws from the posterior.
-
 :meth:`~CmdStanModel.optimize`
     produce a penalized maximum likelihood estimate or maximum a posteriori estimate (point estimate) of the model parameters.
 
 :meth:`~CmdStanModel.laplace_sample`
     draw from a Laplace approximatation centered at the posterior mode found by ``optimize``.
 
+:meth:`~CmdStanModel.pathfinder`
+    runs the Pathfinder variational inference parameters to recieve approximate draws from the posterior.
+
 :meth:`~CmdStanModel.variational`
     run CmdStan’s automatic differentiation variational inference (ADVI) algorithm to approximate the posterior distribution.
 
@@ -43,30 +44,28 @@ A CmdStanModel object encapsulates the Stan program. It manages program compilat
 .. autoclass:: cmdstanpy.CmdStanModel
    :members:
 
-
 CmdStanMCMC
 ===========
 
 .. autoclass:: cmdstanpy.CmdStanMCMC
    :members:
 
-
-CmdStanPathfinder
-=================
-
-.. autoclass:: cmdstanpy.CmdStanPathfinder
-   :members:
-
 CmdStanMLE
 ==========
 
 .. autoclass:: cmdstanpy.CmdStanMLE
    :members:
 
-CmdStanGQ
-=========
+CmdStanLaplace
+==============
 
-.. autoclass:: cmdstanpy.CmdStanGQ
+.. autoclass:: cmdstanpy.CmdStanLaplace
+   :members:
+
+CmdStanPathfinder
+=================
+
+.. autoclass:: cmdstanpy.CmdStanPathfinder
    :members:
 
 CmdStanVB
@@ -75,10 +74,10 @@ CmdStanVB
 .. autoclass:: cmdstanpy.CmdStanVB
    :members:
 
-CmdStanLaplace
-==============
+CmdStanGQ
+=========
 
-.. autoclass:: cmdstanpy.CmdStanLaplace
+.. autoclass:: cmdstanpy.CmdStanGQ
    :members:
 
 *********

docsrc/changes.rst

@@ -5,7 +5,7 @@
 What's New
 ==========
 
-For full changes, see the `Releases page <https://github.com/stan-dev/cmdstanpy/releases>`__ on GitHub.
+For full changes, see the `Releases page <https://github.com/stan-dev/cmdstanpy/releases>`_ on GitHub.
 
 
 CmdStanPy 1.1.0

docsrc/community.rst

@@ -9,26 +9,26 @@ Project templates
 Templates are a great way to piggy back on other users' work, saving you time
 when you start a new project.
 
-- `cookiecutter-cmdstanpy-analysis <https://github.com/teddygroves/cookiecutter-cmdstanpy-analysis>`__
+- `cookiecutter-cmdstanpy-analysis <https://github.com/teddygroves/cookiecutter-cmdstanpy-analysis>`_
   A cookiecutter template for cmdstanpy-based statistical analysis projects.
 
-- `cookiecutter-cmdstanpy-wrapper <https://github.com/WardBrian/cookiecutter-cmdstanpy-wrapper>`__
+- `cookiecutter-cmdstanpy-wrapper <https://github.com/WardBrian/cookiecutter-cmdstanpy-wrapper>`_
   A cookiecutter template using Stan models in Python packages, including
   the ability to pre-compile the model as part of the package distribution.
 
 Software
 --------
 
-- `Prophet <https://github.com/facebook/prophet>`__ A procedure for forecasting
+- `Prophet <https://github.com/facebook/prophet>`_ A procedure for forecasting
   time series data based on an additive model where non-linear trends are fit
   with yearly, weekly, and daily seasonality, plus holiday effects.
 
-- `ArviZ <https://github.com/arviz-devs/arviz>`__ A Python package (with a `Julia
-  interface <https://julia.arviz.org/stable/>`__) for exploratory analysis of
+- `ArviZ <https://github.com/arviz-devs/arviz>`__ A Python package (with a
+  `Julia interface <https://julia.arviz.org/stable/>`_) for exploratory analysis of
   Bayesian models. Includes functions for posterior analysis, data storage,
   model checking, comparison and diagnostics.
 
-- `BridgeStan <https://github.com/roualdes/bridgestan>`__ A project which provides efficient
+- `BridgeStan <https://github.com/roualdes/bridgestan>`_ A project which provides efficient
   in-memory access through Python, Julia, and R to the methods of a Stan model, including
   log densities, gradients, Hessians, and constraining and unconstraining transforms.