Changeset 1208

Show
Ignore:
Timestamp:
08/08/08 10:24:48 (4 months ago)
Author:
pierregm
Message:

doc formatting

Files:

Legend:

Unmodified
Added
Removed
Modified
Copied
Moved

  • trunk/timeseries/scikits/timeseries/src/c_dates.c

    r1163 r1208  
    16951695static char DateObject_strftime_doc[] = 
    16961696"Returns string representation of Date object according to format specified.\n\n" 
    1697 "*Parameters*:\n" 
    1698 "   fmt : {str}\n" 
    1699 "       Formatting string. Uses the same directives as in the time.strftime\n" 
    1700 "       function in the standard Python time module. In addition, a few other\n" 
    1701 "       directives are supported:\n" 
    1702 "           %q -  the 'quarter' of the date\n" 
    1703 "           %f -  Year without century as a decimal number [00,99]. The\n" 
    1704 "                 'year' in this case is the year of the date determined by\n" 
    1705 "                 the year for the current quarter. This is the same as %y\n" 
    1706 "                 unless the Date is one of the 'qtr-s' frequencies\n" 
    1707 "           %F -  Year with century as a decimal number. The 'year' in this\n" 
    1708 "                 case is the year of the date determined by the year for\n" 
    1709 "                 the current quarter. This is the same as %Y unless the\n" 
    1710 "                 Date is one of the 'qtr-s' frequencies\n"; 
     1697"Parameters\n" 
     1698"----------\n" 
     1699"fmt : {str}\n" 
     1700"   Formatting string. Uses the same directives as in the time.strftime\n" 
     1701"   function in the standard Python time module. In addition, a few other\n" 
     1702"   directives are supported:\n" 
     1703"   '%q' - the 'quarter' of the date\n" 
     1704"   '%f' - Year without century as a decimal number [00,99]. The\n" 
     1705"          'year' in this case is the year of the date determined by\n" 
     1706"          the year for the current quarter. This is the same as %y\n" 
     1707"          unless the Date is one of the 'qtr-s' frequencies\n" 
     1708"   '%F' - Year with century as a decimal number. The 'year' in this\n" 
     1709"          case is the year of the date determined by the year for\n" 
     1710"          the current quarter. This is the same as %Y unless the\n" 
     1711"          Date is one of the 'qtr-s' frequencies\n"; 
    17111712static PyObject * 
    17121713DateObject_strftime(DateObject *self, PyObject *args) 

  • trunk/timeseries/scikits/timeseries/tdates.py

    r1204 r1208  
    109109    ----- 
    110110    If it is currently Saturday or Sunday, then the preceding Friday will be 
    111     returned. If it is later than the specified day_end_hour and day_end_min, 
    112     now('Business') will be returned. Otherwise, now('Business')-1 will be 
    113     returned. 
     111    returned. If it is later than the specified ``day_end_hour`` and ``day_end_min``, 
     112    ``now('Business')`` will be returned.  
     113    Otherwise, ``now('Business')-1`` will be returned. 
    114114 
    115115    """ 
    …… 
    185185    When viewed element-wise, DateArray is a sequence of dates. 
    186186    For example, a test such as : 
     187     
    187188    >>> DateArray(...) = value 
     189     
    188190    will be valid only if value is an integer, not a Date 
    189191    However, a loop such as : 
     192     
    190193    >>> for d in DateArray(...): 
     194     
    191195    accesses the array element by element. Therefore, `d` is a Date object. 
    192196    """ 
    …… 
    643647    Parameters 
    644648    ---------- 
    645     dlist : {list of dates or DateArray} (optional) 
    646         may be a list of dates, integer representations of dates for a given 
    647         frequency, datetime objects, or an existing DateArray. If specifying 
    648         a list of dates, you must also specify the `freq` parameter. 
    649  
    650     start_date : {Date} (optional) 
    651         if you want a continuous DateArray, specify a start_date and either an 
    652         `end_date` or a `length`. Frequency of the resulting DateArray will be 
    653         automatically determined based on the frequency of this parameter. 
    654  
     649    dlist : {sequence, DateArray}, optional 
     650        A list of dates, integer representations of dates for a given 
     651        frequency, datetime objects, or an existing DateArray. 
     652        If `dlist` is a list of dates, the `freq` parameter must also be given. 
     653    start_date : {Date}, optional 
     654        First date of a continuous DateArray. 
     655        This parameter is used only if `dlist` is None. In that case, an ending 
     656        date (`end_date`) or the length of the array must be given. 
     657        The frequency of the output will be the frequency of this parameter. 
    655658    end_date : {Date} (optional) 
    656         last date in resulting DateArray. Specify this parameter or `length` 
     659        Last date of the output. Specify this parameter or `length` 
    657660        in combination with `start_date` for a continuous DateArray. 
    658  
    659661    length : {int} (optional) 
    660         the length of the resulting DateArray. Specify this parameter or 
     662        Length of the output. Specify this parameter or 
    661663        `end_date` in combination with `start_date` for a continuous DateArray. 
     664 
     665    Returns 
     666    ------- 
     667    A :class:`DateArray` object 
    662668    """ 
    663669    freq = check_freq(freq) 

  • trunk/timeseries/scikits/timeseries/tseries.py

    r1204 r1208  
    11""" 
    2 The `TimeSeries` class provides  a base for the definition of time series. 
     2The :class:`TimeSeries` class provides  a base for the definition of time series. 
    33A time series is defined here as the combination of two arrays: 
    44 
    5     - an array storing the time information (as a `DateArray` instance); 
    6     - an array storing the data (as a `MaskedArray` instance.) 
     5- an array storing the time information (as a `DateArray` instance); 
     6- an array storing the data (as a `MaskedArray` instance.) 
    77 
    88These two classes were liberally adapted from `MaskedArray` class. 
     9 
    910 
    1011:author: Pierre GF Gerard-Marchant & Matt Knox 
    …… 
    280281##### ------------------------------------------------------------------------ 
    281282class _tsmathmethod(object): 
    282     """Defines a wrapper for arithmetic array methods (add, mul...). 
    283 When called, returns a new TimeSeries object, with the new series the result 
    284 of the method applied on the original series. The `_dates` part remains 
    285 unchanged. 
    286 """ 
     283    """ 
     284    Defines a wrapper for arithmetic array methods (add, mul...). 
     285    When called, returns a new TimeSeries object, with the new series the result 
     286    of the method applied on the original series. The `_dates` part remains 
     287    unchanged. 
     288    """ 
    287289    def __init__ (self, methodname): 
    288         self._name = self.__name__ = methodname 
     290        self.__name__ = methodname 
     291        self.__doc__ = getattr(MaskedArray, methodname).__doc__ 
    289292        self.obj = None 
    290293 
    …… 
    301304        else: 
    302305            compat = True 
    303         func = getattr(super(TimeSeries, instance), self._name) 
     306        func = getattr(super(TimeSeries, instance), self.__name__) 
    304307        if compat: 
    305308            result = np.array(func(other, *args), subok=True).view(type(instance)) 
    …… 
    320323""" 
    321324    def __init__ (self, methodname, ondates=False): 
    322         """abfunc(fillx, filly) must be defined. 
    323            abinop(x, filly) = x for all x to enable reduce. 
    324         """ 
    325         self._name = self.__name__ = methodname 
     325        self.__name__ = methodname 
     326        self.__doc__ = getattr(MaskedArray, methodname).__doc__ 
    326327        self._ondates = ondates 
    327328        self.obj = None 
    …… 
    333334    def __call__ (self, *args): 
    334335        "Execute the call behavior." 
    335         _name = self._name 
     336        _name = self.__name__ 
    336337        instance = self.obj 
    337338        func_series = getattr(super(TimeSeries, instance), _name) 
    …… 
    355356           abinop(x, filly) = x for all x to enable reduce. 
    356357        """ 
    357         self._name = self.__name__ = methodname 
     358        self.__name__ = methodname 
     359        self.__doc__ = getattr(MaskedArray, methodname).__doc__ 
    358360        self.obj = None 
    359361 
    …… 
    365367        "Execute the call behavior." 
    366368        (_dates, _series) = (self.obj._dates, self.obj._series) 
    367         func = getattr(_series, self._name) 
     369        func = getattr(_series, self.__name__) 
    368370        result = func(*args, **params) 
    369371        if _dates.size == _series.size: 
    …… 
    383385 
    384386class TimeSeries(MaskedArray, object): 
    385     """Base class for the definition of time series. 
    386  
    387     A time series is here defined as the combination of two arrays: 
    388     * series : {MaskedArray} 
    389         Data part 
    390     * dates : {DateArray} 
    391          Date part 
    392  
    393 *Construction*: 
     387    """ 
     388    Base class for the definition of time series. 
     389 
     390 
     391    Parameters 
     392    ---------- 
    394393    data : {array_like} 
    395         data portion of the array. Any data that is valid for constructing a 
    396         MaskedArray can be used here. 
     394        Data portion of the array.  
     395        Any data that is valid for constructing a MaskedArray can be used here. 
    397396    dates : {DateArray} 
    398  
    399 *Other Parameters*: 
    400     all other parameters are the same as for MaskedArray. Please see the 
    401     documentation for the MaskedArray class in the numpy.ma module 
    402     for details. 
    403  
    404 *Notes*: 
    405     it is typically recommended to use the `time_series` function for 
    406     construction as it allows greater flexibility and convenience. 
    407 """ 
     397        A :class:`DateArray` instance. 
     398 
     399    Other Parameters 
     400    ---------------- 
     401    All other parameters are the same as for MaskedArray.  
     402    Please refer to the documentation for the :class:`MaskedArray` class in the  
     403    :mod:`numpy.ma` module for details. 
     404 
     405    Notes 
     406    ----- 
     407    It is recommended to use the `time_series` function for construction, 
     408    as it is more flexibile and convenient. 
     409 
     410    """ 
    408411    def __new__(cls, data, dates, mask=nomask, dtype=None, copy=False, 
    409412                fill_value=None, subok=True, keep_mask=True, hard_mask=False, 
    …… 
    716719    mean = _tsaxismethod('mean') 
    717720    var = _tsaxismethod('var') 
    718     varu = _tsaxismethod('varu') 
    719721    std = _tsaxismethod('std') 
    720     stdu = _tsaxismethod('stdu') 
    721722    all = _tsaxismethod('all') 
    722723    any = _tsaxismethod('any') 
    …… 
    874875    #..................................................... 
    875876    def asfreq(self, freq, relation="END"): 
    876         """Converts the dates portion of the TimeSeries to another frequency. 
    877  
    878 The resulting TimeSeries will have the same shape and dimensions as the 
    879 original series (unlike the `convert` method). 
     877        """ 
     878    Converts the dates portion of the TimeSeries to another frequency. 
     879 
     880    The resulting TimeSeries will have the same shape and dimensions as the 
     881    original series (unlike the `convert` method). 
    880882 
    881883    Parameters 
    …… 
    886888    Returns 
    887889    ------- 
    888     A new TimeSeries with the .dates DateArray at the specified frequency (the 
    889     `.asfreq` method of the .dates property will be called). The data in the 
    890     resulting series will be a VIEW of the original series. 
     890    TimeSeries: 
     891        A new TimeSeries with the :attr:`.dates` :class:`DateArray` at the  
     892        specified frequency (the :meth`.asfreq` method of the :attr:`.dates`  
     893        property will be called). 
     894        The data in the resulting series will be a VIEW of the original series. 
    891895 
    892896    Notes 
    893897    ----- 
    894     The parameters are the exact same as for DateArray.asfreq , please see the 
    895     __doc__ string for that method for details on the parameters and how the 
    896     actual conversion is performed. 
    897 """ 
     898    The parameters are the exact same as for :meth:`DateArray.asfreq`, please  
     899    see the `__doc__` string for that method for details on the parameters and  
     900    how the actual conversion is performed. 
     901 
     902    """ 
    898903        if freq is None: return self 
    899904 
    …… 
    945950    def filled(self, fill_value=None): 
    946951        """ 
    947  
    948952    Returns an array of the same class as `_data`,  with masked values 
    949953    filled with `fill_value`. Subclassing is preserved. 
    …… 
    954958        The value to fill in masked values with. 
    955959        If `fill_value` is None, uses self.fill_value. 
    956 """ 
     960 
     961    """ 
    957962        result = self._series.filled(fill_value=fill_value).view(type(self)) 
    958963        result._dates = self._dates 
    …… 
    963968    Returns the dates and data portion of the TimeSeries "zipped" up in 
    964969    a list of standard python objects (eg. datetime, int, etc...). 
    965      
    966         """ 
     970 
     971    """ 
    967972        if self.ndim > 0: 
    968973            return zip(self.dates.tolist(), self.series.tolist()) 
    …… 
    11281133    """ 
    11291134    def __init__(self, methodname): 
    1130         self._methodname = methodname 
     1135        self.__name__ = methodname 
    11311136        self.__doc__ = self.getdoc() 
    11321137    def getdoc(self): 
    11331138        "Returns the doc of the function (from the doc of the method)." 
    11341139        try: 
    1135             return getattr(TimeSeries, self._methodname).__doc__ 
     1140            return getattr(TimeSeries, self.__name__).__doc__ 
    11361141        except: 
    11371142            return "???" 
    11381143    # 
    11391144    def __call__ (self, caller, *args, **params): 
    1140         if hasattr(caller, self._methodname): 
    1141             method = getattr(caller, self._methodname) 
     1145        if hasattr(caller, self.__name__): 
     1146            method = getattr(caller, self.__name__) 
    11421147            # If method is not callable, it's a property, and don't call it 
    11431148            if hasattr(method, '__call__'): 
    11441149                return method.__call__(*args, **params) 
    11451150            return method 
    1146         method = getattr(np.asarray(caller), self._methodname) 
     1151        method = getattr(np.asarray(caller), self.__name__) 
    11471152        try: 
    11481153            return method(*args, **params) 
    11491154        except SystemError: 
    1150             return getattr(np,self._methodname).__call__(caller, *args, **params) 
     1155            return getattr(np,self.__name__).__call__(caller, *args, **params) 
    11511156#............................ 
    11521157weekday = _frommethod('weekday') 
    …… 
    11671172#---- ... Additional methods ... 
    11681173##### --------------------------------------------------------------------------- 
    1169 def tofile(self, fileobject, format=None, 
     1174def tofile(series, fileobject, format=None, 
    11701175           separator=" ", linesep='\n', precision=5, 
    11711176           suppress_small=False, keep_open=False): 
    1172     """Writes the TimeSeries to a file. The series should be 2D at most 
    1173  
    1174 *Parameters*: 
     1177    """ 
     1178    Writes the TimeSeries to a file. The series should be 2D at most. 
     1179 
     1180    Parameters 
     1181    ---------- 
    11751182    series : {TimeSeries} 
    11761183        The array to write. 
    1177     fileobject: 
     1184    fileobject 
    11781185        An open file object or a string to a valid filename. 
    1179     format : {string} 
    1180         Format string for the date. If None, uses the default date format. 
    1181     separator : {string} 
     1186    format : {None, string}, optional 
     1187        Format string for the date. 
     1188        If None, uses the default date format. 
     1189    separator : {string}, optional 
    11821190        Separator to write between elements of the array. 
    1183     linesep : {string} 
     1191    linesep : {string}, optional 
    11841192        Separator to write between rows of array. 
    1185     precision : {integer} 
     1193    precision : {integer}, optional 
    11861194        Number of digits after the decimal place to write. 
    1187     suppress_small : {boolean} 
     1195    suppress_small : {boolean}, optional 
    11881196        Whether on-zero to round small numbers down to 0.0 
    1189     keep_open : {boolean} 
     1197    keep_open : {boolean}, optional 
    11901198        Whether to close the file or to return the open file. 
    11911199 
    1192 *Returns*: 
     1200    Returns 
     1201    ------- 
    11931202    file : {file object} 
    11941203        The open file (if keep_open is non-zero) 
    …… 
    12001209        raise ImportError("scipy is required for the tofile function/method") 
    12011210 
    1202     (_dates, _data) = (self._dates, self._series) 
     1211    (_dates, _data) = (series._dates, series._series) 
    12031212    optpars = dict(separator=separator,linesep=linesep,precision=precision, 
    12041213                   suppress_small=suppress_small,keep_open=keep_open) 
    …… 
    12251234#............................................ 
    12261235def asrecords(series): 
    1227     """Returns the masked time series as a recarray. 
    1228 Fields are `_dates`, `_data` and _`mask`. 
    1229         """ 
     1236    """ 
     1237    Returns the time series as a recarray. 
     1238 
     1239    Fields are ``_dates``, ``_data`` and ``_mask``. 
     1240 
     1241    """ 
    12301242    desctype = [('_dates',int_), ('_series',series.dtype), ('_mask', bool_)] 
    12311243    flat = series.ravel() 
    …… 
    12431255 
    12441256def flatten(series): 
    1245     """Flattens a (multi-) time series to 1D series.""" 
     1257    """ 
     1258    Flattens a (multi-) time series to 1D series. 
     1259 
     1260    """ 
    12461261    shp_ini = series.shape 
    12471262    # Already flat time series.... 
    …… 
    12561271    newseries = series._series.reshape(newshape) 
    12571272    return time_series(newseries, newdates) 
     1273 
    12581274TimeSeries.flatten = flatten 
    12591275 
    …… 
    12641280                dtype=None, copy=False, fill_value=None, keep_mask=True, 
    12651281                hard_mask=False): 
    1266     """Creates a TimeSeries object 
     1282    """ 
     1283    Creates a TimeSeries object 
    12671284 
    12681285    Parameters 
    …… 
    12801297        A valid frequency specification 
    12811298 
    1282 *Other Parameters*: 
    1283     All other parameters that are accepted by the *array* function in the 
    1284     numpy.ma module are also accepted by this function. 
    1285  
    1286 *Notes*: 
    1287     the date portion of the time series must be specified in one of the 
     1299    Other Parameters 
     1300    ---------------- 
     1301    All other parameters that are accepted by the :func:`numpy.ma.array` function  
     1302    in the :mod:`numpy.ma` module are also accepted by this function. 
     1303 
     1304    Notes 
     1305    ----- 
     1306    The date portion of the time series must be specified in one of the 
    12881307    following ways: 
    1289         - specify a TimeSeries object for the *data* parameter 
    1290         - pass a DateArray for the *dates* parameter 
     1308        - specify a TimeSeries object for the `data` parameter 
     1309        - pass a DateArray for the `dates` parameter 
    12911310        - specify a start_date (a continuous DateArray will be automatically 
    12921311          constructed for the dates portion) 
    12931312        - specify just a frequency (for TimeSeries of size zero) 
    1294 """ 
     1313 
     1314    """ 
    12951315    maparms = dict(copy=copy, dtype=dtype, fill_value=fill_value, subok=True, 
    12961316                   keep_mask=keep_mask, hard_mask=hard_mask,) 
    …… 
    15521572 
    15531573def convert(series, freq, func=None, position='END', *args, **kwargs): 
    1554     """Converts a series to a frequency. Private function called by convert 
     1574    """Converts a series from one frequency to another. 
    15551575 
    15561576    Parameters 
    …… 
    15631583        specification (string or integer) 
    15641584    func : {None,function}, optional 
    1565         When converting to a lower frequency, func is a function that acts on 
    1566         one date's worth of data. func should handle masked values appropriately. 
    1567         If func is None, then each data point in the resulting series will a 
     1585        When converting to a lower frequency, `func` is a function that acts on 
     1586        one date's worth of data. `func` should handle masked values appropriately. 
     1587        If `func` is None, then each data point in the resulting series will a 
    15681588        group of data points that fall into the date at the lower frequency. 
    15691589 
    …… 
    18391859 
    18401860def concatenate(series, axis=0, remove_duplicates=True, fill_missing=False): 
    1841     """Joins series together. 
    1842  
    1843 The series are joined in chronological order. Duplicated dates are handled with 
    1844 the `remove_duplicates` parameter. If remove_duplicate=False, duplicated dates are 
    1845 saved. Otherwise, only the first occurence of the date is conserved. 
    1846  
    1847 Example 
    1848 >>> a = time_series([1,2,3], start_date=now('D')) 
    1849 >>> b = time_series([10,20,30], start_date=now('D')+1) 
    1850 >>> c = concatenate((a,b)) 
    1851 >>> c._series 
    1852 masked_array(data = [ 1  2  3 30], 
    1853       mask = False, 
    1854       fill_value=999999) 
     1861    """ 
     1862    Joins series together. 
     1863 
     1864    The series are joined in chronological order. 
     1865    Duplicated dates are handled with the `remove_duplicates` parameter.  
     1866    If `remove_duplicate` is False, duplicated dates are saved.  
     1867    Otherwise, only the first occurence of the date is conserved. 
    18551868 
    18561869 
    …… 
    18651878    fill_missing : {False, True}, optional 
    18661879        Whether to fill the missing dates with missing values. 
     1880 
     1881    Example 
     1882    ------- 
     1883    >>> a = time_series([1,2,3], start_date=now('D')) 
     1884    >>> b = time_series([10,20,30], start_date=now('D')+1) 
     1885    >>> c = concatenate((a,b)) 
     1886    >>> c._series 
     1887    masked_array(data = [ 1  2  3 30], 
     1888          mask = False, 
     1889          fill_value=999999) 
     1890 
    18671891    """ 
    18681892    # Get the common frequency, raise an error if incompatibility