Date and Time Utility Functions

A number of utility functions for encoding and decoding date and time units supplied with cf_units. These are documented below.

cf_units.encode_time(year, month, day, hour, minute, second)

Return date/clock time encoded as a double precision value.

Encoding performed using UDUNITS-2 hybrid Gregorian/Julian calendar. Dates on or after 1582-10-15 are assumed to be Gregorian dates; dates before that are assumed to be Julian dates. In particular, the year 1 BCE is immediately followed by the year 1 CE.

Args:

• year (int):

  Year value to be encoded.

• month (int):

  Month value to be encoded.

• day (int):

  Day value to be encoded.

• hour (int):

  Hour value to be encoded.

• minute (int):

  Minute value to be encoded.

• second (int):

  Second value to be encoded.

Returns:

float.

For example:

>>> import cf_units
>>> cf_units.encode_time(1970, 1, 1, 0, 0, 0)
-978307200.0

cf_units.encode_date(year, month, day)

Return date encoded as a double precision value.

Encoding performed using UDUNITS-2 hybrid Gergorian/Julian calendar. Dates on or after 1582-10-15 are assumed to be Gregorian dates; dates before that are assumed to be Julian dates. In particular, the year 1 BCE is immediately followed by the year 1 CE.

Args:

• year (int):

  Year value to be encoded.

• month (int):

  Month value to be encoded.

• day (int):

  Day value to be encoded.

Returns:

float.

For example:

>>> import cf_units
>>> cf_units.encode_date(1970, 1, 1)
-978307200.0

cf_units.encode_clock(hour, minute, second)

Return clock time encoded as a double precision value.

Args:

• hour (int):

  Hour value to be encoded.

• minute (int):

  Minute value to be encoded.

• second (int):

  Second value to be encoded.

Returns:

float.

For example:

>>> import cf_units
>>> cf_units.encode_clock(0, 0, 0)
0.0

cf_units.decode_time(time)

Decode a double precision date/clock time value into its component parts and return as tuple.

Decode time into it’s year, month, day, hour, minute, second, and resolution component parts. Where resolution is the uncertainty of the time in seconds.

Args:

• time (float): Date/clock time encoded as a double precision value.

Returns:

tuple of (year, month, day, hour, minute, second, resolution).

For example:

>>> import cf_units
>>> cf_units.decode_time(cf_units.encode_time(1970, 1, 1, 0, 0, 0))
(1970, 1, 1, 0, 0, 0.0, 1.086139178596568e-07)

cf_units.julian_day2date(julian_day, calendar)

Return a cftime datetime-like object representing the Julian day.

If calendar is ‘standard’ or ‘gregorian’, Julian day follows Julian calendar on and before 1582-10-5, Gregorian calendar after 1582-10-15. If calendar is ‘proleptic_gregorian’, Julian Day follows Gregorian calendar. If calendar is ‘julian’, Julian Day follows Julian calendar.

The datetime object is a ‘real’ datetime object if the date falls in the Gregorian calendar (i.e. calendar is ‘proleptic_gregorian’, or calendar is ‘standard’/’gregorian’ and the date is after 1582-10-15). Otherwise, it’s a ‘phony’ datetime object which is actually an instance of cftime.datetime.

Algorithm:

Meeus, Jean (1998) Astronomical Algorithms (2nd Edition). Willmann-Bell, Virginia. p. 63.

Args:

• julian_day (float):

  Julian day with a resolution of 1 second.

• calendar (string):

  Name of the calendar, see cf_units.CALENDARS.

Returns:

datetime or cftime.datetime.

For example:

>>> import cf_units
>>> import datetime
>>> cf_units.julian_day2date(
...    cf_units.date2julian_day(datetime.datetime(1970, 1, 1, 0, 0, 0),
...                             cf_units.CALENDAR_STANDARD),
...     cf_units.CALENDAR_STANDARD)
datetime.datetime(1970, 1, 1, 0, 0)

cf_units.date2julian_day(date, calendar)

Return the Julian day (resolution of 1 second) from a cftime datetime-like object.

If calendar is ‘standard’ or ‘gregorian’, Julian day follows Julian calendar on and before 1582-10-5, Gregorian calendar after 1582-10-15. If calendar is ‘proleptic_gregorian’, Julian day follows Gregorian calendar. If calendar is ‘julian’, Julian day follows Julian calendar.

Algorithm:

Meeus, Jean (1998) Astronomical Algorithms (2nd Edition). Willmann-Bell, Virginia. p. 63.

Args:

• date (cftime.date):

  Date and time representation.

• calendar (string):

  Name of the calendar, see cf_units.CALENDARS.

