WCSAxes#

class astropy.visualization.wcsaxes.WCSAxes(fig, *args, wcs=None, transform=None, coord_meta=None, transData=None, slices=None, frame_class=None, **kwargs)[source]#

Bases: Axes

The main axes class that can be used to show world coordinates from a WCS.

Parameters:

figFigure: The figure to add the axes to.
*args: *args can be a single (left, bottom, width, height) rectangle or a single matplotlib.transforms.Bbox. This specifies the rectangle (in figure coordinates) where the Axes is positioned. *args can also consist of three numbers or a single three-digit number; in the latter case, the digits are considered as independent numbers. The numbers are interpreted as (nrows, ncols, index): (nrows, ncols) specifies the size of an array of subplots, and index is the 1-based index of the subplot being created. Finally, *args can also directly be a matplotlib.gridspec.SubplotSpec instance.
wcsWCS, optional: The WCS for the data. If this is specified, transform cannot be specified.
transformTransform, optional: The transform for the data. If this is specified, wcs cannot be specified.
coord_metadict, optional: A dictionary providing additional metadata when transform is specified. This should include the keys type, wrap, and unit. Each of these should be a list with as many items as the dimension of the WCS. The type entries should be one of longitude, latitude, or scalar, the wrap entries should give, for the longitude, the angle at which the coordinate wraps (and None otherwise), and the unit should give the unit of the coordinates as Unit instances. This can optionally also include a format_unit entry giving the units to use for the tick labels (if not specified, this defaults to unit).
transDataTransform, optional: Can be used to override the default data -> pixel mapping.
slicestuple, optional: For WCS transformations with more than two dimensions, we need to choose which dimensions are being shown in the 2D image. The slice should contain one x entry, one y entry, and the rest of the values should be integers indicating the slice through the data. The order of the items in the slice should be the same as the order of the dimensions in the WCS, and the opposite of the order of the dimensions in Numpy. For example, (50, 'x', 'y') means that the first WCS dimension (last Numpy dimension) will be sliced at an index of 50, the second WCS and Numpy dimension will be shown on the x axis, and the final WCS dimension (first Numpy dimension) will be shown on the y-axis (and therefore the data will be plotted using data[:, :, 50].transpose()).
frame_classtype, optional: The class for the frame, which should be a subclass of BaseFrame. The default is to use a RectangularFrame.
**kwargs: Additional keyword arguments are passed to Axes.

Attributes:

coordsCoordinatesMap: Container for coordinate information.

Methods Summary

`contour`(args, *kwargs)	Plot contours.
`contourf`(args, *kwargs)	Plot filled contours.
`draw`(renderer)	Draw the axes.
`draw_wcsaxes`(renderer)
`get_coords_overlay`(frame[, coord_meta])	Get coordinates overlay on given frame.
`get_tightbbox`(renderer, args, *kwargs)	Return the tight bounding box of the Axes, including axis and their decorators (xlabel, title, etc).
`get_transform`(frame)	Return a transform from the specified frame to display coordinates.
`get_xlabel`()	Get the xlabel text string.
`get_ylabel`()	Get the ylabel text string.
`grid`([b, axis, which])	Plot gridlines for both coordinates.
`imshow`(X, args, *kwargs)	Wrapper to Matplotlib's `imshow()`.
`plot_coord`(args, *kwargs)	Plot `SkyCoord` or `BaseCoordinateFrame` objects onto the axes.
`reset_wcs`([wcs, slices, transform, coord_meta])	Reset the current Axes, to use a new WCS object.
`scatter_coord`(args, *kwargs)	Scatter `SkyCoord` or `BaseCoordinateFrame` objects onto the axes.
`set`(*[, adjustable, agg_filter, alpha, ...])	Set multiple properties at once.
`set_xlabel`([xlabel, labelpad, loc])	Set x-label.
`set_ylabel`([ylabel, labelpad, loc])	Set y-label.
`text_coord`(args, *kwargs)	Print a text string using `SkyCoord` or `BaseCoordinateFrame` objects onto the axes.
`tick_params`([axis])	Method to set the tick and tick label parameters in the same way as the `tick_params()` method in Matplotlib.

Methods Documentation

contour(*args, **kwargs)[source]#

Plot contours.

This is a custom implementation of contour() which applies the transform (if specified) to all contours in one go for performance rather than to each contour line individually.

Parameters:

*args, **kwargs: All positional and keyword arguments are the same as for contour().

contourf(*args, **kwargs)[source]#

Plot filled contours.

