New in version 1.7.0.
Starting in NumPy 1.7, there are core array data types which nativelysupport datetime functionality. The data type is called “datetime64”,so named because “datetime” is already taken by the datetime libraryincluded in Python.
Note
The datetime API isexperimental in 1.7.0, and may undergo changesin future versions of NumPy.
The most basic way to create datetimes is from strings inISO 8601 date or datetime format. The unit for internal storageis automatically selected from the form of the string, and canbe either adate unit or atime unit. The date units are years (‘Y’),months (‘M’), weeks (‘W’), and days (‘D’), while the time units arehours (‘h’), minutes (‘m’), seconds (‘s’), milliseconds (‘ms’), andsome additional SI-prefix seconds-based units.
Example
A simple ISO date:
>>>np.datetime64('2005-02-25')numpy.datetime64('2005-02-25')
Using months for the unit:
>>>np.datetime64('2005-02')numpy.datetime64('2005-02')
Specifying just the month, but forcing a ‘days’ unit:
>>>np.datetime64('2005-02','D')numpy.datetime64('2005-02-01')
From a date and time:
>>>np.datetime64('2005-02-25T03:30')numpy.datetime64('2005-02-25T03:30')
When creating an array of datetimes from a string, it is still possibleto automatically select the unit from the inputs, by using thedatetime type with generic units.
Example
>>>np.array(['2007-07-13','2006-01-13','2010-08-13'],dtype='datetime64')array(['2007-07-13', '2006-01-13', '2010-08-13'], dtype='datetime64[D]')
>>>np.array(['2001-01-01T12:00','2002-02-03T13:56:03.172'],dtype='datetime64')array(['2001-01-01T12:00:00.000-0600', '2002-02-03T13:56:03.172-0600'], dtype='datetime64[ms]')
The datetime type works with many common NumPy functions, forexamplearange can be used to generate ranges of dates.
Example
All the dates for one month:
>>>np.arange('2005-02','2005-03',dtype='datetime64[D]')array(['2005-02-01', '2005-02-02', '2005-02-03', '2005-02-04', '2005-02-05', '2005-02-06', '2005-02-07', '2005-02-08', '2005-02-09', '2005-02-10', '2005-02-11', '2005-02-12', '2005-02-13', '2005-02-14', '2005-02-15', '2005-02-16', '2005-02-17', '2005-02-18', '2005-02-19', '2005-02-20', '2005-02-21', '2005-02-22', '2005-02-23', '2005-02-24', '2005-02-25', '2005-02-26', '2005-02-27', '2005-02-28'], dtype='datetime64[D]')
The datetime object represents a single moment in time. If twodatetimes have different units, they may still be representingthe same moment of time, and converting from a bigger unit likemonths to a smaller unit like days is considered a ‘safe’ castbecause the moment of time is still being represented exactly.
Example
>>>np.datetime64('2005')==np.datetime64('2005-01-01')True
>>>np.datetime64('2010-03-14T15Z')==np.datetime64('2010-03-14T15:00:00.00Z')True
NumPy allows the subtraction of two Datetime values, an operation whichproduces a number with a time unit. Because NumPy doesn’t have a physicalquantities system in its core, the timedelta64 data type was createdto complement datetime64.
Datetimes and Timedeltas work together to provide ways forsimple datetime calculations.
Example
>>>np.datetime64('2009-01-01')-np.datetime64('2008-01-01')numpy.timedelta64(366,'D')
>>>np.datetime64('2009')+np.timedelta64(20,'D')numpy.datetime64('2009-01-21')
>>>np.datetime64('2011-06-15T00:00')+np.timedelta64(12,'h')numpy.datetime64('2011-06-15T12:00-0500')
>>>np.timedelta64(1,'W')/np.timedelta64(1,'D')7.0
There are two Timedelta units (‘Y’, years and ‘M’, months) which are treatedspecially, because how much time they represent changes dependingon when they are used. While a timedelta day unit is equivalent to24 hours, there is no way to convert a month unit into days, becausedifferent months have different numbers of days.
Example
>>>a=np.timedelta64(1,'Y')
>>>np.timedelta64(a,'M')numpy.timedelta64(12,'M')
>>>np.timedelta64(a,'D')Traceback (most recent call last): File"<stdin>", line1, in<module>TypeError:Cannot cast NumPy timedelta64 scalar from metadata [Y] to [D] according to the rule 'same_kind'
The Datetime and Timedelta data types support a large number of timeunits, as well as generic units which can be coerced into any of theother units based on input data.
Datetimes are always stored based on POSIX time (though having a TAImode which allows for accounting of leap-seconds is proposed), withan epoch of 1970-01-01T00:00Z. This means the supported dates arealways a symmetric interval around the epoch, called “time span” in thetable below.
The length of the span is the range of a 64-bit integer times the lengthof the date or unit. For example, the time span for ‘W’ (week) is exactly7 times longer than the time span for ‘D’ (day), and the time span for‘D’ (day) is exactly 24 times longer than the time span for ‘h’ (hour).
Here are the date units:
| Code | Meaning | Time span (relative) | Time span (absolute) |
|---|---|---|---|
| Y | year | +/- 9.2e18 years | [9.2e18 BC, 9.2e18 AD] |
| M | month | +/- 7.6e17 years | [7.6e17 BC, 7.6e17 AD] |
| W | week | +/- 1.7e17 years | [1.7e17 BC, 1.7e17 AD] |
| D | day | +/- 2.5e16 years | [2.5e16 BC, 2.5e16 AD] |
And here are the time units:
| Code | Meaning | Time span (relative) | Time span (absolute) |
|---|---|---|---|
| h | hour | +/- 1.0e15 years | [1.0e15 BC, 1.0e15 AD] |
| m | minute | +/- 1.7e13 years | [1.7e13 BC, 1.7e13 AD] |
| s | second | +/- 2.9e11 years | [2.9e11 BC, 2.9e11 AD] |
| ms | millisecond | +/- 2.9e8 years | [ 2.9e8 BC, 2.9e8 AD] |
| us | microsecond | +/- 2.9e5 years | [290301 BC, 294241 AD] |
| ns | nanosecond | +/- 292 years | [ 1678 AD, 2262 AD] |
| ps | picosecond | +/- 106 days | [ 1969 AD, 1970 AD] |
| fs | femtosecond | +/- 2.6 hours | [ 1969 AD, 1970 AD] |
| as | attosecond | +/- 9.2 seconds | [ 1969 AD, 1970 AD] |
To allow the datetime to be used in contexts where only certain days ofthe week are valid, NumPy includes a set of “busday” (business day)functions.
The default for busday functions is that the only valid days are Mondaythrough Friday (the usual business days). The implementation is based ona “weekmask” containing 7 Boolean flags to indicate valid days; customweekmasks are possible that specify other sets of valid days.
The “busday” functions can additionally check a list of “holiday” dates,specific dates that are not valid days.
The functionbusday_offset allows you to apply offsetsspecified in business days to datetimes with a unit of ‘D’ (day).
Example
>>>np.busday_offset('2011-06-23',1)numpy.datetime64('2011-06-24')
>>>np.busday_offset('2011-06-23',2)numpy.datetime64('2011-06-27')
When an input date falls on the weekend or a holiday,busday_offset first applies a rule to roll thedate to a valid business day, then applies the offset. Thedefault rule is ‘raise’, which simply raises an exception.The rules most typically used are ‘forward’ and ‘backward’.
Example
>>>np.busday_offset('2011-06-25',2)Traceback (most recent call last): File"<stdin>", line1, in<module>ValueError:Non-business day date in busday_offset
>>>np.busday_offset('2011-06-25',0,roll='forward')numpy.datetime64('2011-06-27')
>>>np.busday_offset('2011-06-25',2,roll='forward')numpy.datetime64('2011-06-29')
>>>np.busday_offset('2011-06-25',0,roll='backward')numpy.datetime64('2011-06-24')
>>>np.busday_offset('2011-06-25',2,roll='backward')numpy.datetime64('2011-06-28')
In some cases, an appropriate use of the roll and the offsetis necessary to get a desired answer.
Example
The first business day on or after a date:
>>>np.busday_offset('2011-03-20',0,roll='forward')numpy.datetime64('2011-03-21','D')>>>np.busday_offset('2011-03-22',0,roll='forward')numpy.datetime64('2011-03-22','D')
The first business day strictly after a date:
>>>np.busday_offset('2011-03-20',1,roll='backward')numpy.datetime64('2011-03-21','D')>>>np.busday_offset('2011-03-22',1,roll='backward')numpy.datetime64('2011-03-23','D')
The function is also useful for computing some kinds of dayslike holidays. In Canada and the U.S., Mother’s day is onthe second Sunday in May, which can be computed with a customweekmask.
Example
>>>np.busday_offset('2012-05',1,roll='forward',weekmask='Sun')numpy.datetime64('2012-05-13','D')
When performance is important for manipulating many business dateswith one particular choice of weekmask and holidays, there isan objectbusdaycalendar which stores the data necessaryin an optimized form.
To test a datetime64 value to see if it is a valid day, useis_busday.
Example
>>>np.is_busday(np.datetime64('2011-07-15'))# a FridayTrue>>>np.is_busday(np.datetime64('2011-07-16'))# a SaturdayFalse>>>np.is_busday(np.datetime64('2011-07-16'),weekmask="Sat Sun")True>>>a=np.arange(np.datetime64('2011-07-11'),np.datetime64('2011-07-18'))>>>np.is_busday(a)array([ True, True, True, True, True, False, False], dtype='bool')
To find how many valid days there are in a specified range of datetime64dates, usebusday_count:
Example
>>>np.busday_count(np.datetime64('2011-07-11'),np.datetime64('2011-07-18'))5>>>np.busday_count(np.datetime64('2011-07-18'),np.datetime64('2011-07-11'))-5
If you have an array of datetime64 day values, and you want a count ofhow many of them are valid dates, you can do this:
Example
>>>a=np.arange(np.datetime64('2011-07-11'),np.datetime64('2011-07-18'))>>>np.count_nonzero(np.is_busday(a))5
Here are several examples of custom weekmask values. These examplesspecify the “busday” default of Monday through Friday being valid days.
Some examples:
# Positional sequences; positions are Monday through Sunday.# Length of the sequence must be exactly 7.weekmask=[1,1,1,1,1,0,0]# list or other sequence; 0 == invalid day, 1 == valid dayweekmask="1111100"# string '0' == invalid day, '1' == valid day# string abbreviations from this list: Mon Tue Wed Thu Fri Sat Sunweekmask="Mon Tue Wed Thu Fri"# any amount of whitespace is allowed; abbreviations are case-sensitive.weekmask="MonTue Wed Thu\tFri"
In prior versions of NumPy, the datetime64 type always storedtimes in UTC. By default, creating a datetime64 object from a string orprinting it would convert from or to local time:
# old behavior>>>>np.datetime64('2000-01-01T00:00:00')numpy.datetime64('2000-01-01T00:00:00-0800')# note the timezone offset -08:00
A consensus of datetime64 users agreed that this behavior is undesirableand at odds with how datetime64 is usually used (e.g., bypandas). Formost use cases, a timezone naive datetime type is preferred, similar to thedatetime.datetime type in the Python standard library. Accordingly,datetime64 no longer assumes that input is in local time, nor does it printlocal times:
>>>> np.datetime64('2000-01-01T00:00:00')numpy.datetime64('2000-01-01T00:00:00')
For backwards compatibility, datetime64 still parses timezone offsets, whichit handles by converting to UTC. However, the resulting datetime is timezonenaive:
>>>np.datetime64('2000-01-01T00:00:00-08')DeprecationWarning: parsing timezone aware datetimes is deprecated; this will raise an error in the futurenumpy.datetime64('2000-01-01T08:00:00')
As a corollary to this change, we no longer prohibit casting between datetimeswith date units and datetimes with timeunits. With timezone naive datetimes,the rule for casting from dates to times is no longer ambiguous.
The NumPy 1.6 release includes a more primitive datetime data typethan 1.7. This section documents many of the changes that have takenplace.
The datetime string parser in NumPy 1.6 is very liberal in what it accepts,and silently allows invalid input without raising errors. The parser inNumPy 1.7 is quite strict about only accepting ISO 8601 dates, with a fewconvenience extensions. 1.6 always creates microsecond (us) units bydefault, whereas 1.7 detects a unit based on the format of the string.Here is a comparison.:
# NumPy 1.6.1>>>np.datetime64('1979-03-22')1979-03-2200:00:00# NumPy 1.7.0>>>np.datetime64('1979-03-22')numpy.datetime64('1979-03-22')# NumPy 1.6.1, unit default microseconds>>>np.datetime64('1979-03-22').dtypedtype('datetime64[us]')# NumPy 1.7.0, unit of days detected from string>>>np.datetime64('1979-03-22').dtypedtype('<M8[D]')# NumPy 1.6.1, ignores invalid part of string>>>np.datetime64('1979-03-2corruptedstring')1979-03-0200:00:00# NumPy 1.7.0, raises error for invalid input>>>np.datetime64('1979-03-2corruptedstring')Traceback(mostrecentcalllast):File"<stdin>",line1,in<module>ValueError:Errorparsingdatetimestring"1979-03-2corruptedstring"atposition8# NumPy 1.6.1, 'nat' produces today's date>>>np.datetime64('nat')2012-04-3000:00:00# NumPy 1.7.0, 'nat' produces not-a-time>>>np.datetime64('nat')numpy.datetime64('NaT')# NumPy 1.6.1, 'garbage' produces today's date>>>np.datetime64('garbage')2012-04-3000:00:00# NumPy 1.7.0, 'garbage' raises an exception>>>np.datetime64('garbage')Traceback(mostrecentcalllast):File"<stdin>",line1,in<module>ValueError:Errorparsingdatetimestring"garbage"atposition0# NumPy 1.6.1, can't specify unit in scalar constructor>>>np.datetime64('1979-03-22T19:00','h')Traceback(mostrecentcalllast):File"<stdin>",line1,in<module>TypeError:functiontakesatmost1argument(2given)# NumPy 1.7.0, unit in scalar constructor>>>np.datetime64('1979-03-22T19:00','h')numpy.datetime64('1979-03-22T19:00-0500','h')# NumPy 1.6.1, reads ISO 8601 strings w/o TZ as UTC>>>np.array(['1979-03-22T19:00'],dtype='M8[h]')array([1979-03-2219:00:00],dtype=datetime64[h])# NumPy 1.7.0, reads ISO 8601 strings w/o TZ as local (ISO specifies this)>>>np.array(['1979-03-22T19:00'],dtype='M8[h]')array(['1979-03-22T19-0500'],dtype='datetime64[h]')# NumPy 1.6.1, doesn't parse all ISO 8601 strings correctly>>>np.array(['1979-03-22T12'],dtype='M8[h]')array([1979-03-2200:00:00],dtype=datetime64[h])>>>np.array(['1979-03-22T12:00'],dtype='M8[h]')array([1979-03-2212:00:00],dtype=datetime64[h])# NumPy 1.7.0, handles this case correctly>>>np.array(['1979-03-22T12'],dtype='M8[h]')array(['1979-03-22T12-0500'],dtype='datetime64[h]')>>>np.array(['1979-03-22T12:00'],dtype='M8[h]')array(['1979-03-22T12-0500'],dtype='datetime64[h]')
The 1.6 implementation of datetime does not convert between units correctly.:
# NumPy 1.6.1, the representation value is untouched>>>np.array(['1979-03-22'],dtype='M8[D]')array([1979-03-2200:00:00],dtype=datetime64[D])>>>np.array(['1979-03-22'],dtype='M8[D]').astype('M8[M]')array([2250-08-0100:00:00],dtype=datetime64[M])# NumPy 1.7.0, the representation is scaled accordingly>>>np.array(['1979-03-22'],dtype='M8[D]')array(['1979-03-22'],dtype='datetime64[D]')>>>np.array(['1979-03-22'],dtype='M8[D]').astype('M8[M]')array(['1979-03'],dtype='datetime64[M]')
The 1.6 implementation of datetime only works correctly for a small subset ofarithmetic operations. Here we show some simple cases.:
# NumPy 1.6.1, produces invalid results if units are incompatible>>>a=np.array(['1979-03-22T12'],dtype='M8[h]')>>>b=np.array([3*60],dtype='m8[m]')>>>a+barray([1970-01-0100:00:00.080988],dtype=datetime64[us])# NumPy 1.7.0, promotes to higher-resolution unit>>>a=np.array(['1979-03-22T12'],dtype='M8[h]')>>>b=np.array([3*60],dtype='m8[m]')>>>a+barray(['1979-03-22T15:00-0500'],dtype='datetime64[m]')# NumPy 1.6.1, arithmetic works if everything is microseconds>>>a=np.array(['1979-03-22T12:00'],dtype='M8[us]')>>>b=np.array([3*60*60*1000000],dtype='m8[us]')>>>a+barray([1979-03-2215:00:00],dtype=datetime64[us])# NumPy 1.7.0>>>a=np.array(['1979-03-22T12:00'],dtype='M8[us]')>>>b=np.array([3*60*60*1000000],dtype='m8[us]')>>>a+barray(['1979-03-22T15:00:00.000000-0500'],dtype='datetime64[us]')