If possible, it is recommended to use the numpy.ma function instead of its standard numpy counterpart. The reason is that the reduce and accumulate methods of most numpy.ufuncs (such as add or multiply) cannot properly handle masked values.
When applied to a TimeSeries, unary functions that operate on a whole array at once (like numpy.sum) return a scalar or the numpy.ma.masked constant, depending on whether some entries are not invalid or if all the entries are masked. If the function can be applied on an axis, the result is a MaskedArray.
Unary functions that operate element-wise on an array (like numpy.log) return a new TimeSeries object with the same dates and frequency as the input, and whose series attribute is the result of the operation on the input series.
Output values are masked if the corresponding input values are themselves masked, or if they fall outside the validity domain of the operation.
>>> s = ts.time_series([-2, -1, 0, 1, 2, 3], mask=[0, 0, 0, 0, 1, 0] ... start_date=ts.Date('M','2001-01')) >>> logs = ma.log(s) >>> logs timeseries([-- -- -- 0.0 -- 1.09861228867], dates = [Jan-2001 ... Jun-2001], freq = M)
In the previous example, logs[-2] is masked because s[-2] is itself masked; logs[:3] is masked because s[:3] <= 0.
The binary operations defined in numpy or numpy.ma can also be directly applied to TimeSeries if the second input is a scalar, a sequence, a ndarray or a MaskedArray. The standard broadcasting rules about shape compatibility apply.
When the second input is another TimeSeries object, the two series must satisfy the following conditions:
- they must have the same frequency;
- they must be sorted in chronological order;
- they must have matching dates;
- they must have the same shape.
Note that the two series may have duplicated and/or missing dates.
The function align_series (or its alias aligned) forces series to have matching starting and ending dates. By default, the starting date will be set to the smallest starting date sof the series, and the ending date to the largest.
>>> a = ts.time_series([1, 2, 3], ... dates=[2001, 2002, 2003], freq='A') >>> b = ts.time_series([10, 20, 30], ... dates=[2001, 2002, 2003], freq='A') >>> a+b timeseries([11 22 33], dates = [2001 ... 2003], freq = A-DEC)
>>> b = ts.time_series([1,2,3], dates=[2001,2001,2003], freq='A') >>> a+b masked_array(data = [11 22 33], mask = False, fill_value = 999999)