Merge pull request #7727 from josef-pkt/docs_recent

DOC: improve docs and docstrings, mainly for recent additions

docs/source/other_models.rst

@@ -9,11 +9,11 @@
 Other Models :mod:`othermod`
 ==============================
 
-:mod:`statsmodels.other` contains model classes and that do not fit into
+:mod:`statsmodels.othermod` contains model classes that do not fit into
 any other category, for example models for a response variable ``endog`` that
 has support on the unit interval or is positive or non-negative.
 
-:mod:`statsmodels.other` contains models that are, or will be fully developed
+:mod:`statsmodels.othermod` contains models that are, or will be fully developed
 in contrast to :mod:`statsmodels.miscmodels` which contains mainly examples
 for the use of the generic likelihood model setup.
 
@@ -25,6 +25,13 @@ multiple link functions.
 Interval Models :mod:`betareg`
 ------------------------------
 
+Models for continuous dependent variables that are in the unit interval such
+as fractions. These Models are estimated by full Maximum Likelihood. 
+Dependent variables on the unit interval can also be estimate by 
+Quasi Maximum Likelihood using models for binary endog, such as Logit and
+GLM-Binomial. (The implementation of discrete.Probit assumes binary endog and
+cannot estimate a QMLE for continuous dependent variable.)
+
 .. module:: statsmodels.othermod.betareg
 .. currentmodule:: statsmodels.othermod.betareg
 

statsmodels/base/model.py

@@ -961,11 +961,7 @@ def hessian_factor(self, params, scale=None, observed=True):
 
     def fit(self, start_params=None, method='nm', maxiter=500, full_output=1,
             disp=1, callback=None, retall=0, **kwargs):
-        """
-        Fit the model using maximum likelihood.
 
-        See LikelihoodModel.fit for more information.
-        """
         if start_params is None:
             if hasattr(self, 'start_params'):
                 start_params = self.start_params

statsmodels/miscmodels/ordinal_model.py

@@ -14,6 +14,7 @@
 from scipy import stats
 
 from statsmodels.base.model import (
+    LikelihoodModel,
     GenericLikelihoodModel,
     GenericLikelihoodModelResults,
 )
@@ -81,7 +82,7 @@ class OrderedModel(GenericLikelihoodModel):
     Notes
     -----
     Status: experimental, core results are verified, still subclasses
-        `GenericLikelihoodModel` which will change in future versions.
+    `GenericLikelihoodModel` which will change in future versions.
 
     The parameterization of OrderedModel requires that there is no constant in
     the model, neither explicit nor implicit. The constant is equivalent to
@@ -156,9 +157,9 @@ def __init__(self, endog, exog, offset=None, distr='probit', **kwds):
         self.results_class = OrderedResults
 
     def _check_inputs(self, endog, exog):
-        """handle endog that is pandas Categorical
+        """Handle endog that is pandas Categorical.
 
-        checks if self.distrib is legal and provides Pandas ordered Categorical
+        Checks if self.distrib is legal and provides Pandas ordered Categorical
         support for endog.
 
         Parameters
@@ -263,18 +264,42 @@ def from_formula(cls, formula, data, subset=None, drop_cols=None,
 
         return model
 
+    from_formula.__doc__ = LikelihoodModel.from_formula.__doc__
+
     def cdf(self, x):
-        """cdf evaluated at x
+        """Cdf evaluated at x.
+
+        Parameters
+        ----------
+        x : array_like
+            Points at which cdf is evaluated. In the model `x` is the latent
+            variable plus threshold constants.
+
+        Returns
+        -------
+        Value of the cumulative distribution function of the underlying latent
+        variable evaluated at x.
         """
         return self.distr.cdf(x)
 
     def pdf(self, x):
-        """pdf evaluated at x
+        """Pdf evaluated at x
+
+        Parameters
+        ----------
+        x : array_like
+            Points at which cdf is evaluated. In the model `x` is the latent
+            variable plus threshold constants.
+
+        Returns
+        -------
+        Value of the probability density function of the underlying latent
+        variable evaluated at x.
         """
         return self.distr.pdf(x)
 
     def prob(self, low, upp):
-        """interval probability
+        """Interval probability.
 
         Probability that value is in interval (low, upp], computed as
 
@@ -392,9 +417,7 @@ def predict(self, params, exog=None, offset=None, which="prob"):
             raise ValueError("`which` is not available")
 
     def _linpred(self, params, exog=None, offset=None):
-        """linear prediction of latent variable `x b`
-
-        currently only for exog from estimation sample (in-sample)
+        """Linear prediction of latent variable `x b`.
 
         Parameters
         ----------
@@ -533,7 +556,7 @@ def start_params(self):
         start_params = np.concatenate((np.zeros(self.k_vars), start_threshold))
         return start_params
 
-    @Appender(GenericLikelihoodModel.fit.__doc__)
+    @Appender(LikelihoodModel.fit.__doc__)
     def fit(self, start_params=None, method='nm', maxiter=500, full_output=1,
             disp=1, callback=None, retall=0, **kwargs):
 
@@ -554,6 +577,11 @@ def fit(self, start_params=None, method='nm', maxiter=500, full_output=1,
 
 
 class OrderedResults(GenericLikelihoodModelResults):
+    """Results class for OrderedModel
+
+    This class inherits from GenericLikelihoodModelResults and not all
+    inherited methods might be appropriate in this case.
+    """
 
     def pred_table(self):
         """prediction table