<commit_before>.. include:: references.txt

.. _astropy-coordinates:

*******************************************************
Astronomical Coordinate Systems (`astropy.coordinates`)
*******************************************************

Introduction
============

The `~astropy.coordinates` package provides classes for representing a
variety of celestial/spatial  coordinates, as well as tools for
converting between common coordinate systems in a uniform way.


Getting Started
===============

The simplest way to use `~astropy.coordinates` is to use the |skycoord|
class. |skycoord| objects are instantiated with a flexible and natural
approach that supports inputs provided in a number of convenient
formats.  The following ways of initializing a coordinate are all
equivalent::

    >>> from astropy import units as u
    >>> from astropy.coordinates import SkyCoord

    >>> c = SkyCoord(ra=10.5*u.degree, dec=41.2*u.degree, frame='icrs')
    >>> c = SkyCoord(10.5, 41.2, 'icrs', unit='deg')
    >>> c = SkyCoord('00h42m00s', '+41d12m00s', 'icrs')
    >>> c = SkyCoord('00 42 00 +41 12 00', 'icrs', unit=(u.hourangle, u.deg))
    >>> c
    <SkyCoord (ICRS): ra=10.5 deg, dec=41.2 deg>

The examples above illustrate a few simple rules to follow when creating a coordinate
object:

- Coordinate values can be provided either as unnamed positional arguments or
  via keyword arguments like ``ra``, ``dec``, ``l``, or ``b`` (depending on the frame).
- Coordinate frame value is optional and can be specified as a positional
  argument or via the ``frame`` keyword.
- Angle units must be specified, either in the values themselves
  (e.g. ``10.5*u.degree`` or ``'+41d12m00s'``) or via the ``unit`` keyword.

The individual components of equatorial coordinates are
`~astropy.coordinates.Longitude` or `~astropy.coordinates.Latitude`
objects, which are specialized versions of the general
`~astropy.coordinates.Angle` class.  The component values are accessed
using aptly named attributes::

    >>> c = SkyCoord(ra=10.68458*u.degree, dec=41.26917*u.degree)
    >>> c.ra
    <Longitude 10.6845... deg>
    >>> c.ra.hour
    0.712305333...
    >>> c.ra.hms
    hms_tuple(h=0.0, m=42.0, s=44.299...)
    >>> c.dec
    <Latitude 41.2691... deg>
    >>> c.dec.degree
    41.2691...
    >>> c.dec.radian
    0.72028289606...

Coordinates can easily be converted to strings using the
:meth:`~astropy.coordinates.SkyCoord.to_string` method::

    >>> c = SkyCoord(ra=10.68458*u.degree, dec=41.26917*u.degree)
    >>> c.to_string('decimal')
    '10.6846 41.2692'
    >>> c.to_string('dms')
    '10d41m04.488s 41d16m09.012s'
    >>> c.to_string('hmsdms')
    '00h42m44.2992s +41d16m09.012s'

For more control over the string formatting, use the
`~astropy.coordinates.Angle.to_string` method of the individual
components::

    >>> c.ra.to_string(decimal=True)
    '10.6846'
    >>> c.dec.to_string(format='latex')
    '$41^\\circ16{}^\\prime09.012{}^{\\prime\\prime}$'
    >>> msg = 'My coordinates are: ra="{0}"" dec="{1}"'
    >>> msg.format(c.ra.to_string(sep=':'), c.dec.to_string(sep=':'))
    'My coordinates are: ra="10:41:04.488"" dec="41:16:09.012"'


Many of the above examples did not explicitly specify the coordinate frame.
This is fine if you do not need to transform to other frames or compare with
coordinates defined in a different frame.  However, to use the full power of
`~astropy.coordinates`, you should specify the reference frame your coordinates
are defined in::

    >>> c_icrs = SkyCoord(ra=10.68458*u.degree, dec=41.26917*u.degree, frame='icrs')

Once you've defined the frame of your coordinates, you can transform from that
frame to another frame.  You can do this a few different ways: if you just want
the default version of that frame, you can use attribute-style access.  For
more control, you can use the `~astropy.coordinates.SkyCoord.transform_to` method,
which accepts a frame name, frame class, or frame instance::

    >>> from astropy.coordinates import FK5
    >>> c_icrs.galactic
    <SkyCoord (Galactic): l=121.17430... deg, b=-21.572... deg>
    >>> c_fk5 = c_icrs.transform_to('fk5')  # c_icrs.fk5 does the same thing
    >>> c_fk5
    <SkyCoord (FK5): equinox=J2000.000, ra=10.68459... deg, dec=41.269... deg>
    >>> c_fk5.transform_to(FK5(equinox='J1975'))  # precess to a different equinox
    <SkyCoord (FK5): equinox=J1975.000, ra=10.34209... deg, dec=41.132... deg>

