astrotool.date_time module

Date and time functions for AstroTool.

astrotool.date_time.date_from_jd(jd, jd_start_greg=2299160.5)[source]

Compute the calendar date from a given Julian Day.

Parameters:

jd (float) – Julian day (days).
jd_start_greg (float) – JD of start of Gregorian calendar (optional; default=2299160.5 = 1582-10-15.0).

Returns:

Tuple containing (year, month, day):

year (int): Year CE. Note that year=0 indicates 1 BCE.

month (int): Month number of year (1-12).

day (float): Day of month with fraction (1.0-31.999…).

Return type:

tuple (int,int,float)

Note

Date and time will be in the same timezone as the JD (UT for the offical JD).
Decimals can be returned in the day to indicate the time of day, e.g. 1.0 for midnight and 1.5 for noon on the first day of the month.

astrotool.date_time.date_time2jd(year, month, day, hour, minute, second)[source]: Obsolescent function. Use jd_from_date_time() instead.

astrotool.date_time.date_time_from_jd(jd, jd_start_greg=2299160.5)[source]

Compute the calendar date and time from a given Julian Day.

Parameters:

jd (float) – Julian day (days).
jd_start_greg (float) – JD of start of Gregorian calendar (optional; default=2299160.5 = 1582-10-15.0).

Returns:

Tuple containing (year, month, day, hour, minute, second):

year (int): Year CE. Note that year=0 indicates 1 BCE.

month (int): Month number of year (1-12).

day (int): Day of month (1-31).

hour (int): Hour of day (0-23).

minute (int): Minute of hour (0-59).

second (float): Second of minute (0.0-59.999…)

Return type:

tuple (int,int,int, int,int,float)

Note

Date and time will be in the same timezone as the JD, hence UTC for the offical JD.

astrotool.date_time.deltat(jd)[source]: Obsolescent function. Use deltat_from_jd_ipol() instead.

astrotool.date_time.deltat_1820(jd)[source]: Obsolescent function. Use deltat_from_jd_appr() instead.

astrotool.date_time.deltat_from_jd_appr(jd)[source]

Return a rough approximation for the value of Delta T.

A lenghtening of the day of 1.8 ms/century is assumed, as well as and that the minimum of the parabola is DeltaT=12s in 1820.

Parameters:: jd (float) – Julian day (days).
Returns:: Delta T (s).
Return type:: float

References

Extrapolation of Delta T.

astrotool.date_time.deltat_from_jd_ipol(jd)[source]

Return the value of DeltaT through interpolation or ‘extrapolation’.

For the date range -700 - now, the value for Delta T is obtained by interpolation of known historical: values. Outside this range, a lenghtening of the day of 1.8 ms/century is assumed, as well as that the minimum of the parabola is DeltaT=12s in 1820.

Parameters:: jd (float) – Julian day (days).
Returns:: Delta T (s).
Return type:: float

References

International Earth Rotation and Reference Systems Service of the U.S. Naval Observatory.
Robert van Gent’s website on Delta T.
Extrapolation of Delta T.

astrotool.date_time.doy_from_datetime(date_time)[source]

Compute the day of year for a given datetime.

Parameters:: date_time (datetime) – Date and time.
Returns:: Day of year.
Return type:: (int)

astrotool.date_time.doy_from_ymd(year, month, day)[source]

Compute the day of year for a given year, month and day.

Parameters:

year (int) – Year of date.
month (int) – Month of date.
day (int) – Day of date.

Returns:

Day of year.

Return type:

(int)

astrotool.date_time.fix_date_time(year, month, day, hour, minute, second)[source]

Fix a given set of date and time variables (year, month, day, hour, minute and second) to make them consistent.

For example, month=13 will be corrected to month=1 in the next year, day=32 to a date in the next month, hour=24 to hour=0 on the next day, et cetera. This is useful, because some sources list hours between 1 and 24, rather than 0-23, on which Python’s datetime crashes. In rare cases of roundoff of 59.9 or a leap second, second=60. More generally, this makes it straightforward to add or subtract dates and times and to take into account timezones, DST, et cetera.

