DOC: Fix regression doc strings

Use pandas tooling to improve and fix OLS/WLS/GLS doc strings
Add stl_decomposition to example gallery

docs/source/conf.py

@@ -341,12 +341,16 @@
 # numpydoc_show_class_members = False
 # numpydoc_show_inherited_class_members = True
 
+# Create xrefs
+numpydoc_xref_param_type = True
+
+# Example configuration for intersphinx: refer to the Python standard library.
 # Example configuration for intersphinx: refer to the Python standard library.
 intersphinx_mapping = {
-    'numpy': ('https://docs.scipy.org/doc/numpy/', None),
-    'python': ('https://docs.python.org/3/', None),
-    'pydagogue': ('https://matthew-brett.github.io/pydagogue/', None),
-    'patsy': ('https://patsy.readthedocs.io/en/latest/', None),
+    'matplotlib': ('https://matplotlib.org/', None),
+    'scipy': ('https://docs.scipy.org/doc/scipy/reference/', None),
+    'python': ('https://docs.python.org/3', None),
+    'numpy': ('https://docs.scipy.org/doc/numpy', None),
     'pandas': ('https://pandas.pydata.org/pandas-docs/stable/', None),
 }
 

docs/source/examples/landing.json

@@ -176,6 +176,11 @@
             "text": "Exponential Smoothing",
             "target": "notebooks/generated/exponential_smoothing.html",
             "img": "../_static/images/exponential_smoothing.png"
+        },
+        {
+            "text": "Seasonal Decomposition",
+            "target": "notebooks/generated/stl_decomposition.html",
+            "img": "../_static/images/stl_decomposition.png"
         }
           ]
   },

docs/source/regression.rst

@@ -203,6 +203,13 @@ results class of the other linear models.
    OLSResults
    PredictionResults
 
+.. currentmodule:: statsmodels.base.elastic_net
+
+.. autosummary::
+   :toctree: generated/
+
+    RegularizedResults
+
 .. currentmodule:: statsmodels.regression.quantile_regression
 
 .. autosummary::

statsmodels/base/elastic_net.py

