astropy:docs

Note

This is an old version of the documentation. See http://docs.astropy.org/en/stable for the latest version.

SkyCoord

class astropy.coordinates.SkyCoord(*args, **kwargs)[source] [edit on github]

Bases: object

High-level object providing a flexible interface for celestial coordinate representation, manipulation, and transformation between systems.

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. Inputs may be scalars or lists/tuples/arrays, yielding scalar or array coordinates (can be checked via SkyCoord.isscalar). Typically one also specifies the coordinate frame, though this is not required. The general pattern for spherical representations is:

SkyCoord(COORD, [FRAME], keyword_args ...)
SkyCoord(LON, LAT, [FRAME], keyword_args ...)
SkyCoord(LON, LAT, [DISTANCE], frame=FRAME, unit=UNIT, keyword_args ...)
SkyCoord([FRAME], <lon_attr>=LON, <lat_attr>=LAT, keyword_args ...)

It is also possible to input coordinate values in other representations such as cartesian or cylindrical. In this case one includes the keyword argument representation='cartesian' (for example) along with data in x, y, and z.

Parameters:

frame : BaseCoordinateFrame class or string, optional

Type of coordinate frame this SkyCoord should represent. Defaults to to ICRS if not given or given as None.

unit : Unit, string, or tuple of Unit or str, optional

Units for supplied LON and LAT values, respectively. If only one unit is supplied then it applies to both LON and LAT.

obstime : valid Time initializer, optional

Time of observation

equinox : valid Time initializer, optional

Coordinate frame equinox

representation : str or Representation class

Specifies the representation, e.g. ‘spherical’, ‘cartesian’, or ‘cylindrical’. This affects the positional args and other keyword args which must correspond to the given representation.

**keyword_args

Other keyword arguments as applicable for user-defined coordinate frames. Common options include:

ra, dec : valid Angle initializer, optional

RA and Dec for frames where ra and dec are keys in the frame’s representation_component_names, including ICRS, FK5, FK4, and FK4NoETerms.

l, b : valid Angle initializer, optional

Galactic l and b for for frames where l and b are keys in the frame’s representation_component_names, including the Galactic frame.

x, y, z : float or Quantity, optional

Cartesian coordinates values

w, u, v : float or Quantity, optional

Cartesian coordinates values for the Galactic frame.

Examples

The examples below illustrate common ways of initializing a SkyCoord object. For a complete description of the allowed syntax see the full coordinates documentation. 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

The coordinate values and frame specification can now be provided using positional and keyword arguments:

>>> c = SkyCoord(10, 20, unit="deg")  # defaults to ICRS frame
>>> c = SkyCoord([1, 2, 3], [-30, 45, 8], "icrs", unit="deg")  # 3 coords

>>> coords = ["1:12:43.2 +1:12:43", "1 12 43.2 +1 12 43"]
>>> c = SkyCoord(coords, FK4, unit=(u.deg, u.hourangle), obstime="J1992.21")

>>> c = SkyCoord("1h12m43.2s +1d12m43s", Galactic)  # Units from string
>>> c = SkyCoord("galactic", l="1h12m43.2s", b="+1d12m43s")

>>> 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
>>> c = SkyCoord(ra, dec, frame='icrs')
>>> c = SkyCoord(ICRS, ra=ra, dec=dec, obstime='2001-01-02T12:34:56')

>>> c = FK4(1 * u.deg, 2 * u.deg)  # Uses defaults for obstime, equinox
>>> c = SkyCoord(c, obstime='J2010.11', equinox='B1965')  # Override defaults

>>> c = SkyCoord(w=0, u=1, v=2, unit='kpc', frame='galactic', representation='cartesian')

>>> c = SkyCoord([ICRS(ra=1*u.deg, dec=2*u.deg), ICRS(ra=3*u.deg, dec=4*u.deg)])

As shown, the frame can be a BaseCoordinateFrame class or the corresponding string alias. The frame classes that are built in to astropy are ICRS, FK5, FK4, FK4NoETerms, and Galactic. The string aliases are simply lower-case versions of the class name, and allow for creating a SkyCoord object and transforming frames without explicitly importing the frame classes.

Attributes Summary

frame
representation

Methods Summary

