sourcefinder.utility.coordinates

General purpose astronomical coordinate handling routines.

Attributes

CORE_LAT
CORE_LON
ITRF_X
ITRF_Y
ITRF_Z
SECONDS_IN_DAY
SECONDS_IN_HOUR
logger
unix_epoch

Classes

CoordSystem	A container for constant strings representing different
WCS	Wrapper around pywcs.WCS.

Functions

alpha(l, m, alpha0, delta0)	Convert a coordinate in l, m into a coordinate in RA.
alpha_inflate(theta, decl)	Compute the RA expansion for a given theta at a given
alphasep(ra1, ra2, dec1, dec2)	Find the angular separation of two sources in RA, in
altaz(mjds, ra, dec[, lat])	Calculate the azimuth and elevation of a source from time and position
angsep(ra1, dec1, ra2, dec2)	Find the angular separation of two sources, in arcseconds,
angsep_vectorized(ra_dec1, ra_dec2, angular_separation)	Find the angular separation of two sources, in arcseconds,
cmp(a, b)	Compare two values and return an integer indicating their
cmp_jitted(a, b)	Compare two values and return an integer indicating their
convert_coordsystem(ra, dec, insys, outsys)	Convert RA & dec (given in decimal degrees) between equinoxes.
coordsystem(name)	Given a string, return a constant from class CoordSystem.
dectodms(decdegs)	Convert Declination in decimal degrees format to hours,
delta(l, m, delta0)	Convert a coordinate in l, m into a coordinate in declination.
deltasep(dec1, dec2)	Find the angular separation of two sources in declination, in
dmstodec(decd, decm, decs)	Convert Dec in degrees, minutes, seconds format to decimal
eq_to_cart(ra, dec)	Find the cartesian coordinates on the unit sphere given the
eq_to_gal(ra, dec)	Find the Galactic coordinates of a source given the equatorial
gal_to_eq(lon_l, lat_b)	Find the equatorial coordinates of a source given the Galactic
hmstora(rah, ram, ras)	Convert RA in hours, minutes, seconds format to decimal
jd2lst(jd[, position])	Converts a Julian Date into Local Apparent Sidereal Time in seconds at a
julian2unix(timestamp)	Convert a modified Julian timestamp (number of seconds since 17 November
julian_date([time, modified])	Calculate the Julian date at a given timestamp.
l(ra, dec, cra, incr)	Convert a coordinate in RA, Dec into a direction cosine l.
lm_to_radec(ra0, dec0, l, m)	Find the l direction cosine of a source in a radio image,
m(ra, dec, cra, cdec, incr)	Convert a coordinate in RA, Dec into a direction cosine m.
mjd2datetime(mjd)	Convert a Modified Julian Date to datetime via 'unix time' representation.
mjd2lst(mjd[, position])	Converts a Modified Julian Date into Local Apparent Sidereal Time in
mjds2lst(mjds[, position])	As mjd2lst(), but takes an argument in seconds rather than days.
propagate_sign(val1, val2, val3)	Determine the sign of the input values and ensure consistency.
radec_to_lmn(ra0, dec0, ra, dec)	Convert equatorial coordinates (RA, Dec) to direction cosines
ratohms(radegs)	Convert RA in decimal degrees format to hours, minutes,
sec2days(seconds)	Convert seconds to the equivalent number of days.
sec2deg(seconds)	Convert seconds of time to degrees of arc.
sec2hms(seconds)	Convert seconds to hours, minutes, and seconds.
unix2julian(timestamp)	Convert a Unix timestamp (number of seconds since 1 January 1970) to a

Module Contents

class sourcefinder.utility.coordinates.CoordSystem

A container for constant strings representing different coordinate systems.

FK4 = 'B1950 (FK4)'

FK5 = 'J2000 (FK5)'

class sourcefinder.utility.coordinates.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.

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_pixposndarray

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.

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:

pixposlist or tuple

A list or tuple of two floats containing the pixel position as [x, y].

Returns:

rafloat

Right ascension corresponding to the pixel position in decimal degrees.

decfloat

Declination corresponding to the pixel position in decimal degrees.

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:

spatialpostuple[float, float]

A tuple containing: - ra (float): Right ascension in decimal degrees. - dec (float): Declination in decimal degrees.

Returns:

xfloat

X pixel value corresponding to the spatial position.

yfloat

Y pixel value corresponding to the spatial position.

ORIGIN = 1

WCS_ATTRS = ('crpix', 'cdelt', 'crval', 'ctype', 'cunit', 'crota')

wcs

sourcefinder.utility.coordinates.alpha(l, m, alpha0, delta0)

Convert a coordinate in l, m into a coordinate in RA.

Parameters:

lfloat

Direction cosine along the l-axis, given by offset in cells times cell size (in radians).

mfloat

Direction cosine along the m-axis, given by offset in cells times cell size (in radians).

alpha0float

Right ascension of the centre of the field, in decimal degrees.

delta0float

Declination of the centre of the field, in decimal degrees.

Returns:

float

Right Ascension (RA) in decimal degrees.

sourcefinder.utility.coordinates.alpha_inflate(theta, decl)

Compute the RA expansion for a given theta at a given declination.

Parameters:

thetafloat

Angular distance from the center, in decimal degrees.

declfloat

Declination of the source, in decimal degrees.

Returns:

float

RA inflation in decimal degrees.

Notes

For a derivation, see MSR TR 2006 52, Section 2.1: http://research.microsoft.com/apps/pubs/default.aspx?id=64524

sourcefinder.utility.coordinates.alphasep(ra1, ra2, dec1, dec2)

Find the angular separation of two sources in RA, in arcseconds.

Parameters:

ra1float

Right ascension of the first source, in decimal degrees.

ra2float

Right ascension of the second source, in decimal degrees.

dec1float

Declination of the first source, in decimal degrees.

dec2float

Declination of the second source, in decimal degrees.

Returns:

float

Angular separation in RA, in arcseconds.

sourcefinder.utility.coordinates.altaz(mjds, ra, dec, lat=CORE_LAT)

Calculate the azimuth and elevation of a source from time and position on the sky.

Parameters:

mjdsfloat

Modified Julian Date in seconds.

rafloat

Right Ascension of the source in degrees.

decfloat

Declination of the source in degrees.

latfloat, defaultCORE_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.

sourcefinder.utility.coordinates.angsep(ra1, dec1, ra2, dec2)

Find the angular separation of two sources, in arcseconds, using the proper spherical trigonometry formula.

Parameters:

ra1float

Right Ascension of the first source, in decimal degrees.

dec1float

Declination of the first source, in decimal degrees.

ra2float

Right Ascension of the second source, in decimal degrees.

dec2float

Declination of the second source, in decimal degrees.

Returns:

float

Angular separation between the two sources, in arcseconds.

sourcefinder.utility.coordinates.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_dec1ndarray

RA and Dec of the first source, in decimal degrees.

ra_dec2ndarray

RA and Dec of the second source, in decimal degrees.

angular_separationfloat

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.

sourcefinder.utility.coordinates.cmp(a, b)

Compare two values and return an integer indicating their relationship.

Parameters:

aAny

The first value to compare.

bAny

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.

sourcefinder.utility.coordinates.cmp_jitted(a, b)

Compare two values and return an integer indicating their relationship.

Parameters:

aAny

The first value to compare.

bAny

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.

sourcefinder.utility.coordinates.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:

rafloat

Right ascension in decimal degrees.

decfloat

Declination in decimal degrees.

insysstr

Input equinox, e.g., ‘B1950’ or ‘J2000’.

outsysstr

Output equinox, e.g., ‘B1950’ or ‘J2000’.

Returns:

rafloat

Converted right ascension in decimal degrees.

decfloat

Converted declination in decimal degrees.

Raises:

Exception

If the input or output equinox is unknown.

sourcefinder.utility.coordinates.coordsystem(name)

Given a string, return a constant from class CoordSystem.

Parameters:

namestr

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.

sourcefinder.utility.coordinates.dectodms(decdegs)

Convert Declination in decimal degrees format to hours, minutes, seconds format.

Parameters:

decdegsfloat

Declination in decimal degrees format.

Returns:

hoursint

minutesint

secondsfloat

sourcefinder.utility.coordinates.delta(l, m, delta0)

Convert a coordinate in l, m into a coordinate in declination.

Parameters:

lfloat

Direction cosine along the l-axis, given by offset in cells times cell size (in radians).

mfloat

Direction cosine along the m-axis, given by offset in cells times cell size (in radians).

delta0float

Declination of the center of the field, in decimal degrees.

Returns:

float

Declination in decimal degrees.

sourcefinder.utility.coordinates.deltasep(dec1, dec2)

Find the angular separation of two sources in declination, in arcseconds.

Parameters:

dec1float

Declination of the first source, in decimal degrees.

dec2float

Declination of the second source, in decimal degrees.

Returns:

float

Angular separation in declination, in arcseconds.

sourcefinder.utility.coordinates.dmstodec(decd, decm, decs)

Convert Dec in degrees, minutes, seconds format to decimal degrees format.

Parameters:

decdint

Degrees component of the Declination.

decmint

Minutes component of the Declination.

decsfloat

Seconds component of the Declination.

Returns:

float

Declination in decimal degrees.

sourcefinder.utility.coordinates.eq_to_cart(ra, dec)

Find the cartesian coordinates on the unit sphere given the equatorial coordinates.

Parameters:

rafloat

Right ascension (RA) in decimal degrees.

decfloat

Declination (Dec) in decimal degrees.

Returns:

xfloat

Cartesian x-coordinate.

yfloat

Cartesian y-coordinate.

zfloat

Cartesian z-coordinate.

sourcefinder.utility.coordinates.eq_to_gal(ra, dec)

Find the Galactic coordinates of a source given the equatorial coordinates.

Parameters:

rafloat

Right ascension (RA) in decimal degrees.

decfloat

Declination (Dec) in decimal degrees.

Returns:

lon_lfloat

Galactic longitude in decimal degrees.

lat_bfloat

Galactic latitude in decimal degrees.

sourcefinder.utility.coordinates.gal_to_eq(lon_l, lat_b)

Find the equatorial coordinates of a source given the Galactic coordinates.

Parameters:

lon_lfloat

Galactic longitude in decimal degrees.

lat_bfloat

Galactic latitude in decimal degrees.

Returns:

rafloat

Right ascension (RA) in decimal degrees.

decfloat

Declination (Dec) in decimal degrees.

sourcefinder.utility.coordinates.hmstora(rah, ram, ras)

Convert RA in hours, minutes, seconds format to decimal degrees format.

Parameters:

rahfloat

Right Ascension hours.

ramfloat

Right Ascension minutes.

rasfloat

Right Ascension seconds.

Returns:

float

RA in decimal degrees.

sourcefinder.utility.coordinates.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:

jdfloat

Julian Date to be converted.

positioncasacore measure, default: None

Position for Local Sidereal Time calculations.

Returns:

float

Local Apparent Sidereal Time in seconds.

sourcefinder.utility.coordinates.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:

timestampnumbers.Number

Number of seconds since the Unix epoch.

Returns:

numbers.Number

Number of seconds since the modified Julian epoch.

sourcefinder.utility.coordinates.julian_date(time=None, modified=False)

Calculate the Julian date at a given timestamp.

Parameters:

timedatetime.datetime, default: None

Timestamp to calculate JD for. If not provided, the current UTC time will be used.

modifiedbool, 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.

sourcefinder.utility.coordinates.l(ra, dec, cra, incr)

Convert a coordinate in RA, Dec into a direction cosine l.

Parameters:

rafloat

Right ascension of the source, in decimal degrees.

decfloat

Declination of the source, in decimal degrees.

crafloat

Right ascension of the centre of the field, in decimal degrees.

incrfloat

Number of degrees per pixel (negative in the case of RA).

Returns:

float

Direction cosine l.

sourcefinder.utility.coordinates.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:

ra0float

Right ascension of the field center, in decimal degrees.

dec0float

Declination of the field center, in decimal degrees.

lfloat

Direction cosine of the source along the l-axis.

mfloat

Direction cosine of the source along the m-axis.

Returns:

rafloat

Right ascension in decimal degrees.

decfloat

Declination in decimal degrees.

Notes

This function should be the inverse of radec_to_lmn, but it is not. There is likely an error here.

sourcefinder.utility.coordinates.m(ra, dec, cra, cdec, incr)

Convert a coordinate in RA, Dec into a direction cosine m.

Parameters:

rafloat

Right ascension of the source, in decimal degrees.

decfloat

Declination of the source, in decimal degrees.

crafloat

Right ascension of the center of the field, in decimal degrees.

cdecfloat

Declination of the center of the field, in decimal degrees.

incrfloat

Number of degrees per pixel.

Returns:

float

Direction cosine m.

sourcefinder.utility.coordinates.mjd2datetime(mjd)

Convert a Modified Julian Date to datetime via ‘unix time’ representation.

NB ‘unix time’ is defined by the casacore/casacore package.

Parameters:

mjdfloat

Modified Julian Date to be converted.

Returns:

datetime.datetime

A datetime object representing the given Modified Julian Date.

sourcefinder.utility.coordinates.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:

mjdfloat

Modified Julian Date in days.

positioncasacore measure, default: None

Position for the LST calculation.

Returns:

float

Local Apparent Sidereal Time in seconds.

sourcefinder.utility.coordinates.mjds2lst(mjds, position=None)

As mjd2lst(), but takes an argument in seconds rather than days.

Parameters:

mjdsfloat

Modified Julian Date (in seconds).

positioncasacore measure, default: None

Position for Local Sidereal Time calculations.

Returns:

float

Local Apparent Sidereal Time in seconds.

sourcefinder.utility.coordinates.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:

val1float

First input value (hours or degrees).

val2float

Second input value (minutes).

val3float

Third input value (seconds).

Returns:

signstr

“+” or “-” string denoting the sign.

val1: float

Absolute value of val1.

val2float

Absolute value of val2.

val3float

Absolute value of val3.

sourcefinder.utility.coordinates.radec_to_lmn(ra0, dec0, ra, dec)

Convert equatorial coordinates (RA, Dec) to direction cosines (l, m, n).

Parameters:

ra0float

Right ascension of the reference point (in decimal degrees).

dec0float

Declination of the reference point (in decimal degrees).

rafloat

Right Ascension of the target point (in decimal degrees).

decfloat

Declination of the target point (in decimal degrees).

Returns:

lfloat

Direction cosine along the l-axis.

mfloat

Direction cosine along the m-axis.

nfloat

Direction cosine along the n-axis.

sourcefinder.utility.coordinates.ratohms(radegs)

Convert RA in decimal degrees format to hours, minutes, seconds format.

Parameters:

radegsfloat

RA in degrees format.

Returns:

hoursint

minutesint

secondsfloat

sourcefinder.utility.coordinates.sec2days(seconds)

Convert seconds to the equivalent number of days.

Parameters:

secondsfloat

Time duration in seconds.

Returns:

float

Equivalent time duration in days.

sourcefinder.utility.coordinates.sec2deg(seconds)

Convert seconds of time to degrees of arc.

Parameters:

secondsfloat

Time in seconds to be converted to degrees of arc.

Returns:

float

Equivalent value in degrees of arc.

sourcefinder.utility.coordinates.sec2hms(seconds)

Convert seconds to hours, minutes, and seconds.

Returns:

hoursint

minutesint

secondsfloat

sourcefinder.utility.coordinates.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:

timestampnumbers.Number

Number of seconds since the Unix epoch.

Returns:

numbers.Number

Number of seconds since the modified Julian epoch.

sourcefinder.utility.coordinates.CORE_LAT = 52.9088

sourcefinder.utility.coordinates.CORE_LON = -6.8689

sourcefinder.utility.coordinates.ITRF_X = 3826577.06611

sourcefinder.utility.coordinates.ITRF_Y = 461022.947639

sourcefinder.utility.coordinates.ITRF_Z = 5064892.786

sourcefinder.utility.coordinates.SECONDS_IN_DAY = 86400

sourcefinder.utility.coordinates.SECONDS_IN_HOUR = 3600

sourcefinder.utility.coordinates.logger

sourcefinder.utility.coordinates.unix_epoch