SmartTimeSeries
A Smart TimeSeries is an expression that is used to build TimeSeries on demand
Introduction​
Smart TimeSeries are an easy but powerful way of defining TimeSeries derivations.
A Smart TimeSeries consists of the following:
Base TimeSeries​
The base TimeSeries is mandatory and can be either a real TimeSeries or another Smart TimeSeries.
The base TimeSeries is usually used in the expression using the variable name BASE.
Expression​
The expression is also mandatory and is a string formula used to build the TimeSeries.
- It can be a simple operation like
BASE*1.2 - It can use built-in functions like
scale(BASE, 'MONTHLY', 'summed') - It can use functions in the #TimeSeriesScript (if you have not specified a custom script) like
fill(BASE, 'LINEAR') - It can use your own functions in a specified custom script like
myfunction(BASE)
Script​
The script is an optional saved custom script with user defined functions.
These functions can then be used in the expression.
The function script can also import the default #TimeSeriesScript, so your functions can use those too.
References to other TimeSeries​
You can optionally add references to other TimeSeries or Smart TimeSeries that can also be used in your expression
Construction​
You construct a Smart TimeSeries using one of the following constructors:
// Specify base TimeSeries id and expression
st = SmartTimeSeries("CORN:CLOSE", "fill(BASE,'LINEAR')")
// Specify a start date, calendar and expression
// This can be used to create a TimeSeries that has the same scalar value from the start date till now
// Or you can use an expression to build a TimeSeries
st = SmartTimeSeries("2022-01-01", "MONTHLY", "12.5")
Properties​
A SmartTimeSeries has the following properties:
| Name | Description | Type |
|---|---|---|
| baseTimeSeries | The TimeSeries that this Smart TimeSeries uses for a base | ID String, TimeSeries or Reference |
| expression | The expression used to generate the TimeSeries | String |
| script | Optional custom script name used with the expression | String |
| currency | Optional currency of the TimeSeries, defaults to base TimeSeries currency | String |
| units | Optional units of the TimeSeries, defaults to base TimeSeries units | String |
| calendar | The calendar that this timeseries uses | Calendar |
| description | The description of this timeseries | String |
| identity | The configured identities | Object |
| localValues | The list of time observations for this timeseries, returned as a list of TimeValues in the local timezone of this TimeSeries | List |
| name | The name of the timeseries | String |
| observations | The list of values for this timeseries, returned as a list of Vars | List |
| observed | The observed setting of the timeseries used for aggregating | TimeSeriesObserved |
| precision | The precision configuration for this timeseries | Precision |
| source | The source of this timeseries | String |
| start | The starting date/time of the timeseries | Date |
| tenor | The tenor of this timeseries | String |
| timezone | The timezone of this timeseries, defaults to UTC | String |
| valueType | The value type of the timeseries (TRACKED or BASIC) | TimeValueType |
| values | The list of time observations for this timeseries, returned as a list of TimeValues | List |
If a currency and/or units are set, the base TimeSeries and any other TimeSeries added to this Smart TimeSeries will be converted to the specified currency and units
A SmartTimeSeries also supports adding dynamic properties, e.g.
sc = SmartTimeSeries("SMART_TEST:CLOSE", "BASE*1.02")
sc.product = "CORN"
Any dynamic properties added to a SmartTimeSeries can be used in the expression including references to other TimeSeries. Here are some examples of using properties within the Smart TimeSeries expression:
// Example using another TimeSeries
st1 = SmartTimeSeries("TEST_SMART_TS:ASK", "(BASE+BID)/2")
st1.BID = ref("data","TEST_SMART_TS:BID")
// Example using a numeric factor
st2 = SmartTimeSeries("TEST_SMART_TS:CLOSE", "BASE*factor")
st2.factor=1.2
Methods​
A SmartTimeSeries has the following methods:
| Name | Description | Return Type |
|---|---|---|
| build() | Builds a TimeSeries | TimeSeries |
| addCheck(check) | Add a quality check directly to this Timeseries | TimeSeries |
| addValue(value) | Adds a new value to the end of the timeseries using the calendar | TimeSeries |
| applyPrecision() | Apply the precision defined to all the observations of this timeseries | Void |
| convert(currency, units) | Convert this timeseries using currency and units | TimeSeries |
| from(start) | Creates a new TimeSeries from a specified start date | TimeSeries |
| getLast(date) | Get the value at the supplied date or the latest value before that date | Var |
| getLastNValues(n) | Returns a list of the last N values from this TimeSeries | List |
| last(n) | Creates a new TimeSeries using the last n values from this TimeSeries | TimeSeries |
| range(start, end) | Creates a new TimeSeries from a range of values from this TimeSeries | TimeSeries |
| withRange(start, end) | Changes this timeseries to match the provided date range | Void |
Below is an example of creating a Smart TimeSeries and building a TimeSeries using it:
st1 = SmartTimeSeries("TEST_SMART_TS:CLOSE", "BASE*factor)
st1.factor=1.2
t1 = st1.build()
print t1.values
Adding to an object and saving​
A SmartTimeSeries needs to be added to an object in order to save it to the database, e.g.
CORN_TEST = Object()
CORN_TEST.category = "TEST"
cf = SmartTimeSeries("TEST_SMART_TS:CLOSE", "interpolate(BASE,'LINEAR')")
CORN_TEST.FILLED = cf
save ${object: CORN_TEST}