Merge pull request statsmodels#5957 from bashtage/issue-3122

bashtage · web-flow · commit 717808b48f6b · 2019-07-16T16:44:53.000+01:00
DOC: Clarify xname length and purpose
diff --git a/statsmodels/base/model.py b/statsmodels/base/model.py
@@ -2419,11 +2419,12 @@ def summary(self, yname=None, xname=None, title=None, alpha=.05):
 
         Parameters
         ----------
-        yname : string, optional
+        yname : str, optional
             Default is `y`
-        xname : list of strings, optional
-            Default is `var_##` for ## in p the number of regressors
-        title : string, optional
+        xname : list[str], optional
+            Names for the exogenous variables, default is "var_xx".
+            Must match the number of parameters in the model
+        title : str, optional
             Title for the top table. If not None, then this replaces the
             default title
         alpha : float
diff --git a/statsmodels/discrete/conditional_models.py b/statsmodels/discrete/conditional_models.py
@@ -423,11 +423,12 @@ def summary(self, yname=None, xname=None, title=None, alpha=.05):
 
         Parameters
         ----------
-        yname : string, optional
+        yname : str, optional
             Default is `y`
-        xname : list of strings, optional
-            Default is `var_##` for ## in p the number of regressors
-        title : string, optional
+        xname : list[str], optional
+            Names for the exogenous variables, default is "var_xx".
+            Must match the number of parameters in the model
+        title : str, optional
             Title for the top table. If not None, then this replaces the
             default title
         alpha : float