from_name(name[, frame]) Given a name, query the CDS name resolver to attempt to retrieve coordinate information for that object.
from_pixel(xp, yp, wcs[, origin, mode]) Create a new SkyCoord from pixel coordinates using an WCS object.
guess_from_table(table, **coord_kwargs) A convenience method to create and return a new SkyCoord from the data in an astropy Table.
is_equivalent_frame(other) Checks if this object’s frame as the same as that of the other object.
match_to_catalog_3d(catalogcoord[, nthneighbor]) Finds the nearest 3-dimensional matches of this coordinate to a set of catalog coordinates.
match_to_catalog_sky(catalogcoord[, nthneighbor]) Finds the nearest on-sky matches of this coordinate in a set of catalog coordinates.
position_angle(other) Computes the on-sky position angle (East of North) between this SkyCoord and another.
search_around_3d(searcharoundcoords, distlimit) Searches for all coordinates in this object around a supplied set of points within a given 3D radius.
search_around_sky(searcharoundcoords, seplimit) Searches for all coordinates in this object around a supplied set of points within a given on-sky separation.
separation(other) Computes on-sky separation between this coordinate and another.
separation_3d(other) Computes three dimensional separation between this coordinate and another.
to_pixel(wcs[, origin, mode]) Convert this coordinate to pixel coordinates using a WCS object.
to_string([style]) A string representation of the coordinates.
transform_to(frame) Transform this coordinate to a new frame.

Attributes Documentation

frame
representation

Methods Documentation

classmethod from_name(name, frame=u'icrs')[source] [edit on github]

Given a name, query the CDS name resolver to attempt to retrieve coordinate information for that object. The search database, sesame url, and query timeout can be set through configuration items in astropy.coordinates.name_resolve – see docstring for get_icrs_coordinates for more information.

Parameters:

name : str

The name of the object to get coordinates for, e.g. 'M42'.

frame : str or BaseCoordinateFrame class or instance

The frame to transform the object to.

Returns:

coord : SkyCoord

Instance of the SkyCoord class.

classmethod from_pixel(xp, yp, wcs, origin=0, mode=u'all')[source] [edit on github]

Create a new SkyCoord from pixel coordinates using an WCS object.

Parameters:

xp, yp : float or numpy.ndarray

The coordinates to convert.

wcs : WCS

The WCS to use for convert

origin : int

Whether to return 0 or 1-based pixel coordinates.

mode : ‘all’ or ‘wcs’

Whether to do the transformation including distortions ('all') or only including only the core WCS transformation ('wcs').

Returns:

coord : an instance of this class

A new object with sky coordinates corresponding to the input xp and yp.

See also

to_pixel
to do the inverse operation
astropy.wcs.utils.pixel_to_skycoord
the implementation of this method
classmethod guess_from_table(table, **coord_kwargs)[source] [edit on github]

A convenience method to create and return a new SkyCoord from the data in an astropy Table.

This method matches table columns that start with the case-insensitive names of the the components of the requested frames, if they are also followed by a non-alphanumeric character. It will also match columns that end with the component name if a non-alphanumeric character is before it.

For example, the first rule means columns with names like 'RA[J2000]' or 'ra' will be interpreted as ra attributes for ICRS frames, but 'RAJ2000' or 'radius' are not. Similarly, the second rule applied to the Galactic frame means that a column named 'gal_l' will be used as the the l component, but gall or 'fill' will not.

The definition of alphanumeric here is based on Unicode’s definition of alphanumeric, except without _ (which is normally considered alphanumeric). So for ASCII, this means the non-alphanumeric characters are <space>_!"#$%&'()*+,-./:;<=>?@[\]^`{|}~).

Parameters:

table : astropy.Table

The table to load data from.

coord_kwargs

Any additional keyword arguments are passed directly to this class’s constructor.

Returns:

newsc : same as this class

The new SkyCoord (or subclass) object.

is_equivalent_frame(other)[source] [edit on github]

Checks if this object’s frame as the same as that of the other object.

To be the same frame, two objects must be the same frame class and have the same frame attributes. For two SkyCoord objects, all of the frame attributes have to match, not just those relevant for the object’s frame.

Parameters:

other : SkyCoord or BaseCoordinateFrame

The other object to check.

Returns:

isequiv : bool

True if the frames are the same, False if not.

Raises:

TypeError

If other isn’t a SkyCoord or a BaseCoordinateFrame or subclass.

match_to_catalog_3d(catalogcoord, nthneighbor=1)[source] [edit on github]

Finds the nearest 3-dimensional matches of this coordinate to a set of catalog coordinates.

