Using and Designing Coordinate Representations

Points in a 3-d vector space can be represented in different ways, such as cartesian, spherical polar, cylindrical, and so on. These underlie the way coordinate data in astropy.coordinates is represented, as described in the Overview of astropy.coordinates concepts. Below, we describe how one can use them on their own, as a way to convert between different representations, including ones not built-in, and to do simple vector arithmetic.

The built-in representation classes are:

  • CartesianRepresentation: cartesian coordinates x, y, and z
  • SphericalRepresentation: spherical polar coordinates represented by a longitude (lon), a latitude (lat), and a distance (distance). The latitude is a value ranging from -90 to 90 degrees.
  • UnitSphericalRepresentation: spherical polar coordinates on a unit sphere, represented by a longitude (lon) and latitude (lat)
  • PhysicsSphericalRepresentation: spherical polar coordinates, represented by an inclination (theta) and azimuthal angle (phi), and radius r. The inclination goes from 0 to 180 degrees, and is related to the latitude in the SphericalRepresentation by theta = 90 deg - lat.
  • CylindricalRepresentation: cylindrical polar coordinates, represented by a cylindrical radius (rho), azimuthal angle (phi), and height (z).

Note

For information about using and changing the representation of SkyCoord objects, see the Representations section.

Instantiating and converting

Representation classes are instantiated with Quantity objects:

>>> from astropy import units as u
>>> from astropy.coordinates.representation import CartesianRepresentation
>>> car = CartesianRepresentation(3 * u.kpc, 5 * u.kpc, 4 * u.kpc)
>>> car
<CartesianRepresentation (x, y, z) in kpc
    ( 3.,  5.,  4.)>

Array Quantity objects can also be passed to representations. They will have the expected shape, which can be changed using methods with the same names as those for ndarray, such as reshape, ravel, etc.:

>>> x = u.Quantity([[1., 0., 0.], [3., 5., 3.]], u.m)
>>> y = u.Quantity([[0., 2., 0.], [4., 0., -4.]], u.m)
>>> z = u.Quantity([[0., 0., 3.], [0., 12., -12.]], u.m)
>>> car_array = CartesianRepresentation(x, y, z)
>>> car_array
<CartesianRepresentation (x, y, z) in m
    [[( 1.,  0.,   0.), ( 0.,  2.,   0.), ( 0.,  0.,   3.)],
     [( 3.,  4.,   0.), ( 5.,  0.,  12.), ( 3., -4., -12.)]]>
>>> car_array.shape
(2, 3)
>>> car_array.ravel()
<CartesianRepresentation (x, y, z) in m
    [( 1.,  0.,   0.), ( 0.,  2.,   0.), ( 0.,  0.,   3.), ( 3.,  4.,   0.),
     ( 5.,  0.,  12.), ( 3., -4., -12.)]>

Representations can be converted to other representations using the represent_as method:

>>> from astropy.coordinates.representation import SphericalRepresentation, CylindricalRepresentation
>>> sph = car.represent_as(SphericalRepresentation)
>>> sph  
<SphericalRepresentation (lon, lat, distance) in (rad, rad, kpc)
    ( 1.03037683,  0.60126422,  7.07106781)>
>>> cyl = car.represent_as(CylindricalRepresentation)
>>> cyl  
<CylindricalRepresentation (rho, phi, z) in (kpc, rad, kpc)
    ( 5.83095189,  1.03037684, 4.)>

All representations can be converted to each other without loss of information, with the exception of UnitSphericalRepresentation. This class is used to store the longitude and latitude of points but does not contain any distance to the points, and assumes that they are located on a unit and dimensionless sphere:

>>> from astropy.coordinates.representation import UnitSphericalRepresentation
>>> sph_unit = car.represent_as(UnitSphericalRepresentation)
>>> sph_unit  
<UnitSphericalRepresentation (lon, lat) in rad
    ( 1.03037683,  0.60126422)>

Converting back to cartesian, the absolute scaling information has been removed, and the points are still located on a unit sphere:

>>> sph_unit = car.represent_as(UnitSphericalRepresentation)
>>> sph_unit.represent_as(CartesianRepresentation) 
<CartesianRepresentation (x, y, z) [dimensionless]
    ( 0.42426407,  0.70710678,  0.56568542)>

Array values and numpy array method analogs

Array Quantity objects can also be passed to representations, and such representations can be sliced, reshaped, etc., using the same methods as are available to ndarray:

>>> import numpy as np
>>> x = np.linspace(0., 5., 6)
>>> y = np.linspace(10., 15., 6)
>>> z = np.linspace(20., 25., 6)
>>> car_array = CartesianRepresentation(x * u.m, y * u.m, z * u.m)
>>> car_array
<CartesianRepresentation (x, y, z) in m
    [( 0.,  10.,  20.), ( 1.,  11.,  21.), ( 2.,  12.,  22.),
     ( 3.,  13.,  23.), ( 4.,  14.,  24.), ( 5.,  15.,  25.)]>
>>> car_array[2]
<CartesianRepresentation (x, y, z) in m
    ( 2.,  12.,  22.)>
>>> car_array.reshape(3, 2)
<CartesianRepresentation (x, y, z) in m
    [[( 0.,  10.,  20.), ( 1.,  11.,  21.)],
     [( 2.,  12.,  22.), ( 3.,  13.,  23.)],
     [( 4.,  14.,  24.), ( 5.,  15.,  25.)]]>

Vector arithmetic

Representations support basic vector arithmetic, in particular taking the norm, multiplying with and dividing by quantities, taking dot and cross products, as well as adding, subtracting, summing and taking averages of representations, and multiplying with matrices.

Note

All arithmetic except the matrix multiplication works with non-cartesian representations as well. For taking the norm, multiplication, and division this uses just the non-angular components, while for the other operations the representation is converted to cartesian internally before the operation is done, and the result is converted back to the original representation. Hence, for optimal speed it may be best to work using cartesian representations.

To see how the operations work, consider the following examples:

>>> car_array = CartesianRepresentation([[1., 0., 0.], [3., 5.,  3.]] * u.m,
...                                     [[0., 2., 0.], [4., 0., -4.]] * u.m,
...                                     [[0., 0., 3.], [0.,12.,-12.]] * u.m)
>>> car_array
<CartesianRepresentation (x, y, z) in m
    [[( 1.,  0.,   0.), ( 0.,  2.,   0.), ( 0.,  0.,   3.)],
     [( 3.,  4.,   0.), ( 5.,  0.,  12.), ( 3., -4., -12.)]]>
>>> car_array.norm()  
<Quantity [[  1.,  2.,  3.],
           [  5., 13., 13.]] m>
>>> car_array / car_array.norm()  
<CartesianRepresentation (x, y, z) [dimensionless]
    [[( 1.        ,  0.        ,  0.        ),
      ( 0.        ,  1.        ,  0.        ),
      ( 0.        ,  0.        ,  1.        )],
     [( 0.6       ,  0.8       ,  0.        ),
      ( 0.38461538,  0.        ,  0.92307692),
      ( 0.23076923, -0.30769231, -0.92307692)]]>
>>> (car_array[1] - car_array[0]) / (10. * u.s)  
<CartesianRepresentation (x, y, z) in m / s
    [( 0.2,  0.4,  0. ), ( 0.5, -0.2,  1.2), ( 0.3, -0.4, -1.5)]>
>>> car_array.sum()  
<CartesianRepresentation (x, y, z) in m
    ( 12.,  2.,  3.)>
>>> car_array.mean(axis=0)  
<CartesianRepresentation (x, y, z) in m
    [( 2. ,  2.,  0. ), ( 2.5,  1.,  6. ), ( 1.5, -2., -4.5)]>

