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

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

Syncs leap second files with NIST servers

Calling Sequence

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

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

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

import icesat2_toolkit.time
MJD = icesat2_toolkit.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 icesat2_toolkit.time
MJD = icesat2_toolkit.time.convert_calendar_dates(YEAR,MONTH,DAY,hour=HOUR,
    minute=MINUTE,second=SECOND,epoch=(1858,11,17,0,0,0))

Source code

General Methods

icesat2_toolkit.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

icesat2_toolkit.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

icesat2_toolkit.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

icesat2_toolkit.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]

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

Calculates the number of days per month for a given year

Parameters

year: int, float or np.ndarray: calendar year

Returns

dpm: list: number of days for each month

icesat2_toolkit.time.convert_datetime(date: float | numpy.ndarray, epoch: str | tuple | list | numpy.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: tuple or NoneType, default None: epoch for input delta_time
epoch2: tuple or NoneType, default None: epoch for output delta_time
scale: float, default 1.0: scaling factor for converting time to output units

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

Calculate the time in time 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 icesat2_toolkit.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

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

References

1: N. Dershowitz, and E. M. Reingold. Calendrical Calculations, Cambridge: Cambridge University Press, (2008).

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

Converts from Julian day to calendar date and time

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

References

1: W. H. Press, Numerical Recipes in C, Brian P. Flannery, Saul A. Teukolsky, and William T. Vetterling. Cambridge University Press, (1988).
2: D. A. Hatcher, “Simple Formulae for Julian Day Numbers and Calendar Dates”, Quarterly Journal of the Royal Astronomical Society, 25(1), 1984.

icesat2_toolkit.time.count_leap_seconds(GPS_Time: numpy.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

icesat2_toolkit.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

GPS time: float: GPS seconds when leap seconds occurred

icesat2_toolkit.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