time

Utilities for calculating time operations

Can convert delta time from seconds since an epoch to time since a different epoch

Can calculate the time in days since epoch from calendar dates

Calculates the difference between dynamic time and universal time (TT - UT1)

Can count the number of leap seconds between a given GPS time and UTC

Syncs leap second files with NIST servers

Updates differences between universal time (UT) and dynamic time (TT)

Calling Sequence

Count the number of leap seconds between a GPS time and UTC

import timescale.time
leap_seconds = timescale.time.count_leap_seconds(gps_seconds)

Convert a time from seconds since 1980-01-06T00:00:00 to Modified Julian Days (MJD)

import timescale.time
MJD = timescale.time.convert_delta_time(delta_time, epoch1=(1980,1,6,0,0,0),
    epoch2=(1858,11,17,0,0,0), scale=1.0/86400.0)

Convert a calendar date into Modified Julian Days

import timescale.time
MJD = timescale.time.convert_calendar_dates(YEAR,MONTH,DAY,hour=HOUR,
    minute=MINUTE,second=SECOND,epoch=(1858,11,17,0,0,0))

Source code

General Methods

timescale.time.parse(date_string: str)[source]

Parse a date string and convert to a naive datetime object in UTC

Parameters:

date_string: str: formatted time string

Returns:

date: obj: output datetime object

timescale.time.parse_date_string(date_string: str)[source]

Parse a date string of the form

time-units since yyyy-mm-dd hh:mm:ss
yyyy-mm-dd hh:mm:ss for exact calendar dates

Parameters:

date_string: str: time-units since yyyy-mm-dd hh:mm:ss

Returns:

epoch: list: epoch of delta_time
conversion_factor: float: multiplication factor to convert to seconds

timescale.time.split_date_string(date_string: str)[source]

Split a date string into units and epoch

Parameters:

date_string: str: time-units since yyyy-mm-dd hh:mm:ss

timescale.time.datetime_to_list(date)[source]

Convert a datetime object into a list

Parameters:

date: obj: Input datetime object to convert

Returns:

date: list: [year,month,day,hour,minute,second]

Create a range of dates

Parameters:

start: str, np.datetime64 or datetime.datetime

start date

end: str, np.datetime64 or datetime.datetime

end date

step: int or float, default 1

step size

units: str, default ‘D’

datetime units

'Y': year

'M': month

'W': week

'D': day

'h': hour

'm': minute

's': second

'ms': millisecond

endpoint: bool, default True

If True, include the end date in the output

timescale.time.calendar_days(year: int | float) → ndarray[source]

Calculates the number of days per month for a given year

Parameters:

year: int or float: calendar year

Returns:

dpm: np.ndarray: number of days for each month

timescale.time.convert_datetime(date: float | ndarray, epoch: str | tuple | list | datetime64 = (1970, 1, 1, 0, 0, 0))[source]

Convert a numpy datetime array to seconds since epoch

Parameters:

date: np.ndarray: numpy datetime array
epoch: str, tuple, list, np.ndarray, default (1970,1,1,0,0,0): epoch for output delta_time

Returns:

delta_time: float: seconds since epoch

Convert delta time from seconds since epoch1 to time since epoch2

Parameters:

delta_time: np.ndarray: seconds since epoch1
epoch1: str, tuple, list or NoneType, default None: epoch for input delta_time
epoch2: str, tuple, list or NoneType, default None: epoch for output delta_time
scale: float, default 1.0: scaling factor for converting time to output units

timescale.time.convert_calendar_dates(year: ndarray, month: ndarray, day: ndarray, hour: ndarray | float = 0.0, minute: ndarray | float = 0.0, second: ndarray | float = 0.0, epoch: tuple | list | datetime64 = (1992, 1, 1, 0, 0, 0), scale: float = 1.0) → ndarray[source]

Calculate the time in units since epoch from calendar dates

Parameters:

year: np.ndarray: calendar year
month: np.ndarray: month of the year
day: np.ndarray: day of the month
hour: np.ndarray or float, default 0.0: hour of the day
minute: np.ndarray or float, default 0.0: minute of the hour
second: np.ndarray or float, default 0.0: second of the minute
epoch: tuple or list, default timescale.time._tide_epoch: epoch for output delta_time
scale: float, default 1.0: scaling factor for converting time to output units

Returns:

delta_time: np.ndarray: time since epoch

Converts from calendar date into decimal years taking into account leap years [1]

Parameters:

year: np.ndarray: calendar year
month: np.ndarray: calendar month
day: np.ndarray, float or NoneType, default None: day of the month
hour: np.ndarray, float or NoneType, default None: hour of the day
minute: np.ndarray, float or NoneType, default None: minute of the hour
second: np.ndarray, float or NoneType, default None: second of the minute
DofY: np.ndarray, float or NoneType, default None: day of the year

Returns:

t_date: np.ndarray: date in decimal-year format

timescale.time.convert_julian(JD: ndarray, **kwargs)[source]

Converts from Julian day to calendar date and time [9] [4]

Parameters:

JD: np.ndarray

Julian Day (days since 01-01-4713 BCE at 12:00:00)

astype: str or NoneType, default None

convert output to variable type

format: str, default ‘dict’

format of output variables

'dict': dictionary with variable keys

'tuple': tuple in most-to-least-significant order

'zip': aggregated variable sets

Returns:

year: np.ndarray: calendar year
month: np.ndarray: calendar month
day: np.ndarray: day of the month
hour: np.ndarray: hour of the day
minute: np.ndarray: minute of the hour
second: np.ndarray: second of the minute

class timescale.time.Timescale(MJD=None, leaps=None)[source]

Class for converting between time scales

Attributes:

leaps: np.ndarray: Number of leap seconds
MJD: np.ndarray: Modified Julian Days

classmethod from_deltatime(delta_time: ndarray, epoch: str | tuple | list | ndarray, standard: str = 'UTC')[source]

Converts a delta time array and into a Timescale object

Parameters:

delta_time: np.ndarray: seconds since epoch
epoch: str, uuple, list or np.ndarray: epoch for input delta_time
standard: str, default ‘UTC’: time standard for input delta_time

Converts calendar date arrays into a Timescale object

Parameters:

year: np.ndarray: calendar year
month: np.ndarray or float, default 1.0: month of the year
day: np.ndarray or float, default 1.0: day of the month
hour: np.ndarray or float, default 0.0: hour of the day
minute: np.ndarray or float, default 0.0: minute of the hour
second: np.ndarray or float, default 0.0: second of the minute

classmethod from_datetime(dtime: ndarray)[source]

Reads a datetime array and converts into a Timescale object

Parameters:

dtime: np.ndarray: numpy.datetime64 array

classmethod from_list(temp)[source]

Reads a list of Timescale objects and converts into a single Timescale object

Parameters:

temp: list: list of Timescale objects

to_calendar()[source]: Convert a Timescale object to a Calendar object

to_deltatime(epoch: str | tuple | list | ndarray, scale: float = 1.0)[source]

Convert a Timescale object to a delta time array

Parameters:

epoch: str, tuple, list, or np.ndarray: epoch for output delta_time
scale: float, default 1.0: scaling factor for converting time to output units

Returns:

delta_time: np.ndarray: time since epoch

to_datetime(unit='ns')[source]

Convert a Timescale object to a datetime array

Returns:

dtime: np.ndarray: numpy.datetime64 array

to_string(unit: str = 's', **kwargs)[source]

Convert a Timescale object to a formatted string array

Parameters:

unit: str, default ‘s’: datetime unit for output string array
**kwargs: dict: keyword arguments for datetime formatting

polynomial_sum(coefficients: list | ndarray, t: ndarray)[source]

Calculates the sum of a polynomial function of time

Parameters:

coefficients: list or np.ndarray: leading coefficient of polynomials of increasing order
t: np.ndarray: delta time in units for a given astronomical longitudes calculation

era: Earth Rotation Angle (ERA) in degrees

gha: Greenwich Hour Angle (GHA) in degrees

gmst: Greenwich Mean Sidereal Time (GMST) in fractions of day

gps: Seconds since 1980-01-06T00:00:00

gps_utc: Leap seconds between GPS and UTC time

gps_week: GPS week number since 1980-01-06T00:00:00

J2000: Seconds (Terrestrial Time) since 2000-01-01T12:00:00

st: Greenwich Mean Sidereal Time (GMST) in fractions of a day from the Equinox Method

tdb: Approximate Barycentric Dynamical Time (TDB) as Julian Days

tdb_tt: Difference between Barycentric Dynamical Time (TDB) and terrestrial time (TT) [3, 5]

tide: Days since 1992-01-01T00:00:00

tt: Terrestrial Time (TT) as Julian Days

tt_ut1: Difference between dynamical time (TT) and universal time (UT1)

ut1_utc: Difference between universal time (UT1) and coordinated universal time (UTC)

T: Centuries since 2000-01-01T12:00:00

B: Time in Besselian years [6]

ut1: Universal Time (UT) as Julian Days

