Package: tshistory-formula
TSHISTORY FORMULAPurposeThistshistorycomponent provides a formula language to
build computed series.Formulas are defined using a simple lisp-like syntax, using a
pre-defined function library.Formulas are read-only series (you can'tupdateorreplacevalues).They also have an history, which is built, time stamps wise, using the
union of all constituent time stamps, and value wise, by applying the
formula.Because of this thestaircaseoperator is available on formulae.
Somestaircaseoperations can have a very fast implementation if the
formula obeys commutativity rules.FormulaGeneral SyntaxFormulas are expressed in a lisp-like syntax usingoperators,
positional (mandatory) parameters and keyword (optional) parameters.The general form is:(<operator> <param1> ... <paramN> #:<keyword1> <value1> ... #:<keywordN> <valueN>)Here are a couple examples:(add (series "wallonie") (series "bruxelles") (series "flandres"))Here we see the two fundamentaladdandseriesoperators at work.This would form a new synthetic series out of three base series (which
can be either raw series or formulas themselves).Some notes:operator names can contain dashes or arbitrary caractersliteral values can be:3(integer),5.2(float),"hello"(string) and#tor#f(true ot false)Pre-defined operators*Performs a scalar product on a series.Example:(* -1 (series "positive-things"))+Add a constant quantity to a series.Example:(+ 42 (series "i-feel-undervalued"))/Perform a scalar division between numbers or a series and a scalar.Example:(/ (series "div-me") (/ 3 2))addLinear combination of two or more series. Takes a variable number
of series as input.Example:(add (series "wallonie") (series "bruxelles") (series "flandres"))To specify the behaviour of theaddoperation in the face of missing
data, the series can be built with thefillkeyword. This option is
only really applied when several series are combined. By default, if
an input series has missing values for a given time stamp, the
resulting series has no value for this timestamp (unless a fill rule
is provided).clipSet an upper/lower threashold for a series. Takes a series as
positional parameter and accepts two optional keywordsminandmaxwhich must be numbers (integers or floats).Example:(clip (series "must-be-positive") #:min 0)dateProduces an utc timestamp from its input string date in iso format.Thetzkeyword allows to specify an alternate time zone.
Thenaivekeyword forces production of a naive timestamp.
Bothtzandnaivekeywords are mutually exlcusive.divElement wise division of two series.Example:(div (series "$-to-€") (series "€-to-£"))minComputes the row-wise minimum of its input series.Example:(min (series "station0") (series "station1") (series "station2"))maxComputes the row-wise maximum of its input series.Example:(max (series "station0") (series "station1") (series "station2"))mulElement wise multiplication of series. Takes a variable number of series
as input.Example:(mul (series "banana-spot-price ($)") (series "$-to-€" #:fill 'ffill'))This might convert a series priced in dollars to a series priced in
euros, using a currency exchange rate series with a forward-fill
option.naiveAllow demoting a series from a tz-aware index (strongly recommended)
to a tz-naive index (unfortunately sometimes unavoidable for interop
with other tz-naive series).One must provide a country code and a target timezone.Example:(naive (series "tz-aware-series-from-poland") "PL" "Europe/Warsaw")priorityThe priority operator combines its input series as layers. For each
timestamp in the union of all series time stamps, the value comes from
the first series that provides a value.Example:(priority (series "realized") (series "nominated") (series "forecasted"))Hererealizedvalues show up first, and any missing values come fromnominatedfirst and then only fromforecasted.resampleResamples its input series usingfreqand the aggregation methodmethod(as described in the pandas documentation).Example:(resample (series "hourly") "D")row-meanThis operator computes the row-wise mean of its input series using the
seriesweightoption if present. The missing points are handled as
if the whole series were absent.Example:(row-mean (series "station0") (series "station1" #:weight 2) (series "station2"))Weights are provided as a keyword toseries. No weight is
interpreted as 1.seriesTheseriesoperator accepts several keywords:fillto specify a filling policy to avoidnanswhen the series
will beadded with others; accepted values are"ffill"(forward-fill),"bfill"(backward-fill) or any floating value.For instance in(add (series "a" #:fill 0) (series "b")will make
sure that seriesa, if shorter than seriesbwill get zeroes
instead of nans wherebprovides values.sliceThis allows cutting a series at date points. It takes one positional
parameter (the series) and two optional keywordsfromdateandtodatewhich must be strings in theiso8601format.Example:(slice (series "cut-me") #:fromdate "2018-01-01")stdComputes the standard deviation over its input series.Example:(std (series "station0") (series "station1") (series "station2"))timedeltaTakes a timestamp and a number of years, months, weekds, days,
hours, minutes (int) and computes a new date according to the asked
delta elements.Example:(timedelta (date "2020-1-1") #:weeks 1 #:hours 2)todayProduces a timezone-aware timestamp as of todayThetzkeyword allows to specify an alternate time zone.
Thenaivekeyword forces production of a naive timestamp.
Bothtzandnaivekeywords are mutually exlcusive.Example:(today)Series APIA few api calls are added to thetshistorybase:.register_formulato define a formula.eval_formulato evaluate on-the-fly a formula (useful to check
that it computes before registering it)register_formulaExemple:tsa.register_formula('my-sweet-formula','(* 3.14 (series "going-round"))')eval_formulaExample:>>>tsa.eval_formula('(* 3.14 (series "going-round"))')...2020-01-013.142020-01-026.282020-01-039.42dtype:float64