:py:mod:`coord_utils`
=====================

.. py:module:: coord_utils

.. autoapi-nested-parse::

   This module contains utility functions for dealing with sky coordinates,
   sky distances, and healpix grids.



Module Contents
---------------


Functions
~~~~~~~~~

.. autoapisummary::

   coord_utils.uniform_around
   coord_utils.upgrade_healpix
   coord_utils.get_distance
   coord_utils.get_healpix_centers
   coord_utils.get_padded_nside
   coord_utils.get_corners
   coord_utils.is_inside
   coord_utils.get_skycoord
   coord_utils.get_target_nside
   coord_utils.match
   coord_utils.sample_in_aperture



Attributes
~~~~~~~~~~

.. autoapisummary::

   coord_utils.TWO_PI


.. py:data:: TWO_PI

   

.. py:function:: uniform_around(centre, area, size)

   Uniform distribution of points around location.
   Draws randomly distributed points from a circular region of the given area
   around the centre point.

   Parameters
   ----------
   centre : `~astropy.coordinates.SkyCoord`
       Centre of the sampling region.
   area : `~astropy.units.Quantity`
       Area of the sampling region as a `~astropy.units.Quantity` in units of
       solid angle.
   size : int
       Number of points to draw.

   Returns
   -------
   coords : `~astropy.coordinates.SkyCoord`
       Randomly distributed points around the centre. The coordinates are
       returned in the same frame as the input.

   Examples
   --------
   See :ref:`User Documentation <skypy.position.uniform_around>`.
   Modified from the skypy implementation: https://github.com/skypyproject/skypy



.. py:function:: upgrade_healpix(pix_id, nested, nside_in, nside_out)

   Upgrade (superresolve) a healpix into finer ones

   Parameters
   ----------
   pix_id : int
       coarse healpix ID to upgrade
   nested : bool
       whether `pix_id` is given in NESTED scheme
   nside_in : int
       NSIDE of `pix_id`
   nside_out : int
       desired NSIDE of finer healpix

   Returns
   -------
   np.array
       the upgraded healpix IDs in the NESTED scheme



.. py:function:: get_distance(ra_i, dec_i, ra_f, dec_f)

   Compute the distance between two angular positions given in degrees

       


.. py:function:: get_healpix_centers(pix_id, nside, nest)

   Get the ra, dec corresponding to centers of the healpixels with given IDs

   Parameters
   ----------
   pix_id : int or array-like
       IDs of healpixels to evaluate centers. Must be in NESTED scheme
   nside_in : int
       NSIDE of `pix_id`



.. py:function:: get_padded_nside(padding, nside_in)

   Get the maximum nside (finest healpix grid) whose centers along
   the boundary of the input nside are located sufficiently far away
   from the boundaries

   Parameters
   ----------
   padding : float
       Padding in arcmin
   nside_in : int
       NSIDE of the healpix to upgrade


.. py:function:: get_corners(n_pix, counterclockwise=False)

   Get the indices of corners of a set of finer healpixes making up
   a big healpix, e.g. the output of `upgrade_healpix`

   Parameters
   ----------
   n_pix : int
       Number of finer healpixes
   clockwise: bool
       Ordering of the corners are counterclockwise. If False,
       ordering follows healpix ordering. Default: False

   Returns
   -------
   list
       Indices of four corners that can be used
       to slice a list of RA, Dec



.. py:function:: is_inside(ra, dec, ra_bounds, dec_bounds)

   Get the boolean mask for whether points are inside provided bounds

   Parameters
   ----------
   ra : np.ndarray
       RA of candidate positions, of shape [N,]
   dec : np.ndarray
       Dec of candidate positions, of shape [N,]
   ra_bounds : np.ndarray
       RA of bounds, of shape [4,]
   dec_bounds : np.ndarray
       Dec of bounds, of shape [4,]

   Returns
   -------
   np.ndarray
       Boolean mask over ra, dec, whose elements are true if corresponding
       points are inside bounds



.. py:function:: get_skycoord(ra, dec)

   Create an astropy.coordinates.SkyCoord object

   Parameters
   ----------
   ra : np.array
       RA in deg
   dec : np.array
       dec in deg



.. py:function:: get_target_nside(n_pix, nside_in=2**5)

   Get the NSIDE corresponding to the number of sub-healpixels

   Parameters
   ----------
   n_pix : int
       desired number of pixels
   nside_in : int
       input NSIDE to subsample



.. py:function:: match(ra_grid, dec_grid, ra_cat, dec_cat, threshold)

   Match gridpoints to a catalog based on distance threshold

   Parameters
   ----------
   ra_grid : np.array
   dec_grid : np.array
   ra_cat : np.array
   dec_cat : np.array
   gridpoints : astropy.SkyCoord instance
   threshold : float
       matching distance threshold in deg
   extra_constraint : np.array of type bool
       another set of constraints, aside from separation constraint. Ordering
       must be based on gridpoints

   Returns
   -------
   sep_constraint : np.array of shape same as ra/dec_grid and type bool
       whether each gridpoint was matched to a catalog within sep limit
   passing_i_cat : np.array of length same as ra_grid[sep_constraint]
       catalog idx (value) corresponding to each successfully matched
       gridpoint (position)
   passing_dist : np.array of shape same as passing_i_cat
       distance (value) corresponding to each successfully matched gridpoint
       (position)



.. py:function:: sample_in_aperture(N, radius)

   Uniformly sample points around a zero coordinate on the celestial sphere
   and translate to cartesian coordinates

   Parameters
   ----------
   radius : float
       Aperture radius in deg

   Returns
   -------
   tuple
       (RA, dec) of the angular offsets in deg