Parameters:

year (int) – Year CE. Note that year=0 = 1 BCE.
month (int) – Month number of year.
day (int) – Day of month with fraction.
hour (int) – Hour of time of day.
minute (int) – Minute of hour of time.
second (float) – Second of minute of time.

Returns:

tuple containing (year CE, month, day, hour, minute, second):

year (int): Year CE. Note that year=0 = 1 BCE.
month (int): Month number of year (UT; 1-12).
day (int): Day of month with fraction (UT; 1-31).
hour (int): Hour of time of day (0-23).
minute (int): Minute of hour of time (0-59).
second (float): Second of minute of time (0.000-59.999).

Return type:

tuple (int,int,int, int,int,float)

Note

uses jd_from_date_time() and date_time_from_jd().

astrotool.date_time.gmst(jd)[source]: Obsolescent function. Use gmst_from_jd() instead.

astrotool.date_time.gmst_from_jd(jd, deltat=None)[source]

Calculate Greenwich Mean Sidereal Time for any instant, in radians.

Parameters:

jd (float) – Julian day (days).
deltat (float) – Delta T (s).

Returns:

Greenwich mean sidereal time (rad).

Return type:

float

References

Explanatory Supplement to the Astronomical Almanac, 3rd ed, Eq. 6.66 (2012).

astrotool.date_time.gps_time_from_jd(jd)[source]

Compute GPS time from the Julian day.

Parameters:: jd (float) – Julian day (days).
Returns:: GPS time (seconds since 1980-01-06, without leap seconds!).
Return type:: float

Note

number of leap seconds on 1980-01-06 is 19.

astrotool.date_time.hm_str_from_time(time)[source]

Return a float time in hours as a formatted string in hours and minutes: hh:mm.

Parameters:: time (float) – Time in hours.
Returns:: Time in hours and minutes in the format hh:mm.
Return type:: (str)

Note: wrapper for hms_str_from_time().

astrotool.date_time.hms_str_from_time(time, use_sec=True, use_ms=False, use_mus=False, use_ns=False)[source]

Return a float time in hours as a formatted string in hours, minutes (and seconds).

Parameters:

time (float) – Time in hours.
use_sec (bool) – Use seconds in the string. Optional, defaults to True.
use_ms (bool) – Use milliseconds in the string. Optional, defaults to False.
use_mus (bool) – Use microseconds in the string. Optional, defaults to False.
use_ns (bool) – Use nanoseconds in the string. Optional, defaults to False.

Returns:

Time in hours, minutes and seconds of the format hh:mm(:ss(.sss(sss(sss)))).

Return type:

(str)

astrotool.date_time.jd2date_time(jd)[source]: Obsolescent function. Use date_time_from_jd() instead.

astrotool.date_time.jd2tjc(jd)[source]: Obsolescent function. Use tjc_from_jd() instead.

astrotool.date_time.jd2tjm(jd)[source]: Obsolescent function. Use tjm_from_jd() instead.

astrotool.date_time.jd2year(jd)[source]: Obsolescent function. Use year_from_jd() instead.

astrotool.date_time.jd2ymd(jd, jd_start_greg=2299160.5)[source]: Obsolescent function. Use date_from_jd() instead.

astrotool.date_time.jd_from_date(year, month, day, jd_start_greg=2299160.5)[source]

Compute the Julian Day from given year, month and day.

Parameters:

year (int) – Year CE. Note that year=0 = 1 BCE, year=-1 = 2 BCE, etc.
month (int) – Month number of year (1-12).
day (float) – Day of month with fraction (1.0-31.999…).
jd_start_greg (float) – JD of start of Gregorian calendar (optional; default=2299160.5 = 1582-10-15.0).

Returns:

jd: Julian day (days).

Return type:

float

Note

The JD will be in the same timezone as the date and time (use UTC for the offical JD).
Decimals can be used in the day to take into account the time of day other than midnight, e.g. 1.5 for noon on the first day of the month.

