Table Of Contents

Previous topic


Next topic

DateArray objects

This Page

Date objects

Even if you have no use for time series in general, you may still find the Date class contained in the module quite useful.

class Date(freq=frequency, *args)

Defines an object that combines some date- and/or time-related information with a given frequency. The frequency can be pictured as the unit into which the date is expressed.

In practice, Date objects are stored internally as integers. The conversion to integers and back is controlled by the frequency. For example, a Date object with a daily frequency corresponds to the gregorian proleptic date, the number of days since January 1st, 1AD; a Date with a monthly frequency corresponds to the number of months since January 1AD, and so forth.

Details about the creation of a Date object are presented in a following section.

Construction of a Date object

Several options are available to construct a Date object explicitly. In each case, the frequency must be specified with the freq argument. Valid frequency specifications are listed in the Frequency constants section.

  • Give appropriate values to any of the year, month, day, quarter, hour, minute or second arguments.

    >>> ts.Date(freq='Q',year=2004,quarter=3)
    <Q : 2004Q3>
    >>> ts.Date(freq='D',year=2001,month=1,day=1)
    <D : 01-Jan-2001>

    Note that there is only need to specify as much information as is relevant depending on the frequency. In the example above, there was no need to give a day input parameter with a quarterly frequency 'Q'.

  • Use the string keyword. This method uses a modified version of the mx.DateTime parser sub-module. More information is available in its documentation.

    >>> ts.Date('D', string='2007-01-01')
    <D : 01-Jan-2007>
  • Use the datetime keyword with an existing datetime.datetime or object.

    >>> ts.Date('D', datetime=datetime.datetime(2007, 1, 1, 17, 0))
    <D : 01-Jan-2007>
  • Use the value keyword and provide an integer representation of the date.

    >>> ts.Date('D', value=732677)
    <D : 01-Jan-2007>
    >>> ts.Date('M', value=(12*2008+6))
    <M : Jun-2009>
    >>> ts.Date('Y', value=2007)
    <A-DEC : 2008>

Manipulating Date objects

Arithmetic operations

Integers can be added to or subtracted from a Date object to get a new Date object. The frequency of the result is the same as the frequency of the Date input:

>>> yesterday ='D') - 1
>>> infivemonths ='M') + 5

A Date object can also be subtracted from another Date of the same frequency to calculate the number of periods between the two dates.

>>> Y = ts.Date('A', year=2007)
>>> Y_beg = Y.asfreq('D', relation='START')
>>> Y_end = Y.asfreq('D', relation='END')
>>> days_in_year = (Y_end - Y_beg + 1)
>>> days_in_year

If the two Date objects have different frequencies, a ValueError exception is raised.

Comparison operations

Date objects can be compared to integers or other Date objects of the same frequency, using the basic Python comparison operators (==, <, >, <=, >=, !=) or their method equivalents.

If two Date objects of different frequency are compared, a ValueError exception is raised.

Formatting Dates as strings

A Date object can simply be casted to a string with the Python function str. A default output format for that frequency will then be used.


Here we should list the formats...

Alternatively, the strftime method can be used for explicit control.


Base attributes


Returns the integer coding the Date object. This attribute is read-only.

>>> ts.Date('D','2001-01-01').value

Returns the object as a datetime.datetime object. This attribute is read-only.

>>> ts.Date('D','2001-01-01').datetime
datetime.datetime(2001, 1, 1, 0, 0)

Date information

The following attributes are read-only, with an integer type.

Name Description Range
Year ...
Quarter Year (1) ...
Quarter [1-4]
Month [1-12]
Week number [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]


  1. For Date objects with a quarterly frequency, qyear returns the year corresponding to the ending (starting) month of the year. When using QTR or QTR-E based quarterly frequencies, it correponds the fiscal year in a financial context. For non-quarterly frequencies, this simply returns the corresponding year.

Frequency information


Frequency of the Date object, as an integer. This attribute is read-only.

>>> ts.Date('D', '2001-01-01').freq

Frequency of the Date object, as a string. This attribute is read-only.

>>> ts.Date('D', '2001-01-01').freqstr


Date.strftime (format) Returns a string representation of the instance, according to format.
Date.toordinal () Returns the proleptic Gregorian date as an ordinal.
Date.asfreq (freq) Returns a new Date object with frequency freq.

Convenience functions

Two convenience functions are provided to access the current date: