HCrystal Ball

HCrystal Ball consists of two main parts:

• Wrappers - which bring different 3rd party

libraries to time series compatible sklearn API

• Model Selection - to enable gridsearch over wrappers, general or custom made transformers

and add convenient layer over whole process (access to results, plots, storage, ...)

Documentation

See examples, tutorials, contribution, API and more on the documentation site try notebooks on binder or browse example notebooks in docs/examples directly.

Core Installation

If you want really minimal installation, you can install from pip or from conda-forge

pip install hcrystalball

conda install -c conda-forge hcrystalball

Typical Installation

Very often you will want to use more wrappers, than just Sklearn, run examples in jupyterlab, or execute model selection in parallel. Getting such dependencies to play together nicely might be cumbersome, so checking envrionment.yml might give you faster start.

# get dependencies file, e.g. using curl
curl -O https://raw.githubusercontent.com/heidelbergcement/hcrystalball/master/environment.yml
check comments in environment.yml, keep or remove as requested, than create environment using
conda env create -f environment.yml
activate the environment
conda activate hcrystalball
if you want to see progress bar in jupyterlab, execute also
jupyter labextension install @jupyter-widgets/jupyterlab-manager
install the library from pip
pip install hcrystalball
or from conda
conda install -c conda-forge hcrystalball

Development Installation:

To have everything in place including docs build or executing tests, execute following code

git clone https://github.com/heidelbergcement/hcrystalball
cd hcrystalball
conda env create -f environment.yml
conda activate hcrystalball
ensures interactive progress bar will work in example notebooks
jupyter labextension install @jupyter-widgets/jupyterlab-manager
python setup.py develop

Example Usage

Wrappers

from hcrystalball.utils import generate_tsdata
from hcrystalball.wrappers import ProphetWrapper
X, y = generatetsdata(ndates=365*2) Xtrain, ytrain, Xtest, ytest = X[:-10], y[:-10], X[-10:], y[-10:]
model = ProphetWrapper() ypred = model.fit(Xtrain, ytrain).predict(Xtest) y_pred             prophet 2018-12-22  6.066999 2018-12-23  6.050076 2018-12-24  6.105620 2018-12-25  6.141953 2018-12-26  6.150229 2018-12-27  6.163615 2018-12-28  6.147420 2018-12-29  6.048633 2018-12-30  6.031711 2018-12-31  6.087255

Model Selection

import pandas as pd
import matplotlib.pyplot as plt
plt.style.use('seaborn')
plt.rcParams['figure.figsize'] = [12, 6]
from hcrystalball.utils import getsalesdata from hcrystalball.model_selection import ModelSelector
df = getsalesdata(n_dates=200,                     n_assortments=1,                     n_states=2,                     n_stores=2)
ms = ModelSelector(horizon=10,                    frequency="D",                    countrycodecolumn="HolidayCode",                    )
ms.creategridsearch(nsplits=2,                      sklearn_models=True,                      prophet_models=False,                      exog_cols=["Open","Promo","SchoolHoliday","Promo2"],                      )
ms.select_model(df=df,                 targetcolname="Sales",                 partition_columns=["Assortment", "State","Store"],                 )
ms.plotresults(plotfrom="2015-06-01",                 partitions=[{"Assortment":"a","State":"NW","Store":335}]                )