This is a custom implementation of contourf() which applies the transform (if specified) to all contours in one go for performance rather than to each contour line individually.

Parameters:

*args, **kwargs: All positional and keyword arguments are the same as for contourf().

draw(renderer)[source]#

Draw the axes.

Parameters:

rendererRendererBase: The renderer to draw with.

draw_wcsaxes(renderer)[source]#

get_coords_overlay(frame, coord_meta=None)[source]#

Get coordinates overlay on given frame.

Parameters:

framestr, BaseCoordinateFrame: Frame to get overlay for. If a string must correspond to one of the coordinate frames registered in the astropy frame transform graph.
coord_metadict: Metadata for the coordinates overlay.

Returns:

overlayCoordinatesMap: Coordinates overlay.

get_tightbbox(renderer, *args, **kwargs)[source]#

Return the tight bounding box of the Axes, including axis and their decorators (xlabel, title, etc).

Artists that have artist.set_in_layout(False) are not included in the bbox.

Parameters:

rendererRendererBase subclass: renderer that will be used to draw the figures (i.e. fig.canvas.get_renderer())
bbox_extra_artistslist of Artist or None: List of artists to include in the tight bounding box. If None (default), then all artist children of the Axes are included in the tight bounding box.
call_axes_locatorbool, default: True: If call_axes_locator is False, it does not call the _axes_locator attribute, which is necessary to get the correct bounding box. call_axes_locator=False can be used if the caller is only interested in the relative size of the tightbbox compared to the Axes bbox.
for_layout_onlydefault: False: The bounding box will not include the x-extent of the title and the xlabel, or the y-extent of the ylabel.

Returns:

BboxBase: Bounding box in figure pixel coordinates.

See also

matplotlib.axes.Axes.get_window_extent
matplotlib.axis.Axis.get_tightbbox
matplotlib.spines.Spine.get_window_extent

get_transform(frame)[source]#

Return a transform from the specified frame to display coordinates.

This includes the transData transformation

Parameters:

frameWCS or Transform or str

The frame parameter can have several possible types:

WCS instance: assumed to be a transformation from pixel to world coordinates, where the world coordinates are the same as those in the WCS transformation used for this WCSAxes instance. This is used for example to show contours, since this involves plotting an array in pixel coordinates that are not the final data coordinate and have to be transformed to the common world coordinate system first.
Transform instance: it is assumed to be a transform to the world coordinates that are part of the WCS used to instantiate this WCSAxes instance.
'pixel' or 'world': return a transformation that allows users to plot in pixel/data coordinates (essentially an identity transform) and world (the default world-to-pixel transformation used to instantiate the WCSAxes instance).
'fk5' or 'galactic': return a transformation from the specified frame to the pixel/data coordinates. In this case, the values are assumed to be in degrees.
BaseCoordinateFrame instance. In this case, the values are assumed to be in degrees.

get_xlabel()[source]#: Get the xlabel text string.

get_ylabel()[source]#: Get the ylabel text string.

grid(b=None, axis='both', *, which='major', **kwargs)[source]#

Plot gridlines for both coordinates.

Standard matplotlib appearance options (color, alpha, etc.) can be passed as keyword arguments. This behaves like matplotlib.axes.Axes except that if no arguments are specified, the grid is shown rather than toggled.

Parameters:

bbool: Whether to show the gridlines.
axis‘both’, ‘x’, ‘y’: Which axis to turn the gridlines on/off for.
whichstr: Currently only 'major' is supported.
**kwargs: Standard matplotlib appearance keyword arguments (color, alpha, etc.) to use for the grid lines.

imshow(X, *args, **kwargs)[source]#

Wrapper to Matplotlib’s imshow().

If an RGB image is passed as a PIL object, it will be flipped vertically and origin will be set to lower, since WCS transformations - like FITS files - assume that the origin is the lower left pixel of the image (whereas RGB images have the origin in the top left).

Parameters:

Xarray_like: The image data, as for imshow(). A PIL image is also accepted.
*args, **kwargs: All other arguments are passed to imshow().

plot_coord(*args, **kwargs)[source]#

Plot SkyCoord or BaseCoordinateFrame objects onto the axes.

The first argument to plot_coord() should be a coordinate, which will then be converted to the first two parameters to matplotlib.axes.Axes.plot. All other arguments are the same as matplotlib.axes.Axes.plot. If not specified a transform keyword argument will be created based on the coordinate.

Parameters:

*args: The first positional argument should be the coordinate object to plot on the axes, as a SkyCoord or BaseCoordinateFrame instance. This is converted to the first two arguments to matplotlib.axes.Axes.plot, and any remaining positional arguments are passed on unchanged.
**kwargs: All keyword arguments are passed to matplotlib.axes.Axes.plot.

See also

matplotlib.axes.Axes.plot: This method is called from this function with all arguments passed to it.

reset_wcs(wcs=None, slices=None, transform=None, coord_meta=None)[source]#

Reset the current Axes, to use a new WCS object.

Parameters:

wcsWCS, optional: The new WCS for the data. See the WCSAxes documentation for a full description of this and the following arguments.
slicestuple, optional: For WCS transformations with more than two dimensions, the dimensions being shown in the 2D image.
transformTransform, optional: The transform for the data, as an alternative to wcs.
coord_metadict, optional: A dictionary providing additional metadata when transform is specified. See the WCSAxes documentation for a full description of the accepted keys.

scatter_coord(*args, **kwargs)[source]#

Scatter SkyCoord or BaseCoordinateFrame objects onto the axes.

The first argument to scatter_coord() should be a coordinate, which will then be converted to the first two parameters to matplotlib.axes.Axes.scatter. All other arguments are the same as matplotlib.axes.Axes.scatter. If not specified a transform keyword argument will be created based on the coordinate.

Parameters:

*args: The first positional argument should be the coordinate object to scatter on the axes, as a SkyCoord or BaseCoordinateFrame instance. This is converted to the first two arguments to matplotlib.axes.Axes.scatter, and any remaining positional arguments are passed on unchanged.
**kwargs: All keyword arguments are passed to matplotlib.axes.Axes.scatter.

See also

matplotlib.axes.Axes.scatter: This method is called from this function with all arguments passed to it.

set(*, adjustable=<UNSET>, agg_filter=<UNSET>, alpha=<UNSET>, anchor=<UNSET>, animated=<UNSET>, aspect=<UNSET>, autoscale_on=<UNSET>, autoscalex_on=<UNSET>, autoscaley_on=<UNSET>, axes_locator=<UNSET>, axisbelow=<UNSET>, box_aspect=<UNSET>, clip_box=<UNSET>, clip_on=<UNSET>, clip_path=<UNSET>, facecolor=<UNSET>, forward_navigation_events=<UNSET>, frame_on=<UNSET>, gid=<UNSET>, in_layout=<UNSET>, label=<UNSET>, mouseover=<UNSET>, navigate=<UNSET>, path_effects=<UNSET>, picker=<UNSET>, position=<UNSET>, prop_cycle=<UNSET>, rasterization_zorder=<UNSET>, rasterized=<UNSET>, sketch_params=<UNSET>, snap=<UNSET>, subplotspec=<UNSET>, title=<UNSET>, transform=<UNSET>, url=<UNSET>, visible=<UNSET>, xbound=<UNSET>, xinverted=<UNSET>, xlabel=<UNSET>, xlim=<UNSET>, xmargin=<UNSET>, xscale=<UNSET>, xticklabels=<UNSET>, xticks=<UNSET>, ybound=<UNSET>, yinverted=<UNSET>, ylabel=<UNSET>, ylim=<UNSET>, ymargin=<UNSET>, yscale=<UNSET>, yticklabels=<UNSET>, yticks=<UNSET>, zorder=<UNSET>)#

Set multiple properties at once.

a.set(a=A, b=B, c=C)

is equivalent to

a.set_a(A)
a.set_b(B)
a.set_c(C)

In addition to the full property names, aliases are also supported, e.g. set(lw=2) is equivalent to set(linewidth=2), but it is an error to pass both simultaneously.

The order of the individual setter calls matches the order of parameters in set(). However, most properties do not depend on each other so that order is rarely relevant.

Supported properties are

