Skip to main content
`Ctrl`+`K`

# WCSAxes

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

  Bases: `Axes`

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

  Parameters:
    fig `Figure`

      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.

    wcs `WCS`, optional

      The WCS for the data. If this is specified, `transform` cannot be specified.

    transform `Transform`, optional

      The transform for the data. If this is specified, `wcs` cannot be specified.

    coord_meta `python:dict`, 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`).

    transData `Transform`, optional

      Can be used to override the default data -> pixel mapping.

    slices `python:tuple`, 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_class type, optional

      The class for the frame, which should be a subclass of `BaseFrame`. The default is to use a `RectangularFrame`

  Attributes:
    coords `CoordinatesMap`

      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)

    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. All positional and keyword arguments are the same as for `contour()`.

  contourf(*args, **kwargs)

    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. All positional and keyword arguments are the same as for `contourf()`.

  draw(renderer)

    Draw the axes.

  draw_wcsaxes(renderer)
  get_coords_overlay(frame, coord_meta=None)

    Get coordinates overlay on given frame.

    Parameters:
      frame `python:str`, `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_meta `python:dict`

        Metadata for the coordinates overlay.

    Returns:
      overlay `CoordinatesMap`

        Coordinates overlay.

  get_tightbbox(renderer, *args, **kwargs)

    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:
      renderer `RendererBase` subclass

        renderer that will be used to draw the figures (i.e. `fig.canvas.get_renderer()`)

      bbox_extra_artists `python:list` 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_locator bool, default: `python: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_only default: `python: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)

    Return a transform from the specified frame to display coordinates.

    This includes the transData transformation

    Parameters:
      frame `WCS` or `Transform` or `python: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()

    Get the xlabel text string.

  get_ylabel()

    Get the ylabel text string.

  grid(b=None, axis='both', *, which='major', **kwargs)

    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:
      b bool

        Whether to show the gridlines.

      axis‘both’, ‘x’, ‘y’

        Which axis to turn the gridlines on/off for.

      which `python:str`

        Currently only `'major'` is supported.

  imshow(X, *args, **kwargs)

    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).

    All arguments are passed to `imshow()`.

  plot_coord(*args, **kwargs)

    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:
      coordinate `SkyCoord` or `BaseCoordinateFrame`

        The coordinate object to plot on the axes. This is converted to the first two arguments 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)

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

  scatter_coord(*args, **kwargs)

    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:
      coordinate `SkyCoord` or `BaseCoordinateFrame`

        The coordinate object to scatter on the axes. This is converted to the first two arguments 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>, xlabel=<UNSET>, xlim=<UNSET>, xmargin=<UNSET>, xscale=<UNSET>, xticklabels=<UNSET>, xticks=<UNSET>, ybound=<UNSET>, ylabel=<UNSET>, ylim=<UNSET>, ymargin=<UNSET>, yscale=<UNSET>, yticklabels=<UNSET>, yticks=<UNSET>, zorder=<UNSET>)

    Set multiple properties at once.

    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: :mpltype:`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) xlabel: unknown xlim: (left: float, right: float) xmargin: float greater than -0.5 xscale: unknown xticklabels: unknown xticks: unknown ybound: (lower: float, upper: float) ylabel: unknown 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)

    Set x-label.

  set_ylabel(ylabel=None, labelpad=1, loc=None, **kwargs)

    Set y-label.

  text_coord(*args, **kwargs)

    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:
      coordinate `SkyCoord` or `BaseCoordinateFrame`

        The coordinate object to plot on the axes. This is converted to the first two arguments 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)

    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:
      axis `python:int` or `python: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.

      length `python:float`, optional

        Tick length in points.

      width `python:float`, optional

        Tick width in points.

      color color, optional

        Tick color (accepts any valid Matplotlib color)

      pad `python:float`, optional

        Distance in points between tick and label.

      labelsize `python:float` or `python:str`, optional

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

      labelcolor color, optional

        Tick label color (accepts any valid Matplotlib color)

      colors color, optional
        Changes the tick color and the label color to the same value

          (accepts any valid Matplotlib color).

      bottom, top, left, right bool, 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, labelright bool, 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_color color, optional

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

      grid_alpha `python:float`, optional

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

      grid_linewidth `python:float`, optional

        Width of grid lines in points.

      grid_linestyle `python:str`, optional

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