Add docstring for stansummary

Docstring for stansummary with Parameters, Returns and Examples.

Author: ahartikainen

pystan/misc.py

@@ -51,30 +51,67 @@
 
 
 def stansummary(fit, pars=None, probs=(0.025, 0.25, 0.5, 0.75, 0.975), digits_summary=2):
-        if fit.mode == 1:
-            return "Stan model '{}' is of mode 'test_grad';\n"\
-                   "sampling is not conducted.".format(fit.model_name)
-        elif fit.mode == 2:
-            return "Stan model '{}' does not contain samples.".format(fit.model_name)
-
-        n_kept = [s - w for s, w in zip(fit.sim['n_save'], fit.sim['warmup2'])]
-        header = "Inference for Stan model: {}.\n".format(fit.model_name)
-        header += "{} chains, each with iter={}; warmup={}; thin={}; \n"
-        header = header.format(fit.sim['chains'], fit.sim['iter'], fit.sim['warmup'],
-                               fit.sim['thin'], sum(n_kept))
-        header += "post-warmup draws per chain={}, total post-warmup draws={}.\n\n"
-        header = header.format(n_kept[0], sum(n_kept))
-        footer = "\n\nSamples were drawn using {} at {}.\n"\
-            "For each parameter, n_eff is a crude measure of effective sample size,\n"\
-            "and Rhat is the potential scale reduction factor on split chains (at \n"\
-            "convergence, Rhat=1)."
-        sampler = fit.sim['samples'][0]['args']['sampler_t']
-        date = fit.date.strftime('%c')  # %c is locale's representation
-        footer = footer.format(sampler, date)
-        s = _summary(fit, pars, probs)
-        body = _array_to_table(s['summary'], s['summary_rownames'],
-                               s['summary_colnames'], digits_summary)
-        return header + body + footer
+    """
+    Summary statistics table.
+    
+    Parameters
+    ----------
+    fit : StanFit4Model object
+    pars : str or sequence of str, optional
+        Parameter names. By default use all parameters
+    probs : sequence of float, optional
+        Quantiles. By default, (0.025, 0.25, 0.5, 0.75, 0.975)
+    digits_summary : int, optional
+        Number of significant digits. By default, 2
+
+    Returns
+    -------
+    summary : string
+        Table includes mean, se_mean, sd, probs_0, ..., probs_n, n_eff and Rhat.
+    
+    Examples
+    --------
+    >>> model_code = 'parameters {real y;} model {y ~ normal(0,1);}'
+    >>> m = StanModel(model_code=model_code, model_name="example_model")
+    >>> fit = m.sampling()
+    >>> print(stansummary(fit))
+    Inference for Stan model: example_model.
+    4 chains, each with iter=2000; warmup=1000; thin=1; 
+    post-warmup draws per chain=1000, total post-warmup draws=4000.
+    
+           mean se_mean     sd   2.5%    25%    50%    75%  97.5%  n_eff   Rhat
+    y      0.01    0.03    1.0  -2.01  -0.68   0.02   0.72   1.97   1330    1.0
+    lp__   -0.5    0.02   0.68  -2.44  -0.66  -0.24  -0.05-5.5e-4   1555    1.0
+    
+    Samples were drawn using NUTS at Thu Aug 17 00:52:25 2017.
+    For each parameter, n_eff is a crude measure of effective sample size,
+    and Rhat is the potential scale reduction factor on split chains (at 
+    convergence, Rhat=1).
+    """
+    if fit.mode == 1:
+        return "Stan model '{}' is of mode 'test_grad';\n"\
+               "sampling is not conducted.".format(fit.model_name)
+    elif fit.mode == 2:
+        return "Stan model '{}' does not contain samples.".format(fit.model_name)
+
+    n_kept = [s - w for s, w in zip(fit.sim['n_save'], fit.sim['warmup2'])]
+    header = "Inference for Stan model: {}.\n".format(fit.model_name)
+    header += "{} chains, each with iter={}; warmup={}; thin={}; \n"
+    header = header.format(fit.sim['chains'], fit.sim['iter'], fit.sim['warmup'],
+                           fit.sim['thin'], sum(n_kept))
+    header += "post-warmup draws per chain={}, total post-warmup draws={}.\n\n"
+    header = header.format(n_kept[0], sum(n_kept))
+    footer = "\n\nSamples were drawn using {} at {}.\n"\
+        "For each parameter, n_eff is a crude measure of effective sample size,\n"\
+        "and Rhat is the potential scale reduction factor on split chains (at \n"\
+        "convergence, Rhat=1)."
+    sampler = fit.sim['samples'][0]['args']['sampler_t']
+    date = fit.date.strftime('%c')  # %c is locale's representation
+    footer = footer.format(sampler, date)
+    s = _summary(fit, pars, probs)
+    body = _array_to_table(s['summary'], s['summary_rownames'],
+                           s['summary_colnames'], digits_summary)
+    return header + body + footer
 
 def _print_stanfit(fit, pars=None, probs=(0.025, 0.25, 0.5, 0.75, 0.975), digits_summary=2):
     # warning added in PyStan 2.17.0