A (third) proposal for implementing some date/time types in NumPy

Time units

It accepts different time units, each of them implying a different time span. The table below describes the time units supported with their corresponding time spans.

The value of an absolute date is thus an integer number of units of the chosen time unit passed since the internal epoch. When working with business days, Saturdays and Sundays are simply ignored from the count (i.e. day 3 in business days is not Saturday 1970-01-03, but Monday 1970-01-05).

Building a datetime64 dtype

The proposed ways to specify the time unit in the dtype constructor are:

Using the long string notation:

dtype('datetime64[us]')

Using the short string notation:

dtype('T8[us]')

Note that a time unit should always be specified, as there is not a default.

Setting and getting values

The objects with this dtype can be set in a series of ways:

t = numpy.ones(3, dtype='T8[s]')
t[0] = 1199164176    # assign to July 30th, 2008 at 17:31:00
t[1] = datetime.datetime(2008, 7, 30, 17, 31, 01) # with datetime

module

t[2] = '2008-07-30T17:31:02' # with ISO 8601

And can be get in different ways too:

str(t[0])  -->  2008-07-30T17:31:00
repr(t[1]) -->  datetime64(1199164177, 's')
str(t[0].item()) --> 2008-07-30 17:31:00  # datetime module object
repr(t[0].item()) --> datetime.datetime(2008, 7, 30, 17, 31)  # idem
str(t)  -->  [2008-07-30T17:31:00  2008-07-30T17:31:01

2008-07-30T17:31:02]

repr(t) --> array([1199164176, 1199164177, 1199164178],

dtype='datetime64[s]')

Comparisons

The comparisons will be supported too:

numpy.array(['1980'], 'T8[Y]') == numpy.array(['1979'], 'T8[Y]')
--> [False]

or by applying broadcasting:

numpy.array(['1979', '1980'], 'T8[Y]') == numpy.datetime64

('1980', 'Y')

--> [False, True]

The next should work too:

numpy.array(['1979', '1980'], 'T8[Y]') == '1980-01-01'
--> [False, True]

because the right hand expression can be broadcasted into an array of 2 elements of dtype 'T8[Y]'.

Compatibility issues

This will be fully compatible with the datetime class of the datetime module of Python only when using a time unit of microseconds. For other time units, the conversion process will loose precision or will overflow as needed. The conversion from/to a datetime object doesn't take leap seconds into account.

Time units

It accepts different time units, each of them implying a different time span. The table below describes the time units supported with their corresponding time spans.

The value of a time delta is thus an integer number of units of the chosen time unit.

Building a timedelta64 dtype

The proposed ways to specify the time unit in the dtype constructor are:

Using the long string notation:

dtype('timedelta64[us]')

Using the short string notation:

dtype('t8[us]')

Note that a time unit should always be specified, as there is not a default.

Setting and getting values

The objects with this dtype can be set in a series of ways:

t = numpy.ones(3, dtype='t8[ms]')
t[0] = 12    # assign to 12 ms
t[1] = datetime.timedelta(0, 0, 13000)   # 13 ms
t[2] = '0:00:00.014'    # 14 ms

And can be get in different ways too:

str(t[0])  -->  0:00:00.012
repr(t[1]) -->  timedelta64(13, 'ms')
str(t[0].item()) --> 0:00:00.012000   # datetime module object
repr(t[0].item()) --> datetime.timedelta(0, 0, 12000)  # idem
str(t)     -->  [0:00:00.012  0:00:00.014  0:00:00.014]
repr(t)    -->  array([12, 13, 14], dtype="timedelta64[ms]")

Comparisons

The comparisons will be supported too:

numpy.array([12, 13, 14], 't8[ms]') == numpy.array([12, 13, 13], 't8

[ms]')

--> [True, True, False]

or by applying broadcasting:

numpy.array([12, 13, 14], 't8[ms]') == numpy.timedelta64(13, 'ms')
--> [False, True, False]

The next should work too:

numpy.array([12, 13, 14], 't8[ms]') == '0:00:00.012'
--> [True, False, False]

because the right hand expression can be broadcasted into an array of 3 elements of dtype 't8[ms]'.

Compatibility issues

This will be fully compatible with the timedelta class of the datetime module of Python only when using a time unit of microseconds. For other units, the conversion process will loose precision or will overflow as needed.

Casting rules

When operating (basically, only the subtraction will be allowed) two absolute times with different unit times, the outcome would be to raise an exception. This is because the ranges and time-spans of the different time units can be very different, and it is not clear at all what time unit will be preferred for the user. For example, this should be allowed:

>>> numpy.ones(3, dtype="T8[Y]") - numpy.zeros(3, dtype="T8[Y]")
array([1, 1, 1], dtype="timedelta64[Y]")

But the next should not:

>>> numpy.ones(3, dtype="T8[Y]") - numpy.zeros(3, dtype="T8[ns]")
raise numpy.IncompatibleUnitError  # what unit to choose?

Casting rules

In this case the absolute time should have priority for determining the time unit of the outcome. That would represent what the people wants to do most of the times. For example, this would allow to do:

>>> series = numpy.array(['1970-01-01', '1970-02-01', '1970-09-01'],
dtype='datetime64[D]')
>>> series2 = series + numpy.timedelta(1, 'Y')  # Add 2 relative years
>>> series2
array(['1972-01-01', '1972-02-01', '1972-09-01'],
dtype='datetime64[D]')  # the 'D'ay time unit has been chosen

Casting rules

When combining two timedelta64 dtypes with different time units the outcome will be the shorter of both ("keep the precision" rule). For example:

In [10]: numpy.ones(3, 't8[s]') + numpy.ones(3, 't8[m]')
Out[10]: array([61, 61, 61],  dtype="timedelta64[s]")

However, due to the impossibility to know the exact duration of a relative year or a relative month, when these time units appear in one of the operands, the operation will not be allowed:

In [11]: numpy.ones(3, 't8[Y]') + numpy.ones(3, 't8[D]')
raise numpy.IncompatibleUnitError  # how to convert relative years to

days?

In order to being able to perform the above operation a new NumPy function, called change_timeunit is proposed. Its signature will be:

change_timeunit(time_object, new_unit, reference)

where 'time_object' is the time object whose unit is to be changed, 'new_unit' is the desired new time unit, and 'reference' is an absolute date (NumPy datetime64 scalar) that will be used to allow the conversion of relative times in case of using time units with an uncertain number of smaller time units (relative years or months cannot be expressed in days).

With this, the above operation can be done as follows:

In [10]: t_years = numpy.ones(3, 't8[Y]')

In [11]: t_days = numpy.change_timeunit(t_years, 'D', '2001-01-01')

In [12]: t_days + numpy.ones(3, 't8[D]')
Out[12]: array([366, 366, 366],  dtype="timedelta64[D]")