@@ -350,12 +350,24 @@ def _opt_1d(func, grad, hess, model, start, L1_wt, tol,
 
 
 class RegularizedResults(Results):
+    """
+    Results for models estimated using regularization
 
+    Parameters
+    ----------
+    model : Model
+        The model instance used to estimate the parameters.
+    params : ndarray
+        The estimated (regularized) parameters.
+    """
     def __init__(self, model, params):
         super(RegularizedResults, self).__init__(model, params)
 
     @cache_readonly
     def fittedvalues(self):
+        """
+        The predicted values from the model at the estimated parameters.
+        """
         return self.model.predict(self.params)
 
 

statsmodels/base/model.py

@@ -19,11 +19,10 @@
 from statsmodels.base.optimizer import Optimizer
 
 
-_model_params_doc = """
-    Parameters
+_model_params_doc = """Parameters
     ----------
     endog : array_like
-        1-d endogenous response variable. The dependent variable.
+        A 1-d endogenous response variable. The dependent variable.
     exog : array_like
         A nobs x k array where `nobs` is the number of observations and `k`
         is the number of regressors. An intercept is not included by default
@@ -34,14 +33,16 @@
 missing : str
         Available options are 'none', 'drop', and 'raise'. If 'none', no nan
         checking is done. If 'drop', any observations with nans are dropped.
-        If 'raise', an error is raised. Default is 'none.'"""
+        If 'raise', an error is raised. Default is 'none'."""
 _extra_param_doc = """
     hasconst : None or bool
         Indicates whether the RHS includes a user-supplied constant. If True,
         a constant is not checked for and k_constant is set to 1 and all
         result statistics are calculated as if a constant is present. If
         False, a constant is not checked for and k_constant is set to 0.
-"""
+    **kwargs
+        Extra arguments that are used to set model properties when using the
+        formula interface."""
 
 
 class Model(object):
@@ -117,19 +118,19 @@ def from_formula(cls, formula, data, subset=None, drop_cols=None,
         Parameters
         ----------
         formula : str or generic Formula object
-            The formula specifying the model
+            The formula specifying the model.
         data : array_like
             The data for the model. See Notes.
         subset : array_like
             An array-like object of booleans, integers, or index values that
             indicate the subset of df to use in the model. Assumes df is a
-            `pandas.DataFrame`
+            `pandas.DataFrame`.
         drop_cols : array_like
             Columns to drop from the design matrix.  Cannot be used to
             drop terms involving categoricals.
-        args : extra arguments
-            These are passed to the model
-        kwargs : extra keyword arguments
+        *args
+            Additional positional argument that are passed to the model.
+        **kwargs
             These are passed to the model with one exception. The
             ``eval_env`` keyword is passed to patsy. It can be either a
             :class:`patsy:patsy.EvalEnvironment` object or an integer
@@ -139,7 +140,8 @@ def from_formula(cls, formula, data, subset=None, drop_cols=None,
 
         Returns
         -------
-        model : Model instance
+        model
+            The model instance.
 
         Notes
         -----
@@ -198,12 +200,16 @@ def from_formula(cls, formula, data, subset=None, drop_cols=None,
 
     @property
     def endog_names(self):
-        """Names of endogenous variables"""
+        """
+        Names of endogenous variables.
+        """
         return self.data.ynames
 
     @property
     def exog_names(self):
-        """Names of exogenous variables"""
+        """
+        Names of exogenous variables.
+        """
         return self.data.xnames
 
     def fit(self):
@@ -232,9 +238,11 @@ def __init__(self, endog, exog=None, **kwargs):
 
     def initialize(self):
         """
-        Initialize (possibly re-initialize) a Model instance. For
-        instance, the design matrix of a linear model may change
-        and some things must be recomputed.
+        Initialize (possibly re-initialize) a Model instance.
+
+        For example, if the the design matrix of a linear model changes then
+        initialized can be used to recompute values using the modified design
+        matrix.
         """
         pass
 
@@ -252,20 +260,45 @@ def score(self, params):
         Score vector of model.
 
         The gradient of logL with respect to each parameter.
+
+        Parameters
+        ----------
+        params : ndarray
+            The parameters to use when evaluating the Hessian.
+
+        Returns
+        -------
+        ndarray
+            The score vector evaluated at the parameters.
         """
         raise NotImplementedError
 
     def information(self, params):
         """
-        Fisher information matrix of model
+        Fisher information matrix of model.
 
-        Returns -Hessian of loglike evaluated at params.
+        Returns -1 * Hessian of the log-loglikelihood evaluated at params.
+
+        Parameters
+        ----------
+        params : ndarray
+            The model parameters.
         """
         raise NotImplementedError
 
     def hessian(self, params):
         """
-        The Hessian matrix of the model
+        The Hessian matrix of the model.
+
+        Parameters
+        ----------
+        params : ndarray
+            The parameters to use when evaluating the Hessian.
+
+        Returns
+        -------
+        ndarray
+            The hessian evaluated at the parameters.
         """
         raise NotImplementedError
 

statsmodels/regression/_prediction.py

@@ -95,7 +95,7 @@ def summary_frame(self, what='all', alpha=0.05):
 def get_prediction(self, exog=None, transform=True, weights=None,
                    row_labels=None, pred_kwds=None):
     """
-    compute prediction results
+    Compute prediction results.
 
     Parameters
     ----------
@@ -111,13 +111,16 @@ def get_prediction(self, exog=None, transform=True, weights=None,
     weights : array_like, optional
         Weights interpreted as in WLS, used for the variance of the predicted
         residual.
-    args, kwargs :
-        Some models can take additional arguments or keywords, see the
-        predict method of the model for the details.
+    row_labels : list
+        A list of row labels to use.  If not provided, read `exog` is
+        available.
+    **kwargs
+        Some models can take additional keyword arguments, see the predict
+        method of the model for the details.
 
     Returns
     -------
-    prediction_results : linear_model.PredictionResults
+    linear_model.PredictionResults
         The prediction results instance contains prediction and prediction
         variance and can on demand calculate confidence intervals and summary
         tables for the prediction of the mean and of new observations.