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_type='cartesian' (for example) along with data in x, y, and z.

See also: https://docs.astropy.org/en/stable/coordinates/

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], frame="icrs", unit="deg")  # 3 coords

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

>>> c = SkyCoord("1h12m43.2s +1d12m43s", frame=Galactic)  # Units from string
>>> c = SkyCoord(frame="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(frame=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_type='cartesian')

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

Velocity components (proper motions or radial velocities) can also be provided in a similar manner:

>>> c = SkyCoord(ra=1*u.deg, dec=2*u.deg, radial_velocity=10*u.km/u.s)

>>> c = SkyCoord(ra=1*u.deg, dec=2*u.deg, pm_ra_cosdec=2*u.mas/u.yr, pm_dec=1*u.mas/u.yr)

As shown, the frame can be a ~astropy.coordinates.BaseCoordinateFrame class or the corresponding string alias – lower-case versions of the class name that allow for creating a |SkyCoord| object and transforming frames without explicitly importing the frame classes.

Parameters¶

frame~astropy.coordinates.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~astropy.units.Unit, string, or tuple of Unit or str, optional

Units for supplied coordinate values. If only one unit is supplied then it applies to all values. Note that passing only one unit might lead to unit conversion errors if the coordinate values are expected to have mixed physical meanings (e.g., angles and distances).

obstimetime-like, optional

Time(s) of observation.

equinoxtime-like, optional

Coordinate frame equinox time.

representation_typestr 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.

copybool, optional

If True (default), a copy of any coordinate data is made. This argument can only be passed in as a keyword argument.

**keyword_args

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

ra, decangle-like, 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.

pm_ra_cosdec, pm_dec~astropy.units.Quantity [‘angular speed’], optional

Proper motion components, in angle per time units.

l, bangle-like, 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.

pm_l_cosb, pm_b~astropy.units.Quantity [‘angular speed’], optional

Proper motion components in the ~astropy.coordinates.Galactic frame, in angle per time units.

x, y, zfloat or ~astropy.units.Quantity [‘length’], optional

Cartesian coordinates values

u, v, wfloat or ~astropy.units.Quantity [‘length’], optional

Cartesian coordinates values for the Galactic frame.

radial_velocity~astropy.units.Quantity [‘speed’], optional

The component of the velocity along the line-of-sight (i.e., the radial direction), in velocity units.

Public members¶

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.

SkyCoord(*args, copy=True, **kwargs)

Initialize self. See help(type(self)) for accurate signature.

__eq__(value)

Equality operator for SkyCoord

__ne__(value)

Return self!=value.

__setitem__(item, value)

Implement self[item] = value for SkyCoord

insert(obj, values, axis=0)

Insert coordinate values before the given indices in the object and return a new Frame object.

is_transformable_to(new_frame)

Determines if this coordinate frame can be transformed to another given frame.

transform_to(frame, merge_attributes=True)

Transform this coordinate to a new frame.

apply_space_motion(new_obstime=None, dt=None)

Compute the position of the source represented by this coordinate object to a new time using the velocities stored in this object and assuming linear space motion (including relativistic corrections). This is sometimes referred to as an “epoch transformation.”

__getattr__(attr)

Overrides getattr to return coordinates that this can be transformed to, based on the alias attr in the primary transform graph.

__setattr__(attr, val)

Implement setattr(self, name, value).

__delattr__(attr)

Implement delattr(self, name).

__dir__()

Override the builtin dir behavior to include: - Transforms available by aliases - Attribute / methods of the underlying self.frame object

__repr__()

Return repr(self).

to_string(style='decimal', **kwargs)

A string representation of the coordinates.

to_table()

Convert this |SkyCoord| to a |QTable|.

is_equivalent_frame(other)

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

separation(other)

Computes on-sky separation between this coordinate and another.

separation_3d(other)

Computes three dimensional separation between this coordinate and another.

spherical_offsets_to(tocoord)

Computes angular offsets to go from this coordinate to another.

spherical_offsets_by(d_lon, d_lat)

Computes the coordinate that is a specified pair of angular offsets away from this coordinate.

directional_offset_by(position_angle, separation)

Computes coordinates at the given offset from this coordinate.

match_to_catalog_sky(catalogcoord, nthneighbor=1)

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

match_to_catalog_3d(catalogcoord, nthneighbor=1)

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

search_around_sky(searcharoundcoords, seplimit)

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

search_around_3d(searcharoundcoords, distlimit)

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

position_angle(other)

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

skyoffset_frame(rotation=None)

Returns the sky offset frame with this SkyCoord at the origin.

get_constellation(short_name=False, constellation_list='iau')

Determines the constellation(s) of the coordinates this SkyCoord contains.

to_pixel(wcs, origin=0, mode='all')

Convert this coordinate to pixel coordinates using a ~astropy.wcs.WCS object.

classmethod from_pixel(xp, yp, wcs, origin=0, mode='all')

Create a new SkyCoord from pixel coordinates using a World Coordinate System.

contained_by(wcs, image=None, **kwargs)

Determines if the SkyCoord is contained in the given wcs footprint.

radial_velocity_correction(kind='barycentric', obstime=None, ...)

Compute the correction required to convert a radial velocity at a given time and place on the Earth’s Surface to a barycentric or heliocentric velocity.

classmethod guess_from_table(table, **coord_kwargs)

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

classmethod from_name(name, frame='icrs', parse=False, cache=True)

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 ~astropy.coordinates.get_icrs_coordinates for more information.

__bool__()

Any instance should evaluate to True, except when it is empty.

__getitem__(item)

__array_function__(function, types, args, kwargs)

Wrap numpy functions that make sense.

copy(*args, **kwargs)

Return an instance containing copies of the internal data.

reshape(*args, **kwargs)

Returns an instance containing the same data with a new shape.

ravel(*args, **kwargs)

Return an instance with the array collapsed into one dimension.

flatten(*args, **kwargs)

Return a copy with the array collapsed into one dimension.

transpose(*args, **kwargs)

Return an instance with the data transposed.

swapaxes(*args, **kwargs)

Return an instance with the given axes interchanged.

diagonal(*args, **kwargs)

Return an instance with the specified diagonals.

squeeze(*args, **kwargs)

Return an instance with single-dimensional shape entries removed

take(indices, axis=None, out=None, mode='raise')

Return a new instance formed from the elements at the given indices.

Properties¶

property frame

property representation_type

property representation

property shape

The shape of the underlying data.

property ndim

The number of dimensions of the instance and underlying arrays.

property size

The size of the object, as calculated from its shape.

property isscalar

property T

Return an instance with the data transposed.