Skip to main content
`Ctrl`+`K`

# BaseRepresentation

class astropy.coordinates.BaseRepresentation(*args, differentials=None, **kwargs)

  Bases: `BaseRepresentationOrDifferential`

  Base for representing a point in a 3D coordinate system.

  Parameters:
    comp1, comp2, comp3 `Quantity` or subclass

      The components of the 3D points. The names are the keys and the subclasses the values of the `attr_classes` attribute.

    differentials `python:dict`, `BaseDifferential`, optional

      Any differential classes that should be associated with this representation. The input must either be a single `BaseDifferential` subclass instance, or a dictionary with keys set to a string representation of the SI unit with which the differential (derivative) is taken. For example, for a velocity differential on a positional representation, the key would be `'s'` for seconds, indicating that the derivative is a time derivative.

    copy bool, optional

      If `True` (default), arrays will be copied. If `False`, arrays will be references, though possibly broadcast to ensure matching shapes.

  Notes

  All representation classes should subclass this base representation class, and define an `attr_classes` attribute, a `dict` which maps component names to the class that creates them. They must also define a `to_cartesian` method and a `from_cartesian` class method. By default, transformations are done via the cartesian system, but classes that want to define a smarter transformation path can overload the `represent_as` method. If one wants to use an associated differential class, one should also define `unit_vectors` and `scale_factors` methods (see those methods for details).

  Attributes Summary

  `differentials` | A dictionary of differential class instances.
  `info` |
  `name` | Name of the representation or differential.
  `shape` | The shape of the instance and underlying arrays.

  Methods Summary

  `cross`(other) | Vector cross product of two representations.
  `dot`(other) | Dot product of two representations.
  `from_representation`(representation) | Create a new instance of this representation from another one.
  `mean`(*args, **kwargs) | Vector mean.
  `norm`() | Vector norm.
  `represent_as`(other_class[, differential_class]) | Convert coordinates to another representation.
  `scale_factors`() | Scale factors for each component's direction.
  `sum`(*args, **kwargs) | Vector sum.
  `transform`(matrix) | Transform coordinates using a 3x3 matrix in a Cartesian basis.
  `unit_vectors`() | Cartesian unit vectors in the direction of each component.
  `with_differentials`(differentials) | Create a new representation with the same positions as this representation, but with these new differentials.
  `without_differentials`() | Return a copy of the representation without attached differentials.

  Attributes Documentation

  differentials

    A dictionary of differential class instances.

    The keys of this dictionary must be a string representation of the SI unit with which the differential (derivative) is taken. For example, for a velocity differential on a positional representation, the key would be `'s'` for seconds, indicating that the derivative is a time derivative.

  info
  name = 'base'

    Name of the representation or differential.

    When a subclass is defined, by default, the name is the lower-cased name of the class with with any trailing ‘representation’ or ‘differential’ removed. (E.g., ‘spherical’ for `SphericalRepresentation` or `SphericalDifferential`.)

    This can be customized when defining a subclass by setting the class attribute.

  shape

    The shape of the instance and underlying arrays.

    Like `shape`, can be set to a new shape by assigning a tuple. Note that if different instances share some but not all underlying data, setting the shape of one instance can make the other instance unusable. Hence, it is strongly recommended to get new, reshaped instances with the `reshape` method.

    Raises:
      `ValueError`

        If the new shape has the wrong total number of elements.

      `AttributeError`

        If the shape of any of the components cannot be changed without the arrays being copied. For these cases, use the `reshape` method (which copies any arrays that cannot be reshaped in-place).

  Methods Documentation

  cross(other)

    Vector cross product of two representations.

    The calculation is done by converting both `self` and `other` to `CartesianRepresentation`, and converting the result back to the type of representation of `self`.

    Parameters:
      other `BaseRepresentation` subclass instance

        The representation to take the cross product with.

    Returns:
      cross_product `BaseRepresentation` subclass instance

        With vectors perpendicular to both `self` and `other`, in the same type of representation as `self`.

  dot(other)

    Dot product of two representations.

    The calculation is done by converting both `self` and `other` to `CartesianRepresentation`.

    Note that any associated differentials will be dropped during this operation.

    Parameters:
      other `BaseRepresentation`

        The representation to take the dot product with.

    Returns:
      dot_product `Quantity`

        The sum of the product of the x, y, and z components of the cartesian representations of `self` and `other`.

  classmethod from_representation(representation)

    Create a new instance of this representation from another one.

    Parameters:
      representation `BaseRepresentation` instance

        The presentation that should be converted to this class.

  mean(*args, **kwargs)

    Vector mean.

    Averaging is done by converting the representation to cartesian, and taking the mean of the x, y, and z components. The result is converted back to the same representation as the input.

    Refer to `mean` for full documentation of the arguments, noting that `axis` is the entry in the `shape` of the representation, and that the `out` argument cannot be used.

    Returns:
      mean `BaseRepresentation` subclass instance

        Vector mean, in the same representation as that of the input.

  norm()

    Vector norm.

    The norm is the standard Frobenius norm, i.e., the square root of the sum of the squares of all components with non-angular units.

    Note that any associated differentials will be dropped during this operation.

    Returns:
      norm `astropy.units.Quantity`

        Vector norm, with the same shape as the representation.

  represent_as(other_class, differential_class=None)

    Convert coordinates to another representation.

    If the instance is of the requested class, it is returned unmodified. By default, conversion is done via Cartesian coordinates. Also note that orientation information at the origin is not preserved by conversions through Cartesian coordinates. See the docstring for `to_cartesian()` for an example.

    Parameters:
      other_class `BaseRepresentation` subclass

        The type of representation to turn the coordinates into.

      differential_class `python:dict` of `BaseDifferential`, optional

        Classes in which the differentials should be represented. Can be a single class if only a single differential is attached, otherwise it should be a `dict` keyed by the same keys as the differentials.

  scale_factors()

    Scale factors for each component’s direction.

    Given unit vectors \(\hat{e}_c\) and scale factors \(f_c\), a change in one component of \(\delta c\) corresponds to a change in representation of \(\delta c \times f_c \times \hat{e}_c\).

    Returns:
      scale_factors `python:dict` of `Quantity`

        The keys are the component names.

  sum(*args, **kwargs)

    Vector sum.

    Adding is done by converting the representation to cartesian, and summing the x, y, and z components. The result is converted back to the same representation as the input.

    Refer to `sum` for full documentation of the arguments, noting that `axis` is the entry in the `shape` of the representation, and that the `out` argument cannot be used.

    Returns:
      sum `BaseRepresentation` subclass instance

        Vector sum, in the same representation as that of the input.

  transform(matrix)

    Transform coordinates using a 3x3 matrix in a Cartesian basis.

    This returns a new representation and does not modify the original one. Any differentials attached to this representation will also be transformed.

    Parameters:
      matrix(3,3) numpy:array_like

        A 3x3 (or stack thereof) matrix, such as a rotation matrix.

  unit_vectors()

    Cartesian unit vectors in the direction of each component.

    Given unit vectors \(\hat{e}_c\) and scale factors \(f_c\), a change in one component of \(\delta c\) corresponds to a change in representation of \(\delta c \times f_c \times \hat{e}_c\).

    Returns:
      unit_vectors `python:dict` of `CartesianRepresentation`

        The keys are the component names.

  with_differentials(differentials)

    Create a new representation with the same positions as this representation, but with these new differentials.

    Differential keys that already exist in this object’s differential dict are overwritten.

    Parameters:
      differentials python:sequence of `BaseDifferential` subclass instance

        The differentials for the new representation to have.

    Returns:
      `BaseRepresentation` subclass instance

        A copy of this representation, but with the `differentials` as its differentials.

  without_differentials()

    Return a copy of the representation without attached differentials.

    Returns:
      `BaseRepresentation` subclass instance

        A shallow copy of this representation, without any differentials. If no differentials were present, no copy is made.