diff --git a/statsmodels/discrete/discrete_model.py b/statsmodels/discrete/discrete_model.py
@@ -3602,11 +3602,12 @@ def summary(self, yname=None, xname=None, title=None, alpha=.05,
 
         Parameters
         ----------
-        yname : string, optional
+        yname : str, optional
             Default is `y`
-        xname : list of strings, optional
-            Default is `var_##` for ## in p the number of regressors
-        title : string, optional
+        xname : list[str], optional
+            Names for the exogenous variables, default is "var_xx".
+            Must match the number of parameters in the model
+        title : str, optional
             Title for the top table. If not None, then this replaces the
             default title
         alpha : float
@@ -3671,16 +3672,17 @@ def summary2(self, yname=None, xname=None, title=None, alpha=.05,
 
         Parameters
         ----------
-        xname : List of strings of length equal to the number of parameters
-            Names of the independent variables (optional)
-        yname : string
+        yname : str
             Name of the dependent variable (optional)
-        title : string, optional
+        xname : list[str], optional
+            List of strings of length equal to the number of parameters
+            Names of the independent variables (optional)
+        title : str, optional
             Title for the top table. If not None, then this replaces the
             default title
         alpha : float
             significance level for the confidence intervals
-        float_format: string
+        float_format : str
             print format for floats in parameters summary
 
         Returns
@@ -4157,7 +4159,7 @@ def summary2(self, alpha=0.05, float_format="%.4f"):
         ----------
         alpha : float
             significance level for the confidence intervals
-        float_format: string
+        float_format : str
             print format for floats in parameters summary
 
         Returns
diff --git a/statsmodels/duration/hazard_regression.py b/statsmodels/duration/hazard_regression.py
@@ -1546,11 +1546,13 @@ def summary(self, yname=None, xname=None, title=None, alpha=.05):
 
         Parameters
         ----------
-        yname : string, optional
+        yname : str, optional
             Default is `y`
-        xname : list of strings, optional
-            Default is `x#` for ## in p the number of regressors
-        title : string, optional
+        xname : list[str], optional
+            Names for the exogenous variables, default is `x#` for ## in p the
+            number of regressors. Must match the number of parameters in
+            the model
+        title : str, optional
             Title for the top table. If not None, then this replaces
             the default title
         alpha : float
diff --git a/statsmodels/genmod/generalized_estimating_equations.py b/statsmodels/genmod/generalized_estimating_equations.py
@@ -2063,16 +2063,18 @@ def summary(self, yname=None, xname=None, title=None, alpha=.05):
 
         Parameters
         ----------
-        yname : string, optional
+        yname : str, optional
             Default is `y`
-        xname : list of strings, optional
-            Default is `var_##` for ## in p the number of regressors
-        title : string, optional
+        xname : list[str], optional
+            Names for the exogenous variables, default is `var_#` for ## in
+            the number of regressors. Must match the number of parameters in
+            the model
+        title : str, optional
             Title for the top table. If not None, then this replaces
             the default title
         alpha : float
             significance level for the confidence intervals
-        cov_type : string
+        cov_type : str
             The covariance type used to compute the standard errors;
             one of 'robust' (the usual robust sandwich-type covariance
             estimate), 'naive' (ignores dependence), and 'bias
diff --git a/statsmodels/genmod/generalized_linear_model.py b/statsmodels/genmod/generalized_linear_model.py
@@ -1804,11 +1804,13 @@ def summary(self, yname=None, xname=None, title=None, alpha=.05):
 
         Parameters
         ----------
-        yname : string, optional
+        yname : str, optional
             Default is `y`
-        xname : list of strings, optional
-            Default is `var_##` for ## in p the number of regressors
-        title : string, optional
+        xname : list[str], optional
+            Names for the exogenous variables, default is `var_#` for ## in
+            the number of regressors. Must match the number of parameters in
+            the model
+        title : str, optional
             Title for the top table. If not None, then this replaces the
             default title
         alpha : float
@@ -1870,16 +1872,18 @@ def summary2(self, yname=None, xname=None, title=None, alpha=.05,
 
         Parameters
         ----------
-        yname : string
+        yname : str
             Name of the dependent variable (optional)
-        xname : List of strings of length equal to the number of parameters
-            Names of the independent variables (optional)
-        title : string, optional
+        xname : list[str], optional
+            Names for the exogenous variables, default is `var_#` for ## in
+            the number of regressors. Must match the number of parameters in
+            the model
+        title : str, optional
             Title for the top table. If not None, then this replaces the
             default title
         alpha : float
             significance level for the confidence intervals
-        float_format: string
+        float_format : str
             print format for floats in parameters summary
 
         Returns
diff --git a/statsmodels/genmod/qif.py b/statsmodels/genmod/qif.py
@@ -443,11 +443,13 @@ def summary(self, yname=None, xname=None, title=None, alpha=.05):
 
         Parameters
         ----------
-        yname : string, optional
+        yname : str, optional
             Default is `y`
-        xname : list of strings, optional
-            Default is `var_##` for ## in p the number of regressors
-        title : string, optional
+        xname : list[str], optional
+            Names for the exogenous variables, default is `var_#` for ## in
+            the number of regressors. Must match the number of parameters in
+            the model
+        title : str, optional
             Title for the top table. If not None, then this replaces
             the default title
         alpha : float
diff --git a/statsmodels/imputation/bayes_mi.py b/statsmodels/imputation/bayes_mi.py
@@ -392,7 +392,7 @@ def summary(self, title=None, alpha=.05):
 
         Parameters
         ----------
-        title : string, optional
+        title : str, optional
             Title for the top table. If not None, then this replaces
             the default title
         alpha : float
diff --git a/statsmodels/imputation/mice.py b/statsmodels/imputation/mice.py
@@ -1289,7 +1289,7 @@ def summary(self, title=None, alpha=.05):
 
         Parameters
         ----------
-        title : string, optional
+        title : str, optional
             Title for the top table. If not None, then this replaces
             the default title
         alpha : float
diff --git a/statsmodels/iolib/summary.py b/statsmodels/iolib/summary.py
@@ -727,7 +727,8 @@ def summary_return(tables, return_fmt='text'):
 
 
 class Summary(object):
-    '''class to hold tables for result summary presentation
+    """
+    Result summary
 
     Construction does not take any parameters. Tables and text can be added
     with the `add_` methods.
@@ -737,10 +738,10 @@ class Summary(object):
     tables : list of tables
         Contains the list of SimpleTable instances, horizontally concatenated
         tables are not saved separately.
-    extra_txt : string
+    extra_txt : str
         extra lines that are added to the text output, used for warnings
         and explanations.
-    '''
+    """
     def __init__(self):
         self.tables = []
         self.extra_txt = None
@@ -757,30 +758,27 @@ def _repr_html_(self):
 
     def add_table_2cols(self, res,  title=None, gleft=None, gright=None,
                         yname=None, xname=None):
-        '''add a double table, 2 tables with one column merged horizontally
+        """
+        Add a double table, 2 tables with one column merged horizontally
 
         Parameters
         ----------
         res : results instance
             some required information is directly taken from the result
             instance
-        title : string or None
+        title : str, optional
             if None, then a default title is used.
-        gleft : list of tuples
+        gleft : list[tuple], optional
             elements for the left table, tuples are (name, value) pairs
             If gleft is None, then a default table is created
-        gright : list of tuples or None
+        gright : list[tuple], optional
             elements for the right table, tuples are (name, value) pairs
-        yname : string or None
+        yname : str, optional
             optional name for the endogenous variable, default is "y"
-        xname : list of strings or None
-            optional names for the exogenous variables, default is "var_xx"
-
-        Returns
-        -------
-        None : tables are attached
-
-        '''
+        xname : list[str], optional
+            optional names for the exogenous variables, default is "var_xx".
+            Must match the number of parameters in the model.
+        """
 
         table = summary_top(res, title=title, gleft=gleft, gright=gright,
                             yname=yname, xname=xname)
diff --git a/statsmodels/iolib/summary2.py b/statsmodels/iolib/summary2.py
@@ -43,9 +43,9 @@ def add_df(self, df, index=True, header=True, float_format='%.4f',
             Reproduce the DataFrame column labels in summary table
         index: bool
             Reproduce the DataFrame row labels in summary table
-        float_format: string
+        float_format : str
             Formatting to float data columns
-        align : string
+        align : str
             Data alignment (l/c/r)
         '''
 
@@ -60,9 +60,9 @@ def add_array(self, array, align='r', float_format="%.4f"):
         Parameters
         ----------
         array : numpy array (2D)
-        float_format: string
+        float_format : str
             Formatting to array if type is float
-        align : string
+        align : str
             Data alignment (l/c/r)
         '''
 
@@ -332,7 +332,7 @@ def summary_params(results, yname=None, xname=None, alpha=.05, use_t=True,
     skip_headers : bool
         If false (default), then the header row is added. If true, then no
         header row is added.
-    float_format : string
+    float_format : str
         float formatting options (e.g. ".3g")
 
     Returns
@@ -441,10 +441,10 @@ def summary_col(results, float_format='%.4f', model_names=(), stars=False,
     Parameters
     ----------
     results : statsmodels results instance or list of result instances
-    float_format : string, optional
+    float_format : str, optional
         float format for coefficients and standard errors
         Default : '%.4f'
-    model_names : list of strings, optional
+    model_names : list[str], optional
         Must have same length as the number of results. If the names are not
         unique, a roman number will be appended to all model names
     stars : bool
@@ -458,7 +458,7 @@ def summary_col(results, float_format='%.4f', model_names=(), stars=False,
         all other results.
         Default : None (use the info_dict specified in
         result.default_model_infos, if this property exists)
-    regressor_order : list of strings, optional
+    regressor_order : list[str], optional
         list of names of the regressors in the desired order. All regressors
         not specified will be appended to the end of the list.
     drop_omitted : bool, optional
diff --git a/statsmodels/regression/linear_model.py b/statsmodels/regression/linear_model.py
@@ -2426,11 +2426,13 @@ def summary(self, yname=None, xname=None, title=None, alpha=.05):
 
         Parameters
         ----------
-        yname : string, optional
+        yname : str, optional
             Default is `y`
-        xname : list of strings, optional
-            Default is `var_##` for ## in p the number of regressors
-        title : string, optional
+        xname : list[str], optional
+            Names for the exogenous variables. Default is `var_##` for ## in
+            the number of regressors. Must match the number of parameters
+            in the model
+        title : str, optional
             Title for the top table. If not None, then this replaces the
             default title
         alpha : float
@@ -2556,16 +2558,18 @@ def summary2(self, yname=None, xname=None, title=None, alpha=.05,
 
         Parameters
         ----------
-        xname : List of strings of length equal to the number of parameters
-            Names of the independent variables (optional)
-        yname : string
+        yname : str
             Name of the dependent variable (optional)
-        title : string, optional
+        xname : list[str], optional
+            Names for the exogenous variables. Default is `var_##` for ## in
+            the number of regressors. Must match the number of parameters
+            in the model
+        title : str, optional
             Title for the top table. If not None, then this replaces the
             default title
         alpha : float
             significance level for the confidence intervals
-        float_format: string
+        float_format : str
             print format for floats in parameters summary
 
         Returns
diff --git a/statsmodels/regression/mixed_linear_model.py b/statsmodels/regression/mixed_linear_model.py
@@ -2549,13 +2549,13 @@ def summary(self, yname=None, xname_fe=None, xname_re=None,
 
         Parameters
         ----------
-        yname : string, optional
+        yname : str, optional
             Default is `y`
         xname_fe : list of strings, optional
             Fixed effects covariate names
         xname_re : list of strings, optional
             Random effects covariate names
-        title : string, optional
+        title : str, optional
             Title for the top table. If not None, then this replaces
             the default title
         alpha : float
diff --git a/statsmodels/regression/quantile_regression.py b/statsmodels/regression/quantile_regression.py
@@ -342,11 +342,13 @@ def summary(self, yname=None, xname=None, title=None, alpha=.05):
 
         Parameters
         ----------
-        yname : string, optional
+        yname : str, optional
             Default is `y`
-        xname : list of strings, optional
-            Default is `var_##` for ## in p the number of regressors
-        title : string, optional
+        xname : list[str], optional
+            Names for the exogenous variables. Default is `var_##` for ## in
+            the number of regressors. Must match the number of parameters
+            in the model
+        title : str, optional
             Title for the top table. If not None, then this replaces the
             default title
         alpha : float
diff --git a/statsmodels/robust/robust_linear_model.py b/statsmodels/robust/robust_linear_model.py
diff --git a/statsmodels/sandbox/regression/gmm.py b/statsmodels/sandbox/regression/gmm.py
diff --git a/statsmodels/stats/contingency_tables.py b/statsmodels/stats/contingency_tables.py
diff --git a/statsmodels/stats/contrast.py b/statsmodels/stats/contrast.py
diff --git a/statsmodels/tsa/arima_model.py b/statsmodels/tsa/arima_model.py