Returns:

float.

For example:

>>> import cf_units
>>> import datetime
>>> cf_units.date2julian_day(datetime.datetime(1970, 1, 1, 0, 0, 0),
...                          cf_units.CALENDAR_STANDARD)
2440587.5...

cf_units.date2num(date, unit, calendar)

Return numeric time value (resolution of 1 second) encoding of datetime object.

The units of the numeric time values are described by the unit and calendar arguments. The datetime objects must be in UTC with no time-zone offset. If there is a time-zone offset in unit, it will be applied to the returned numeric values.

Like the matplotlib.dates.date2num() function, except that it allows for different units and calendars. Behaves the same as if unit = ‘days since 0001-01-01 00:00:00’ and calendar = ‘proleptic_gregorian’.

Args:

• date (datetime):

  A datetime object or a sequence of datetime objects. The datetime objects should not include a time-zone offset.

• unit (string):

  A string of the form ‘<time-unit> since <time-origin>’ describing the time units. The <time-unit> can be days, hours, minutes or seconds. The <time-origin> is a date/time reference point. A valid choice would be unit=’hours since 1800-01-01 00:00:00 -6:00’.

• calendar (string):

  Name of the calendar, see cf_units.CALENDARS.

Returns:

float, or numpy.ndarray of float.

For example:

>>> import cf_units
>>> import datetime
>>> dt1 = datetime.datetime(1970, 1, 1, 6, 0, 0)
>>> dt2 = datetime.datetime(1970, 1, 1, 7, 0, 0)
>>> cf_units.date2num(dt1, 'hours since 1970-01-01 00:00:00',
...               cf_units.CALENDAR_STANDARD)
6.0
>>> cf_units.date2num([dt1, dt2], 'hours since 1970-01-01 00:00:00',
...               cf_units.CALENDAR_STANDARD)
array([6., 7.])

cf_units.num2date(time_value, unit, calendar)

Return datetime encoding of numeric time value (resolution of 1 second).

The units of the numeric time value are described by the unit and calendar arguments. The returned datetime object represent UTC with no time-zone offset, even if the specified unit contain a time-zone offset.

Like the matplotlib.dates.num2date() function, except that it allows for different units and calendars. Behaves the same if unit = ‘days since 001-01-01 00:00:00’} calendar = ‘proleptic_gregorian’.

The datetime instances returned are ‘real’ python datetime objects if the date falls in the Gregorian calendar (i.e. calendar=’proleptic_gregorian’, or calendar = ‘standard’ or ‘gregorian’ and the date is after 1582-10-15). Otherwise, they are ‘phony’ datetime objects which support some but not all the methods of ‘real’ python datetime objects. This is because the python datetime module cannot use the ‘proleptic_gregorian’ calendar, even before the switch occured from the Julian calendar in 1582. The datetime instances do not contain a time-zone offset, even if the specified unit contains one.

Works for scalars, sequences and numpy arrays. Returns a scalar if input is a scalar, else returns a numpy array.

Args:

• time_value (float):

  Numeric time value/s. Maximum resolution is 1 second.

• unit (sting):

  A string of the form ‘<time-unit> since <time-origin>’ describing the time units. The <time-unit> can be days, hours, minutes or seconds. The <time-origin> is the date/time reference point. A valid choice would be unit=’hours since 1800-01-01 00:00:00 -6:00’.

• calendar (string):

  Name of the calendar, see cf_units.CALENDARS.

Returns:

datetime, or numpy.ndarray of datetime object.

For example:

>>> import cf_units
>>> import datetime
>>> cf_units.num2date(6, 'hours since 1970-01-01 00:00:00',
...                   cf_units.CALENDAR_STANDARD)
datetime.datetime(1970, 1, 1, 6, 0)
>>> cf_units.num2date([6, 7], 'hours since 1970-01-01 00:00:00',
...                   cf_units.CALENDAR_STANDARD)
array([datetime.datetime(1970, 1, 1, 6, 0),
       datetime.datetime(1970, 1, 1, 7, 0)], dtype=object)

cf_units.CALENDARS = ['standard', 'gregorian', 'proleptic_gregorian', 'noleap', 'julian', 'all_leap', '365_day', '366_day', '360_day']

The calendars recognised by cf_units. These are accessible as strings, or as constants in the form cf_units.CALENDAR_{ calendar_name.upper() }. For example, cf_units.CALENDAR_NO_LEAP and cf_units.CALENDAR_366_DAY.

cf_units.CALENDAR_ALIASES = {'all_leap': '366_day', 'noleap': '365_day', 'standard': 'gregorian'}

Where calendars have multiple names, we map the alias to the definitive form.