sourcefinder.utility.coordinates ================================ .. py:module:: sourcefinder.utility.coordinates .. autoapi-nested-parse:: General purpose astronomical coordinate handling routines. .. !! processed by numpydoc !! Attributes ---------- .. autoapisummary:: sourcefinder.utility.coordinates.CORE_LAT sourcefinder.utility.coordinates.CORE_LON sourcefinder.utility.coordinates.ITRF_X sourcefinder.utility.coordinates.ITRF_Y sourcefinder.utility.coordinates.ITRF_Z sourcefinder.utility.coordinates.SECONDS_IN_DAY sourcefinder.utility.coordinates.SECONDS_IN_HOUR sourcefinder.utility.coordinates.logger sourcefinder.utility.coordinates.unix_epoch Classes ------- .. autoapisummary:: sourcefinder.utility.coordinates.CoordSystem sourcefinder.utility.coordinates.WCS Functions --------- .. autoapisummary:: sourcefinder.utility.coordinates.alpha sourcefinder.utility.coordinates.alpha_inflate sourcefinder.utility.coordinates.alphasep sourcefinder.utility.coordinates.altaz sourcefinder.utility.coordinates.angsep sourcefinder.utility.coordinates.angsep_vectorized sourcefinder.utility.coordinates.cmp sourcefinder.utility.coordinates.cmp_jitted sourcefinder.utility.coordinates.convert_coordsystem sourcefinder.utility.coordinates.coordsystem sourcefinder.utility.coordinates.dectodms sourcefinder.utility.coordinates.delta sourcefinder.utility.coordinates.deltasep sourcefinder.utility.coordinates.dmstodec sourcefinder.utility.coordinates.eq_to_cart sourcefinder.utility.coordinates.eq_to_gal sourcefinder.utility.coordinates.gal_to_eq sourcefinder.utility.coordinates.hmstora sourcefinder.utility.coordinates.jd2lst sourcefinder.utility.coordinates.julian2unix sourcefinder.utility.coordinates.julian_date sourcefinder.utility.coordinates.l sourcefinder.utility.coordinates.lm_to_radec sourcefinder.utility.coordinates.m sourcefinder.utility.coordinates.mjd2datetime sourcefinder.utility.coordinates.mjd2lst sourcefinder.utility.coordinates.mjds2lst sourcefinder.utility.coordinates.propagate_sign sourcefinder.utility.coordinates.radec_to_lmn sourcefinder.utility.coordinates.ratohms sourcefinder.utility.coordinates.sec2days sourcefinder.utility.coordinates.sec2deg sourcefinder.utility.coordinates.sec2hms sourcefinder.utility.coordinates.unix2julian Module Contents --------------- .. py:class:: CoordSystem A container for constant strings representing different coordinate systems. .. !! processed by numpydoc !! .. py:attribute:: FK4 :value: 'B1950 (FK4)' .. py:attribute:: FK5 :value: 'J2000 (FK5)' .. py:class:: WCS Wrapper around pywcs.WCS. This is primarily to preserve API compatibility with the earlier, home-brewed python-wcslib wrapper. It includes: * A fix for the reference pixel lying at the zenith; * Raises ValueError if coordinates are invalid. .. !! processed by numpydoc !! .. py:method:: all_p2s(array_of_pixpos) Vectorized pixel to spatial coordinate conversion, making use of all_pix2world from astropy. This will save time when thousands of sources are detected. :Parameters: **array_of_pixpos** : ndarray A (N, 2) array where each row represents [x, y] pixel positions. :Returns: ndarray A (N, 2) array where each row contains: - Right ascension (float) in decimal degrees. - Declination (float) in decimal degrees. .. !! processed by numpydoc !! .. py:method:: p2s(pixpos) Convert pixel coordinates to spatial coordinates. This function converts a given pixel position (x, y) into spatial coordinates (right ascension and declination). :Parameters: **pixpos** : list or tuple A list or tuple of two floats containing the pixel position as [x, y]. :Returns: **ra** : float Right ascension corresponding to the pixel position in decimal degrees. **dec** : float Declination corresponding to the pixel position in decimal degrees. .. !! processed by numpydoc !! .. py:method:: s2p(spatialpos) Convert spatial coordinates to pixel coordinates. This function converts a given spatial position (right ascension and declination) into pixel coordinates (x, y). :Parameters: **spatialpos** : tuple[float, float] A tuple containing: - ra (float): Right ascension in decimal degrees. - dec (float): Declination in decimal degrees. :Returns: **x** : float X pixel value corresponding to the spatial position. **y** : float Y pixel value corresponding to the spatial position. .. !! processed by numpydoc !! .. py:attribute:: ORIGIN :value: 1 .. py:attribute:: WCS_ATTRS :value: ('crpix', 'cdelt', 'crval', 'ctype', 'cunit', 'crota') .. py:attribute:: wcs .. py:function:: alpha(l, m, alpha0, delta0) Convert a coordinate in l, m into a coordinate in RA. :Parameters: **l** : float Direction cosine along the l-axis, given by offset in cells times cell size (in radians). **m** : float Direction cosine along the m-axis, given by offset in cells times cell size (in radians). **alpha0** : float Right ascension of the centre of the field, in decimal degrees. **delta0** : float Declination of the centre of the field, in decimal degrees. :Returns: float Right Ascension (RA) in decimal degrees. .. !! processed by numpydoc !! .. py:function:: alpha_inflate(theta, decl) Compute the RA expansion for a given theta at a given declination. :Parameters: **theta** : float Angular distance from the center, in decimal degrees. **decl** : float Declination of the source, in decimal degrees. :Returns: float RA inflation in decimal degrees. .. rubric:: Notes For a derivation, see MSR TR 2006 52, Section 2.1: http://research.microsoft.com/apps/pubs/default.aspx?id=64524 .. !! processed by numpydoc !! .. py:function:: alphasep(ra1, ra2, dec1, dec2) Find the angular separation of two sources in RA, in arcseconds. :Parameters: **ra1** : float Right ascension of the first source, in decimal degrees. **ra2** : float Right ascension of the second source, in decimal degrees. **dec1** : float Declination of the first source, in decimal degrees. **dec2** : float Declination of the second source, in decimal degrees. :Returns: float Angular separation in RA, in arcseconds. .. !! processed by numpydoc !! .. py:function:: altaz(mjds, ra, dec, lat=CORE_LAT) Calculate the azimuth and elevation of a source from time and position on the sky. :Parameters: **mjds** : float Modified Julian Date in seconds. **ra** : float Right Ascension of the source in degrees. **dec** : float Declination of the source in degrees. **lat** : float, default : CORE_LAT Latitude of the observer in degrees. :Returns: hrz_altitude: float Altitude of the source in degrees. hrz_azimuth :float Azimuth of the source in degrees. .. !! processed by numpydoc !! .. py:function:: angsep(ra1, dec1, ra2, dec2) Find the angular separation of two sources, in arcseconds, using the proper spherical trigonometry formula. :Parameters: **ra1** : float Right Ascension of the first source, in decimal degrees. **dec1** : float Declination of the first source, in decimal degrees. **ra2** : float Right Ascension of the second source, in decimal degrees. **dec2** : float Declination of the second source, in decimal degrees. :Returns: float Angular separation between the two sources, in arcseconds. .. !! processed by numpydoc !! .. py:function:: angsep_vectorized(ra_dec1, ra_dec2, angular_separation) Find the angular separation of two sources, in arcseconds, using the proper spherical trigonometry formula. :Parameters: **ra_dec1** : ndarray RA and Dec of the first source, in decimal degrees. **ra_dec2** : ndarray RA and Dec of the second source, in decimal degrees. **angular_separation** : float Angular separation between the two sources, in arcseconds. This value is assigned within the function due to the guvectorize decorator. :Returns: None The result is stored in the `angular_separation` parameter. .. !! processed by numpydoc !! .. py:function:: cmp(a, b) Compare two values and return an integer indicating their relationship. :Parameters: **a** : Any The first value to compare. **b** : Any The second value to compare. :Returns: int 1 if `a` is greater than `b`, -1 if `a` is less than `b`, and 0 if they are equal. .. !! processed by numpydoc !! .. py:function:: cmp_jitted(a, b) Compare two values and return an integer indicating their relationship. :Parameters: **a** : Any The first value to compare. **b** : Any The second value to compare. :Returns: int 1 if `a` is greater than `b`, -1 if `a` is less than `b`, and 0 if they are equal. .. !! processed by numpydoc !! .. py:function:: convert_coordsystem(ra, dec, insys, outsys) Convert RA & dec (given in decimal degrees) between equinoxes. This function takes right Ascension (RA) and declination (Dec) coordinates in decimal degrees and converts them between different equinoxes, such as B1950 and J2000. The input and output equinoxes are specified as parameters. :Parameters: **ra** : float Right ascension in decimal degrees. **dec** : float Declination in decimal degrees. **insys** : str Input equinox, e.g., 'B1950' or 'J2000'. **outsys** : str Output equinox, e.g., 'B1950' or 'J2000'. :Returns: **ra** : float Converted right ascension in decimal degrees. **dec** : float Converted declination in decimal degrees. :Raises: Exception If the input or output equinox is unknown. .. !! processed by numpydoc !! .. py:function:: coordsystem(name) Given a string, return a constant from class CoordSystem. :Parameters: **name** : str The name of the coordinate system (e.g., 'j2000', 'fk5', 'b1950', 'fk4'). :Returns: str A constant from the CoordSystem class representing the coordinate system. :Raises: KeyError If the provided name does not match any known coordinate system. .. !! processed by numpydoc !! .. py:function:: dectodms(decdegs) Convert Declination in decimal degrees format to hours, minutes, seconds format. :Parameters: **decdegs** : float Declination in decimal degrees format. :Returns: **hours** : int .. **minutes** : int .. **seconds** : float .. .. !! processed by numpydoc !! .. py:function:: delta(l, m, delta0) Convert a coordinate in l, m into a coordinate in declination. :Parameters: **l** : float Direction cosine along the l-axis, given by offset in cells times cell size (in radians). **m** : float Direction cosine along the m-axis, given by offset in cells times cell size (in radians). **delta0** : float Declination of the center of the field, in decimal degrees. :Returns: float Declination in decimal degrees. .. !! processed by numpydoc !! .. py:function:: deltasep(dec1, dec2) Find the angular separation of two sources in declination, in arcseconds. :Parameters: **dec1** : float Declination of the first source, in decimal degrees. **dec2** : float Declination of the second source, in decimal degrees. :Returns: float Angular separation in declination, in arcseconds. .. !! processed by numpydoc !! .. py:function:: dmstodec(decd, decm, decs) Convert Dec in degrees, minutes, seconds format to decimal degrees format. :Parameters: **decd** : int Degrees component of the Declination. **decm** : int Minutes component of the Declination. **decs** : float Seconds component of the Declination. :Returns: float Declination in decimal degrees. .. !! processed by numpydoc !! .. py:function:: eq_to_cart(ra, dec) Find the cartesian coordinates on the unit sphere given the equatorial coordinates. :Parameters: **ra** : float Right ascension (RA) in decimal degrees. **dec** : float Declination (Dec) in decimal degrees. :Returns: **x** : float Cartesian x-coordinate. **y** : float Cartesian y-coordinate. **z** : float Cartesian z-coordinate. .. !! processed by numpydoc !! .. py:function:: eq_to_gal(ra, dec) Find the Galactic coordinates of a source given the equatorial coordinates. :Parameters: **ra** : float Right ascension (RA) in decimal degrees. **dec** : float Declination (Dec) in decimal degrees. :Returns: **lon_l** : float Galactic longitude in decimal degrees. **lat_b** : float Galactic latitude in decimal degrees. .. !! processed by numpydoc !! .. py:function:: gal_to_eq(lon_l, lat_b) Find the equatorial coordinates of a source given the Galactic coordinates. :Parameters: **lon_l** : float Galactic longitude in decimal degrees. **lat_b** : float Galactic latitude in decimal degrees. :Returns: **ra** : float Right ascension (RA) in decimal degrees. **dec** : float Declination (Dec) in decimal degrees. .. !! processed by numpydoc !! .. py:function:: hmstora(rah, ram, ras) Convert RA in hours, minutes, seconds format to decimal degrees format. :Parameters: **rah** : float Right Ascension hours. **ram** : float Right Ascension minutes. **ras** : float Right Ascension seconds. :Returns: float RA in decimal degrees. .. !! processed by numpydoc !! .. py:function:: jd2lst(jd, position=None) Converts a Julian Date into Local Apparent Sidereal Time in seconds at a given position. If position is None, we default to the reference position of CS002. :Parameters: **jd** : float Julian Date to be converted. **position** : casacore measure, default: None Position for Local Sidereal Time calculations. :Returns: float Local Apparent Sidereal Time in seconds. .. !! processed by numpydoc !! .. py:function:: julian2unix(timestamp) Convert a modified Julian timestamp (number of seconds since 17 November 1858) to Unix timestamp (number of seconds since 1 January 1970). :Parameters: **timestamp** : numbers.Number Number of seconds since the Unix epoch. :Returns: numbers.Number Number of seconds since the modified Julian epoch. .. !! processed by numpydoc !! .. py:function:: julian_date(time=None, modified=False) Calculate the Julian date at a given timestamp. :Parameters: **time** : datetime.datetime, default: None Timestamp to calculate JD for. If not provided, the current UTC time will be used. **modified** : bool, default: False If True, return the Modified Julian Date, which is the number of days (including fractions) that have elapsed between the start of 17 November 1858 AD and the specified time. :Returns: float Julian date value. .. !! processed by numpydoc !! .. py:function:: l(ra, dec, cra, incr) Convert a coordinate in RA, Dec into a direction cosine l. :Parameters: **ra** : float Right ascension of the source, in decimal degrees. **dec** : float Declination of the source, in decimal degrees. **cra** : float Right ascension of the centre of the field, in decimal degrees. **incr** : float Number of degrees per pixel (negative in the case of RA). :Returns: float Direction cosine l. .. !! processed by numpydoc !! .. py:function:: lm_to_radec(ra0, dec0, l, m) Find the l direction cosine of a source in a radio image, given the RA and Dec of the field centre. :Parameters: **ra0** : float Right ascension of the field center, in decimal degrees. **dec0** : float Declination of the field center, in decimal degrees. **l** : float Direction cosine of the source along the l-axis. **m** : float Direction cosine of the source along the m-axis. :Returns: **ra** : float Right ascension in decimal degrees. **dec** : float Declination in decimal degrees. .. rubric:: Notes This function should be the inverse of radec_to_lmn, but it is not. There is likely an error here. .. !! processed by numpydoc !! .. py:function:: m(ra, dec, cra, cdec, incr) Convert a coordinate in RA, Dec into a direction cosine m. :Parameters: **ra** : float Right ascension of the source, in decimal degrees. **dec** : float Declination of the source, in decimal degrees. **cra** : float Right ascension of the center of the field, in decimal degrees. **cdec** : float Declination of the center of the field, in decimal degrees. **incr** : float Number of degrees per pixel. :Returns: float Direction cosine m. .. !! processed by numpydoc !! .. py:function:: mjd2datetime(mjd) Convert a Modified Julian Date to datetime via 'unix time' representation. NB 'unix time' is defined by the casacore/casacore package. :Parameters: **mjd** : float Modified Julian Date to be converted. :Returns: datetime.datetime A datetime object representing the given Modified Julian Date. .. !! processed by numpydoc !! .. py:function:: mjd2lst(mjd, position=None) Converts a Modified Julian Date into Local Apparent Sidereal Time in seconds at a given position. If position is None, we default to the reference position of CS002. :Parameters: **mjd** : float Modified Julian Date in days. **position** : casacore measure, default: None Position for the LST calculation. :Returns: float Local Apparent Sidereal Time in seconds. .. !! processed by numpydoc !! .. py:function:: mjds2lst(mjds, position=None) As mjd2lst(), but takes an argument in seconds rather than days. :Parameters: **mjds** : float Modified Julian Date (in seconds). **position** : casacore measure, default: None Position for Local Sidereal Time calculations. :Returns: float Local Apparent Sidereal Time in seconds. .. !! processed by numpydoc !! .. py:function:: propagate_sign(val1, val2, val3) Determine the sign of the input values and ensure consistency. casacore (reasonably enough) demands that a minus sign (if required) comes at the start of the quantity. Thus "-0D30M" rather than "0D-30M". Python regards "-0" as equal to "0"; we need to split off a separate sign field. If more than one of our inputs is negative, it's not clear what the user meant: we raise an exception. :Parameters: **val1** : float First input value (hours or degrees). **val2** : float Second input value (minutes). **val3** : float Third input value (seconds). :Returns: **sign** : str "+" or "-" string denoting the sign. val1: float Absolute value of ``val1``. **val2** : float Absolute value of ``val2``. **val3** : float Absolute value of ``val3``. .. !! processed by numpydoc !! .. py:function:: radec_to_lmn(ra0, dec0, ra, dec) Convert equatorial coordinates (RA, Dec) to direction cosines (l, m, n). :Parameters: **ra0** : float Right ascension of the reference point (in decimal degrees). **dec0** : float Declination of the reference point (in decimal degrees). **ra** : float Right Ascension of the target point (in decimal degrees). **dec** : float Declination of the target point (in decimal degrees). :Returns: **l** : float Direction cosine along the l-axis. **m** : float Direction cosine along the m-axis. **n** : float Direction cosine along the n-axis. .. !! processed by numpydoc !! .. py:function:: ratohms(radegs) Convert RA in decimal degrees format to hours, minutes, seconds format. :Parameters: **radegs** : float RA in degrees format. :Returns: **hours** : int .. **minutes** : int .. **seconds** : float .. .. !! processed by numpydoc !! .. py:function:: sec2days(seconds) Convert seconds to the equivalent number of days. :Parameters: **seconds** : float Time duration in seconds. :Returns: float Equivalent time duration in days. .. !! processed by numpydoc !! .. py:function:: sec2deg(seconds) Convert seconds of time to degrees of arc. :Parameters: **seconds** : float Time in seconds to be converted to degrees of arc. :Returns: float Equivalent value in degrees of arc. .. !! processed by numpydoc !! .. py:function:: sec2hms(seconds) Convert seconds to hours, minutes, and seconds. :Returns: **hours** : int .. **minutes** : int .. **seconds** : float .. .. !! processed by numpydoc !! .. py:function:: unix2julian(timestamp) Convert a Unix timestamp (number of seconds since 1 January 1970) to a modified Julian timestamp (number of seconds since 17 November 1858). :Parameters: **timestamp** : numbers.Number Number of seconds since the Unix epoch. :Returns: numbers.Number Number of seconds since the modified Julian epoch. .. !! processed by numpydoc !! .. py:data:: CORE_LAT :value: 52.9088 .. py:data:: CORE_LON :value: -6.8689 .. py:data:: ITRF_X :value: 3826577.06611 .. py:data:: ITRF_Y :value: 461022.947639 .. py:data:: ITRF_Z :value: 5064892.786 .. py:data:: SECONDS_IN_DAY :value: 86400 .. py:data:: SECONDS_IN_HOUR :value: 3600 .. py:data:: logger .. py:data:: unix_epoch