Skip to main content
`Ctrl`+`K`

# CoordinateHelper

class astropy.visualization.wcsaxes.CoordinateHelper(parent_axes=None, parent_map=None, transform=None, coord_index=None, coord_type='scalar', coord_unit=None, coord_wrap=None, frame=None, format_unit=None, default_label=None)

  Bases: `object`

  Helper class to control one of the coordinates in the `WCSAxes`.

  Parameters:
    parent_axes `WCSAxes`

      The axes the coordinate helper belongs to.

    parent_map `CoordinatesMap`

      The `CoordinatesMap` object this coordinate belongs to.

    transform `Transform`

      The transform corresponding to this coordinate system.

    coord_index `python:int`

      The index of this coordinate in the `CoordinatesMap`.

    coord_type{‘longitude’, ‘latitude’, ‘scalar’}

      The type of this coordinate, which is used to determine the wrapping and boundary behavior of coordinates. Longitudes wrap at `coord_wrap`, latitudes have to be in the range -90 to 90, and scalars are unbounded and do not wrap.

    coord_unit `Unit`

      The unit that this coordinate is in given the output of transform.

    format_unit `Unit`, optional

      The unit to use to display the coordinates.

    coord_wrap `astropy.units.Quantity`

      The angle at which the longitude wraps (defaults to 360 degrees).

    frame `BaseFrame`

      The frame of the `WCSAxes`.

    default_label `python:str`, optional

      The axis label to show by default if none is set later.

  Attributes Summary

  `axislabels` |
  `coord_index` | The index of this coordinate in the `CoordinatesMap`.
  `coord_type` | The type of this coordinate (e.g., `'longitude'`)
  `coord_unit` | The unit that this coordinate is in given the output of transform.
  `coord_wrap` | The angle at which the longitude wraps (defaults to 360 degrees).
  `default_label` | The axis label to show by default if none is set later.
  `formatter` |
  `frame` | The frame of the `WCSAxes`.
  `locator` |
  `parent_axes` | The axes the coordinate helper belongs to.
  `parent_map` | The `CoordinatesMap` object this coordinate belongs to.
  `ticklabels` |
  `ticks` |
  `transform` | The transform corresponding to this coordinate system.

  Methods Summary

  `add_tickable_gridline`(name, constant) | Define a gridline that can be used for ticks and labels.
  `display_minor_ticks`(display_minor_ticks) | Display minor ticks for this coordinate.
  `format_coord`(value[, format]) | Given the value of a coordinate, will format it according to the format of the formatter_locator.
  `get_auto_axislabel`() | Render default axis labels if no explicit label is provided.
  `get_axislabel`() | Get the text for the axis label.
  `get_axislabel_position`() | Get where axis labels will appear.
  `get_axislabel_visibility_rule`(rule) | Get the rule used to determine when the axis label is drawn.
  `get_axislabel_visible`() | Get whether the axis label is currently visible.
  `get_format_unit`() | Get the unit for the major tick labels.
  `get_minor_frequency`() |
  `get_ticklabel_position`() | Get where tick labels will appear.
  `get_ticklabel_visible`() | Get whether the tick labels are currently visible.
  `get_ticks_position`() | Get where tick labels will appear.
  `get_ticks_visible`() | Get whether the ticks are currently visible.
  `grid`([draw_grid, grid_type]) | Plot grid lines for this coordinate.
  `set_auto_axislabel`(auto_label) | Render default axis labels if no explicit label is provided.
  `set_axislabel`(text[, minpad]) | Set the text and optionally visual properties for the axis label.
  `set_axislabel_position`(position) | Set where axis labels should appear.
  `set_axislabel_visibility_rule`(rule) | Set the rule used to determine when the axis label is drawn.
  `set_coord_type`(coord_type[, coord_wrap]) | Set the coordinate type for the axis.
  `set_format_unit`(unit[, decimal, ...]) | Set the unit for the major tick labels.
  `set_major_formatter`(formatter[, ...]) | Set the format string to use for the major tick labels.
  `set_minor_frequency`(frequency) | Set the frequency of minor ticks per major ticks.
  `set_position`(position) | Set the position for ticks, tick labels, and axis labels.
  `set_separator`(separator) | Set the separator to use for the angle major tick labels.
  `set_ticklabel`([color, size, pad, ...]) | Set the visual properties for the tick labels.
  `set_ticklabel_position`(position) | Set where tick labels should appear.
  `set_ticklabel_visible`(visible) | Set whether the tick labels are visible or not.
  `set_ticks`([values, spacing, number, size, ...]) | Set the location and properties of the ticks.
  `set_ticks_position`(position) | Set where ticks should appear.
  `set_ticks_visible`(visible) | Set whether ticks are visible or not.
  `set_visible`(visible) | Set the visibility for ticks, tick labels, and axis labels.
  `tick_params`([which]) | Method to set the tick and tick label parameters in the same way as the `tick_params()` method in Matplotlib.

  Attributes Documentation

  axislabels
  coord_index

    The index of this coordinate in the `CoordinatesMap`.

  coord_type

    The type of this coordinate (e.g., `'longitude'`)

  coord_unit

    The unit that this coordinate is in given the output of transform.

  coord_wrap

    The angle at which the longitude wraps (defaults to 360 degrees).

  default_label

    The axis label to show by default if none is set later.

  formatter
  frame

    The frame of the `WCSAxes`.

  locator
  parent_axes

    The axes the coordinate helper belongs to.

  parent_map

    The `CoordinatesMap` object this coordinate belongs to.

  ticklabels
  ticks
  transform

    The transform corresponding to this coordinate system.

  Methods Documentation

  add_tickable_gridline(name, constant)

    Define a gridline that can be used for ticks and labels.

    This gridline is not itself drawn, but instead can be specified in calls to methods such as `set_ticklabel_position()` for drawing ticks and labels. Since the gridline has a constant value in this coordinate, and thus would not have any ticks or labels for the same coordinate, the call to `set_ticklabel_position()` would typically be made on the complementary coordinate.

    Parameters:
      name `python:str`

        The name for the gridline, usually a single character, but can be longer

      constant `Quantity`

        The constant coordinate value of the gridline

    Notes

    A limitation is that the tickable part of the gridline must be contiguous. If the gridline consists of more than one disconnected segment within the plot extent, only one of those segments will be made tickable.

  display_minor_ticks(display_minor_ticks)

    Display minor ticks for this coordinate.

    Parameters:
      display_minor_ticks bool

        Whether or not to display minor ticks.

  format_coord(value, format='auto')

    Given the value of a coordinate, will format it according to the format of the formatter_locator.

    Parameters:
      value `python:float`

        The value to format

      format{‘auto’, ‘ascii’, ‘latex’}, optional

        The format to use - by default the formatting will be adjusted depending on whether Matplotlib is using LaTeX or MathTex. To get plain ASCII strings, use format=’ascii’.

  get_auto_axislabel()

    Render default axis labels if no explicit label is provided.

    Returns:
      auto_axislabel `bool`

        `True` if default labels will be rendered.

  get_axislabel()

    Get the text for the axis label.

    Returns:
      label `python:str`

        The axis label

  get_axislabel_position()

    Get where axis labels will appear.

  get_axislabel_visibility_rule(rule)

    Get the rule used to determine when the axis label is drawn.

  get_axislabel_visible()

    Get whether the axis label is currently visible.

  get_format_unit()

    Get the unit for the major tick labels.

  get_minor_frequency()
  get_ticklabel_position()

    Get where tick labels will appear.

  get_ticklabel_visible()

    Get whether the tick labels are currently visible.

  get_ticks_position()

    Get where tick labels will appear.

  get_ticks_visible()

    Get whether the ticks are currently visible.

  grid(draw_grid=True, grid_type=None, **kwargs)

    Plot grid lines for this coordinate.

    Standard matplotlib appearance options (color, alpha, etc.) can be passed as keyword arguments.

    Parameters:
      draw_grid bool

        Whether to show the gridlines

      grid_type{‘lines’, ‘contours’}

        Whether to plot the contours by determining the grid lines in world coordinates and then plotting them in world coordinates (`'lines'`) or by determining the world coordinates at many positions in the image and then drawing contours (`'contours'`). The first is recommended for 2-d images, while for 3-d (or higher dimensional) cubes, the `'contours'` option is recommended. By default, ‘lines’ is used if the transform has an inverse, otherwise ‘contours’ is used.

  set_auto_axislabel(auto_label)

    Render default axis labels if no explicit label is provided.

    Parameters:
      auto_label `bool`

        `True` if default labels will be rendered.

  set_axislabel(text, minpad=1, **kwargs)

    Set the text and optionally visual properties for the axis label.

    Parameters:
      text `python:str`

        The axis label text.

      minpad `python:float`, optional

        The padding for the label in terms of axis label font size.

      **kwargs

        Keywords are passed to `matplotlib.text.Text`. These can include keywords to set the `color`, `size`, `weight`, and other text properties.

  set_axislabel_position(position)

    Set where axis labels should appear.

    Parameters:
      position `python:str` or `python:list`

        The axes on which the axis label for this coordinate should appear. Should be a sequence containing zero or more of `'b'`, `'t'`, `'l'`, `'r'`. For example, `'lb'` will lead the axis label to be shown on the left and bottom axis. In addition, if `'#'` is included in the sequence, the position will be considered dynamic and will be updated at draw-time in order to show the axis label on the same axes as the tick labels are shown.

  set_axislabel_visibility_rule(rule)

    Set the rule used to determine when the axis label is drawn.

    Parameters:
      rule `python:str`

        If the rule is ‘always’ axis labels will always be drawn on the axis. If the rule is ‘ticks’ the label will only be drawn if ticks were drawn on that axis. If the rule is ‘labels’ the axis label will only be drawn if tick labels were drawn on that axis.

  set_coord_type(coord_type, coord_wrap=None)

    Set the coordinate type for the axis.

    Parameters:
      coord_type `python:str`

        One of ‘longitude’, ‘latitude’ or ‘scalar’

      coord_wrap `Quantity`, optional

        The value to wrap at for angular coordinates.

  set_format_unit(unit, decimal=None, show_decimal_unit=True)

    Set the unit for the major tick labels.

    Parameters:
      unit class:`Unit`

        The unit to which the tick labels should be converted to.

      decimal bool, optional

        Whether to use decimal formatting. By default this is `False` for degrees or hours (which therefore use sexagesimal formatting) and `True` for all other units.

      show_decimal_unit bool, optional

        Whether to include units when in decimal mode.

  set_major_formatter(formatter, show_decimal_unit=True)

    Set the format string to use for the major tick labels.

    See Tick label format for accepted format strings and examples.

    Parameters:
      formatter `python:str` or `python:callable()`

        The format string to use, or a callable (for advanced use cases). If specified as a callable, this should take a `Quantity` (which could be scalar or array) of tick world coordinates as well as an optional `spacing` keyword argument, which gives (also as a `Quantity`) the spacing between ticks, and returns an iterable of strings containing the labels.

      show_decimal_unit `python:str`

        Whether to show the unit or not when using decimal formatting (e.g., `d.dd` or `x.xxx`).

  set_minor_frequency(frequency)

    Set the frequency of minor ticks per major ticks.

    Parameters:
      frequency `python:int`

        The number of minor ticks per major ticks.

  set_position(position)

    Set the position for ticks, tick labels, and axis labels.

    Parameters:
      position `python:str`

        Show all elements at the given position string (e.g. ‘t’, ‘lb’, ‘#’).

  set_separator(separator)

    Set the separator to use for the angle major tick labels.

    Parameters:
      separator `python:str` or `python:tuple` or `python:None`

        The separator between numbers in sexagesimal representation. Can be either a string or a tuple (or `None` for default).

  set_ticklabel(color=None, size=None, pad=None, exclude_overlapping=None, *, simplify=True, **kwargs)

    Set the visual properties for the tick labels.

    Parameters:
      size `python:float`, optional

        The size of the ticks labels in points

      color `python:str` or `python:tuple`, optional

        A valid Matplotlib color for the tick labels

      pad `python:float`, optional

        Distance in points between tick and label.

      exclude_overlapping bool, optional

        Whether to exclude tick labels that overlap over each other.

      simplify bool, optional

        Whether to remove repeated parts of tick labels.

      **kwargs

        Other keyword arguments are passed to `matplotlib.text.Text`.

  set_ticklabel_position(position)

    Set where tick labels should appear.

    Parameters:
      position `python:str` or `python:list`

        The axes on which the tick labels for this coordinate should appear. Should be a sequence containing zero or more of `'b'`, `'t'`, `'l'`, `'r'`. For example, `'lb'` will lead the tick labels to be shown on the left and bottom axis. In addition, if `'#'` is included in the sequence, the position will be considered dynamic and will be updated at draw-time in order to attempt to optimize the layout of all the coordinates.

  set_ticklabel_visible(visible)

    Set whether the tick labels are visible or not.

    Parameters:
      visible bool

        The visibility of ticks. Setting as `False` will hide this coordinate’s tick labels.

  set_ticks(values=None, spacing=None, number=None, size=None, width=None, color=None, alpha=None, direction=None, exclude_overlapping=None)

    Set the location and properties of the ticks.

    At most one of the options from `values`, `spacing`, or `number` can be specified.

    Parameters:
      values python:iterable, optional

        The coordinate values at which to show the ticks.

      spacing `python:float`, optional

        The spacing between ticks.

      number `python:float`, optional

        The approximate number of ticks shown.

      size `python:float`, optional

        The length of the ticks in points

      color `python:str` or `python:tuple`, optional

        A valid Matplotlib color for the ticks

      alpha `python:float`, optional

        The alpha value (transparency) for the ticks.

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

        Whether the ticks should point inwards or outwards.

  set_ticks_position(position)

    Set where ticks should appear.

    Parameters:
      position `python:str` or `python:list`

        The axes on which the ticks for this coordinate should appear. Should be a sequence containing zero or more of `'b'`, `'t'`, `'l'`, `'r'`. For example, `'lb'` will lead the ticks to be shown on the left and bottom axis. In addition, if `'#'` is included in the sequence, the position will be considered dynamic and will be updated at draw-time in order to show the ticks on the same axes as the tick labels are shown.

  set_ticks_visible(visible)

    Set whether ticks are visible or not.

    Parameters:
      visible bool

        The visibility of ticks. Setting as `False` will hide ticks along this coordinate.

  set_visible(visible)

    Set the visibility for ticks, tick labels, and axis labels.

    Parameters:
      visible bool

        If ‘True’, show all elements. If ‘False’, hide all elements.

  tick_params(which='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:
      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 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 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).