DOC: Improve graphics docstrings

statsmodels/graphics/_regressionplots_doc.py

@@ -1,9 +1,10 @@
-_plot_added_variable_doc = """\
-    Create an added variable plot for a fitted regression model.
+_plot_added_variable_doc = """
+    Create an added variable plot for a fitted regression model
 
     Parameters
     ----------
-    %(extra_params_doc)sfocus_exog : int or string
+    %(extra_params_doc)s
+    focus_exog : int or string
         The column index of exog, or a variable name, indicating the
         variable whose role in the regression is to be assessed.
     resid_type : str
@@ -17,7 +18,7 @@
     fit_kwargs : dict, optional
         Keyword arguments to be passed to fit when refitting the
         model.
-    ax: Axes
+    ax : Axes
         Matplotlib Axes instance
 
     Returns
@@ -26,16 +27,17 @@
         A matplotlib figure instance.
 """
 
-_plot_partial_residuals_doc = """\
+_plot_partial_residuals_doc = """
     Create a partial residual, or 'component plus residual' plot for a
-    fitted regression model.
+    fitted regression model
 
     Parameters
     ----------
-    %(extra_params_doc)sfocus_exog : int or string
+    %(extra_params_doc)s
+    focus_exog : int or string
         The column index of exog, or variable name, indicating the
         variable whose role in the regression is to be assessed.
-    ax: Axes
+    ax : Axes
         Matplotlib Axes instance
 
     Returns
@@ -44,8 +46,8 @@
         A matplotlib figure instance.
 """
 
-_plot_ceres_residuals_doc = """\
-    Conditional Expectation Partial Residuals (CERES) plot.
+_plot_ceres_residuals_doc = """
+    Conditional Expectation Partial Residuals (CERES) plot
 
     Produce a CERES plot for a fitted regression model.
 
@@ -122,8 +124,8 @@
 """
 
 
-_plot_influence_doc = """\
-    Plot of influence in regression. Plots studentized resids vs. leverage.
+_plot_influence_doc = """
+    Plot of influence in regression. Plots studentized resids vs. leverage
 
     Parameters
     ----------
@@ -180,13 +182,12 @@
     """
 
 
-_plot_leverage_resid2_doc = """\
+_plot_leverage_resid2_doc = """
     Plot leverage statistics vs. normalized residuals squared
 
     Parameters
     ----------
-    results : results instance
-        A regression results instance
+    {extra_params_doc}
     alpha : float
         Specifies the cut-off for large-standardized residuals. Residuals
         are assumed to be distributed N(0, 1) with alpha=alpha.

statsmodels/graphics/agreement.py

@@ -20,7 +20,7 @@ def mean_diff_plot(
     limit_lines_kwds=None,
 ):
     """
-    Construct a Tukey/Bland-Altman Mean Difference Plot.
+    Construct a Tukey/Bland-Altman Mean Difference Plot
 
     Tukey's Mean Difference Plot (also known as a Bland-Altman plot) is a
     graphical method to analyze the differences between two methods of
@@ -44,18 +44,18 @@ def mean_diff_plot(
         of the differences. If sd_limit = 0, no limits will be plotted, and
         the ylimit of the plot defaults to 3 standard deviations on either
         side of the mean.
-    ax : AxesSubplot
+    ax : AxesSubplot, optional
         If `ax` is None, then a figure is created. If an axis instance is
         given, the mean difference plot is drawn on the axis.
-    scatter_kwds : dict
-        Options to to style the scatter plot. Accepts any keywords for the
-        matplotlib Axes.scatter plotting method
-    mean_line_kwds : dict
-        Options to to style the scatter plot. Accepts any keywords for the
-        matplotlib Axes.axhline plotting method
-    limit_lines_kwds : dict
-        Options to to style the scatter plot. Accepts any keywords for the
-        matplotlib Axes.axhline plotting method
+    scatter_kwds : dict, optional
+        Options to style the scatter plot. Accepts any keywords for the
+        matplotlib Axes.scatter plotting method.
+    mean_line_kwds : dict, optional
+        Options to style the mean difference line. Accepts any keywords for
+        the matplotlib Axes.axhline plotting method.
+    limit_lines_kwds : dict, optional
+        Options to style the limit-of-agreement lines. Accepts any keywords
+        for the matplotlib Axes.axhline plotting method.
 
     Returns
     -------
@@ -65,8 +65,8 @@ def mean_diff_plot(
 
     References
     ----------
-    Bland JM, Altman DG (1986). "Statistical methods for assessing agreement
-    between two methods of clinical measurement"
+    .. [1] Bland JM, Altman DG (1986). "Statistical methods for assessing
+           agreement between two methods of clinical measurement"
 
     Examples
     --------

statsmodels/graphics/boxplots.py

@@ -1,4 +1,4 @@
-"""Variations on boxplots."""
+"""Variations on boxplots"""
 
 # Author: Ralf Gommers
 # Based on code by Flavio Coelho and Teemu Ikonen.
@@ -23,7 +23,7 @@ def violinplot(
     plot_opts=None,
 ):
     """
