Skip to content

Commit 4b21463

Browse files
committed
Add documentation about shaping of coordinates, representations, frames.
1 parent 2837ef9 commit 4b21463

4 files changed

Lines changed: 191 additions & 103 deletions

File tree

‎docs/coordinates/frames.rst‎

Lines changed: 63 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,7 @@ Frames without Data
2323
Frame objects have two distinct (but related) uses. The first is
2424
storing the information needed to uniquely define a frame (e.g.,
2525
equinox, observation time). This information is stored on the frame
26-
objects as (read-only) Python attributes, which are set with the object
26+
objects as (read-only) Python attributes, which are set when the object
2727
is first created::
2828

2929
>>> from astropy.coordinates import ICRS, FK5
@@ -100,18 +100,23 @@ class::
100100
>>> icrs.representation
101101
<class 'astropy.coordinates.representation.SphericalRepresentation'>
102102
>>> icrs.representation_component_names
103-
OrderedDict([(u'ra', u'lon'), (u'dec', u'lat'), (u'distance', u'distance')])
104-
105-
The representation of the coordinate object can be changed, as shown
106-
below. This actually does *nothing* to the object internal data which
107-
stores the coordinate values, but it changes the external view of that
108-
data in two ways: (1) the object prints itself in accord with the
109-
new representation, and (2) the available attributes change to match
110-
those of the new representation (e.g. from ``ra, dec, distance`` to
111-
``x, y, z``). Setting the ``representation`` thus changes a *property*
112-
of the object (how it appears) without changing the intrinsic object
113-
itself which represents a point in 3d space.
114-
::
103+
OrderedDict([('ra', 'lon'), ('dec', 'lat'), ('distance', 'distance')])
104+
105+
One can get the data in a different representation if needed::
106+
107+
>>> icrs.represent_as('cartesian') # doctest: +FLOAT_CMP
108+
<CartesianRepresentation (x, y, z) [dimensionless]
109+
(0.99923861, 0.01744177, 0.0348995)>
110+
111+
The representation of the coordinate object can also be changed directly, as
112+
shown below. This actually does *nothing* to the object internal data which
113+
stores the coordinate values, but it changes the external view of that data in
114+
two ways: (1) the object prints itself in accord with the new representation,
115+
and (2) the available attributes change to match those of the new
116+
representation (e.g. from ``ra, dec, distance`` to ``x, y, z``). Setting the
117+
``representation`` thus changes a *property* of the object (how it appears)
118+
without changing the intrinsic object itself which represents a point in 3d
119+
space.::
115120

116121
>>> from astropy.coordinates import CartesianRepresentation
117122
>>> icrs.representation = CartesianRepresentation
@@ -167,8 +172,9 @@ if it is preset, it can be accessed from the ``data`` attribute::
167172
<UnitSphericalRepresentation (lon, lat) in deg
168173
(1.1, 2.2)>
169174

170-
All of the above methods can also accept array data (or other Python
171-
sequences) to create arrays of coordinates::
175+
All of the above methods can also accept array data (in the form of
176+
class:`~astropy.unit.Quantity`, or other Python sequences) to create arrays of
177+
coordinates::
172178

173179
>>> ICRS(ra=[1.5, 2.5]*u.deg, dec=[3.5, 4.5]*u.deg)
174180
<ICRS Coordinate: (ra, dec) in deg
@@ -181,15 +187,48 @@ over the scalars appropriately::
181187
<ICRS Coordinate: (ra, dec, distance) in (deg, deg, kpc)
182188
[(1.5, 3.5, 5.0), (2.5, 4.5, 5.0)]>
183189

184-
An additional operation that may be useful is the ability to extract the
185-
data in different representations. E.g., to get the Cartesian form of
186-
an ICRS coordinate::
187-
188-
>>> from astropy.coordinates import CartesianRepresentation
189-
>>> cooi = ICRS(ra=0*u.deg, dec=45*u.deg, distance=10*u.pc)
190-
>>> cooi.represent_as(CartesianRepresentation) # doctest: +FLOAT_CMP
191-
<CartesianRepresentation (x, y, z) in pc
192-
(7.07106781187, 0.0, 7.07106781187)>
190+
Similar broadcasting happens if you transform to another frame. E.g.::
191+
192+
>>> import numpy as np
193+
>>> from astropy.coordinates import EarthLocation, AltAz
194+
>>> coo = ICRS(ra=180.*u.deg, dec=51.477811*u.deg)
195+
>>> lf = AltAz(location=EarthLocation.of_site('greenwich'),
196+
... obstime=['2012-03-21T00:00:00', '2012-06-21T00:00:00'])
197+
>>> coo.transform_to(lf) # doctest: +FLOAT_CMP
198+
<AltAz Coordinate (obstime=['2012-03-21T00:00:00.000' '2012-06-21T00:00:00.000'], location=(3980608.9024681724, -102.47522910648239, 4966861.273100675) m, pressure=0.0 hPa, temperature=0.0 deg_C, relative_humidity=0, obswl=1.0 micron): (az, alt) in deg
199+
[(94.71264994, 89.2142425), (307.69488826, 37.98077772)]>
200+
201+
Above, the shapes -- ``()`` for ``coo`` and ``(2,)`` for ``lf`` -- were
202+
broadcast against each other. If you wished to determine the positions for a
203+
set of coordinates, you'd need to make sure that the shapes allowed this::
204+
205+
>>> coo2 = ICRS(ra=[180., 225., 270.]*u.deg, dec=[51.5, 0., 51.5]*u.deg)
206+
>>> coo2.transform_to(lf)
207+
Traceback (most recent call last):
208+
...
209+
ValueError: shape mismatch: objects cannot be broadcast to a single shape
210+
>>> coo2.shape
211+
(3,)
212+
>>> lf.shape
213+
(2,)
214+
>>> lf2 = lf[:, np.newaxis]
215+
>>> lf2.shape
216+
(2, 1)
217+
>>> coo2.transform_to(lf2) # doctest: +FLOAT_CMP
218+
<AltAz Coordinate (obstime=[['2012-03-21T00:00:00.000' '2012-03-21T00:00:00.000'
219+
'2012-03-21T00:00:00.000']
220+
['2012-06-21T00:00:00.000' '2012-06-21T00:00:00.000'
221+
'2012-06-21T00:00:00.000']], location=(3980608.9024681724, -102.47522910648239, 4966861.273100675) m, pressure=0.0 hPa, temperature=0.0 deg_C, relative_humidity=0, obswl=1.0 micron): (az, alt) in deg
222+
[[(93.09845202, 89.21613119), (126.85789652, 25.46600543),
223+
(51.37993229, 37.18532521)],
224+
[(307.71713699, 37.99437658), (231.37407871, 26.36768329),
225+
(85.42187335, 89.69297997)]]>
226+
227+
.. Note::
228+
One sees that frames without data have a ``shape`` that is determined by
229+
their frame attributes. For frames with data the ``shape`` always is that
230+
of the data; any non-scalar attributes are broadcast to have matching shape
231+
(as can be seen for ``obstime`` in the last line above).
193232

