diff --git a/.flake8 b/.flake8 index 1cbb5f8f53a2..8e8ccdbccfd6 100644 --- a/.flake8 +++ b/.flake8 @@ -153,6 +153,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 diff --git a/examples/lines_bars_and_markers/xcorr_acorr_demo.py b/examples/lines_bars_and_markers/xcorr_acorr_demo.py index 3ccae86929f5..e78eefa84493 100644 --- a/examples/lines_bars_and_markers/xcorr_acorr_demo.py +++ b/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 diff --git a/lib/matplotlib/axes/_axes.py b/lib/matplotlib/axes/_axes.py index 862c7b7b4eec..3b7d8f62de7f 100644 --- a/lib/matplotlib/axes/_axes.py +++ b/lib/matplotlib/axes/_axes.py @@ -1905,19 +1905,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 @@ -1926,24 +1932,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 ----- @@ -1964,47 +1973,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 -----