|skycoord| and all other `~astropy.coordinates` objects also support
array coordinates.  These work the same as single-value coordinates, but
they store multiple coordinates in a single object.  When you're going
to apply the same operation to many different coordinates (say, from a
catalog), this is a better choice than a list of |skycoord| objects,
because it will be *much* faster than applying the operation to each
|skycoord| in a for loop.

    >>> SkyCoord(ra=[10, 11]*u.degree, dec=[41, -5]*u.degree)
    <SkyCoord (ICRS): (ra, dec) in deg
        [(10.0, 41.0), (11.0, -5.0)]>

So far we have been using a spherical coordinate representation in the all the
examples, and this is the default for the built-in frames.  Frequently it is
convenient to initialize or work with a coordinate using a different
representation such as cartesian or cylindrical.  This can be done by setting
the ``representation`` for either |SkyCoord| objects or low-level frame
coordinate objects::

    >>> c = SkyCoord(x=1, y=2, z=3, unit='kpc', frame='icrs', representation='cartesian')
    >>> c
    <SkyCoord (ICRS): x=1.0 kpc, y=2.0 kpc, z=3.0 kpc>
    >>> c.x, c.y, c.z
    (<Quantity 1.0 kpc>, <Quantity 2.0 kpc>, <Quantity 3.0 kpc>)

    >>> c.representation = 'cylindrical'
    >>> c
    <SkyCoord (ICRS): rho=2.236067... kpc, phi=63.434948... deg, z=3.0 kpc>
    >>> c.phi.to(u.deg)
    <Angle 63.43494882292201 deg>

    >>> c.representation = 'spherical'
    >>> c
    <SkyCoord (ICRS): ra=63.434948... deg, dec=53.300774... deg, distance=3.741657... kpc>

    >>> c.representation = 'unitspherical'
    >>> c
    <SkyCoord (ICRS): ra=63.434948... deg, dec=53.300774... deg>

|skycoord| defines a number of convenience methods as well, like on-sky
separation between two coordinates and catalog matching (detailed in
:ref:`astropy-coordinates-matching`)::

    >>> c1 = SkyCoord(ra=10*u.degree, dec=9*u.degree, frame='icrs')
    >>> c2 = SkyCoord(ra=11*u.degree, dec=10*u.degree, frame='fk5')
    >>> c1.separation(c2)  # Differing frames handled correctly
    <Angle 1.40453358... deg>
<commit_msg>doc fixes in coordinates as suggested by @taldcroft<commit_after>.. include:: references.txt

.. _astropy-coordinates:

*******************************************************
Astronomical Coordinate Systems (`astropy.coordinates`)
*******************************************************

Introduction
============

The `~astropy.coordinates` package provides classes for representing a
variety of celestial/spatial  coordinates, as well as tools for
converting between common coordinate systems in a uniform way.


Getting Started
===============

The simplest way to use `~astropy.coordinates` is to use the |skycoord|
class. |skycoord| objects are instantiated with a flexible and natural
approach that supports inputs provided in a number of convenient
formats.  The following ways of initializing a coordinate are all
equivalent::

    >>> from astropy import units as u
    >>> from astropy.coordinates import SkyCoord

    >>> c = SkyCoord(ra=10.5*u.degree, dec=41.2*u.degree, frame='icrs')
    >>> c = SkyCoord(10.5, 41.2, 'icrs', unit='deg')
    >>> c = SkyCoord('00h42m00s', '+41d12m00s', 'icrs')
    >>> c = SkyCoord('00 42 00 +41 12 00', 'icrs', unit=(u.hourangle, u.deg))
    >>> c
    <SkyCoord (ICRS): ra=10.5 deg, dec=41.2 deg>

The examples above illustrate a few simple rules to follow when creating a coordinate
object:

- Coordinate values can be provided either as unnamed positional arguments or
  via keyword arguments like ``ra``, ``dec``, ``l``, or ``b`` (depending on the frame).
- Coordinate frame value is optional and can be specified as a positional
  argument or via the ``frame`` keyword.
- Angle units must be specified, either in the values themselves
  (e.g. ``10.5*u.degree`` or ``'+41d12m00s'``) or via the ``unit`` keyword.

The individual components of equatorial coordinates are
`~astropy.coordinates.Longitude` or `~astropy.coordinates.Latitude`
objects, which are specialized versions of the general
`~astropy.coordinates.Angle` class.  The component values are accessed
using aptly named attributes::

    >>> c = SkyCoord(ra=10.68458*u.degree, dec=41.26917*u.degree)
    >>> c.ra
    <Longitude 10.6845... deg>
    >>> c.ra.hour
    0.712305333...
    >>> c.ra.hms
    hms_tuple(h=0.0, m=42.0, s=44.299...)
    >>> c.dec
    <Latitude 41.2691... deg>
    >>> c.dec.degree
    41.2691...
    >>> c.dec.radian
    0.72028289606...

