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
scikits.timeseries.prevbusday