Package: pyteller
An open source project from Data to AI Lab at MIT.pytellerTime series forecasting using MLPrimitivesDocumentation:https://signals-dev.github.io/pytellerHomepage:https://github.com/signals-dev/pytellerOverviewpyteller is a time series forecasting library built with the end user in mind.LeaderboardIn this repository we maintain an up-to-date leaderboard with the current scoring of the
pipelines according to the benchmarking procedure explained in thebenchmark documentation.The benchmark is run on many datasets and we record the number of wins each pipeline has over the
baseline pipeline. Results obtained during benchmarking as well as previous releases can be
found withinbenchmark/resultsfolder as CSV files. Results can also
be browsed in the following Googlesheet.PipelinePercent Outperforms PersistenceTable of ContentsI. Data FormatI.1 InputI.2 OutputI.3 Datasets in the libraryII. pyteller PipelinesII.1 Current Available PipelinesIII. InstallIV. Quick StartData FormatInputThe expected input to pyteller pipelines is a .csv file with data in one of the following formats:Targets TableOption 1: Single Entity (Academic Form)The user must specify the following:timestamp_col: thestringdenoting which column contains thepandas timestampobjects orpython datetimeobjects corresponding to the time at which the observation is madetarget_column: anintegerorfloatcolumn with the observed target values at the indicated timestampsThis is an example of such table, where the values are the number of NYC taxi passengers at the corresponding timestamp.timestampvalue7/1/14 1:0062107/1/14 1:3046567/1/14 2:0038207/1/14 1:3046567/1/14 2:0038207/1/14 2:3028737/1/14 3:0023697/1/14 3:3020647/1/14 4:0022217/1/14 4:3021587/1/14 5:002515Option 2: Multiple Entity-Instances (Flatform)The user must specify the following:timestamp_col: thestringdenoting which column contains thepandas timestampobjects orpython datetimeobjects corresponding to the time at which the observation is madeentity_col: thestringdenoting which column contains the entities you will seperately make forecasts fortarget: thestringdenoting which columns contain the observed target values that you want to forecast fordynamic_variable: thestringdenoting which columns contain other input time series that will help the forecaststatic_variable: thestringdenoting which columns are a static variblesThis is an example of such table, where thetimestamp_colis 'timestamp', theentity_colis 'region',  thetargetis 'demand,' and thedynamic_variableare 'Temp' and 'Rain':timestampregiondemandTempRain9/27/20 21:20DAYTON1841.665.7809/27/20 21:20DEOK2892.575.9209/27/20 21:20DOM1127655.2909/27/20 21:20DPL2113.775.020.069/27/20 21:25DAYTON1834.165.7209/27/20 21:25DEOK2880.275.9209/27/20 21:25DOM11211.755.5409/27/20 21:25DPL2086.675.020.06Option 3: Multiple Entity-Instances: LongformThe user must specify the following:timestamp_col: thestringdenoting which column contains thepandas timestampobjects orpython datetimeobjects corresponding to the time at which the observation is madeentity_col: thestringdenoting which column contains the entities you will seperately make forecasts forvariable_col: thestringdenoting which column contains the names of the observed variablestarget: thestringdenoting which variable names are the observed target values in thevariable_colthat you want to forecast fordynamic_variable: thestringdenoting which variable names are other input time series in thevariable_colthat will help the forecaststatic_variable: thestringdenoting which variable names are static varibles in thevariable_colvalue_col: thestringdenoting which column contains the values of the observations of thevariable_colThis is an example of such table, where thetimestamp_colis 'timestamp', theentity_colis 'region', thevariable_colis 'var_name', thetargetis 'demand,' thedynamic_variableare 'Temp' and 'Rain', and thevalue_colis 'value':timestampregionvar_namevalue9/27/20 21:20DAYTONdemand1841.69/27/20 21:20DAYTONTemp65.789/27/20 21:20DAYTONTemp09/27/20 21:20DEOKdemand2892.59/27/20 21:20DEOKTemp75.929/27/20 21:20DEOKRain09/27/20 21:20DOMdemand112769/27/20 21:20DOMTemp55.299/27/20 21:20DOMRain09/27/20 21:20DPLdemand2113.79/27/20 21:20DPLTemp75.029/27/20 21:20DPLRain0.069/27/20 21:25DAYTONdemand1834.19/27/20 21:25DAYTONTemp65.729/27/20 21:25DAYTONTemp09/27/20 21:25DEOKdemand2880.29/27/20 21:25DEOKTemp75.929/27/20 21:25DEOKRain09/27/20 21:25DOMdemand11211.79/27/20 21:25DOMTemp55.549/27/20 21:25DOMRain09/27/20 21:25DPLdemand2086.69/27/20 21:25DPLTemp75.029/27/20 21:25DPLRain0.06OutputThe output of the pyteller Pipelines is another table that contains the timestamp and the forecasting value(s), matching the format of the input targets table.Datasets in the libraryFor development and evaluation of pipelines, we include the following datasets:NYC taxi dataFound on thenyc website, or the processed version maintained by Numentahere.No modifications were made from the Numenta versionWind dataFound here onkaggleAfter downloading the FasTrak 5-Minute .txt files the .txt files for each day from 1/1/13-1/8/18 were compiled into one .csv fileWeather dataMaintained by Iowa State University'sIEMThe downloaded data was from the selected network of 8A0 Albertville and the selected date range was 1/1/16 0:15 - 2/16/16 0:55Traffic dataFound onCaltrans PeMSNo modifications were made from the Numenta versionEnergy dataFound onkaggleNo modifications were made after downloading pjm_hourly_est.csv
We also use PJM electricity demand data foundhere.Current Available PipelinesThe pipelines are included asJSONfiles, which can be found
in the subdirectories inside thepyteller/pipelinesfolder.This is the list of pipelines available so far, which will grow over time:namelocationdescriptionPersistencepyteller/pipelines/sandbox/persistenceuses the latest input to the model as the next outputInstallRequirementspytellerhas been developed and tested onPython 3.5, 3.6, 3.7 and 3.8Also, although it is not strictly required, the usage of avirtualenvis highly recommended in order to avoid interfering with other software installed in the system
in whichpytelleris run.These are the minimum commands needed to create a virtualenv using python3.6 forpyteller:pipinstallvirtualenv
virtualenv-p$(whichpython3.6)pyteller-venvAfterwards, you have to execute this command to activate the virtualenv:sourcepyteller-venv/bin/activateRemember to execute it every time you start a new console to work onpyteller!Install from sourceWith your virtualenv activated, you can clone the repository and install it from
source by runningmake installon thestablebranch:gitclonegit@github.com:signals-dev/pyteller.gitcdpyteller
gitcheckoutstable
makeinstallInstall for DevelopmentIf you want to contribute to the project, a few more steps are required to make the project ready
for development.Please head to theContributing Guidefor more details about this process.Quick StartIn this short tutorial we will guide you through a series of steps that will help you
getting started withpyteller.1. Load the dataIn the first step we will load theelectricity_demanddata from theDemo Dataset.Import thepyteller.data.load_signalfunction and call itfrompyteller.dataimportload_signaltrain,test=load_signal(data=dataset,timestamp_col='timestamp',targets='Total Flow',static_variables=None,entity_cols='Location Identifier',train_size=.75)2. ForecastOnce we have the data, let us try to use a pyteller pipeline to make a forecast.Create an instance of thepyteller.Pytellerclass and pass in arguments that help describe your prediction problemfrompytellerimportPytellerpyteller=Pyteller(hyperparameters=hyperparameters,pipeline='persistence',pred_length=3,goal=None,goal_window=None)Now, since the persistence pipeline does not require a fit method, we are ready to forecast:forecast=pyteller.predict(test_data=test)3. EvaluateNow, we can evaluate the forecastsscores=pyteller.evaluate(train_data=train,test_data=test,forecast=forecast,metrics=['MAPE','MSE'])What's next?For more details aboutpytellerand all its possibilities
and features, please check thedocumentation site.History0.1.0 - 2020-11-02First pyteller release to PyPI