>>> unit_x = UnitSphericalRepresentation(0.*u.deg, 0.*u.deg)
>>> unit_y = UnitSphericalRepresentation(90.*u.deg, 0.*u.deg)
>>> unit_z = UnitSphericalRepresentation(0.*u.deg, 90.*u.deg)
>>> car_array.dot(unit_x)  
<Quantity [[ 1., 0., 0.],
           [ 3., 5., 3.]] m>
>>> car_array.dot(unit_y)  
<Quantity [[  6.12323400e-17,  2.00000000e+00,  0.00000000e+00],
           [  4.00000000e+00,  3.06161700e-16, -4.00000000e+00]] m>
>>> car_array.dot(unit_z)  
<Quantity [[  6.12323400e-17,  0.00000000e+00,  3.00000000e+00],
           [  1.83697020e-16,  1.20000000e+01, -1.20000000e+01]] m>
>>> car_array.cross(unit_x)  
<CartesianRepresentation (x, y, z) in m
    [[( 0.,  0.,  0.), ( 0.,   0., -2.), ( 0.,   3.,  0.)],
     [( 0.,  0., -4.), ( 0.,  12.,  0.), ( 0., -12.,  4.)]]>

>>> from astropy.coordinates.matrix_utilities import rotation_matrix
>>> rotation = rotation_matrix(90 * u.deg, axis='z')
>>> rotation  
array([[  6.12323400e-17,   1.00000000e+00,   0.00000000e+00],
       [ -1.00000000e+00,   6.12323400e-17,   0.00000000e+00],
       [  0.00000000e+00,   0.00000000e+00,   1.00000000e+00]])
>>> car_array.transform(rotation)  
<CartesianRepresentation (x, y, z) in m
    [[(  6.12323400e-17,  -1.00000000e+00,   0.),
      (  2.00000000e+00,   1.22464680e-16,   0.),
      (  0.00000000e+00,   0.00000000e+00,   3.)],
     [(  4.00000000e+00,  -3.00000000e+00,   0.),
      (  3.06161700e-16,  -5.00000000e+00,  12.),
      ( -4.00000000e+00,  -3.00000000e+00, -12.)]]>

Creating your own representations

To create your own representation class, your class must inherit from the BaseRepresentation class. In addition the following must be defined:

  • __init__ method:

    Has a signature like __init__(self, comp1, comp2, comp3, copy=True) for inputting the representation component values.

  • from_cartesian class method:

    Takes a CartesianRepresentation object and returns an instance of your class.

  • to_cartesian method:

    Returns a CartesianRepresentation object.

  • attr_classes class attribute (OrderedDict):

    Defines the initializer class for each component.In most cases this class should be derived from Quantity. In particular these class initializers must take the value as the first argument and accept a unit keyword which takes a Unit initializer or None to indicate no unit. Also not that the keys of this dictionary are treated as the names of the components for this representation, with the default ordered given in the order they appear as keys.

  • recommended_units dictionary (optional):

    Maps component names to the recommended unit to convert the values of that component to. Can be None (or missing) to indicate there is no preferred unit. If this dictionary is not defined, no conversion of components to particular units will occur.

In pseudo-code, this means that your class will look like:

class MyRepresentation(BaseRepresentation):

    attr_classes = OrderedDict([('comp1', ComponentClass1),
                                 ('comp2', ComponentClass2),
                                 ('comp3', ComponentClass3)])

    # recommended_units is optional
    recommended_units = {'comp1': u.unit1, 'comp2': u.unit2, 'comp3': u.unit3}

    def __init__(self, ...):
        ...

    @classmethod
    def from_cartesian(self, cartesian):
        ...
        return MyRepresentation(...)

    def to_cartesian(self):
        ...
        return CartesianRepresentation(...)

Once you do this, you will then automatically be able to call represent_as to convert other representations to/from your representation class. Your representation will also be available for use in SkyCoord and all frame classes.

A representation class may also have a _unit_representation attribute (although it is not required). This attribute points to the appropriate “unit” representation (i.e., a representation that is dimensionless). This is probably only meaningful for subclasses of SphericalRepresentation, where it is assumed that it will be a subclass of UnitSphericalRepresentation.