Package: tshistory-xl
TSHISTORY XLWhatThis is an Excel client fortshistory.Removing the old versionspipuninstallxl_data_hubInstallationpipinstalltshistory_xl
pipinstallxlwingsClose Excel.
Make sure that xlwings is registered:xlwingsaddininstallThen type:$tshxl-addininstallIn Excel you should see two new tabs:xlwingsandSaturn.If you have to uninstall the old proprietary version, dotshxl-addinuninstall-any--nameZATURN.xlamBase useOn a brand new Excel sheet, you need initially a tab named_SATURN_CFG, which must contain:in A1:webapiin B1:http://uri-of-the-tshistory-instanceAB1webapihttp://uri-of-the-tshistory-instanceThen, let's create the conditions to play with one series.Push data (Save them server side)Warning: with this addin one can easly push data in production
database. Be sure to only use series begining with "test" until you
completly master the process to not make a mess.test.series.1test.series.22020-09-01162020-09-02252020-09-03342020-09-04432020-09-05522020-09-0661In anew sheet, let's go toB1. There we type the name of a
series (e.g.test.series.1), same thing forB2.FromA2toA7, type timestamps e.g. "2020-9-1", ...,
"2020-9-6". Make sure Excel really understand those as dates.Then you have to create aname(e.g. using the name manager
accessible from theformulatab) for the rangeB2:C7, whose name
is e.g.rwc_test_zone(it is crucial that we have a prefix likerwc_.Only the data must be included into the range of the
name. The margins (series name and date) must be adjacent to its
range.Finally in theSaturntab, click onSave TabYou can watch the result in base with the adapted url :http://uri-of-the-tshistory-instance/tsinfo?name=test.series.1Pull data (Get them, client side)On another sheet, you can recreate the previous step:build a name (with the correct suffix)write in the margin the names of the series and the dateClick onGet Tabto obtain the data in Excel.Configuration optionsPrefix name optionsIn the example, we use arwc_prefix. Each caracter has its meaning
and can be omited.r: indicate that the zone can read data from the database. Could
be omited if this excel zone is only used for manual entryw: allows to write in the database. Should be omited if the zone
is only used for data consultationc: put some colors in the name range. Very useful: most of the
errors that you will encounter are linked to the size of the range
that does not fit the data.Specific request options:f: will fill the trailing empty values with the last non-empty oneIfr_name would return such data:test.series.32020-09-0112020-09-022020-09-0332020-09-042020-09-05rf_name would return :test.series.32020-09-0112020-09-022020-09-0332020-09-0432020-09-053_month_: when pushing data, a value defined on one date of the
month will be extrapolated (daily) for the whole monthLayoutThe name range can be placed anywhere on the sheet, as long as the
margins (with series and dates) are placed adjacently.One could play a little with the data layout by letting empty cells in
the margins:test.series.1test.series.2I can2020-09-011put62020-09-022any52020-09-033comment42020-09-044in32020-09-055this2alsohere2020-09-066column1Revisiting the pastAll the series are versionned, which mean anyone can access to a
previous version of the series. There are two ways to access it:Whole nameAfter the first pulling of data, the sheet should be decorated in the
upper left corner of the name range with a comment "ASOF".A date (recognized as such by excel) placed in this corner will allow
to view the state of all series at this given time.Finally in theSaturntab, click onGet All, and see the values
coming.ASOF date should be heretest.series.32020-09-011Note that when such a date is given,the data can not be pushed in
the database(iow you cannot rewrite the past from the excel
client).By columnSometimes you want to be able to see side by side the same series at
different times. You can display such data with additionnal argumentasofin the upper margintest.series.4test.series.4(asof = 2020-09-03)2020-09-01112020-09-02222020-09-03332020-09-044#N/A2020-09-055#N/A2020-09-066#N/ANote: date must be in ISO format YYYY-MM-DDAs before, the series with theasofparameter will not be pushed
when pressing theSave taborSave allbutton.Model backtestWhen backtesting a forecast model, one will need astaircaserequest, i.e. a request where the selected value dates are linked to
the insertion dates. It allows to evaluate the validity of a model
given a forecast horizon. For this, one has to use in the upper left
corner a new keywordasofdelta=<number>where the number is the
forecast horizon in hours.asofdelta=24test.series.32020-09-011Not A NumberhandlingBy default, when the data are missing at a given date, the
corresponding cell will be filled with#N/A.This default behaviour can be altered with some more columns options(blank=empy),(blank=prev),(blank=3.14)test.5test.6(blank=empy)test.7(blank=prev)test.8(blank=3.14)test.9(blank=0)2020-09-01111112020-09-02#N/A13.1402020-09-03333332020-09-04#N/A33.140ResamplingThe excel addin allows to resample the data when pulling them with the
option(agg = <method>)where the method can bemean,sum,max,min.The resampling algorithm uses the dates in the left margin as
intervals for the resampling wich will led to an empty cell at the
end.test.series.102020-09-0112020-09-0212020-09-0312020-09-0412020-09-051test.series.10(agg=sum)comments2020-09-013Sum from date >= 2020-09-01 and date < 2020-09-042020-09-042Sum from date >= 2020-09-04 and date < 2020-09-072020-09-07*No computation here *Notes on resamplingThe last cell will be empty, in any caseThe resampled data won't be pushedIf such resampling is reoccuring, we strongly advise to define a new
resampled series,server side, with theformulasystem
of tshistoryCommon pitfallsMost of your errors will come from a range name with an incorrect
form. Check it thoroughly. Check that all your left margin are
dates, and that the upper margin does not have the same series
called twice (with an exception when the series are asociated with
anasofoption)The error returned byxlwingsare quite a mouthful. However, most
of the error that will raise will provide a usefull comment bury
somewhere, provided by the developpers of this addin. Your eyes may
bleed because of it, but the solution might be there.It is quite easy to push some data in the database, it is also very
simple to prevent it (use therc_prefix)If one change the value of series inserted by a different process,
the rule of updating such data might surprise you at first
look. More informationhereTestingWhile the environment works well with recent versions of python and
pandas, it might not work under the most recent versions of Excel
(timedelta tests fail under V16.0). Keep that in mind whenever you're
launching pytest.Some tests might not work especially if you haven't configured your
local Postgres instance, sincepytest_sa_pgrequires commands from
your local Postgres installation, likeinitdb.# For Linux, add the following to your .profileexportPATH=$PATH:/usr/lib/postgresql/{version_number}/bin/source~/.profile# For Windows[System.Environment]::SetEnvironmentVariable('path',$Env:Programfiles+".\PostgreSQL\{version_number}\bin;"+[System.Environment]::GetEnvironmentVariable('path',"User"),"User")# Or add the variables manually through your panel