astrobase.timeutils module

Contains various useful tools for dealing with time in astronomical contexts.

astrobase.timeutils.precess_coordinates(ra, dec, epoch_one, epoch_two, jd=None, mu_ra=0.0, mu_dec=0.0, outscalar=False)[source]

Precesses target coordinates ra, dec from epoch_one to epoch_two.

This takes into account the jd of the observations, as well as the proper motion of the target mu_ra, mu_dec. Adapted from J. D. Hartman’s VARTOOLS/converttime.c [coordprecess].

Parameters:
  • ra,dec (float) – The equatorial coordinates of the object at epoch_one to precess in decimal degrees.
  • epoch_one (float) – Origin epoch to precess from to target epoch. This is a float, like: 1985.0, 2000.0, etc.
  • epoch_two (float) – Target epoch to precess from origin epoch. This is a float, like: 2000.0, 2018.0, etc.
  • jd (float) – The full Julian date to use along with the propermotions in mu_ra, and mu_dec to handle proper motion along with the coordinate frame precession. If one of jd, mu_ra, or mu_dec is missing, the proper motion will not be used to calculate the final precessed coordinates.
  • mu_ra,mu_dec (float) – The proper motion in mas/yr in right ascension and declination. If these are provided along with jd, the total proper motion of the object will be taken into account to calculate the final precessed coordinates.
  • outscalar (bool) – If True, converts the output coordinates from one-element np.arrays to scalars.
Returns:

precessed_ra, precessed_dec – A tuple of precessed equatorial coordinates in decimal degrees at epoch_two taking into account proper motion if jd, mu_ra, and mu_dec are provided.
Return type:

float
astrobase.timeutils.get_epochs_given_midtimes_and_period(t_mid, period, err_t_mid=None, t0_fixed=None, t0_percentile=None, verbose=False)[source]

This calculates the future epochs for a transit, given a period and a starting epoch

The equation used is:

t_mid = period*epoch + t0

Default behavior if no kwargs are used is to define t0 as the median finite time of the passed t_mid array.

Only one of err_t_mid or t0_fixed should be passed.

Parameters:
  • t_mid (np.array) – A np.array of transit mid-time measurements
  • period (float) – The period used to calculate epochs, per the equation above. For typical use cases, a period precise to ~1e-5 days is sufficient to get correct epochs.
  • err_t_mid (None or np.array) – If provided, contains the errors of the transit mid-time measurements. The zero-point epoch is then set equal to the average of the transit times, weighted as 1/err_t_mid^2 . This minimizes the covariance between the transit epoch and the period (e.g., Gibson et al. 2013). For standard O-C analysis this is the best method.
  • t0_fixed (None or float:) – If provided, use this t0 as the starting epoch. (Overrides all others).
  • t0_percentile (None or float) – If provided, use this percentile of t_mid to define t0.
Returns:

This is the of the form (integer_epoch_array, t0). integer_epoch_array is an array of integer epochs (float-type), of length equal to the number of finite mid-times passed.
Return type:

tuple
astrobase.timeutils.unixtime_to_jd(unix_time)[source]

This converts UNIX time in seconds to a Julian date in UTC (JD_UTC).

Parameters:unix_time (float) – A UNIX time in decimal seconds since the 1970 UNIX epoch.
Returns:jd – The Julian date corresponding to the provided UNIX time.
Return type:float
astrobase.timeutils.datetime_to_jd(dt)[source]

This converts a Python datetime object (naive, time in UT) to JD_UTC.

Parameters:dt (datetime) – A naive Python datetime object (e.g. with no tz attribute) measured at UTC.
Returns:jd – The Julian date corresponding to the datetime object.
Return type:float
astrobase.timeutils.jd_to_datetime(jd, returniso=False)[source]

This converts a UTC JD to a Python datetime object or ISO date string.

Parameters:
  • jd (float) – The Julian date measured at UTC.
  • returniso (bool) – If False, returns a naive Python datetime object corresponding to jd. If True, returns the ISO format string corresponding to the date and time at UTC from jd.
Returns:

Depending on the value of returniso.
Return type:

datetime or str
astrobase.timeutils.jd_now()[source]

Gets the Julian date at the current time.

Returns:The current Julian date in days.
Return type:float
astrobase.timeutils.jd_to_mjd(jd)[source]

Converts Julian Date to Modified Julian Date.

Parameters:jd (float) – The Julian date measured at UTC.
Returns:mjd – mjd = jd - 2400000.5
Return type:float
astrobase.timeutils.mjd_to_jd(mjd)[source]

Converts Modified Julian date to Julian Date.

Parameters:mjd (float) – The Modified Julian date measured at UTC.
Returns:jd – jd = mjd + 2400000.5
Return type:float
astrobase.timeutils.jd_corr(jd, ra, dec, obslon=None, obslat=None, obsalt=None, jd_type='bjd')[source]

Returns BJD_TDB or HJD_TDB for input JD_UTC.

The equation used is:

BJD_TDB = JD_UTC + JD_to_TDB_corr + romer_delay

where:

  • JD_to_TDB_corr is the difference between UTC and TDB JDs
  • romer_delay is the delay caused by finite speed of light from Earth-Sun

This is based on the code at:

https://mail.scipy.org/pipermail/astropy/2014-April/003148.html

Note that this does not correct for:

  1. precession of coordinates if the epoch is not 2000.0
  2. precession of coordinates if the target has a proper motion
  3. Shapiro delay
  4. Einstein delay
Parameters:
  • jd (float or array-like) – The Julian date(s) measured at UTC.
  • ra,dec (float) – The equatorial coordinates of the object in decimal degrees.
  • obslon,obslat,obsalt (float or None) – The longitude, latitude of the observatory in decimal degrees and altitude of the observatory in meters. If these are not provided, the corrected JD will be calculated with respect to the center of the Earth.
  • jd_type ({'bjd','hjd'}) – Conversion type to perform, either to Baryocentric Julian Date (‘bjd’) or to Heliocenter Julian Date (‘hjd’).
Returns:

The converted BJD or HJD.
Return type:

float or np.array