Skip to main content
`Ctrl`+`K`

# BaseCoordinateFrame

class astropy.coordinates.BaseCoordinateFrame(*args, copy=True, representation_type=None, differential_type=None, **kwargs)

  Bases: `MaskableShapedLikeNDArray`

  The base class for coordinate frames.

  This class is intended to be subclassed to create instances of specific systems. Subclasses can implement the following attributes:

  - `default_representation`

      A subclass of `BaseRepresentation` that will be treated as the default representation of this frame. This is the representation assumed by default when the frame is created.

  - `default_differential`

      A subclass of `BaseDifferential` that will be treated as the default differential class of this frame. This is the differential class assumed by default when the frame is created.

  - `Attribute` class attributes

      Frame attributes such as `FK4.equinox` or `FK4.obstime` are defined using a descriptor class. See the narrative documentation or built-in classes code for details.

  - `frame_specific_representation_info`

      A dictionary mapping the name or class of a representation to a list of `RepresentationMapping` objects that tell what names and default units should be used on this frame for the components of that representation.

  Unless overridden via `frame_specific_representation_info`, velocity name defaults are:

  > - `pm_{lon}_cos{lat}`, `pm_{lat}` for `SphericalCosLatDifferential` velocity components

  > - `pm_{lon}`, `pm_{lat}` for `SphericalDifferential` velocity components

  > - `radial_velocity` for any `d_distance` component

  > - `v_{x,y,z}` for `CartesianDifferential` velocity components

  where `{lon}` and `{lat}` are the frame names of the angular components.

  Parameters:
    data `BaseRepresentation` subclass instance

      A representation object or `None` to have no data (or use the coordinate component arguments, see below).

    *args, **kwargs

      Coordinate components, with names that depend on the subclass.

    representation_type `BaseRepresentation` subclass, `python:str`, optional

      A representation class or string name of a representation class. This sets the expected input representation class, thereby changing the expected keyword arguments for the data passed in. For example, passing `representation_type='cartesian'` will make the classes expect position data with cartesian names, i.e. `x, y, z` in most cases unless overridden via `frame_specific_representation_info`. To see this frame’s names, check out `<this frame>().representation_info`.

    differential_type `BaseDifferential` subclass, `python:str`, `python:dict`, optional

      A differential class or dictionary of differential classes (currently only a velocity differential with key ‘s’ is supported). This sets the expected input differential class, thereby changing the expected keyword arguments of the data passed in. For example, passing `differential_type='cartesian'` will make the classes expect velocity data with the argument names `v_x, v_y, v_z` unless overridden via `frame_specific_representation_info`. To see this frame’s names, check out `<this frame>().representation_info`.

    copy bool, optional

      If `True` (default), make copies of the input coordinate arrays. Can only be passed in as a keyword argument.

  Attributes Summary

  `cache` | Cache for this frame, a dict.
  `cartesian` | Shorthand for a cartesian representation of the coordinates in this object.
  `cylindrical` | Shorthand for a cylindrical representation of the coordinates in this object.
  `data` | The coordinate data for this object.
  `default_differential` |
  `default_representation` |
  `differential_type` | The differential used for this frame's data.
  `frame_attributes` |
  `frame_specific_representation_info` |
  `has_data` | True if this frame has `data`, False otherwise.
  `info` | Container for meta information like name, description, format.
  `mask` | The mask associated with these coordinates.
  `masked` | Whether the underlying data is masked.
  `proper_motion` | Shorthand for the two-dimensional proper motion as a `Quantity` object with angular velocity units.
  `radial_velocity` | Shorthand for the radial or line-of-sight velocity as a `Quantity` object.
  `representation_component_names` |
  `representation_component_units` |
  `representation_info` | A dictionary with the information of what attribute names for this frame apply to particular representations.
  `representation_type` | The representation class used for this frame's data.
  `shape` | The shape of the underlying data.
  `size` | The size of the object, as calculated from its shape.
  `spherical` | Shorthand for a spherical representation of the coordinates in this object.
  `sphericalcoslat` | Shorthand for a spherical representation of the positional data and a `SphericalCosLatDifferential` for the velocity data in this object.
  `velocity` | Shorthand for retrieving the Cartesian space-motion as a `CartesianDifferential` object.

  Methods Summary

  `get_frame_attr_defaults`() | Return a dict with the defaults for each frame attribute.
  `get_mask`(*attrs) | Get the mask associated with these coordinates.
  `get_representation_cls`([which]) | The class used for part of this frame's data.
  `get_representation_component_names`([which]) |
  `get_representation_component_units`([which]) |
  `insert`(obj, values[, axis]) | Make a copy with coordinate values inserted before the given indices.
  `is_equivalent_frame`(other) | Checks if this object is the same frame as the `other` object.
  `is_frame_attr_default`(attrnm) | Determine whether or not a frame attribute has its value because it's the default value, or because this frame was created with that value explicitly requested.
  `is_transformable_to`(new_frame) | Determines if this coordinate frame can be transformed to another given frame.
  `position_angle`(other) | Compute the on-sky position angle to another coordinate.
  `realize_frame`(data, **kwargs) | Generates a new frame with new data from another frame (which may or may not have data).
  `replicate`([copy]) | Return a replica of the frame, optionally with new frame attributes.
  `replicate_without_data`([copy]) | Return a replica without data, optionally with new frame attributes.
  `represent_as`(base[, s, in_frame_units]) | Generate and return a new representation of this frame's `data` as a Representation object.
  `separation`(other, *[, origin_mismatch]) | Computes on-sky separation between this coordinate and another.
  `separation_3d`(other) | Computes three dimensional separation between this coordinate and another.
  `set_representation_cls`([base, s]) | Set representation and/or differential class for this frame's data.
  `to_table`() | Convert this |BaseFrame| to a |QTable|.
  `transform_to`(new_frame) | Transform this object's coordinate data to a new frame.

  Attributes Documentation

  cache

    Cache for this frame, a dict.

    It stores anything that should be computed from the coordinate data (not from the frame attributes). This can be used in functions to store anything that might be expensive to compute but might be reused by some other function. E.g.:

        if 'user_data' in myframe.cache:
            data = myframe.cache['user_data']
        else:
            myframe.cache['user_data'] = data = expensive_func(myframe.lat)

    If in-place modifications are made to the frame data, the cache should be cleared:

        myframe.cache.clear()

  cartesian

    Shorthand for a cartesian representation of the coordinates in this object.

  cylindrical

    Shorthand for a cylindrical representation of the coordinates in this object.

  data

    The coordinate data for this object. If this frame has no data, a `ValueError` will be raised. Use `has_data` to check if data is present on this frame object.

  default_differential = None
  default_representation = None
  differential_type

    The differential used for this frame’s data.

    This will be a subclass from `BaseDifferential`. For simultaneous setting of representation and differentials, see the `set_representation_cls` method.

  frame_attributes = {}
  frame_specific_representation_info = {<class 'astropy.coordinates.representation.cartesian.CartesianDifferential'>: [('d_x', 'v_x', Unit("km / s")), ('d_y', 'v_y', Unit("km / s")), ('d_z', 'v_z', Unit("km / s"))], <class 'astropy.coordinates.representation.spherical.RadialDifferential'>: [('d_distance', 'radial_velocity', Unit("km / s"))], <class 'astropy.coordinates.representation.spherical.SphericalCosLatDifferential'>: [('d_lon_coslat', 'pm_lon_coslat', Unit("mas / yr")), ('d_lat', 'pm_lat', Unit("mas / yr")), ('d_distance', 'radial_velocity', Unit("km / s"))], <class 'astropy.coordinates.representation.spherical.SphericalDifferential'>: [('d_lon', 'pm_lon', Unit("mas / yr")), ('d_lat', 'pm_lat', Unit("mas / yr")), ('d_distance', 'radial_velocity', Unit("km / s"))], <class 'astropy.coordinates.representation.spherical.SphericalRepresentation'>: [('lon', 'lon', 'recommended'), ('lat', 'lat', 'recommended')], <class 'astropy.coordinates.representation.spherical.UnitSphericalCosLatDifferential'>: [('d_lon_coslat', 'pm_lon_coslat', Unit("mas / yr")), ('d_lat', 'pm_lat', Unit("mas / yr")), ('d_distance', 'radial_velocity', Unit("km / s"))], <class 'astropy.coordinates.representation.spherical.UnitSphericalDifferential'>: [('d_lon', 'pm_lon', Unit("mas / yr")), ('d_lat', 'pm_lat', Unit("mas / yr")), ('d_distance', 'radial_velocity', Unit("km / s"))], <class 'astropy.coordinates.representation.spherical.UnitSphericalRepresentation'>: [('lon', 'lon', 'recommended'), ('lat', 'lat', 'recommended')]}
  has_data

    True if this frame has `data`, False otherwise.

  info

    Container for meta information like name, description, format. This is required when the object is used as a mixin column within a table, but can be used as a general way to store meta information.

  mask

    The mask associated with these coordinates.

    Combines the masks of all components of the underlying representation, including possible differentials.

  masked

    Whether the underlying data is masked.

    Raises:
      `ValueError`

        If the frame has no associated data.

  proper_motion

    Shorthand for the two-dimensional proper motion as a `Quantity` object with angular velocity units. In the returned `Quantity`, `axis=0` is the longitude/latitude dimension so that `.proper_motion[0]` is the longitudinal proper motion and `.proper_motion[1]` is latitudinal. The longitudinal proper motion already includes the cos(latitude) term.

  radial_velocity

    Shorthand for the radial or line-of-sight velocity as a `Quantity` object.

  representation_component_names
  representation_component_units
  representation_info

    A dictionary with the information of what attribute names for this frame apply to particular representations.

  representation_type

    The representation class used for this frame’s data.

    This will be a subclass from `BaseRepresentation`. Can also be set using the string name of the representation. If you wish to set an explicit differential class (rather than have it be inferred), use the `set_representation_cls` method.

  shape
  size
  spherical

    Shorthand for a spherical representation of the coordinates in this object.

  sphericalcoslat

    Shorthand for a spherical representation of the positional data and a `SphericalCosLatDifferential` for the velocity data in this object.

  velocity

    Shorthand for retrieving the Cartesian space-motion as a `CartesianDifferential` object.

    This is equivalent to calling `self.cartesian.differentials['s']`.

  Methods Documentation

  classmethod get_frame_attr_defaults()

    Return a dict with the defaults for each frame attribute.

  get_mask(*attrs)

    Get the mask associated with these coordinates.

    Parameters:
      *attrs `python:str`

        Attributes from which to get the masks to combine. Items can be dotted, like `"data.lon", "data.lat"`. By default, get the combined mask of all components (including from differentials), ignoring possible masks of attributes.

    Returns:
      mask `ndarray` of bool

        The combined, read-only mask. If the instance is not masked, it is an array of `False` with the correct shape.

    Raises:
      `ValueError`

        If the coordinate frame has no associated data.

  get_representation_cls(which='base')

    The class used for part of this frame’s data.

    Parameters:
      which(‘base’, ‘s’, `None`)

        The class of which part to return. ‘base’ means the class used to represent the coordinates; ‘s’ the first derivative to time, i.e., the class representing the proper motion and/or radial velocity. If `None`, return a dict with both.

    Returns:
      representation `BaseRepresentation` or `BaseDifferential`.
  get_representation_component_names(which='base')
  get_representation_component_units(which='base')
  insert(obj, values, axis=0)

    Make a copy with coordinate values inserted before the given indices.

    The values to be inserted must conform to the rules for in-place setting of the object.

    The API signature matches the `np.insert` API, but is more limited. The specification of insert index `obj` must be a single integer, and the `axis` must be `0` for simple insertion before the index.

    Parameters:
      obj `python:int`

        Integer index before which `values` is inserted.

      values numpy:array_like

        Value(s) to insert. If the type of `values` is different from that of quantity, `values` is converted to the matching type.

      axis `python:int`, optional

        Axis along which to insert `values`. Default is 0, which is the only allowed value and will insert a row.

    Returns:
      coord|SkyCoord|, |BaseFrame|

        Copy of instance with new values inserted.

  is_equivalent_frame(other)

    Checks if this object is the same frame as the `other` object.

    To be the same frame, two objects must be the same frame class and have the same frame attributes. Note that it does not matter what, if any, data either object has.

    Parameters:
      other `BaseCoordinateFrame`

        the other frame to check

    Returns:
      isequiv bool

        True if the frames are the same, False if not.

    Raises:
      `TypeError`

        If `other` isn’t a `BaseCoordinateFrame` or subclass.

  is_frame_attr_default(attrnm)

    Determine whether or not a frame attribute has its value because it’s the default value, or because this frame was created with that value explicitly requested.

    Parameters:
      attrnm `python:str`

        The name of the attribute to check.

    Returns:
      isdefault bool

        True if the attribute `attrnm` has its value by default, False if it was specified at creation of this frame.

  is_transformable_to(new_frame)

    Determines if this coordinate frame can be transformed to another given frame.

    Parameters:
      new_frame `BaseCoordinateFrame` subclass or instance

        The proposed frame to transform into.

    Returns:
      transformable bool or `python:str`

        `True` if this can be transformed to `new_frame`, `False` if not, or the string ‘same’ if `new_frame` is the same system as this object but no transformation is defined.

    Notes

    A return value of ‘same’ means the transformation will work, but it will just give back a copy of this object. The intended usage is:

        if coord.is_transformable_to(some_unknown_frame):
            coord2 = coord.transform_to(some_unknown_frame)

    This will work even if `some_unknown_frame` turns out to be the same frame class as `coord`. This is intended for cases where the frame is the same regardless of the frame attributes (e.g. ICRS), but be aware that it might also indicate that someone forgot to define the transformation between two objects of the same frame class but with different attributes.

  position_angle(other)

    Compute the on-sky position angle to another coordinate.

    Parameters:
      other `BaseCoordinateFrame` or `SkyCoord`

        The other coordinate to compute the position angle to. It is treated as the “head” of the vector of the position angle.

    Returns:
      `Angle`

        The (positive) position angle of the vector pointing from `self` to `other`, measured East from North. If either `self` or `other` contain arrays, this will be an array following the appropriate `numpy` broadcasting rules.

    Examples

        >>> from astropy import units as u
        >>> from astropy.coordinates import ICRS, SkyCoord
        >>> c1 = SkyCoord(0*u.deg, 0*u.deg)
        >>> c2 = ICRS(1*u.deg, 0*u.deg)
        >>> c1.position_angle(c2).to(u.deg)
        <Angle 90. deg>
        >>> c2.position_angle(c1).to(u.deg)
        <Angle 270. deg>
        >>> c3 = SkyCoord(1*u.deg, 1*u.deg)
        >>> c1.position_angle(c3).to(u.deg)
        <Angle 44.995636455344844 deg>

  realize_frame(data, **kwargs)

    Generates a new frame with new data from another frame (which may or may not have data). Roughly speaking, the converse of `replicate_without_data`.

    Parameters:
      data `BaseRepresentation`

        The representation to use as the data for the new frame.

      **kwargs

        Any additional keywords are treated as frame attributes to be set on the new frame object. In particular, `representation_type` can be specified.

    Returns:
      frameobj `BaseCoordinateFrame` subclass instance

        A new object in this frame, with the same frame attributes as this one, but with the `data` as the coordinate data.

  replicate(copy=False, **kwargs)

    Return a replica of the frame, optionally with new frame attributes.

    The replica is a new frame object that has the same data as this frame object and with frame attributes overridden if they are provided as extra keyword arguments to this method. If `copy` is set to `True` then a copy of the internal arrays will be made. Otherwise the replica will use a reference to the original arrays when possible to save memory. The internal arrays are normally not changeable by the user so in most cases it should not be necessary to set `copy` to `True`.

    Parameters:
      copy bool, optional

        If True, the resulting object is a copy of the data. When False, references are used where possible. This rule also applies to the frame attributes.

      **kwargs

        Any additional keywords are treated as frame attributes to be set on the new frame object.

    Returns:
      frameobj `BaseCoordinateFrame` subclass instance

        Replica of this object, but possibly with new frame attributes.

  replicate_without_data(copy=False, **kwargs)

    Return a replica without data, optionally with new frame attributes.

    The replica is a new frame object without data but with the same frame attributes as this object, except where overridden by extra keyword arguments to this method. The `copy` keyword determines if the frame attributes are truly copied vs being references (which saves memory for cases where frame attributes are large).

    This method is essentially the converse of `realize_frame`.

    Parameters:
      copy bool, optional

        If True, the resulting object has copies of the frame attributes. When False, references are used where possible.

      **kwargs

        Any additional keywords are treated as frame attributes to be set on the new frame object.

    Returns:
      frameobj `BaseCoordinateFrame` subclass instance

        Replica of this object, but without data and possibly with new frame attributes.

  represent_as(base, s='base', in_frame_units=False)

    Generate and return a new representation of this frame’s `data` as a Representation object.

    Note: In order to make an in-place change of the representation of a Frame or SkyCoord object, set the `representation` attribute of that object to the desired new representation, or use the `set_representation_cls` method to also set the differential.

    Parameters:
      base subclass of `BaseRepresentation` or `python:str`

        The type of representation to generate. Must be a class (not an instance), or the string name of the representation class.

      s subclass of `BaseDifferential`, `python:str`, optional

        Class in which any velocities should be represented. Must be a class (not an instance), or the string name of the differential class. If equal to ‘base’ (default), inferred from the base class. If `None`, all velocity information is dropped.

      in_frame_units bool, keyword-only

        Force the representation units to match the specified units particular to this frame

    Returns:
      newrep BaseRepresentation-derived `object`

        A new representation object of this frame’s `data`.

    Raises:
      `AttributeError`

        If this object had no `data`

    Examples

        >>> from astropy import units as u
        >>> from astropy.coordinates import SkyCoord, CartesianRepresentation
        >>> coord = SkyCoord(0*u.deg, 0*u.deg)
        >>> coord.represent_as(CartesianRepresentation)
        <CartesianRepresentation (x, y, z) [dimensionless]
                (1., 0., 0.)>

        >>> coord.representation_type = CartesianRepresentation
        >>> coord
        <SkyCoord (ICRS): (x, y, z) [dimensionless]
            (1., 0., 0.)>

  separation(other, *, origin_mismatch='warn')

    Computes on-sky separation between this coordinate and another.

    For more on how to use this (and related) functionality, see the examples in Separations, Offsets, Catalog Matching, and Related Functionality.

    Parameters:
      other `BaseCoordinateFrame` or `SkyCoord`

        The coordinate to get the separation to.

      origin_mismatch{“warn”, “ignore”, “error”}, keyword-only

        If the `other` coordinates are in a different frame then they will have to be transformed, and if the transformation is not a pure rotation then `self.separation(other)` can be different from `other.separation(self)`. With `origin_mismatch="warn"` (default) the transformation is always performed, but a warning is emitted if it is not a pure rotation. If `origin_mismatch="ignore"` then the required transformation is always performed without warnings. If `origin_mismatch="error"` then only transformations that are pure rotations are allowed.

    Returns:
      sep `Angle`

        The on-sky separation between this and the `other` coordinate.

    Notes

    The separation is calculated using the Vincenty formula, which is stable at all locations, including poles and antipodes [1].

    [1]

    https://en.wikipedia.org/wiki/Great-circle_distance

  separation_3d(other)

    Computes three dimensional separation between this coordinate and another.

    For more on how to use this (and related) functionality, see the examples in Separations, Offsets, Catalog Matching, and Related Functionality.

    Parameters:
      other `BaseCoordinateFrame` or `SkyCoord`

        The coordinate system to get the distance to.

    Returns:
      sep `Distance`

        The real-space distance between these two coordinates.

    Raises:
      `ValueError`

        If this or the other coordinate do not have distances.

  set_representation_cls(base=None, s='base')

    Set representation and/or differential class for this frame’s data.

    Parameters:
      base `python:str`, `BaseRepresentation` subclass, optional

        The name or subclass to use to represent the coordinate data.

      s `BaseDifferential` subclass, optional

        The differential subclass to use to represent any velocities, such as proper motion and radial velocity. If equal to ‘base’, which is the default, it will be inferred from the representation. If `None`, the representation will drop any differentials.

  to_table()

    Convert this |BaseFrame| to a |QTable|.

    Any attributes that have the same length as the |BaseFrame| will be converted to columns of the |QTable|. All other attributes will be recorded as metadata.

    Returns:
      `QTable`

        A |QTable| containing the data of this |BaseFrame|.

    Examples

        >>> from astropy.coordinates import ICRS
        >>> coord = ICRS(ra=[40, 70]*u.deg, dec=[0, -20]*u.deg)
        >>> t =  coord.to_table()
        >>> t
        <QTable length=2>
           ra     dec
          deg     deg
        float64 float64
        ------- -------
           40.0     0.0
           70.0   -20.0
        >>> t.meta
        {'representation_type': 'spherical'}

  transform_to(new_frame)

    Transform this object’s coordinate data to a new frame.

    Parameters:
      new_frame astropy:coordinate-like

        The frame to transform this coordinate frame into.

    Returns:
      transframe astropy:coordinate-like

        A new object with the coordinate data represented in the `newframe` system.

    Raises:
      `ValueError`

        If there is no possible transformation route.