This finds the 3-dimensional closest neighbor, which is only different from the on-sky distance if distance is set in this object or the catalogcoord object.

For more on how to use this (and related) functionality, see the examples in Separations, Catalog Matching, and Related Functionality.

Parameters:

catalogcoord : SkyCoord or BaseCoordinateFrame

The base catalog in which to search for matches. Typically this will be a coordinate object that is an array (i.e., catalogcoord.isscalar == False)

nthneighbor : int, optional

Which closest neighbor to search for. Typically 1 is desired here, as that is correct for matching one set of coordinates to another. The next likely use case is 2, for matching a coordinate catalog against itself (1 is inappropriate because each point will find itself as the closest match).

Returns:

idx : integer array

Indices into catalogcoord to get the matched points for each of this object’s coordinates. Shape matches this object.

sep2d : Angle

The on-sky separation between the closest match for each element in this object in catalogcoord. Shape matches this object.

dist3d : Quantity

The 3D distance between the closest match for each element in this object in catalogcoord. Shape matches this object.

Notes

This method requires SciPy to be installed or it will fail.

match_to_catalog_sky(catalogcoord, nthneighbor=1)[source] [edit on github]

Finds the nearest on-sky matches of this coordinate in a set of catalog coordinates.

For more on how to use this (and related) functionality, see the examples in Separations, Catalog Matching, and Related Functionality.

Parameters:

catalogcoord : SkyCoord or BaseCoordinateFrame

The base catalog in which to search for matches. Typically this will be a coordinate object that is an array (i.e., catalogcoord.isscalar == False)

nthneighbor : int, optional

Which closest neighbor to search for. Typically 1 is desired here, as that is correct for matching one set of coordinates to another. The next likely use case is 2, for matching a coordinate catalog against itself (1 is inappropriate because each point will find itself as the closest match).

Returns:

idx : integer array

Indices into catalogcoord to get the matched points for each of this object’s coordinates. Shape matches this object.

sep2d : Angle

The on-sky separation between the closest match for each element in this object in catalogcoord. Shape matches this object.

dist3d : Quantity

The 3D distance between the closest match for each element in this object in catalogcoord. Shape matches this object.

Notes

This method requires SciPy to be installed or it will fail.

position_angle(other)[source] [edit on github]

Computes the on-sky position angle (East of North) between this SkyCoord and another.

Parameters:

other : SkyCoord

The other coordinate to compute the position angle to. It is treated as the “head” of the vector of the position angle.

Returns:

pa : Angle

The (positive) position angle of the vector pointing from self to other. If either self or other contain arrays, this will be an array following the appropriate numpy broadcasting rules.

Examples

>>> c1 = SkyCoord(0*u.deg, 0*u.deg)
>>> c2 = SkyCoord(1*u.deg, 0*u.deg)
>>> c1.position_angle(c2).degree
90.0
>>> c3 = SkyCoord(1*u.deg, 1*u.deg)
>>> c1.position_angle(c3).degree  
44.995636455344844
search_around_3d(searcharoundcoords, distlimit)[source] [edit on github]

Searches for all coordinates in this object around a supplied set of points within a given 3D radius.

This is inteded for use on SkyCoord objects with coordinate arrays, rather than a scalar coordinate. For a scalar coordinate, it is better to use separation_3d.

For more on how to use this (and related) functionality, see the examples in Separations, Catalog Matching, and Related Functionality.

Parameters:

searcharoundcoords : SkyCoord or BaseCoordinateFrame

The coordinates to search around to try to find matching points in this SkyCoord. This should be an object with array coordinates, not a scalar coordinate object.

distlimit : Quantity with distance units

The physical radius to search within.

Returns:

idxsearcharound : integer array

Indices into self that matches to the corresponding element of idxself. Shape matches idxself.

idxself : integer array

Indices into searcharoundcoords that matches to the corresponding element of idxsearcharound. Shape matches idxsearcharound.

sep2d : Angle

The on-sky separation between the coordinates. Shape matches idxsearcharound and idxself.

dist3d : Quantity

The 3D distance between the coordinates. Shape matches idxsearcharound and idxself.

Notes

This method requires SciPy (>=0.12.0) to be installed or it will fail.

In the current implementation, the return values are always sorted in the same order as the searcharoundcoords (so idxsearcharound is in ascending order). This is considered an implementation detail, though, so it could change in a future release.

search_around_sky(searcharoundcoords, seplimit)[source] [edit on github]

