Skip to content

Improve docstring of Axes.spy #11366

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Jun 5, 2018
Merged

Improve docstring of Axes.spy #11366

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
94 changes: 59 additions & 35 deletions lib/matplotlib/axes/_axes.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5044,7 +5044,7 @@ def imshow(self, X, cmap=None, norm=None, aspect=None,
that the data fit in the axes. In general, this will result in
non-square pixels.

Defaults to :rc:`image.aspect`.
If not given, use :rc:`image.aspect` (default: 'equal').

interpolation : str, optional
The interpolation method used. If *None*
Expand Down Expand Up @@ -7290,64 +7290,88 @@ def specgram(self, x, NFFT=None, Fs=None, Fc=None, detrend=None,

return spec, freqs, t, im

@docstring.dedent_interpd
def spy(self, Z, precision=0, marker=None, markersize=None,
aspect='equal', origin="upper", **kwargs):
"""
Plot the sparsity pattern on a 2-D array.
Plot the sparsity pattern of a 2D array.

This visualizes the non-zero values of the array.

Two plotting styles are available: image and marker. Both
are available for full arrays, but only the marker style
works for `scipy.sparse.spmatrix` instances.

``spy(Z)`` plots the sparsity pattern of the 2-D array *Z*.
**Image style**

If *marker* and *markersize* are *None*, `~.Axes.imshow` is used. Any
extra remaining kwargs are passed to this method.

**Marker style**

If *Z* is a `scipy.sparse.spmatrix` or *marker* or *markersize* are
*None*, a `~matplotlib.lines.Line2D` object will be returned with
the value of marker determining the marker type, and any
remaining kwargs passed to `~.Axes.plot`.

Parameters
----------

Z : sparse array (n, m)
Z : array-like (M, N)
The array to be plotted.

precision : float, optional, default: 0
If *precision* is 0, any non-zero value will be plotted; else,
precision : float or 'present', optional, default: 0
If *precision* is 0, any non-zero value will be plotted. Otherwise,
values of :math:`|Z| > precision` will be plotted.

For :class:`scipy.sparse.spmatrix` instances, there is a special
case: if *precision* is 'present', any value present in the array
For :class:`scipy.sparse.spmatrix` instances, you can also
pass 'present'. In this case any value present in the array
will be plotted, even if it is identically zero.

origin : ["upper", "lower"], optional, default: "upper"
origin : {'upper', 'lower'}, optional
Place the [0,0] index of the array in the upper left or lower left
corner of the axes.
corner of the axes. The convention 'upper' is typically used for
matrices and images.
If not given, :rc:`image.origin` is used, defaulting to 'upper'.


aspect : ['auto' | 'equal' | scalar], optional, default: "equal"
aspect : {'equal', 'auto', None} or float, optional
Controls the aspect ratio of the axes. The aspect is of particular
relevance for images since it may distort the image, i.e. pixel
will not be square.

If 'equal', and `extent` is None, changes the axes aspect ratio to
match that of the image. If `extent` is not `None`, the axes
aspect ratio is changed to match that of the extent.
This parameter is a shortcut for explicitly calling
`.Axes.set_aspect`. See there for further details.

- 'equal': Ensures an aspect ratio of 1. Pixels will be square.
- 'auto': The axes is kept fixed and the aspect is adjusted so
that the data fit in the axes. In general, this will result in
non-square pixels.
- *None*: Use :rc:`image.aspect` (default: 'equal').

If 'auto', changes the image aspect ratio to match that of the
axes.
Default: 'equal'

If None, default to rc ``image.aspect`` value.
Returns
-------
ret : `~matplotlib.image.AxesImage` or `.Line2D`
The return type depends on the plotting style (see above).

Two plotting styles are available: image or marker. Both
are available for full arrays, but only the marker style
works for :class:`scipy.sparse.spmatrix` instances.
Other Parameters
----------------
**kwargs
The supported additional parameters depend on the plotting style.

If *marker* and *markersize* are *None*, an image will be
returned and any remaining kwargs are passed to
:func:`~matplotlib.pyplot.imshow`; else, a
:class:`~matplotlib.lines.Line2D` object will be returned with
the value of marker determining the marker type, and any
remaining kwargs passed to the
:meth:`~matplotlib.axes.Axes.plot` method.
For the image style, you can pass the following additional
parameters of `~.Axes.imshow`:

If *marker* and *markersize* are *None*, useful kwargs include:
- *cmap*
- *alpha*
- *url*
- any `.Artist` properties (passed on to the `.AxesImage`)

* *cmap*
* *alpha*
For the marker style, you can pass any `.Line2D` property except
for *linestyle*:

See also
--------
imshow : for image options.
plot : for plotting options
%(Line2D)s
"""
if marker is None and markersize is None and hasattr(Z, 'tocoo'):
marker = 's'
Expand Down