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 viaSkyCoord.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 inx
,y
, andz
.Parameters: frame :
BaseCoordinateFrame
class or string, optionalType of coordinate frame this
SkyCoord
should represent. Defaults to to ICRS if not given or given as None.unit :
Unit
, string, or tuple ofUnit
or str, optionalUnits for supplied
LON
andLAT
values, respectively. If only one unit is supplied then it applies to bothLON
andLAT
.obstime : valid
Time
initializer, optionalTime of observation
equinox : valid
Time
initializer, optionalCoordinate 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
anddec
are keys in the frame’srepresentation_component_names
, includingICRS
,FK5
,FK4
, andFK4NoETerms
.- l, b : valid
Angle
initializer, optional Galactic
l
andb
for for frames wherel
andb
are keys in the frame’srepresentation_component_names
, including theGalactic
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 areICRS
,FK5
,FK4
,FK4NoETerms
, andGalactic
. The string aliases are simply lower-case versions of the class name, and allow for creating aSkyCoord
object and transforming frames without explicitly importing the frame classes.Attributes Summary
frame
info
Container for meta information like name, description, format. 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 anWCS
object.get_constellation
([short_name, ...])Determines the constellation(s) of the coordinates this SkyCoord
contains.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
¶
-
info
¶ Container for meta information like name, description, format. This is required when the object is used as a mixin column within a table, but can be used as a general way to store meta information.
-
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 forget_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 instanceThe 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 anWCS
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
andyp
.See also
to_pixel
- to do the inverse operation
astropy.wcs.utils.pixel_to_skycoord
- the implementation of this method
-
get_constellation
(short_name=False, constellation_list=u'iau')[source] [edit on github]¶ Determines the constellation(s) of the coordinates this
SkyCoord
contains.Parameters: short_name : bool
If True, the returned names are the IAU-sanctioned abbreviated names. Otherwise, full names for the constellations are used.
constellation_list : str
The set of constellations to use. Currently only
'iau'
is supported, meaning the 88 “modern” constellations endorsed by the IAU.Returns: constellation : str or string array
If this is a scalar coordinate, returns the name of the constellation. If it is an array
SkyCoord
, it returns an array of names.Notes
To determine which constellation a point on the sky is in, this first precesses to B1875, and then uses the Delporte boundaries of the 88 modern constellations, as tabulated by Roman 1987.
-
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 asra
attributes forICRS
frames, but'RAJ2000'
or'radius'
are not. Similarly, the second rule applied to theGalactic
frame means that a column named'gal_l'
will be used as the thel
component, butgall
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 aSkyCoord
or aBaseCoordinateFrame
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 thecatalogcoord
object.For more on how to use this (and related) functionality, see the examples in Separations, Catalog Matching, and Related Functionality.
Parameters: catalogcoord :
SkyCoord
orBaseCoordinateFrame
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 is2
, 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
orBaseCoordinateFrame
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 is2
, 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
toother
. If eitherself
orother
contain arrays, this will be an array following the appropriatenumpy
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 intended for use on
SkyCoord
objects with coordinate arrays, rather than a scalar coordinate. For a scalar coordinate, it is better to useseparation_3d
.For more on how to use this (and related) functionality, see the examples in Separations, Catalog Matching, and Related Functionality.
Parameters: searcharoundcoords :
SkyCoord
orBaseCoordinateFrame
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 unitsThe physical radius to search within.
Returns: idxsearcharound : integer array
Indices into
self
that matches to the corresponding element ofidxself
. Shape matchesidxself
.idxself : integer array
Indices into
searcharoundcoords
that matches to the corresponding element ofidxsearcharound
. Shape matchesidxsearcharound
.sep2d :
Angle
The on-sky separation between the coordinates. Shape matches
idxsearcharound
andidxself
.dist3d :
Quantity
The 3D distance between the coordinates. Shape matches
idxsearcharound
andidxself
.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
(soidxsearcharound
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 intended for use on
SkyCoord
objects with coordinate arrays, rather than a scalar coordinate. For a scalar coordinate, it is better to useseparation
.For more on how to use this (and related) functionality, see the examples in Separations, Catalog Matching, and Related Functionality.
Parameters: searcharoundcoords :
SkyCoord
orBaseCoordinateFrame
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 unitsThe on-sky separation to search within.
Returns: idxsearcharound : integer array
Indices into
self
that matches to the corresponding element ofidxself
. Shape matchesidxself
.idxself : integer array
Indices into
searcharoundcoords
that matches to the corresponding element ofidxsearcharound
. Shape matchesidxsearcharound
.sep2d :
Angle
The on-sky separation between the coordinates. Shape matches
idxsearcharound
andidxself
.dist3d :
Quantity
The 3D distance between the coordinates. Shape matches
idxsearcharound
andidxself
.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
(soidxsearcharound
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
orBaseCoordinateFrame
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
orBaseCoordinateFrame
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
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 bothAngle
instances). Keyword arguments have precedence over the style defaults and are passed toto_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:- Non-default value in the supplied frame
- Non-default value in the SkyCoord instance
- Default value in the supplied frame
Parameters: frame : str or
BaseCoordinateFrame
class / instance orSkyCoord
instanceThe 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.
- ra, dec : valid