API/Reference

The supertype for all sky coordinate systems.

ICRSCoords(ra, dec)

International Celestial Reference System

This is the current standard adopted by the International Astronomical Union notably due to its high level of accuracy compared to standard equatorial coordinate systems. What sets this apart from FK5Coords is that it is completely defined using extragalactic radio sources rather than a geocentric frame, which means the reference frame will not change due to Earth's motion.

Coordinates

• ra - Right ascension in radians (0, 2π)
• dec - Declination in radians (-π/2, π/2)

GalCoords(l, b)

Galactic Coordinate System

This coordinate system is defined based on the projection of the Milky Way galaxy onto our celestial sphere, with (0, 0) being approximately the center of our galaxy.

Coordinates

• l - Galactic longitude in radians (-π, π)
• b - Galactic latitude in radians (-π/2, π/2)

SuperGalCoords(l, b)

Supergalactic Coordinate System

The supergalactic plane is part of a reference frame for the supercluster of galaxies that contains the Milky Way galaxy. The supergalactic plane as so-far observed is more or less perpendicular to the plane of the Milky Way, the angle is 84.5 degrees. Viewed from the Earth, the plane traces a great circle across the sky through the constellations

Coordinates

• l - SuperGalCoords longitude in radians (-π, π)
• b - SuperGalCoords latitude in radians (-π/2, π/2)

FK5Coords{equinox}(ra, dec)

Equatorial Coordinate System

This coordinate system maps the celestial sphere based on a geocentric observer. Historically the oldest, this coordinate system has been shown to be inaccurate due to its definitions based on the Earth, which has long-scale precession causing the reference frame to change. Because of this, an equinox must be provided (typically 2000, commonly known as J2000) which defines the reference frame.

Coordinates

• ra - Right ascension in radians (0, 2π)
• dec - Declination in radians (-π/2, π/2)

EclipticCoords{equinox}(lon, lat)

Ecliptic Coordinate System

This coordinate system is geocentric with the ecliptic plane as the xy-plane with x oriented according to the equinox specified by equinox.

Coordinates

• lon - Longitude in radians (0, 2π)
• lat - Latitude in radians (-π/2, π/2)

match(refcoords::AbstractArray{<:AbstractSkyCoords}, 
      matchcoords::AbstractArray{<:AbstractSkyCoords};
      nthneighbor::Int = 1)

Requires Julia ≥ 1.9 and NearestNeighbors.jl to be loaded (e.g., using NearestNeighbors).

Finds the nearest entries in refcoords to the coordinates contained in matchcoords. The keyword argument nthneighbor determines which nearest neighbor to search for; typically this should be 1 when matching one set of coordinates to another. Another common use case is setting nthneighbor = 2 when matching a catalog against itself to find the nearest neighbor of each coordinate in the same catalog.

Returns (id, sep), where

• id is an array containing indices of the coordinates in refcoords that matched with the elements of matchcoords, and
• sep is an array giving the angular separation between the elements of matchcoords and the above matches.

Note that this method creates a KDTree from refcoords and then calls the method below. If you plan to use the same refcoords to match to many different matchcoords, then you should directly construct KDTree(refcoords) and call the method below.

match(tree::KDTree, matchcoords::AbstractArray{<:AbstractSkyCoords};
      nthneighbor::Int = 1)

As above, but uses a pre-constructed tree::KDTree rather than creating one from a reference catalog of coordinates.

KDTree(data::AbstractArray{<:AbstractSkyCoords}; kws...)

Requires Julia ≥ 1.9 and NearestNeighbors.jl to be loaded (e.g., using NearestNeighbors).

Construct a KDTree from NearestNeighbors.jl. The provided data are used to construct the tree, and the kws... are passed to NearestNeighbors.KDTree. An internal Cartesian coordinate representation is used, with a standard coordinate representation of CartesianCoords{ICRSCoords}. Coordinate conversions are applied automatically in the following methods, which extend those from NearestNeighbors.jl.

