Skip to content

Commit f25adbf

Browse files
committed
Merge pull request #31 from astrofrog/coordinates-docs-representations
Documentation for representation classes
2 parents 970c78f + cc711fc commit f25adbf

1 file changed

Lines changed: 122 additions & 114 deletions

File tree

‎docs/coordinates/representations.rst‎

Lines changed: 122 additions & 114 deletions
Original file line numberDiff line numberDiff line change
@@ -3,119 +3,127 @@
33
Using and Designing Coordinate Representations
44
----------------------------------------------
55

6-
As described in :ref:`astropy-coordinates-overview`, the actual
7-
coordinate data in `~astropy.coordinates` is represented via
8-
"Representation classes"...
6+
As described in :ref:`astropy-coordinates-overview`, the actual coordinate
7+
data in `astropy.coordinates` frames is represented via
8+
"Representation classes". These can be used to store 3-d coordinates in
9+
various representations, such as cartesian, spherical polar, cylindrical, and
10+
so on. The built-in representation classes are:
11+
12+
* `~astropy.coordinates.CartesianRepresentation`: cartesian
13+
coordinates ``x``, ``y``, and ``z``
14+
* `~astropy.coordinates.SphericalRepresentation`: spherical
15+
polar coordinates represented by a longitude (``lon``), a latitude
16+
(``lat``), and a distance (``distance``). The latitude is a value ranging
17+
from -90 to 90 degrees.
18+
* `~astropy.coordinates.UnitSphericalRepresentation`:
19+
spherical polar coordinates on a unit sphere, represented by a longitude
20+
(``lon``) and latitude (``lat``)
21+
* `~astropy.coordinates.PhysicsSphericalRepresentation`:
22+
spherical polar coordinates, represented by an inclination (``theta``) and
23+
azimuthal angle (``phi``), and radius ``r``. The inclination goes from 0 to
24+
180 degrees, and is related to the latitude in the
25+
`~astropy.coordinates.SphericalRepresentation` by
26+
``theta = 90 deg - lat``.
27+
* `~astropy.coordinates.CylindricalRepresentation`:
28+
cylindrical polar coordinates, represented by a cylindrical radius
29+
(``rho``), azimuthal angle (``phi``), and height (``z``).
30+
31+
Instantiating and converting
32+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
33+
34+
Representation classes should be instantiated with `~astropy.units.Quantity`
35+
objects:
936