astrotool.date_time.jd_from_date_time(year, month, day, hour, minute, second, jd_start_greg=2299160.5)[source]

Compute the Julian Day from given year, month, day, hour, minute and second.

Parameters:

year (int) – Year CE. Note that year=0 = 1 BCE, year=-1 = 2 BCE, etc.
month (int) – Month number of year (1-12).
day (int) – Day of month (1-31).
hour (int) – Hour of day (0-23).
minute (int) – Minute of hour (0-59).
second (float) – Second of minute (0.0-59.999…).
jd_start_greg (float) – JD of start of Gregorian calendar (optional; default=2299160.5 = 1582-10-15.0).

Returns:

jd: Julian day (days).

Return type:

float

Note

The JD will be in the same timezone as the date and time (use UTC for the offical JD).
Decimals can be used in the second.

astrotool.date_time.jd_from_datetime(dtm, jd_start_greg=2299160.5)[source]

Compute the Julian Day from given year, month, day, hour, minute and second.

Parameters:

dtm (dt.datetime) – Datetime object.
jd_start_greg (float) – JD of start of Gregorian calendar (optional; default=2299160.5 = 1582-10-15.0).

Returns:

jd: Julian day (days).

Return type:

float

Note

The JD will be in the same timezone as the date and time (use UTC for the offical JD).

astrotool.date_time.jd_from_gps_time(gps_time)[source]

Compute the Julian day from the GPS time.

Parameters:: gps_time (float) – GPS time (seconds since 1980-01-06, without leap seconds!).
Returns:: Julian day (days).
Return type:: float

Note

number of leap seconds on 1980-01-06 is 19.

astrotool.date_time.julian_day(year, month, day, jd_start_greg=2299160.5)[source]: Obsolescent function. Use jd_from_date() instead.

astrotool.date_time.leap_seconds_from_jd(jd, warn=True)[source]

Brief description of function.

Parameters:

jd (float) – Julian day (days).
warn (bool) – Warn when offering a date before 1972 (defaults to True).

Returns:

(TAI-UTC), or the number of leap seconds.

Return type:

(float)

Note

Between 1961 and 1972, there were no leap seconds, but continuous functions to compute TAI-UTC.

See:

https://hpiers.obspm.fr/eoppc/bul/bulc/UTC-TAI.history

astrotool.date_time.tjc_from_jd(jd)[source]

Compute the time in Julian centuries since 2000.0.

Parameters:: jd (float) – Julian day (days).
Returns:: Time in Julian centuries since 2000.0 (UT).
Return type:: float

astrotool.date_time.tjm_from_jd(jd)[source]

Compute the time in Julian millennia since 2000.0.

Parameters:: jd (float) – Julian day (days).
Returns:: Time in Julian millennia since 2000.0 (UT).
Return type:: float

astrotool.date_time.weekday_en_abbr_from_datetime(datetime)[source]

Return an English abbreviation of the weekday for a given datetime.

Parameters:: datetime (datetime)
Returns:: String with the three-character English abbreviation of the weekday (Mon-Sun).
Return type:: (str)

astrotool.date_time.year_from_jd(jd)[source]

Compute a year with fraction from a given Julian Day.

Parameters:: jd (float) – Julian day (days).
Returns:: Year CE, with decimals. Note that year=0 indicates 1 BCE, year=-1 2 BCE, etc.
Return type:: float

astrotool.date_time.ymdhms_us_from_datetime64(dt64)[source]

Convert (array of) datetime64 to a calendar (array of) year, month, day, hour, minute, seconds, microsecond with these quantites indexed on the last axis.

Parameters:

dt64 (datetime64) – (numpy array of) datetime(s) (of arbitrary shape).

Returns:

(…, 7) calendar array with last axis representing year, month, day, hour, minute,: second, microsecond.

Return type:

uint32 array

Note

Nicked from https://stackoverflow.com/a/56260054/1386750