• nn(tree::KDTree, coord::AbstractSkyCoords) queries the tree for the entry nearest the provided coord.
• nn(tree::KDTree, coords::AbstractArray{<:AbstractSkyCoords}) queries the tree for the entry nearest each coordinate in coords.
• knn(tree::KDTree, coord::AbstractSkyCoords, k::Int) queries the tree for the k coordinates nearest the provided coord.
• knn(tree::KDTree, coords::AbstractArray{<:AbstractSkyCoords}, k::Int) queries the tree for the k coordinates nearest each coordinate in coords.

nn(tree::KDTree, coord::AbstractSkyCoords)

Requires Julia ≥ 1.9 and NearestNeighbors.jl to be loaded (e.g., using NearestNeighbors).

Queries the tree for the nearest entry to the provided coord. Returns the index into the tree of the nearest entry and the angular separation between the two coordinates, in radians.

nn(tree::KDTree, coords::AbstractArray{<:AbstractSkyCoords})

Returns arrays (id, sep) containing the indices and angular separations (in radians) of the closest entries in tree for each coordinate in coords.

knn(tree::KDTree, coord::AbstractSkyCoords, 
    k::Int, sortres::Bool = false)

Requires Julia ≥ 1.9 and NearestNeighbors.jl to be loaded (e.g., using NearestNeighbors).

Queries the tree for the k nearest entries to the provided coord. Returns vectors (id, sep), which, respectively, contain the indices into the tree of the k nearest entries, and the angular separations between coord and the k nearest entries, in radians. If sortres is true, the returned neighbors are sorted by separation.

knn(tree::KDTree, coords::AbstractArray{<:AbstractSkyCoords}, k::Int, sortres::Bool = false)

Returns arrays (id, sep) containing vectors of indices and angular separations (in radians) of the k closest entries in tree for each coordinate in coords. If sortres is true, the returned neighbors are sorted by separation.

inrange(tree::KDTree, coord::AbstractSkyCoords, seplim::Number)

Requires Julia ≥ 1.9 and NearestNeighbors.jl to be loaded (e.g., using NearestNeighbors).

Searches for coordinates in the tree with angular separations from coord less than seplim, which must be given in radians. If tree = KDTree(data), returns indices into data.

inrange(tree::KDTree, coords::AbstractArray{<:AbstractSkyCoords}, seplim::Number)

For each coordinate in coords, finds coordinates in tree that lie within seplim radians.

separation(c1::AbstractSkyCoords, c2::AbstractSkyCoords) -> distance

Return angular separation between two sky coordinates, in radians.

The angular separation is calculated using the Vincenty formula, which is slightly more complex and computationally expensive than some alternatives, but is stable at at all distances, including the poles and antipodes.

position_angle(c1::AbstractSkyCoords, c2::AbstractSkyCoords) -> angle

Return position angle between two sky coordinates, in positive radians.

Examples

julia> c1 = ICRSCoords(0, 0); c2 = ICRSCoords(deg2rad(1), 0);

julia> position_angle(c1, c2) |> rad2deg
90.0

offset(::AbstractSkyCoords, separation, pa) -> coordinate

Offset a coordinate by a given angular separation, separation, in radians and position angle, pa, in radians.

Uses the sine and cosine rules in spherical coordinates with corrections for the antipodes. Returns a sky coordinate of the same type as input.

Examples

julia> c1 = ICRSCoords(0, 0);

julia> c2 = offset(c1, deg2rad(1), deg2rad(90))
ICRSCoords{Float64}(0.017453292519943295, 1.0686516840418957e-18)

julia> offset(c1, c2) .|> rad2deg
(1.0, 90.0)

See Also

• separation, position_angle

offset(::AbstractSkyCoords, AbstractSkyCoords) -> angle, angle

Return the separation and position angle in radians between two sky coordinates.

Examples

julia> c1 = ICRSCoords(0, 0); c2 = ICRSCoords(deg2rad(1), 0);

julia> offset(c1, c2) .|> rad2deg
(1.0, 90.0)

See Also

• separation, position_angle