Merge pull request matplotlib#14197 from timhoffm/doc-xcorr

Minor cleanup of acorr/xcoor docs

Author: timhoffm

.flake8

@@ -151,6 +151,7 @@ per-file-ignores =
     examples/lines_bars_and_markers/stem_plot.py: E402
     examples/lines_bars_and_markers/step_demo.py: E402
     examples/lines_bars_and_markers/timeline.py: E402
+    examples/lines_bars_and_markers/xcorr_acorr_demo.py: E402
     examples/misc/agg_buffer.py: E402
     examples/misc/anchored_artists.py: E501
     examples/misc/contour_manual.py: E501

examples/lines_bars_and_markers/xcorr_acorr_demo.py

@@ -3,8 +3,8 @@
 Cross- and Auto-Correlation Demo
 ================================
 
-Example use of cross-correlation (`xcorr`) and auto-correlation (`acorr`)
-plots.
+Example use of cross-correlation (`~.Axes.xcorr`) and auto-correlation
+(`~.Axes.acorr`) plots.
 """
 import matplotlib.pyplot as plt
 import numpy as np
@@ -18,10 +18,24 @@
 fig, [ax1, ax2] = plt.subplots(2, 1, sharex=True)
 ax1.xcorr(x, y, usevlines=True, maxlags=50, normed=True, lw=2)
 ax1.grid(True)
-ax1.axhline(0, color='black', lw=2)
 
 ax2.acorr(x, usevlines=True, normed=True, maxlags=50, lw=2)
 ax2.grid(True)
-ax2.axhline(0, color='black', lw=2)
 
 plt.show()
+
+#############################################################################
+#
+# ------------
+#
+# References
+# """"""""""
+#
+# The use of the following functions, methods, classes and modules is shown
+# in this example:
+
+import matplotlib
+matplotlib.axes.Axes.acorr
+matplotlib.axes.Axes.xcorr
+matplotlib.pyplot.acorr
+matplotlib.pyplot.xcorr

lib/matplotlib/axes/_axes.py

@@ -1904,19 +1904,25 @@ def acorr(self, x, **kwargs):
 
         Parameters
         ----------
-
-        x : sequence of scalar
+        x : array-like
 
         detrend : callable, optional, default: `mlab.detrend_none`
-            *x* is detrended by the *detrend* callable. Default is no
-            normalization.
+            *x* is detrended by the *detrend* callable. This must be a
+            function ``x = detrend(x)`` accepting and returning an
+            `numpy.array`. Default is no normalization.
 
         normed : bool, optional, default: True
             If ``True``, input vectors are normalised to unit length.
 
         usevlines : bool, optional, default: True
-            If ``True``, `Axes.vlines` is used to plot the vertical lines from
-            the origin to the acorr. Otherwise, `Axes.plot` is used.
+            Determines the plot style.
+
+            If ``True``, vertical lines are plotted from 0 to the acorr value
+            using `Axes.vlines`. Additionally, a horizontal line is plotted
+            at y=0 using `Axes.axhline`.
+
+            If ``False``, markers are plotted at the acorr values using
+            `Axes.plot`.
 
         maxlags : int, optional, default: 10
             Number of lags to show. If ``None``, will return all
@@ -1925,24 +1931,27 @@ def acorr(self, x, **kwargs):
         Returns
         -------
         lags : array (length ``2*maxlags+1``)
-            lag vector.
+            The lag vector.
         c : array  (length ``2*maxlags+1``)
-            auto correlation vector.
+            The auto correlation vector.
         line : `.LineCollection` or `.Line2D`
-            `.Artist` added to the axes of the correlation.
+            `.Artist` added to the axes of the correlation:
 
-             `.LineCollection` if *usevlines* is True
-             `.Line2D` if *usevlines* is False
+            - `.LineCollection` if *usevlines* is True.
+            - `.Line2D` if *usevlines* is False.
         b : `.Line2D` or None
             Horizontal line at 0 if *usevlines* is True
-            None *usevlines* is False
+            None *usevlines* is False.
 
         Other Parameters
         ----------------
-        linestyle : `.Line2D` property, optional, default: None
-            Only used if usevlines is ``False``.
+        linestyle : `.Line2D` property, optional
+            The linestyle for plotting the data points.
+            Only used if *usevlines* is ``False``.
 
         marker : str, optional, default: 'o'
+            The marker for plotting the data points.
+            Only used if *usevlines* is ``False``.
 
         Notes
         -----
@@ -1963,47 +1972,56 @@ def xcorr(self, x, y, normed=True, detrend=mlab.detrend_none,
 
         Parameters
         ----------
-        x : sequence of scalars of length n
+        x : array-like of length n
 
-        y : sequence of scalars of length n
+        y : array-like of length n
 
         detrend : callable, optional, default: `mlab.detrend_none`
-            *x* is detrended by the *detrend* callable. Default is no
-            normalization.
+            *x* and *y* are detrended by the *detrend* callable. This must be a
+            function ``x = detrend(x)`` accepting and returning an
+            `numpy.array`. Default is no normalization.
 
         normed : bool, optional, default: True
             If ``True``, input vectors are normalised to unit length.
 
         usevlines : bool, optional, default: True
-            If ``True``, `Axes.vlines` is used to plot the vertical lines from
-            the origin to the acorr. Otherwise, `Axes.plot` is used.
+            Determines the plot style.
 
-        maxlags : int, optional
+            If ``True``, vertical lines are plotted from 0 to the xcorr value
+            using `Axes.vlines`. Additionally, a horizontal line is plotted
+            at y=0 using `Axes.axhline`.
+
+            If ``False``, markers are plotted at the xcorr values using
+            `Axes.plot`.
+
+        maxlags : int, optional, default: 10
             Number of lags to show. If None, will return all ``2 * len(x) - 1``
-            lags. Default is 10.
+            lags.
 
         Returns
         -------
         lags : array (length ``2*maxlags+1``)
-            lag vector.
+            The lag vector.
         c : array  (length ``2*maxlags+1``)
-            auto correlation vector.
+            The auto correlation vector.
         line : `.LineCollection` or `.Line2D`
-            `.Artist` added to the axes of the correlation
+            `.Artist` added to the axes of the correlation:
 
-             `.LineCollection` if *usevlines* is True
-             `.Line2D` if *usevlines* is False
+            - `.LineCollection` if *usevlines* is True.
+            - `.Line2D` if *usevlines* is False.
         b : `.Line2D` or None
             Horizontal line at 0 if *usevlines* is True
-            None *usevlines* is False
+            None *usevlines* is False.
 
         Other Parameters
         ----------------
         linestyle : `.Line2D` property, optional
-            Only used if usevlines is ``False``.
+            The linestyle for plotting the data points.
+            Only used if *usevlines* is ``False``.
 
-        marker : string, optional
-            Default is 'o'.
+        marker : str, optional, default: 'o'
+            The marker for plotting the data points.
+            Only used if *usevlines* is ``False``.
 
         Notes
         -----