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

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, 30, 0)
>>> dt2 = datetime.datetime(1970, 1, 1, 7, 30, 0)
>>> cf_units.date2num(dt1, 'hours since 1970-01-01 00:00:00',
...               cf_units.CALENDAR_STANDARD)
6.5
>>> cf_units.date2num([dt1, dt2], 'hours since 1970-01-01 00:00:00',
...               cf_units.CALENDAR_STANDARD)
array([6.5, 7.5])

cf_units.num2date(time_value, unit, calendar, only_use_cftime_datetimes=True, only_use_python_datetimes=False)

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.

By default, the datetime instances returned are cftime.datetime objects, regardless of calendar. If the only_use_cftime_datetimes keyword is set to False, they are datetime.datetime objects if the date falls in the Gregorian calendar (i.e. calendar is ‘proleptic_gregorian’, ‘standard’ or ‘gregorian’ and the date is after 1582-10-15). 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.

Kwargs:

• only_use_cftime_datetimes (bool):

  If True, will always return cftime datetime objects, regardless of calendar. If False, returns datetime.datetime instances where possible. Defaults to True.

• only_use_python_datetimes (bool):

  If True, will always return datetime.datetime instances where possible, and raise an exception if not. Ignored if only_use_cftime_datetimes is True. Defaults to False.

Returns:

datetime, or numpy.ndarray of datetime object.

For example:

>>> import cf_units
>>> import datetime
>>> print(cf_units.num2date(6, 'hours since 1970-01-01 00:00:00',
...                         cf_units.CALENDAR_STANDARD))
1970-01-01 06:00:00
>>> dts = cf_units.num2date([6, 7], 'hours since 1970-01-01 00:00:00',
...                         cf_units.CALENDAR_STANDARD)
>>> [str(dt) for dt in dts]
['1970-01-01 06:00:00', '1970-01-01 07:00:00']

cf_units.num2pydate(time_value, unit, calendar)

Convert time value(s) to python datetime.datetime objects, or raise an exception if this is not possible. Same as:

num2date(time_value, unit, calendar,
         only_use_cftime_datetimes=False,
         only_use_python_datetimes=True)

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.