Docs/701 pathfinder

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.
 

docsrc/conf.py

@@ -133,7 +133,7 @@ def emit(self, record):
 
 # General information about the project.
 project = 'CmdStanPy'
-copyright = '2022, Stan Development Team'
+copyright = '2023, Stan Development Team'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
@@ -399,8 +399,10 @@ def emit(self, record):
     "DataFrame": "~pandas.DataFrame",
     "CmdStanMCMC": "~cmdstanpy.CmdStanMCMC",
     "CmdStanMLE": "~cmdstanpy.CmdStanMLE",
-    "CmdStanMCVB": "~cmdstanpy.CmdStanMCVB",
-    "CmdStanMCGQ": "~cmdstanpy.CmdStanMCGQ",
+    "CmdStanVB": "~cmdstanpy.CmdStanVB",
+    "CmdStanGQ": "~cmdstanpy.CmdStanGQ",
+    "CmdStanLaplace": "~cmdstanpy.CmdStanLaplace",
+    "CmdStanPathfinder": "~cmdstanpy.CmdStanPathfinder"
 }
 
 nbsphinx_allow_errors = False

docsrc/index.rst

@@ -16,7 +16,7 @@ CmdStanPy is a lightweight interface to Stan for Python users which
 provides the necessary objects and functions to do Bayesian inference
 given a probability model and data.
 It wraps the
-`CmdStan <https://mc-stan.org/docs/cmdstan-guide/cmdstan-installation.html>`__
+`CmdStan <https://mc-stan.org/docs/cmdstan-guide/cmdstan-installation.html>`_
 command line interface in a small set of
 Python classes which provide methods to do analysis and manage the resulting
 set of model, data, and posterior estimates.

docsrc/installation.rst

@@ -9,11 +9,11 @@ There are several ways to install CmdStanPy and the underlying CmdStan component
 
 * You can download CmdStanPy, CmdStan, and the C++ toolchain from conda-forge.
 
-* You can download the CmdStanPy package from `PyPI <https://pypi.org>`__
-  using `pip <https://pip.pypa.io/en/stable/>`__.
+* You can download the CmdStanPy package from `PyPI <https://pypi.org>`_
+  using `pip <https://pip.pypa.io/en/stable/>`_.
 
 * If you want the current development version, you can clone the
-  GitHub `CmdStanPy <https://github.com/stan-dev/cmdstanpy>`__ repository.
+  GitHub `CmdStanPy <https://github.com/stan-dev/cmdstanpy>`_ repository.
 
 If you install CmdStanPy from PyPI or GitHub you will need to
 install CmdStan as well, see section :ref:`CmdStan Installation <cmdstan-install>` below.
@@ -22,9 +22,9 @@ install CmdStan as well, see section :ref:`CmdStan Installation <cmdstan-install
 Conda: install CmdStanPy, CmdStan, C++ toolchain
 ------------------------------------------------
 
-If you use `conda <https://docs.conda.io/en/latest/>`__,
+If you use `conda <https://docs.conda.io/en/latest/>`_,
 you can install CmdStanPy and the underlying CmdStan components from the
-`conda-forge <https://conda-forge.org/>`__ repository
+`conda-forge <https://conda-forge.org/>`_ repository
 via the following command:
 
 
@@ -60,7 +60,7 @@ If you require a specific release of CmdStan, CmdStan versions
 ``cmdstan==VERSION`` in the install command.
 Versions before 2.26.1 are not available from conda
 but can be downloaded from the CmdStan
-`releases <https://github.com/stan-dev/cmdstan/releases>`__ page.
+`releases <https://github.com/stan-dev/cmdstan/releases>`_ page.
 
 A Conda environment is a directory that contains a specific collection of Conda packages.
 To see the locations of your conda environments, use the command
@@ -120,12 +120,12 @@ To install the current develop branch from GitHub:
 
   **Jupyter notebook users:**  If you intend to run CmdStanPy from within a Jupyter notebook,
   you may need to install the
-  `ipywidgets <https://ipywidgets.readthedocs.io/en/latest/index.html>`__.
-  This will allow for progress bars implemented using the `tqdm <https://pypi.org/project/tqdm/>`__
+  `ipywidgets <https://ipywidgets.readthedocs.io/en/latest/index.html>`_.
+  This will allow for progress bars implemented using the `tqdm <https://pypi.org/project/tqdm/>`_
   to display properly in the browser.
   For further help on Jupyter notebook installation and configuration , see
-  `ipywidgets installation instructions <https://ipywidgets.readthedocs.io/en/latest/user_install.html#>`__
-  and `this tqdm GitHub issue <https://github.com/tqdm/tqdm/issues/394#issuecomment-384743637>`__.
+  `ipywidgets installation instructions <https://ipywidgets.readthedocs.io/en/latest/user_install.html#>`_
+  and `this tqdm GitHub issue <https://github.com/tqdm/tqdm/issues/394#issuecomment-384743637>`_.
 
 
 .. _cmdstan-install:
@@ -156,7 +156,7 @@ There is usually a pre-installed C++ compiler as well, but not necessarily new e
 **MacOS** The Xcode and Xcode command line tools must be installed.  Xcode is available for free from the Mac App Store.
 To install the Xcode command line tools, run the shell command: ``xcode-select --install``.
 
-**Windows**  We recommend using the `RTools 4.0 <https://cran.r-project.org/bin/windows/Rtools/rtools40.html>`__ toolchain
+**Windows**  We recommend using the `RTools 4.0 <https://cran.r-project.org/bin/windows/Rtools/rtools40.html>`_ toolchain
 which contains a ``g++ 8`` compiler and ``Mingw``, the native Windows equivalent of the GNU-Make utility.
 This can be installed along with CmdStan when you invoke the function :meth:`cmdstanpy.install_cmdstan`
 with argument ``compiler=True``.
@@ -206,7 +206,7 @@ can be used to override these defaults:
 
 .. code-block:: bash
 
-    install_cmdstan -d my_local_cmdstan -v 2.27.0
+    install_cmdstan -d my_local_cmdstan -v 2.33.0
     ls -F my_local_cmdstan
 
 Alternate Linux Architectures
@@ -224,7 +224,7 @@ DIY Installation
 ^^^^^^^^^^^^^^^^
 
 If you with to install CmdStan yourself, follow the instructions
-in the `CmdStan User's Guide <https://mc-stan.org/docs/cmdstan-guide/cmdstan-installation.html>`__.
+in the `CmdStan User's Guide <https://mc-stan.org/docs/cmdstan-guide/cmdstan-installation.html>`_.
 
 Locating the CmdStan installation directory
 -------------------------------------------