Searches for all coordinates in this object around a supplied set of points within a given on-sky separation.

This is inteded for use on SkyCoord objects with coordinate arrays, rather than a scalar coordinate. For a scalar coordinate, it is better to use separation.

For more on how to use this (and related) functionality, see the examples in Separations, Catalog Matching, and Related Functionality.

Parameters:

searcharoundcoords : SkyCoord or BaseCoordinateFrame

The coordinates to search around to try to find matching points in this SkyCoord. This should be an object with array coordinates, not a scalar coordinate object.

seplimit : Quantity with angle units

The on-sky separation to search within.

Returns:

idxsearcharound : integer array

Indices into self that matches to the corresponding element of idxself. Shape matches idxself.

idxself : integer array

Indices into searcharoundcoords that matches to the corresponding element of idxsearcharound. Shape matches idxsearcharound.

sep2d : Angle

The on-sky separation between the coordinates. Shape matches idxsearcharound and idxself.

dist3d : Quantity

The 3D distance between the coordinates. Shape matches idxsearcharound and idxself.

Notes

This method requires SciPy (>=0.12.0) to be installed or it will fail.

In the current implementation, the return values are always sorted in the same order as the searcharoundcoords (so idxsearcharound is in ascending order). This is considered an implementation detail, though, so it could change in a future release.

separation(other)[source] [edit on github]

Computes on-sky separation between this coordinate and another.

For more on how to use this (and related) functionality, see the examples in Separations, Catalog Matching, and Related Functionality.

Parameters:

other : SkyCoord or BaseCoordinateFrame

The coordinate to get the separation to.

Returns:

sep : Angle

The on-sky separation between this and the other coordinate.

Notes

The separation is calculated using the Vincenty formula, which is stable at all locations, including poles and antipodes [R4].

[R4]http://en.wikipedia.org/wiki/Great-circle_distance
separation_3d(other)[source] [edit on github]

Computes three dimensional separation between this coordinate and another.

For more on how to use this (and related) functionality, see the examples in Separations, Catalog Matching, and Related Functionality.

Parameters:

other : SkyCoord or BaseCoordinateFrame

The coordinate to get the separation to.

Returns:

sep : Distance

The real-space distance between these two coordinates.

Raises:

ValueError

If this or the other coordinate do not have distances.

to_pixel(wcs, origin=0, mode=u'all')[source] [edit on github]

Convert this coordinate to pixel coordinates using a WCS object.

Parameters:

wcs : WCS

The WCS to use for convert

origin : int

Whether to return 0 or 1-based pixel coordinates.

mode : ‘all’ or ‘wcs’

Whether to do the transformation including distortions ('all') or only including only the core WCS transformation ('wcs').

Returns:

xp, yp : numpy.ndarray

The pixel coordinates

See also

from_pixel
to do the inverse operation
astropy.wcs.utils.skycoord_to_pixel
the implementation of this method
to_string(style=u'decimal', **kwargs)[source] [edit on github]

A string representation of the coordinates.

The default styles definitions are:

'decimal': 'lat': {'decimal': True, 'unit': "deg"}
           'lon': {'decimal': True, 'unit': "deg"}
'dms': 'lat': {'unit': "deg"}
       'lon': {'unit': "deg"}
'hmsdms': 'lat': {'alwayssign': True, 'pad': True, 'unit': "deg"}
          'lon': {'pad': True, 'unit': "hour"}

See to_string() for details and keyword arguments (the two angles forming the coordinates are are both Angle instances). Keyword arguments have precedence over the style defaults and are passed to to_string().

Parameters:

style : {‘hmsdms’, ‘dms’, ‘decimal’}

The formatting specification to use. These encode the three most common ways to represent coordinates. The default is decimal.

kwargs

Keyword args passed to to_string().

transform_to(frame)[source] [edit on github]

Transform this coordinate to a new frame.

The frame attributes (e.g. equinox or obstime) for the returned object depend on the corresponding attributes of SkyCoord object and the supplied frame, with the following precedence:

  1. Non-default value in the supplied frame
  2. Non-default value in the SkyCoord instance
  3. Default value in the supplied frame
Parameters:

frame : str or BaseCoordinateFrame class / instance or SkyCoord instance

The frame to transform this coordinate into.

Returns:

coord : SkyCoord

A new object with this coordinate represented in the frame frame.

Raises:

ValueError

If there is no possible transformation route.

Page Contents