-    Make a violin plot of each dataset in the `data` sequence.
+    Make a violin plot of each dataset in the `data` sequence
 
     A violin plot is a boxplot combined with a kernel density estimate of the
     probability density function per point.
@@ -54,7 +54,7 @@ def violinplot(
           - 'violin_fc', MPL color.  Fill color for violins.  Default is 'y'.
           - 'violin_ec', MPL color.  Edge color for violins.  Default is 'k'.
           - 'violin_lw', scalar.  Edge linewidth for violins.  Default is 1.
-          - 'violin_alpha', float.  Transparancy of violins.  Default is 0.5.
+          - 'violin_alpha', float.  Transparency of violins.  Default is 0.5.
           - 'cutoff', bool.  If True, limit violin range to data range.
                 Default is False.
           - 'cutoff_val', scalar.  Where to cut off violins if `cutoff` is
@@ -167,11 +167,11 @@ def violinplot(
 
 
 def _single_violin(ax, pos, pos_data, width, side, plot_opts):
-    """"""
+    """Draw a single violin onto `ax` at position `pos`"""
     bw_factor = plot_opts.get("bw_factor", None)
 
     def _violin_range(pos_data, plot_opts):
-        """Return array with correct range, with which violins can be plotted."""
+        """Return array with correct range, with which violins can be plotted"""
         cutoff = plot_opts.get("cutoff", False)
         cutoff_type = plot_opts.get("cutoff_type", "std")
         cutoff_val = plot_opts.get("cutoff_val", 1.5)
@@ -221,7 +221,7 @@ def _violin_range(pos_data, plot_opts):
 
 
 def _set_ticks_labels(ax, data, labels, positions, plot_opts):
-    """Set ticks and labels on horizontal axis."""
+    """Set ticks and labels on horizontal axis"""
 
     # Set xticks and limits.
     ax.set_xlim([np.min(positions) - 0.5, np.max(positions) + 0.5])
@@ -257,7 +257,7 @@ def beanplot(
     rng=None,
 ):
     """
-    Bean plot of each dataset in a sequence.
+    Bean plot of each dataset in a sequence
 
     A bean plot is a combination of a `violinplot` (kernel density estimate of
     the probability density function per point) with a line-scatter plot of all
@@ -267,7 +267,7 @@ def beanplot(
     ----------
     data : sequence[array_like]
         Data arrays, one array per value in `positions`.
-    ax : AxesSubplot
+    ax : AxesSubplot, optional
         If given, this subplot is used to plot in instead of a new figure being
         created.
     labels : list[str], optional
@@ -440,7 +440,7 @@ def beanplot(
 
 
 def _jitter_envelope(pos_data, xvals, violin, side, rng):
-    """Determine envelope for jitter markers."""
+    """Determine envelope for jitter markers"""
     if side == "both":
         low, high = (-1.0, 1.0)
     elif side == "right":
@@ -457,7 +457,7 @@ def _jitter_envelope(pos_data, xvals, violin, side, rng):
 
 
 def _show_legend(ax):
-    """Utility function to show legend."""
+    """Utility function to show legend"""
     leg = ax.legend(loc=1, shadow=True, fancybox=True, labelspacing=0.2, borderpad=0.15)
     ltext = leg.get_texts()
     llines = leg.get_lines()

statsmodels/graphics/correlation.py

@@ -1,11 +1,11 @@
-"""correlation plots
+"""
+Correlation plots
 
 Author: Josef Perktold
 License: BSD-3
 
 example for usage with different options in
 statsmodels/sandbox/examples/thirdparty/ex_ratereturn.py
-
 """
 import numpy as np
 
@@ -14,7 +14,8 @@
 
 def plot_corr(dcorr, xnames=None, ynames=None, title=None, normcolor=False,
               ax=None, cmap="RdYlBu_r"):
-    """Plot correlation of many variables in a tight color grid.
+    """
+    Plot correlation of many variables in a tight color grid
 
     Parameters
     ----------
@@ -124,7 +125,7 @@ def plot_corr(dcorr, xnames=None, ynames=None, title=None, normcolor=False,
 def plot_corr_grid(dcorrs, titles=None, ncols=None, normcolor=False, xnames=None,
                    ynames=None, fig=None, cmap="RdYlBu_r"):
     """
-    Create a grid of correlation plots.
+    Create a grid of correlation plots
 
     The individual correlation plots are assumed to all have the same
     variables, axis labels can be specified only once.
@@ -160,8 +161,8 @@ def plot_corr_grid(dcorrs, titles=None, ncols=None, normcolor=False, xnames=None
     Returns
     -------
     Figure
-        If `ax` is None, the created figure.  Otherwise the figure to which
-        `ax` is connected.
+        If `fig` is None, the created figure.  Otherwise the figure that was
+        passed in.
 
     Examples
     --------

statsmodels/graphics/dotplots.py

@@ -11,7 +11,7 @@ def dot_plot(points, intervals=None, lines=None, sections=None,
              fmt_left_name=None, fmt_right_name=None,
              show_section_titles=None, ax=None):
     """
-    Dot plotting (also known as forest and blobbogram).
+    Dot plotting (also known as forest and blobbogram)
 
     Produce a dotplot similar in style to those in Cleveland's
     "Visualizing Data" book ([1]_).  These are also known as "forest plots".
@@ -82,7 +82,7 @@ def dot_plot(points, intervals=None, lines=None, sections=None,
         The left/top margin names are passed through this function
         before drawing on the plot.
     fmt_right_name : callable
-        The right/bottom marginnames are passed through this function
+        The right/bottom margin names are passed through this function
         before drawing on the plot.
     show_section_titles : bool or None
         If None, section titles are drawn only if there is more than

statsmodels/graphics/factorplots.py

@@ -27,12 +27,7 @@ def interaction_plot(
     **kwargs,
 ):
     """
-    Interaction plot for factor level statistics.
-
-    Note. If categorial factors are supplied levels will be internally
-    recoded to integers. This ensures matplotlib compatibility. Uses
-    a DataFrame to calculate an `aggregate` statistic for each level of the
-    factor or group given by `trace`.
+    Interaction plot for factor level statistics
 
     Parameters
     ----------
@@ -44,14 +39,14 @@ def interaction_plot(
         If `trace` is a `pandas.Series` its name will be used as the
         `legendtitle` if `legendtitle` is None.
     response : array_like
-        The reponse or dependent variable. If a `pandas.Series` is given
+        The response or dependent variable. If a `pandas.Series` is given
         its name will be used in `ylabel` if `ylabel` is None.
-    func : function
+    func : str or callable
         Anything accepted by `pandas.DataFrame.aggregate`. This is applied to
         the response variable grouped by the trace levels.
     ax : axes, optional
         Matplotlib axes instance
-    plottype : str {'line', 'scatter', 'both'}, optional
+    plottype : {'b', 'both', 'l', 'line', 's', 'scatter'}, optional
         The type of plot to return. Can be 'l', 's', or 'b'
     xlabel : str, optional
         Label to use for `x`. Default is 'X'. If `x` is a `pandas.Series` it
@@ -78,6 +73,13 @@ def interaction_plot(
     Figure
         The figure given by `ax.figure` or a new instance.
 
+    Notes
+    -----
+    If categorical factors are supplied levels will be internally
+    recoded to integers. This ensures matplotlib compatibility. Uses
+    a DataFrame to calculate an `aggregate` statistic for each level of the
+    factor or group given by `trace`.
+
     Examples
     --------
     >>> import numpy as np
@@ -191,19 +193,22 @@ def interaction_plot(
 
 
 def _recode(x, levels):
-    """Recode categorial data to int factor.
+    """
+    Recode categorical data to int factor
 
     Parameters
     ----------
     x : array_like
-        array like object supporting with numpy array methods of categorially
-        coded data.
+        Array-like object of categorically coded data, supporting numpy
+        array methods.
     levels : dict
-        mapping of labels to integer-codings
+        Mapping of labels to integer codings.
 
     Returns
     -------
-    out : instance numpy.ndarray
+    out : ndarray or Series
+        The recoded data as an ndarray, or as a Series with the same name
+        and index as `x` if `x` was a `pandas.Series`.
     """
     from pandas import Series