.. include:: references.txt .. _astropy-coordinates-high-level: Using the SkyCoord High-level Class *********************************** The |SkyCoord| class provides a simple and flexible user interface for celestial coordinate representation, manipulation, and transformation between coordinate frames. This is a high-level class that serves as a wrapper around the low-level coordinate frame classes like `~astropy.coordinates.ICRS` and `~astropy.coordinates.FK5` which do most of the heavy lifting. The key distinctions between |SkyCoord| and the low-level classes (:doc:`frames`) are as follows: - The |SkyCoord| object can maintain the union of frame attributes for all built-in and user-defined coordinate frames in the ``astropy.coordinates.frame_transform_graph``. Individual frame classes hold only the required attributes (e.g. equinox, observation time or observer location) for that frame. This means that a transformation from `~astropy.coordinates.FK4` (with equinox and observation time) to `~astropy.coordinates.ICRS` (with neither) and back to `~astropy.coordinates.FK4` via the low-level classes would not remember the original equinox and observation time. Since the |SkyCoord| object stores all attributes, such a round-trip transformation will return to the same coordinate object. - The |SkyCoord| class is more flexible with inputs to accommodate a wide variety of user preferences and available data formats. - The |SkyCoord| class has a number of convenience methods that are useful in typical analysis. - At present, |SkyCoord| objects can use only coordinate frames that have transformations defined in the ``astropy.coordinates.frame_transform_graph`` transform graph object. Creating SkyCoord objects =========================== The |SkyCoord| class accepts a wide variety of inputs for initialization. At a minimum these must provide one or more celestial coordinate values with unambiguous units. Typically one also specifies the coordinate frame, though this is not required. Common patterns are shown below. In this description the values in upper case like ``COORD`` or ``FRAME`` represent inputs which are described in detail in the `Initialization Syntax`_ section. Elements in square brackets like ``[unit=UNIT]`` are optional. :: SkyCoord(COORD, [FRAME], keyword_args ...) SkyCoord(LON, LAT, [frame=FRAME], [unit=UNIT], keyword_args ...) SkyCoord([FRAME], =LON, =LAT, keyword_args ...) The examples below illustrate common ways of initializing a |SkyCoord| object. These all reflect initializing using spherical coordinates, which is the default for all built-in frames. In order to understand working with coordinates using a different representation such as cartesian or cylindrical, see the section on `Representations`_. First some imports:: >>> from astropy.coordinates import SkyCoord # High-level coordinates >>> from astropy.coordinates import ICRS, Galactic, FK4, FK5 # Low-level frames >>> from astropy.coordinates import Angle, Latitude, Longitude # Angles >>> import astropy.units as u >>> import numpy as np The coordinate values and frame specification can now be provided using positional and keyword arguments. First we show positional arguments for RA and Dec:: >>> SkyCoord(10, 20, unit='deg') # Defaults to ICRS # doctest: +FLOAT_CMP >>> SkyCoord([1, 2, 3], [-30, 45, 8], frame='icrs', unit='deg') # doctest: +FLOAT_CMP Notice that the first example above does not explicitly give a frame. In this case, the default is taken to be the ICRS system (approximately correct for "J2000" equatorial coordinates). It is always better to explicitly specify the frame when it is known to be ICRS, however, as anyone reading the code will be better able to understand the intent. String inputs in common formats are acceptable, and the frame can be supplied as either a class type like `~astropy.coordinates.FK4`, an instance of a frame class, a `~astropy.coordinates.SkyCoord` instance (from which the frame will be extracted), or the lower-case version of a frame name as a string, e.g. ``"fk4"``:: >>> coords = ["1:12:43.2 +1:12:43", "1 12 43.2 +1 12 43"] >>> sc = SkyCoord(coords, frame=FK4, unit=(u.hourangle, u.deg), obstime="J1992.21") >>> sc = SkyCoord(coords, frame=FK4(obstime="J1992.21"), unit=(u.hourangle, u.deg)) >>> sc = SkyCoord(coords, frame='fk4', unit='hourangle,deg', obstime="J1992.21") >>> sc = SkyCoord("1h12m43.2s", "+1d12m43s", frame=Galactic) # Units from strings >>> sc = SkyCoord("1h12m43.2s +1d12m43s", frame=Galactic) # Units from string >>> sc = SkyCoord(l="1h12m43.2s", b="+1d12m43s", frame='galactic') >>> sc = SkyCoord("1h12.72m +1d12.71m", frame='galactic') Note that frame instances with data and `~astropy.coordinates.SkyCoord` instances can only be passed as frames using the ``frame=`` keyword argument and not as positional arguments. For representations that have ``ra`` and ``dec`` attributes one can supply a coordinate string in a number of other common formats. Examples include:: >>> sc = SkyCoord("15h17+89d15") >>> sc = SkyCoord("275d11m15.6954s+17d59m59.876s") >>> sc = SkyCoord("8 00 -5 00.6", unit=(u.hour, u.deg)) >>> sc = SkyCoord("J080000.00-050036.00", unit=(u.hour, u.deg)) >>> sc = SkyCoord("J1874221.31+122328.03", unit=u.deg) Astropy `~astropy.units.Quantity`-type objects are acceptable and encouraged as a form of input:: >>> ra = Longitude([1, 2, 3], unit=u.deg) # Could also use Angle >>> dec = np.array([4.5, 5.2, 6.3]) * u.deg # Astropy Quantity >>> sc = SkyCoord(ra, dec, frame='icrs') >>> sc = SkyCoord(ra=ra, dec=dec, frame=ICRS, obstime='2001-01-02T12:34:56') Finally it is possible to initialize from a low-level coordinate frame object. >>> c = FK4(1 * u.deg, 2 * u.deg) >>> sc = SkyCoord(c, obstime='J2010.11', equinox='B1965') # Override defaults A key subtlety highlighted here is that when low-level objects are created they have certain default attribute values. For instance the `~astropy.coordinates.FK4` frame uses ``equinox='B1950.0`` and ``obstime=equinox`` as defaults. If this object is used to initialize a |SkyCoord| it is possible to override the low-level object attributes that were not explicitly set. If the coordinate above were created with ``c = FK4(1 * u.deg, 2 * u.deg, equinox='B1960')`` then creating a |SkyCoord| with a different ``equinox`` would raise an exception. Initialization Syntax --------------------- For spherical representations, which are the most common and are the default input format for all built-in frames, the syntax for |SkyCoord| is given below:: SkyCoord(COORD, [FRAME | frame=FRAME], [unit=UNIT], keyword_args ...) SkyCoord(LON, LAT, [DISTANCE], [FRAME | frame=FRAME], [unit=UNIT], keyword_args ...) SkyCoord([FRAME | frame=FRAME], =LON, =LAT, [unit=UNIT], keyword_args ...) In the above description, elements in all capital letters (e.g. ``FRAME``) describes a user input of that element type. Elements in square brackets are optional. For non-spherical inputs see the `Representations`_ section. **LON**, **LAT** Longitude and latitude value can be specified as separate positional arguments. The following options are available for longitude and latitude: - Single angle value: - |Quantity| object - Plain numeric value with ``unit`` keyword specifying the unit - Angle string which is formatted for :ref:`angle-creation` of |Longitude| or |Latitude| objects - List or |Quantity| array or numpy array of angle values - |Angle|, |Longitude|, or |Latitude| object, which can be scalar or array-valued **DISTANCE** The distance to the object from the frame center can be optionally specified: - Single distance value: - |Quantity| or `~astropy.coordinates.Distance` object - Plain numeric value for a dimensionless distance - Plain numeric value with ``unit`` keyword specifying the unit - List or |Quantity| or `~astropy.coordinates.Distance` array or numpy array of angle values **COORD** This input form uses a single object to supply coordinate data. For the case of spherical coordinate frames, the coordinate can include one or more longitude and latitude pairs in one of the following ways: - Single coordinate string with a LON and LAT value separated by a space. The respective values can be any string which is formatted for :ref:`angle-creation` of |Longitude| or |Latitude| objects, respectively. - List or numpy array of such coordinate strings - List of (LON, LAT) tuples, where each LON and LAT are scalars (not arrays) - ``N x 2`` numpy or |Quantity| array of values where the first column is longitude and the second column is latitude, e.g. ``[[270, -30], [355, +85]] * u.deg`` - List of (LON, LAT, DISTANCE) tuples - ``N x 3`` numpy or |Quantity| array of values where columns are longitude, latitude, and distance respectively. The input can also be more generalized objects that are not necessarily represented in the standard spherical coordinates: - Coordinate frame object, e.g. ``FK4(1*u.deg, 2*u.deg, obstime='J2012.2')`` - |SkyCoord| object (which just makes a copy of the object) - `~astropy.coordinates.BaseRepresentation` subclass object like `~astropy.coordinates.SphericalRepresentation`, `~astropy.coordinates.CylindricalRepresentation`, or `~astropy.coordinates.CartesianRepresentation`. **FRAME** This can be a `~astropy.coordinates.BaseCoordinateFrame` frame class, an instance of such a class, or the corresponding string alias. The frame classes that are built in to astropy are `~astropy.coordinates.ICRS`, `~astropy.coordinates.FK5`, `~astropy.coordinates.FK4`, `~astropy.coordinates.FK4NoETerms`, `~astropy.coordinates.Galactic`, and `~astropy.coordinates.AltAz`. The string aliases are simply lower-case versions of the class name. If the frame is not supplied then you will see a special ``ICRS`` identifier. This indicates that the frame is unspecified and operations that require comparing coordinates (even within that object) are not allowed. **unit=UNIT** The unit specifier can be one of the following: - `~astropy.units.Unit` object which is an angular unit that is equivalent to ``Unit('radian')`` - Single string with a valid angular unit name - 2-tuple of `~astropy.units.Unit` objects or string unit names specifying the LON and LAT unit respectively, e.g. ``('hourangle', 'degree')`` - Single string with two unit names separated by a comma, e.g. ``'hourangle,degree'`` If only a single unit is provided then it applies to both LON and LAT. **Other keyword arguments** In lieu of positional arguments to specify the longitude and latitude, the frame-specific names can be used as keyword arguments: *ra*, *dec*: **LON**, **LAT** values, optional RA and Dec for frames where these are representation, including [FIXME] `~astropy.coordinates.ICRS`, `~astropy.coordinates.FK5`, `~astropy.coordinates.FK4`, and `~astropy.coordinates.FK4NoETerms`. *l*, *b*: **LON**, **LAT** values, optional Galactic ``l`` and ``b`` for the `~astropy.coordinates.Galactic` frame. The following keywords can be specified for any frame: *distance*: valid `~astropy.coordinates.Distance` initializer, optional Distance from reference from center to source. *obstime*: valid `~astropy.time.Time` initializer, optional Time of observation *equinox*: valid `~astropy.time.Time` initializer, optional Coordinate frame equinox If custom user-defined frames are included in the transform graph and they have additional frame attributes, then those attributes can also be set via corresponding keyword args in the |SkyCoord| initialization. .. _astropy-coordinates-array-operations: Array operations ================= It is possible to store arrays of coordinates in a |SkyCoord| object, and manipulations done in this way will be orders of magnitude faster than looping over a list of individual |SkyCoord| objects:: >>> ra = np.linspace(0, 36000, 1001) * u.deg >>> dec = np.linspace(-90, 90, 1001) * u.deg >>> sc_list = [SkyCoord(r, d, frame='icrs') for r, d in zip(ra, dec)] # doctest: +SKIP >>> timeit sc_gal_list = [c.galactic for c in sc_list] # doctest: +SKIP 1 loops, best of 3: 20.4 s per loop >>> sc = SkyCoord(ra, dec, frame='icrs') >>> timeit sc_gal = sc.galactic # doctest: +SKIP 100 loops, best of 3: 21.8 ms per loop In addition to vectorized transformations, you can do the usual array slicing, dicing, and selection, using the same methods and attributes that one uses for `~numpy.ndarray` instances:: >>> north_mask = sc.dec > 0 >>> sc_north = sc[north_mask] >>> len(sc_north) 500 >>> sc[2:4] # doctest: +FLOAT_CMP >>> sc[500] # doctest: +FLOAT_CMP >>> sc[0:-1:100].reshape(2, 5) # doctest: +FLOAT_CMP Note that similarly to the `~numpy.ndarray` methods, all but ``flatten`` try to use new views of the data, with the data copied only if that it is impossible (as discussed, e.g., in the documentation for numpy :func:`~numpy.reshape`). Attributes =========== The |SkyCoord| object has a number of useful attributes which come in handy. By digging through these we'll learn a little bit about |SkyCoord| and how it works. To begin (if you don't know already) one of the most important tools for learning about attributes and methods of objects is "TAB-discovery". From within IPython you can type an object name, the period, and then the key to see what's available. This can often be faster than reading the documentation:: >>> sc = SkyCoord(1, 2, frame='icrs', unit='deg', obstime='2013-01-02 14:25:36') >>> sc. # doctest: +SKIP sc.T sc.match_to_catalog_3d sc.altaz sc.match_to_catalog_sky sc.barycentrictrueecliptic sc.name sc.cartesian sc.ndim sc.cirs sc.obsgeoloc sc.copy sc.obsgeovel sc.data sc.obstime sc.dec sc.obswl sc.default_representation sc.position_angle sc.diagonal sc.precessedgeocentric sc.distance sc.pressure sc.equinox sc.ra sc.fk4 sc.ravel sc.fk4noeterms sc.realize_frame sc.fk5 sc.relative_humidity sc.flatten sc.represent_as sc.frame sc.representation sc.frame_attributes sc.representation_component_names sc.frame_specific_representation_info sc.representation_component_units sc.from_name sc.representation_info sc.from_pixel sc.reshape sc.galactic sc.roll sc.galactocentric sc.search_around_3d sc.galcen_dec sc.search_around_sky sc.galcen_distance sc.separation sc.galcen_ra sc.separation_3d sc.gcrs sc.shape sc.geocentrictrueecliptic sc.size sc.get_constellation sc.skyoffset_frame sc.get_frame_attr_names sc.spherical sc.guess_from_table sc.spherical_offsets_to sc.has_data sc.squeeze sc.hcrs sc.supergalactic sc.heliocentrictrueecliptic sc.swapaxes sc.icrs sc.take sc.info sc.temperature sc.is_equivalent_frame sc.to_pixel sc.is_frame_attr_default sc.to_string sc.is_transformable_to sc.transform_to sc.isscalar sc.transpose sc.itrs sc.z_sun sc.location Here we see many attributes and methods, the most recognizable may be the longitude and latitude attributes which are named ``ra`` and ``dec`` for the ``ICRS`` frame:: >>> sc.ra # doctest: +FLOAT_CMP >>> sc.dec # doctest: +FLOAT_CMP Next notice that all the built-in frame names ``icrs``, ``galactic``, ``fk5`` ``fk4``, and ``fk4noeterms`` are there. Through the magic of Python properties, accessing these attributes calls the object `~astropy.coordinates.SkyCoord.transform_to` method appropriately and returns a new |SkyCoord| object in the requested frame:: >>> sc_gal = sc.galactic >>> sc_gal # doctest: +FLOAT_CMP Other attributes you should recognize are ``distance``, ``equinox``, ``obstime``, ``shape``. Digging deeper -------------- *[Casual users can skip this section]* After transforming to Galactic the longitude and latitude values are now labeled ``l`` and ``b``, following the normal convention for Galactic coordinates. How does the object know what to call its values? The answer lies in some less-obvious attributes:: >>> sc_gal.representation_component_names OrderedDict([('l', 'lon'), ('b', 'lat'), ('distance', 'distance')]) >>> sc_gal.representation_component_units OrderedDict([('l', Unit("deg")), ('b', Unit("deg"))]) >>> sc_gal.representation_type Together these tell the object that ``l`` and ``b`` are the longitude and latitude, and that they should both be displayed in units of degrees as a spherical-type coordinate (and not, e.g. a cartesian coordinate). Furthermore the frame's ``representation_component_names`` attribute defines the coordinate keyword arguments that |SkyCoord| will accept. Another important attribute is ``frame_attr_names``, which defines the additional attributes that are required to fully define the frame:: >>> sc_fk4 = SkyCoord(1, 2, frame='fk4', unit='deg') >>> sc_fk4.get_frame_attr_names() OrderedDict([('equinox',