Properties:: adjustable: {‘box’, ‘datalim’} agg_filter: a filter function, which takes a (m, n, 3) float array and a dpi value, and returns a (m, n, 3) array and two offsets from the bottom left corner of the image alpha: float or None anchor: (float, float) or {‘C’, ‘SW’, ‘S’, ‘SE’, ‘E’, ‘NE’, …} animated: bool aspect: {‘auto’, ‘equal’} or float autoscale_on: bool autoscalex_on: unknown autoscaley_on: unknown axes_locator: Callable[[Axes, Renderer], Bbox] axisbelow: bool or ‘line’ box_aspect: float or None clip_box: BboxBase or None clip_on: bool clip_path: Patch or (Path, Transform) or None facecolor or fc: color figure: Figure or SubFigure forward_navigation_events: bool or “auto” frame_on: bool gid: str in_layout: bool label: object mouseover: bool navigate: bool navigate_mode: unknown path_effects: list of AbstractPathEffect picker: None or bool or float or callable position: [left, bottom, width, height] or Bbox prop_cycle: Cycler rasterization_zorder: float or None rasterized: bool sketch_params: (scale: float, length: float, randomness: float) snap: bool or None subplotspec: unknown title: str transform: Transform url: str visible: bool xbound: (lower: float, upper: float) xinverted: unknown xlabel: str xlim: (left: float, right: float) xmargin: float greater than -0.5 xscale: unknown xticklabels: unknown xticks: unknown ybound: (lower: float, upper: float) yinverted: unknown ylabel: str ylim: (bottom: float, top: float) ymargin: float greater than -0.5 yscale: unknown yticklabels: unknown yticks: unknown zorder: float

set_xlabel(xlabel=None, labelpad=1, loc=None, **kwargs)[source]#

Set x-label.

Parameters:

xlabelstr: The label text.
labelpadfloat, optional: The minimum distance between the label and the axis, in points.
locstr, optional: Not supported by WCSAxes and ignored.
**kwargs: Additional keyword arguments are passed to set_axislabel.

set_ylabel(ylabel=None, labelpad=1, loc=None, **kwargs)[source]#

Set y-label.

Parameters:

ylabelstr: The label text.
labelpadfloat, optional: The minimum distance between the label and the axis, in points.
locstr, optional: Not supported by WCSAxes and ignored.
**kwargs: Additional keyword arguments are passed to set_axislabel.

text_coord(*args, **kwargs)[source]#

Print a text string using SkyCoord or BaseCoordinateFrame objects onto the axes.

The first argument to text_coord() should be a coordinate, which will then be converted to the first two parameters to matplotlib.axes.Axes.text. All other arguments are the same as matplotlib.axes.Axes.text. If not specified a transform keyword argument will be created based on the coordinate.

Parameters:

*args: The first positional argument should be the coordinate object to plot on the axes, as a SkyCoord or BaseCoordinateFrame instance. This is converted to the first two arguments to matplotlib.axes.Axes.text, and any remaining positional arguments are passed on unchanged.
**kwargs: All keyword arguments are passed to matplotlib.axes.Axes.text.

See also

matplotlib.axes.Axes.text: This method is called from this function with all arguments passed to it.

tick_params(axis='both', **kwargs)[source]#

Method to set the tick and tick label parameters in the same way as the tick_params() method in Matplotlib.

This is provided for convenience, but the recommended API is to use set_ticks(), set_ticklabel(), set_ticks_position(), set_ticklabel_position(), and grid().

Parameters:

axisint or str, optional

Which axis to apply the parameters to. This defaults to ‘both’ but this can also be set to an int or str that refers to the axis to apply it to, following the valid values that can index ax.coords. Note that 'x' and 'y’ are also accepted in the case of rectangular axes.

which{‘both’, ‘major’, ‘minor’}, optional

Which ticks to apply the settings to. By default, setting are applied to both major and minor ticks. Note that if 'minor' is specified, only the length of the ticks can be set currently.

direction{‘in’, ‘out’}, optional

Puts ticks inside the axes, or outside the axes.

lengthfloat, optional

Tick length in points.

widthfloat, optional

Tick width in points.

colorcolor, optional

Tick color (accepts any valid Matplotlib color)

padfloat, optional

Distance in points between tick and label.

labelsizefloat or str, optional

Tick label font size in points or as a string (e.g., ‘large’).

labelcolorcolor, optional

Tick label color (accepts any valid Matplotlib color)

colorscolor, optional

Changes the tick color and the label color to the same value: (accepts any valid Matplotlib color).

bottom, top, left, rightbool, optional

Where to draw the ticks. Note that this can only be given if a specific coordinate is specified via the axis argument, and it will not work correctly if the frame is not rectangular.

labelbottom, labeltop, labelleft, labelrightbool, optional

Where to draw the tick labels. Note that this can only be given if a specific coordinate is specified via the axis argument, and it will not work correctly if the frame is not rectangular.

grid_colorcolor, optional

The color of the grid lines (accepts any valid Matplotlib color).

grid_alphafloat, optional

Transparency of grid lines: 0 (transparent) to 1 (opaque).

grid_linewidthfloat, optional

Width of grid lines in points.

grid_linestylestr, optional

The style of the grid lines (accepts any valid Matplotlib line style).