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 datetime.date 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 = ts.now('D') - 1
>>> infivemonths = ts.now('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
365

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.

Tip

Here we should list the formats...

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

Attributes

Base attributes

value

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

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

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
Date.year
 Year ...
Date.qyear
 Quarter Year (1) ...
Date.quarter
 Quarter [1-4]
Date.month
 Month [1-12]
Date.week
 Week number [1-53]
Date.day
 Day of the month [1-31]
Date.day_of_week
 Day of the week, starting Monday [0-6]
Date.weekday
    
Date.day_of_year
 Day of the year, starting Jan-01 [1-366]
Date.hour
 Hour [00-23]
Date.minute
 Minute [00-59]
Date.second
 Seconds [00-59]

Note

  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

Date.freq

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

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

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

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

Methods

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:

scikits.timeseries.now(freq) Returns the current date/time, at the given frequency
scikits.timeseries.prevbusday([...]) Returns the previous business day (Monday-Friday) at business frequency.