Based on numpy.ndarray.
Defines a ndarray of dates, as ordinals. The dates parameter must then be a sequence of Date objects or a sequence of integers. The freq parameter must be a valid frequency specification, as listed in the Frequency constants section.
When viewed globally (array-wise), a DateArray object behaves as an ndarray of integers. When viewed element-wise, DateArray behaves as a standard sequence of Date objects.
Thus, a test such as:
>>> DateArray(...) == value
is valid only if value is an integer, not a Date object. In that case, the test returns a boolean ndarray that has the same shape as the DateArray object.
However, a loop such as :
>>> for d in DateArray(...):
The only requirement for the Date elements of a DateArray is that they must have the same frequency. Otherwise, they do not have to be in chronological order nor to be regularly spaced, and duplicated entries are also permitted.
A DateArray object can be created simply by calling the class with the required inputs. However, the recommended method is to use the date_array factory function.
Factory function for constructing a DateArray.
| Parameters: | dlist : {sequence, DateArray}, optional
start_date : {var}, optional
end_date : {var}, optional
length : {int}, optional
autosort : {True, False}, optional
|
|---|---|
| Returns: | output : DateArray object. |
Notes
As subclasses of ndarray, DateArray objects follow the same rules for accessing elements through indexing. In addition, DateArray objects can be indexed with one or several Date objects.
When a single element of a DateArray is accessed, the result is a Date object with the same frequency as the input. Otherwise, the result is a DateArray with the same frequency as the input. Note that when using a slice to access specific elements of a DateArray, the result is always a DateArray.
>>> dates = ts.date_array(start_date=ts.Date('M', '2001-01'), length=36)
>>> # Accessing a single element with an integer
>>> dates[0]
<M : Jan-2001>
>>> # Accessing a single element with a Date object
>>> dates[ts.Date('M', '2002-01')]
<M : Jan-2002>
>>> # Using a slice to access a single element : the result is a DateArray
>>> dates[-1:]
DateArray([Dec-2003],
freq='M')
>>> # Accessing multiple elements with a list of integers
>>> dates[[0, 12, 24]]
DateArray([Jan-2001, Jan-2002, Jan-2003],
freq='M')
>>> # Accessing multiple elements with a list of Date objects
>>> dates[[ts.Date('M', '2002-01'), ts.Date('M', '2003-01')]]
DateArray([Jan-2002, Jan-2003],
freq='M')
Arithmetic operations on DateArray objects are limited to additions and subtractions. Any other arithmetic operation will raise a ArithmeticDateError exception.
Adding (subtracting) a scalar or a sequence of scalars to (from) a DateArray returns a DateArray with the same frequency. The shapes of the inputs must be compatible, as described in the broadcasting section of the Numpy documentation.
Adding (subtracting) two DateArray or a DateArray and a Date is possible only if the two objects have the same frequency. The result is then a ndarray. If the inputs do not share the same frequency, a FrequencyDateError exception is raised.
All the comparison operations involving the standard Python operators (==, <, >, <=, >=, !=) or their method equivalents are supported between a DateArray and:
In the last two cases, the objects must have the same frequency, or a FrequencyDateError is raised. If the other input is a sequence, its shape must be compatible with the shape of the DateArray.
In every case, the result is then an array of booleans, with the same shape as the input.
In addition, it is possible to check whether a single Date object or its equivalent integer value is contained in a DateArray with the in operator or its method equivalent DateArray.__contains__.
Because DateArray objects are subclasses of ndarray, they inherit all its attributes, as describe in the Numpy documentation.
In addition, they have the specific following attributes.
The following attributes give some information about the dates. They are read-only.
| Name | Description | Range |
|---|---|---|
| Integer ndarrays, with the same size as the instance. | ||
|
Year | ... |
|
Quarter Year (1) | ... |
|
Quarter | [1-4] |
|
Month | [1-12] |
|
Week | [1-53] |
|
Day of the month | [1-31] |
|
Day of the week, starting Monday | [0-6] |
|
Day of the year, starting Jan-01 | [1-366] |
|
Hour | [00-23] |
|
Minute | [00-59] |
|
Seconds | [00-59] |
| Single Date objects, with the same frequency as the instance | ||
|
First date of the series (in chronological order). | |
|
Last date of the series (in chronological order). | |
Warning
The following attributes are private and are not meant to be used directly by a user. They are reported here for the sake of completeness.
The _cachedinfo attribute is a directory storing some information about the instance. It has the following keys:
'toobj' : {None, ndarray}
Because DateArray objects are subclasses of ndarray, they inherit their methods, as described in the Numpy documentation.
In addition, they accept the following specific methods.
The following methods give some information about the distribution of dates. They do not need any argument.
|
Returns the time steps between consecutive dates, in the same unit as the instance frequency. |
|
Returns whether the instance has missing dates. |
|
Returns whether the instance has duplicated dates. |
|
Returns whether the instance has no missing dates. |
|
Returns whether the instance is valid (that there are no missing nor duplicated dates). |
|
Returns whether the instance is sorted in chronological order. |
These methods allow the user to access specific elements of a DateArray by directly giving a date instead of an integer.
| DateArray.date_to_index | |
| DateArray.find_dates |
| DateArray.tovalue | |
| DateArray.tofloat | |
| DateArray.toordinal | |
| DateArray.tostring | |
| DateArray.tolist |
| DateArray.asfreq |
| DateArray.sort_chronologically |
| period_break | |
| convert_to_float |