194233
Transforming between Frames
195234
===========================

‎docs/coordinates/index.rst‎

Lines changed: 9 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -50,16 +50,21 @@ they store multiple coordinates in a single object. When you're going
5050
to apply the same operation to many different coordinates (say, from a
5151
catalog), this is a better choice than a list of |skycoord| objects,
5252
because it will be *much* faster than applying the operation to each
53-
|skycoord| in a for loop.
54-
::
53+
|skycoord| in a for loop. Like the underlying `~numpy.ndarray` instances
54+
holding the data, |skycoord| objects can be sliced, reshaped, etc.::
5555

56-
>>> c = SkyCoord(ra=[10, 11]*u.degree, dec=[41, -5]*u.degree)
56+
>>> c = SkyCoord(ra=[10, 11, 12, 13]*u.degree, dec=[41, -5, 42, 0]*u.degree)
5757
>>> c
5858
<SkyCoord (ICRS): (ra, dec) in deg
59-
[(10.0, 41.0), (11.0, -5.0)]>
59+
[(10.0, 41.0), (11.0, -5.0), (12.0, 42.0), (13.0, 0.0)]>
6060
>>> c[1]
6161
<SkyCoord (ICRS): (ra, dec) in deg
6262
(11.0, -5.0)>
63+
>>> c.reshape(2, 2)
64+
<SkyCoord (ICRS): (ra, dec) in deg
65+
[[(10.0, 41.0), (11.0, -5.0)],
66+
[(12.0, 42.0), (13.0, 0.0)]]>
67+
6368

6469
Coordinate access
6570
-----------------

‎docs/coordinates/representations.rst‎

Lines changed: 19 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -83,24 +83,30 @@ removed, and the points are still located on a unit sphere:
8383
(0.424264068712, 0.707106781187, 0.565685424949)>
8484

8585

86-
Array values
87-
^^^^^^^^^^^^
86+
Array values and numpy array method analogs
87+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
8888

89-
Array `~astropy.units.Quantity` objects can also be passed to
90-
representations::
89+
Array `~astropy.units.Quantity` objects can also be passed to representations,
90+
and such representations can be sliced, reshaped, etc., using the same
91+
methods as are available to `~numpy.ndarray`::
9192

9293
>>> import numpy as np
93-
>>> x = np.random.random(100)
94-
>>> y = np.random.random(100)
95-
>>> z = np.random.random(100)
94+
>>> x = np.linspace(0., 5., 6)
95+
>>> y = np.linspace(10., 15., 6)
96+
>>> z = np.linspace(20., 25., 6)
9697
>>> car_array = CartesianRepresentation(x * u.m, y * u.m, z * u.m)
97-
>>> car_array # doctest: +SKIP
98+
>>> car_array
9899
<CartesianRepresentation (x, y, z) in m
99-
[(0.7093..., 0.7788..., 0.3842...),
100-
(0.8434..., 0.4543..., 0.9579...),
101-
...
102-
(0.0179..., 0.8587..., 0.4916...),
103-
(0.0207..., 0.3355..., 0.2799...)]>
100+
[(0.0, 10.0, 20.0), (1.0, 11.0, 21.0), (2.0, 12.0, 22.0),
101+
(3.0, 13.0, 23.0), (4.0, 14.0, 24.0), (5.0, 15.0, 25.0)]>
102+
>>> car_array[2]
103+
<CartesianRepresentation (x, y, z) in m
104+
(2.0, 12.0, 22.0)>
105+
>>> car_array.reshape(3, 2)
106+
<CartesianRepresentation (x, y, z) in m
107+
[[(0.0, 10.0, 20.0), (1.0, 11.0, 21.0)],
108+
[(2.0, 12.0, 22.0), (3.0, 13.0, 23.0)],
109+
[(4.0, 14.0, 24.0), (5.0, 15.0, 25.0)]]>
104110

105111
.. _astropy-coordinates-create-repr:
106112

0 commit comments

Comments
 (0)