ut2: UT0 corrected for polar motion and seasonal variation

utc: Coordinated Universal Time (UTC) as Julian Days

year: Universal Time (UT) as calendar year

nominal_year: Universal Time (UT) as nominal years of 365.25 days

min()[source]: Minimum time value as a Timescale object

max()[source]: Maximum time value as a Timescale object

mean()[source]: Mean time value as a Timescale object

property turnasec: Arcseconds in a full turn

property asec2rad: Arcseconds to radians

property masec2rad: Microarcseconds to radians

property dtype: Main data type of Timescale object

property shape: Dimensions of Timescale object

property ndim: Number of dimensions in Timescale object

class timescale.time.Calendar(utc=None)[source]

Class for converting from Julian dates to calendar dates

from_julian()[source]: Converts from Julian dates to calendar dates

property dtype: Main data type of Calendar object

property shape: Dimensions of Calendar object

property ndim: Number of dimensions in Calendar object

timescale.time.interpolate_delta_time(delta_file: str | Path | None, idays: ndarray, validate: bool = False)[source]

Calculates the difference between dynamical time (TT) and universal time (UT) [7]

Parameters:

delta_file: str or Pathlib.Path: file containing the delta times (TT-UT1)
idays: np.ndarray: input times to interpolate (days since 1992-01-01T00:00:00)
validate: bool, default False: check that delta time file is up to date

Returns:

deltat: np.ndarray: estimated TT-UT1 values

timescale.time.count_leap_seconds(GPS_Time: ndarray | float, truncate: bool = True)[source]

Counts the number of leap seconds between a given GPS time and UTC

Parameters:

GPS_Time: np.ndarray or float: seconds since January 6, 1980 at 00:00:00
truncate: bool, default True: Reduce list of leap seconds to positive GPS times

Returns:

n_leaps: float: number of elapsed leap seconds

timescale.time.get_leap_seconds(truncate: bool = True)[source]

Gets a list of GPS times for when leap seconds occurred

Parameters:

truncate: bool, default True: Reduce list of leap seconds to positive GPS times

Returns:

leap_GPS: float: GPS seconds when leap seconds occurred

timescale.time.update_leap_seconds(timeout: int | None = 20, verbose: bool = False, mode: oct = 509)[source]

Connects to servers to download leap-seconds.list files from NIST servers

https://www.nist.gov/pml/time-and-frequency-division/leap-seconds-faqs

Servers and Mirrors

Parameters:

timeout: int or None, default 20: timeout in seconds for blocking operations
verbose: bool, default False: print file information about output file
mode: oct, default 0o775: permissions mode of output file

timescale.time.validate_delta_time(delta_file: str | Path = PosixPath('/home/docs/checkouts/readthedocs.org/user_builds/timescale/checkouts/stable/timescale/data/merged_deltat.data'))[source]

Checks that the delta time file is still up to date

Parameters:

delta_file: str or Pathlib.Path: file containing the delta times (TT-UT1)

timescale.time.update_delta_time(delta_file: str | Path, branch: str = 'main', timeout: int | None = 20, verbose: bool = False, mode: oct = 509)[source]

Downloads an updated delta time file from the project GitHub repository

Parameters:

delta_file: str or Pathlib.Path: file containing the delta times (TT-UT1)
branch: str, default ‘main’: branch of the GitHub repository for downloading files
timeout: int or None, default 20: timeout for the HTTP request in seconds
verbose: bool, default False: print file information about output file
mode: oct, default 0o775: permissions mode of output file

Notes

Delta times are the difference between dynamical time and universal time

timescale.time.merge_delta_time(username: str | None = None, password: str | None = None, verbose: bool = False, mode: oct = 509)[source]

Connects to servers to download historic_deltat.data and deltat.data files

Reads IERS Bulletin-A produced iers_deltat.data files

Creates a merged file combining the historic, monthly and daily files

Long-term Delta T

https://www.usno.navy.mil/USNO/earth-orientation/eo-products/long-term

Parameters:

username: str or NoneType, default None: NASA Earthdata username
password: str or NoneType, default None: NASA Earthdata password
verbose: bool, default False: print file information about output file
mode: oct, default 0o775: permissions mode of output file

Notes

Delta times are the difference between dynamical time and universal time

timescale.time.append_delta_time(verbose: bool = False, mode: oct = 509)[source]

Appends merged delta time file with values from latest Bulletin-A file

Parameters:

verbose: bool, default False: print file information about output file
mode: oct, default 0o775: permissions mode of output file

Notes

Delta times are the difference between dynamical time and universal time

timescale.time.merge_bulletin_a_files(username: str | None = None, password: str | None = None, verbose: bool = False, mode: oct = 509)[source]

Attempt to connects to the IERS server and the CDDIS Earthdata server to download and merge Bulletin-A files

Reads the IERS Bulletin-A files and calculates the daily delta times

Servers and Mirrors

Parameters:

username: str or NoneType, default None: NASA Earthdata username
password: str or NoneType, default None: NASA Earthdata password
verbose: bool, default False: print file information about output file
mode: oct, default 0o775: permissions mode of output file

Notes

Delta times are the difference between dynamical time and universal time

timescale.time.iers_ftp_delta_time(daily_file: str | Path, timeout: int | None = 120, verbose: bool = False, mode: oct = 509)[source]

Connects to the IERS ftp server to download Bulletin-A files

https://datacenter.iers.org/productMetadata.php?id=6

Reads the IERS Bulletin-A files and calculates the daily delta times

Servers and Mirrors

ftp://ftp.iers.org/products/eop/rapid/bulletina/

Parameters:

daily_file: str or pathlib.Path: output daily delta time file from merged Bulletin-A files
timeout: int, default 120: timeout in seconds for blocking operations
verbose: bool, default False: print file information about output file
mode: oct, default 0o775: permissions mode of output file

Notes

Delta times are the difference between dynamical time and universal time

timescale.time.iers_delta_time(daily_file: str | Path, timeout: int | None = 120, verbose: bool = False, mode: oct = 509)[source]

Connects to the IERS server to download Bulletin-A files

https://datacenter.iers.org/productMetadata.php?id=6

Reads the IERS Bulletin-A files and calculates the daily delta times

Servers and Mirrors

https://datacenter.iers.org/availableVersions.php?id=6

Parameters:

daily_file: str or pathlib.Path: output daily delta time file from merged Bulletin-A files
timeout: int, default 120: timeout in seconds for blocking operations
verbose: bool, default False: print file information about output file
mode: oct, default 0o775: permissions mode of output file

Notes

Delta times are the difference between dynamical time and universal time

timescale.time.cddis_delta_time(daily_file: str | Path, username: str | None = None, password: str | None = None, verbose: bool = False, mode: oct = 509)[source]

Connects to the CDDIS Earthdata server to download Bulletin-A files

Reads the IERS Bulletin-A files and calculates the daily delta times

Servers and Mirrors

https://cddis.nasa.gov/archive/products/iers/iers_bulletins/bulletin_a/

Parameters:

daily_file: str: output daily delta time file from merged Bulletin-A files
username: str or NoneType, default None: NASA Earthdata username
password: str or NoneType, default None: NASA Earthdata password
verbose: bool, default False: print file information about output file
mode: oct, default 0o775: permissions mode of output file

Notes

Delta times are the difference between dynamical time and universal time

timescale.time.read_iers_bulletin_a(fileID)[source]

Read a weekly IERS Bulletin-A file and calculate the delta times (TT - UT1)

Parameters:

fileID: obj: open file object for Bulletin-A file

Returns:

Y: float,: calendar year
M: float: calendar month
D: float: day of the month
DELTAT: float: difference between universal time and dynamical time

Notes

Delta times are the difference between dynamical time and universal time

timescale.time.update_bulletin_a(timeout: int | None = 20, verbose: bool = False, mode: oct = 509)[source]

Connects to IERS Rapid Service/Prediction Center (RS/PC) and downloads latest Bulletin-A file

https://maia.usno.navy.mil/ser7/readme.bulla

Servers and Mirrors

https://maia.usno.navy.mil/ser7/ser7.dat

Parameters:

timeout: int or NoneType, default 20: timeout in seconds for blocking operations
verbose: bool, default False: print file information about output file
mode: oct, default 0o775: permissions mode of output file

timescale.time.pull_deltat_file(FILE: str, username: str | None = None, password: str | None = None, timeout: int | None = 20, verbose: bool = False, mode: oct = 509)[source]

Connects to servers and downloads delta time files

Servers and Mirrors

Parameters:

FILE: str

delta time file to download from remote servers

deltat.data: monthly deltat file

historic_deltat.data: historic deltat file

username: str or NoneType, default None

NASA Earthdata username

password: str or NoneType, default None

NASA Earthdata password

timeout: int or NoneType, default 20

timeout in seconds for blocking operations

verbose: bool, default False

print file information about output file

mode: oct, default 0o775

permissions mode of output file

Notes

Delta times are the difference between dynamical time and universal time