Coordinates can easily be converted to strings using the
:meth:`~astropy.coordinates.SkyCoord.to_string` method::

    >>> c = SkyCoord(ra=10.68458*u.degree, dec=41.26917*u.degree)
    >>> c.to_string('decimal')
    '10.6846 41.2692'
    >>> c.to_string('dms')
    '10d41m04.488s 41d16m09.012s'
    >>> c.to_string('hmsdms')
    '00h42m44.2992s +41d16m09.012s'

For more control over the string formatting, use the
`~astropy.coordinates.Angle.to_string` method of the individual
components::

    >>> c.ra.to_string(decimal=True)
    '10.6846'
    >>> c.dec.to_string(format='latex')
    '$41^\\circ16{}^\\prime09.012{}^{\\prime\\prime}$'
    >>> msg = 'My coordinates are: ra="{0}"" dec="{1}"'
    >>> msg.format(c.ra.to_string(sep=':'), c.dec.to_string(sep=':'))
    'My coordinates are: ra="10:41:04.488"" dec="41:16:09.012"'


Many of the above examples did not explicitly specify the coordinate frame.
This is fine if you do not need to transform to other frames or compare with
coordinates defined in a different frame.  However, to use the full power of
`~astropy.coordinates`, you should specify the reference frame your coordinates
are defined in::

    >>> c_icrs = SkyCoord(ra=10.68458*u.degree, dec=41.26917*u.degree, frame='icrs')

Once you've defined the frame of your coordinates, you can transform from that
frame to another frame.  You can do this a few different ways: if you just want
the default version of that frame, you can use attribute-style access.  For
more control, you can use the `~astropy.coordinates.SkyCoord.transform_to` method,
which accepts a frame name, frame class, or frame instance::

    >>> from astropy.coordinates import FK5
    >>> c_icrs.galactic
    <SkyCoord (Galactic): l=121.17430... deg, b=-21.572... deg>
    >>> c_fk5 = c_icrs.transform_to('fk5')  # c_icrs.fk5 does the same thing
    >>> c_fk5
    <SkyCoord (FK5): equinox=J2000.000, ra=10.68459... deg, dec=41.269... deg>
    >>> c_fk5.transform_to(FK5(equinox='J1975'))  # precess to a different equinox
    <SkyCoord (FK5): equinox=J1975.000, ra=10.34209... deg, dec=41.132... deg>

|skycoord| and all other `~astropy.coordinates` objects also support
array coordinates.  These work the same as single-value coordinates, but
they store multiple coordinates in a single object.  When you're going
to apply the same operation to many different coordinates (say, from a
catalog), this is a better choice than a list of |skycoord| objects,
because it will be *much* faster than applying the operation to each
|skycoord| in a for loop.

    >>> SkyCoord(ra=[10, 11]*u.degree, dec=[41, -5]*u.degree)
    <SkyCoord (ICRS): (ra, dec) in deg
        [(10.0, 41.0), (11.0, -5.0)]>

So far we have been using a spherical coordinate representation in the all the
examples, and this is the default for the built-in frames.  Frequently it is
convenient to initialize or work with a coordinate using a different
representation such as cartesian or cylindrical.  This can be done by setting
the ``representation`` for either |SkyCoord| objects or low-level frame
coordinate objects::

    >>> c = SkyCoord(x=1, y=2, z=3, unit='kpc', frame='icrs', representation='cartesian')
    >>> c
    <SkyCoord (ICRS): x=1.0 kpc, y=2.0 kpc, z=3.0 kpc>
    >>> c.x, c.y, c.z
    (<Quantity 1.0 kpc>, <Quantity 2.0 kpc>, <Quantity 3.0 kpc>)

    >>> c.representation = 'cylindrical'
    >>> c
    <SkyCoord (ICRS): rho=2.236067... kpc, phi=63.434948... deg, z=3.0 kpc>
    >>> c.phi
    <Angle 63.434948... deg>
    >>> c.phi.to(u.radian)
    <Angle 1.107148... rad>

    >>> c.representation = 'spherical'
    >>> c
    <SkyCoord (ICRS): ra=63.434948... deg, dec=53.300774... deg, distance=3.741657... kpc>

    >>> c.representation = 'unitspherical'
    >>> c
    <SkyCoord (ICRS): ra=63.434948... deg, dec=53.300774... deg>

|skycoord| defines a number of convenience methods as well, like on-sky
separation between two coordinates and catalog matching (detailed in
:ref:`astropy-coordinates-matching`)::

    >>> c1 = SkyCoord(ra=10*u.degree, dec=9*u.degree, frame='icrs')
    >>> c2 = SkyCoord(ra=11*u.degree, dec=10*u.degree, frame='fk5')
    >>> c1.separation(c2)  # Differing frames handled correctly
    <Angle 1.40453358... deg>

{'fraction_non_alphanumeric': 0.15676995878491834, 'fraction_numerical': 0.06357807968249123, 'mean_word_length': 3.8728151729267384, 'pattern_counts': {'":': 0, '<': 36, '<?xml version=': 0, '>': 291, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '633092', 'n_tokens_mistral': 4859, 'n_tokens_neox': 4264, 'n_words': 1411}