10-
.. todo:: @astrofrog writes this
11-
12-
* describe creating/using representation objects. Emphasize that they
13-
are mostly used inside frame classes
14-
* describe how to get other representations, esp. cartesian, and at least a brief
15-
mention of how things work with/without `distance`
16-
* brief discussion of how users can create their own for use
17-
18-
19-
20-
21-
The text below is the old ``distances.rst`` - that's not necessarily
22-
relevant because a lot of it isn't that important, but some of it can be
23-
rolled into the above. Use as needed then remove when done
24-
25-
REMOVE THIS AFTER ABOVE SECTION IS WRITTEN
26-
==========================================
27-
28-
Coordinates can also have line-of-sight distances. If these are provided, a
29-
coordinate object becomes a full-fledged point in three-dimensional space.
30-
31-
The `~astropy.coordinates.Distance` class is provided to represent a
32-
line-of-sight distance for a coordinate. It must include a length unit to
33-
be valid.::
34-
35-
>>> from astropy.coordinates import Distance, ICRS, CartesianRepresentation
3637
>>> from astropy import units as u
37-
>>> d = Distance(770.)
38-
Traceback (most recent call last):
39-
...
40-
UnitsError: No unit was provided for Distance
41-
>>> d = Distance(770., u.kpc)
42-
>>> d
43-
<Distance 770.0 kpc>
44-
>>> c = ICRS('00h42m44.3s', '+41d16m9s', distance=d)
45-
>>> c
46-
<SkyCoord (ICRS): ra=10.6845833333 deg, dec=41.2691666667 deg, distance=770.0 kpc>
47-
48-
Because `~astropy.coordinates.Distance` is a subclass of
49-
`~astropy.units.Quantity`, in general a `~astropy.units.Quantity` with units
50-
of length may be provided and it will automatically convert to a
51-
`~astropy.coordinates.Distance`::
52-
53-
>>> ICRS('00h42m44.3s', '+41d16m9s', distance=770*u.kpc)
54-
<SkyCoord (ICRS): ra=10.6845833333 deg, dec=41.2691666667 deg, distance=770.0 kpc>
55-
56-
By default, `~astropy.coordinates.Distance` values must be non-negative. For some cosmologies,
57-
distance metrics may become zero or negative; negative distance values are supported
58-
by setting the ``allow_negative`` keyword argument to ``True``::
59-
60-
>>> d = Distance(-42., u.kpc)
61-
Traceback (most recent call last):
62-
...
63-
ValueError: Distance must be >= 0. Set the kwarg 'allow_negative=True' to
64-
allow negative values.
65-
>>> d = Distance(-42., u.kpc, allow_negative=True)
66-
67-
If a ``distance`` is present, the coordinate can be converted into Cartesian
68-
coordinates using the `~astropy.coordinates.CartesianRepresentation` class, or
69-
the :attr:`~astropy.coordinates.CartesianRepresentation` attribute shorthand::
70-
71-
>>> cart = c.represent_as(CartesianRepresentation)
72-
>>> cart.x
73-
<Quantity 568.71288821656... kpc>
74-
>>> cart.y
75-
<Quantity 107.30093596881... kpc>
76-
>>> cart.z
77-
<Quantity 507.88990924863... kpc>
78-
>>> cart = c.cartesian
79-
>>> cart.x
80-
<Quantity 568.71288821656... kpc>
81-
82-
If a ``distance`` is not present, the Cartesian coordinates are still
83-
available, but the point is interpreted as lying on the (dimensionless)
84-
unit sphere::
85-
86-
>>> c2 = ICRS('00h42m44.3s', '+41d16m9s')
87-
>>> c2.cartesian.x
88-
<Quantity 0.73858816651502...>
89-
>>> c2.cartesian.y
90-
<Quantity 0.13935186489455...>
91-
>>> c2.cartesian.z
92-
<Quantity 0.65959728473848...>
93-
94-
95-
.. note::
96-
97-
The location of the origin is different for different coordinate
98-
systems, but for common celestial coordinate systems it is often
99-
the Earth center (or for precision work, the Earth/Moon barycenter).
100-
101-
This Cartesian representation can also be used to create a new coordinate
102-
object through a `~astropy.coordinates.CartesianRepresentation` object::
103-
104-
>>> cart = CartesianRepresentation(x=568.7129*u.kpc, y=107.3009*u.kpc, z=507.8899*u.kpc)
105-
>>> ICRS(cart)
106-
<ICRS Coordinate: ra=10.6845796179 deg, dec=41.2691659084 deg, distance=769.99999759 kpc>
107-
108-
Finally, two coordinates with distances can be used to derive a real-space
109-
distance (i.e., non-projected separation)::
110-
111-
>>> c1 = ICRS('5h23m34.5s', '-69d45m22s', distance=49*u.kpc)
112-
>>> c2 = ICRS('0h52m44.8s', '-72d49m43s', distance=61*u.kpc)
113-
>>> sep3d = c1.separation_3d(c2)
114-
>>> sep3d
115-
<Distance 23.056848146957... kpc>
116-
>>> sep3d.kpc
117-
23.056848146957...
118-
>>> sep3d.Mpc
119-
0.023056848146957...
120-
>>> sep3d.au
121-
4755816315.663...
38+
>>> from astropy.coordinates.representation import CartesianRepresentation
39+
>>> car = CartesianRepresentation(3 * u.kpc, 5 * u.kpc, 4 * u.kpc)
40+
>>> car
41+
<CartesianRepresentation x=3.0 kpc, y=5.0 kpc, z=4.0 kpc>
42+
43+
Representations can be converted to other representations using the
44+
``represent_as`` method::
45+
46+
>>> from astropy.coordinates.representation import SphericalRepresentation, CylindricalRepresentation
47+
>>> sph = car.represent_as(SphericalRepresentation)
48+
>>> sph
49+
<SphericalRepresentation lon=1.0303... rad, lat=0.6012... rad, distance=7.0710... kpc>
50+
>>> cyl = car.represent_as(CylindricalRepresentation)
51+
>>> cyl
52+
<CylindricalRepresentation rho=5.8309... kpc, phi=1.0303... rad, z=4.0 kpc>
53+
54+
All representations can be converted to each other without loss of
55+
information, with the exception of
56+
`~astropy.coordinates.UnitSphericalRepresentation`. This class
57+
is used to store the longitude and latitude of points but does not contain
58+
any distance to the points, and assumes that they are located on a unit and
59+
dimensionless sphere::
60+
61+
>>> from astropy.coordinates.representation import UnitSphericalRepresentation
62+
>>> sph_unit = car.represent_as(UnitSphericalRepresentation)
63+
>>> sph_unit
64+
<UnitSphericalRepresentation lon=1.0303... rad, lat=0.6012... rad>
65+
66+
Converting back to cartesian, the absolute scaling information has been
67+
removed, and the points are still located on a unit sphere:
68+
69+
>>> sph_unit = car.represent_as(UnitSphericalRepresentation)
70+
>>> sph_unit.represent_as(CartesianRepresentation)
71+
<CartesianRepresentation x=0.4242... , y=0.7071... , z=0.5656... >
72+
73+
Array values
74+
^^^^^^^^^^^^
75+
76+
Array `~astropy.units.Quantity` objects can also be passed to
77+
representations::
78+
79+
>>> import numpy as np
80+
>>> x = np.random.random(100)
81+
>>> y = np.random.random(100)
82+
>>> z = np.random.random(100)
83+
>>> car_array = CartesianRepresentation(x * u.m, y * u.m, z * u.m)
84+
>>> car_array # doctest: +SKIP
85+
<CartesianRepresentation (x, y, z) in m
86+
[(0.7093..., 0.7788..., 0.3842...),
87+
(0.8434..., 0.4543..., 0.9579...),
88+
...
89+
(0.0179..., 0.8587..., 0.4916...),
90+
(0.0207..., 0.3355..., 0.2799...)]>
91+
92+
Creating your own representations
93+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
94+
95+
To create your own representation class, your class should:
96+
97+
* Your class should inherit from the ``BaseRepresentation`` class.
98+
* Define ``__init__``
99+
* Define a ``from_cartesian`` class method which should take a
100+
`~astropy.coordinates.CartesianRepresentation` object and
101+
return an instance of your class.
102+
* Define a ``to_cartesian`` method which should return a
103+
`~astropy.coordinates.CartesianRepresentation` object
104+
* Define a ``components`` property that returns a list of the names of the
105+
coordinate components (such as ``x``, ``lon``, and so on).
106+
107+
In pseudo-code, this means that your class will look like::
108+
109+
class MyRepresentation(BaseRepresentation):
110+
111+
def __init__(self, ...):
112+
...
113+
114+
@classmethod
115+
def from_cartesian(self, cartesian):
116+
...
117+
return MyRepresentation(...)
118+
119+
def to_cartesian(self):
120+
...
121+
return CartesianRepresentation(...)
122+
123+
@property
124+
def components(self):
125+
return [...]
126+
127+
Once you do this, you will then automatically be able to call
128+
``represent_as`` to convert other representations to/from your representation
129+
class.

0 commit comments

Comments
 (0)