.. currentmodule:: scikits.timeseries .. index:: single: Date ===================== :class:`Date` objects ===================== Even if you have no use for time series in general, you may still find the :class:`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, :class:`Date` objects are stored internally as integers. The conversion to integers and back is controlled by the frequency. For example, a :class:`Date` object with a daily frequency corresponds to the gregorian proleptic date, the number of days since January 1st, 1AD; a :class:`Date` with a monthly frequency corresponds to the number of months since January 1AD, and so forth. Details about the creation of a :class:`Date` object are presented in a following `section `_. .. _dates_creation: Construction of a :class:`Date` object ====================================== Several options are available to construct a :class:`Date` object explicitly. In each case, the frequency must be specified with the :keyword:`freq` argument. Valid frequency specifications are listed in the :ref:`date_frequencies` section. * Give appropriate values to any of the :keyword:`year`, :keyword:`month`, :keyword:`day`, :keyword:`quarter`, :keyword:`hour`, :keyword:`minute` or :keyword:`second` arguments. >>> ts.Date(freq='Q',year=2004,quarter=3) >>> ts.Date(freq='D',year=2001,month=1,day=1) 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 :keyword:`day` input parameter with a quarterly frequency ``'Q'``. * Use the :keyword:`string` keyword. This method uses a modified version of the :mod:`mx.DateTime` parser sub-module. More information is available in its `documentation `_. >>> ts.Date('D', string='2007-01-01') * Use the :keyword:`datetime` keyword with an existing :class:`datetime.datetime` or :class:`datetime.date` object. >>> ts.Date('D', datetime=datetime.datetime(2007, 1, 1, 17, 0)) * Use the :keyword:`value` keyword and provide an integer representation of the date. >>> ts.Date('D', value=732677) >>> ts.Date('M', value=(12*2008+6)) >>> ts.Date('Y', value=2007) Manipulating :class:`Date` objects ================================== Arithmetic operations --------------------- Integers can be added to or subtracted from a :class:`Date` object to get a new :class:`Date` object. The frequency of the result is the same as the frequency of the :class:`Date` input:: >>> yesterday = ts.now('D') - 1 >>> infivemonths = ts.now('M') + 5 A :class:`Date` object can also be subtracted from another :class:`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 :class:`Date` objects have different frequencies, a :exc:`ValueError` exception is raised. Comparison operations --------------------- :class:`Date` objects can be compared to integers or other :class:`Date` objects of the same frequency, using the basic Python comparison operators (``==``, ``<``, ``>``, ``<=``, ``>=``, ``!=``) or their method equivalents. If two :class:`Date` objects of different frequency are compared, a :exc:`ValueError` exception is raised. Formatting :class:`Dates` as strings ------------------------------------ A :class:`Date` object can simply be casted to a string with the Python function :func:`str`. A default output format for that frequency will then be used. .. tip:: Here we should list the formats... Alternatively, the :meth:`~Date.strftime` method can be used for explicit control. Attributes ========== Base attributes --------------- .. attribute:: value Returns the integer coding the :class:`Date` object. This attribute is read-only. >>> ts.Date('D','2001-01-01').value 730486 .. attribute:: datetime Returns the object as a :class:`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. .. .. tabularcolumns:: |l|l|c| .. only:: html +-----------------------------------+----------------------------------+---------+ | Name | Description | Range | +===================================+==================================+=========+ | .. attribute:: Date.year | Year | ... | +-----------------------------------+----------------------------------+---------+ | .. attribute:: Date.qyear | Quarter Year (1) | ... | +-----------------------------------+----------------------------------+---------+ | .. attribute:: Date.quarter | Quarter | [1-4] | +-----------------------------------+----------------------------------+---------+ | .. attribute:: Date.month | Month | [1-12] | +-----------------------------------+----------------------------------+---------+ | .. attribute:: Date.week | Week number | [1-53] | +-----------------------------------+----------------------------------+---------+ | .. attribute:: Date.day | Day of the month | [1-31] | +-----------------------------------+----------------------------------+---------+ | .. attribute:: Date.day_of_week | Day of the week, starting Monday | [0-6] | +-----------------------------------+----------------------------------+---------+ | .. attribute:: Date.weekday | | | +-----------------------------------+----------------------------------+---------+ | .. attribute:: Date.day_of_year | Day of the year, starting Jan-01 | [1-366] | +-----------------------------------+----------------------------------+---------+ | .. attribute:: Date.hour | Hour | [00-23] | +-----------------------------------+----------------------------------+---------+ | .. attribute:: Date.minute | Minute | [00-59] | +-----------------------------------+----------------------------------+---------+ | .. attribute:: Date.second | Seconds | [00-59] | +-----------------------------------+----------------------------------+---------+ .. note:: (1) For :class:`Date` objects with a quarterly frequency, :attr:`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 --------------------- .. attribute:: Date.freq Frequency of the :class:`Date` object, as an integer. This attribute is read-only. >>> ts.Date('D', '2001-01-01').freq 6000 .. attribute:: Date.freqstr Frequency of the :class:`Date` object, as a string. This attribute is read-only. >>> ts.Date('D', '2001-01-01').freqstr 'D' Methods ======= ============================== =================================================== :meth:`Date.strftime` (format) Returns a string representation of the instance, according to :keyword:`format`. :meth:`Date.toordinal` () Returns the proleptic Gregorian date as an ordinal. :meth:`Date.asfreq` (freq) Returns a new :class:`Date` object with frequency :keyword:`freq`. ============================== =================================================== .. _date_function : Convenience functions ===================== Two convenience functions are provided to access the current date: .. autosummary:: scikits.timeseries.now scikits.timeseries.prevbusday