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

Calling Sequence

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

import gravity_toolkit.time
MJD = gravity_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 from Julian Days into calendar dates

import gravity_toolkit.time
JD = MJD + 2400000.5
YEAR,MONTH,DAY,HOUR,MINUTE,SECOND = gravity_toolkit.time.convert_julian(JD,
    format='tuple')

Convert a calendar date into Modified Julian Days (MJD)

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

Convert a calendar date into decimal years

import gravity_toolkit.time
t_date = gravity_toolkit.time.convert_calendar_decimal(YEAR,MOMTH,day=DAY,
    hour=HOUR,minute=MINUTE,second=SECOND)

Source code

General Methods

gravity_toolkit.time.parse_date_string(date_string)[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

gravity_toolkit.time.split_date_string(date_string)[source]

split a date string into units and epoch

Parameters:

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

gravity_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]

gravity_toolkit.time.parse_grace_file(granule)[source]

Extract dates from GRACE/GRACE-FO files

Parameters:

granule: str: GRACE/GRACE-FO Level-2 spherical harmonic data file

gravity_toolkit.time.parse_gfc_file(granule, PROC, DSET)[source]

Extract dates from Gravity Field Coefficient (gfc) files

Parameters:

granule: str

GRAZ or Swarm spherical harmonic data file

PROC: str

GRACE/GRACE-FO Processing Center or Satellite mission

'GRAZ': Institute of Geodesy from GRAZ University of Technology

'Swarm': Time-variable gravity data from Swarm satellites

DSET: str

GRACE/GRACE-FO/Swarm dataset

'GAA': non-tidal atmospheric correction

'GAB': non-tidal oceanic correction

'GAC': combined non-tidal atmospheric and oceanic correction

'GAD': ocean bottom pressure product

'GSM': corrected monthly static gravity field product

gravity_toolkit.time.reduce_by_date(granules)[source]

Reduce list of GRACE/GRACE-FO files by date to the newest version

Parameters:

granules: list: GRACE/GRACE-FO Level-2 spherical harmonic data files

gravity_toolkit.time.adjust_months(grace_month)[source]

Adjust estimated GRACE/GRACE-FO months to fix “Special Cases”

Parameters:

grace_month: np.ndarray: GRACE/GRACE-FO months

Notes

The “Special Months” (Nov 2011, Dec 2011 and April 2012) with Accelerometer shutoffs make the relation between month number and date more complicated as days from other months are used.

For CSR and GFZ: Nov 2011 (119) is centered in Oct 2011 (118)

For JPL: Dec 2011 (120) is centered in Jan 2012 (121)

For all: May 2015 (161) is centered in Apr 2015 (160)

For GSFC: Oct 2018 (202) is centered in Nov 2018 (203)

gravity_toolkit.time.calendar_to_grace(year, month=1, around=<ufunc 'floor'>)[source]

Converts calendar dates to GRACE/GRACE-FO months

Parameters:

year: np.ndarray: calendar year
month: np.ndarray, default 1: calendar month
around: obj, default np.floor: method of rounding to nearest method

Returns:

grace_month: np.ndarray: GRACE/GRACE-FO month

gravity_toolkit.time.grace_to_calendar(grace_month)[source]

Converts GRACE/GRACE-FO months to calendar dates

Parameters:

grace_month: np.ndarray: GRACE/GRACE-FO month

Returns:

year: np.ndarray: calendar year
month: np.ndarray: calendar month

gravity_toolkit.time.calendar_to_julian(year_decimal)[source]

Converts calendar dates to Julian days

Parameters:

year: np.ndarray: calendar year

Returns:

JD: np.ndarray: Julian Day (days since 01-01-4713 BCE at 12:00:00)

gravity_toolkit.time.calendar_days(year)[source]

Calculates the number of days per month for a given year

Parameters:

year: np.ndarray: calendar year

Returns:

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

gravity_toolkit.time.convert_datetime(date, epoch=(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

gravity_toolkit.time.convert_delta_time(delta_time, epoch1=None, epoch2=None, scale=1.0)[source]

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

gravity_toolkit.time.convert_calendar_dates(year, month, day, hour=0.0, minute=0.0, second=0.0, epoch=(1992, 1, 1, 0, 0, 0), scale=1.0)[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: str, tuple, list or NoneType, default (1992,1,1,0,0,0): epoch for output delta_time
scale: float, default 1.0: scaling factor for converting time to output units

Returns:

delta_time: np.ndarray: days since epoch

gravity_toolkit.time.convert_calendar_decimal(year, month, day=None, hour=None, minute=None, second=None, DofY=None)[source]

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

Parameters:

year: np.ndarray: calendar year
month: np.ndarray: calendar month
day: np.ndarray or NoneType, default None: day of the month
hour: np.ndarray or NoneType, default None: hour of the day
minute: np.ndarray or NoneType, default None: minute of the hour
second: np.ndarray or NoneType, default None: second of the minute
DofY: np.ndarray or NoneType, default None: day of the year (January 1 = 1)

Returns:

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

gravity_toolkit.time.convert_julian(JD, **kwargs)[source]

Converts from Julian day to calendar date and time [51], [24]

Parameters:

JD: np.ndarray

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

astype: str, np.dtype 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