From b11496db600097142e58f6ab9ab51c3c06f6b3ba Mon Sep 17 00:00:00 2001 From: Chaselzxy <47959406+Chaselzxy@users.noreply.github.com> Date: Wed, 17 Aug 2022 20:11:24 +0800 Subject: [PATCH] Chronos: How-to-Guides (How to train forecaster on single node) (#5224) * how to train forecaster * add a notebook * add new notebook * add index * fix colab link * change content Co-authored-by: Xinyi Zhang Co-authored-by: theaperdeng --- docs/readthedocs/source/_toc.yml | 1 + .../how_to_train_forecaster_on_one_node.ipynb | 269 ++++++++++++++++++ .../source/doc/Chronos/Howto/index.rst | 16 ++ 3 files changed, 286 insertions(+) create mode 100644 docs/readthedocs/source/doc/Chronos/Howto/how_to_train_forecaster_on_one_node.ipynb create mode 100644 docs/readthedocs/source/doc/Chronos/Howto/index.rst diff --git a/docs/readthedocs/source/_toc.yml b/docs/readthedocs/source/_toc.yml index 57a1c9c3..4c1dbdd6 100644 --- a/docs/readthedocs/source/_toc.yml +++ b/docs/readthedocs/source/_toc.yml @@ -55,6 +55,7 @@ subtrees: - file: doc/Chronos/Overview/windows_guide - file: doc/Chronos/Overview/quick-tour - file: doc/Chronos/Overview/deep_dive + - file: doc/Chronos/Howto/index - file: doc/Chronos/QuickStart/index - file: doc/Chronos/Overview/chronos_known_issue diff --git a/docs/readthedocs/source/doc/Chronos/Howto/how_to_train_forecaster_on_one_node.ipynb b/docs/readthedocs/source/doc/Chronos/Howto/how_to_train_forecaster_on_one_node.ipynb new file mode 100644 index 00000000..6224772f --- /dev/null +++ b/docs/readthedocs/source/doc/Chronos/Howto/how_to_train_forecaster_on_one_node.ipynb @@ -0,0 +1,269 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "metadata": { + "id": "SQRh9TDkmexb" + }, + "source": [ + "![image.png](data:image/png;base64,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)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "[Open in Colab Here](https://colab.research.google.com/github/intel-analytics/BigDL/blob/main/docs/readthedocs/source/doc/Chronos/Howto/how_to_train_forecaster_on_one_node.ipynb)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "# Train forcaster on single node" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "id": "onZXfhnkmexc" + }, + "source": [ + "## Introduction\n", + "\n", + "In Chronos, Forecaster (`bigdl.chronos.forecaster.Forecaster`) is the forecasting abstraction. It hides the complex logic of model's creation, training, scaling to cluster, tuning, optimization and inferencing while expose some APIs for users (e.g. `fit` in this guide) to control.\n", + "\n", + "In this guidance, **we demonstrate how to train forecasters on one node**. In the training process, forecaster will learn the pattern (like the period, scale...) in history data. Although Chronos supports training on a cluster, it's highly recommeneded to try one node first before allocating a cluster to make life easier.\n", + "\n", + "We will take `TCNForecaster` and nyc_taxi dataset as an exmaple in this guide." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Setup\n", + "\n", + "Before we begin, we need to install chronos if it isn’t already available, we choose to use pytorch as deep learning backend." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "!pip install --pre --upgrade bigdl-chronos[pytorch]\n", + "!pip uninstall -y torchtext # uninstall torchtext to avoid version conflict\n", + "exit()" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Data preparation\n", + "\n", + "First, we load the nyc taxi dataset." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "from bigdl.chronos.data.repo_dataset import get_public_dataset\n", + "from sklearn.preprocessing import StandardScaler\n", + "\n", + "tsdata_train, tsdata_val, _ = get_public_dataset(name='nyc_taxi')\n", + "\n", + "stand = StandardScaler()\n", + "for tsdata in [tsdata_train, tsdata_val]:\n", + " tsdata.impute()\\\n", + " .scale(stand, fit=tsdata is tsdata_train)" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "id": "i8kjsyL4mexd" + }, + "source": [ + "Forecaster supports learning history data in many formats, including:\n", + "\n", + "1. `bigdl.chronos.data.TSDataset` (**recommended**)\n", + "2. pytorch dataloader\n", + "3. tensorflow dataset\n", + "4. numpy ndarray\n", + "\n", + "It's always recommended to use `TSDataset` direcetly when possible, while many other formats are supported if users want to customize their own data processing and feature engineering procedure." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "# comment this line if you want to try other formats\n", + "train_data = tsdata_train\n", + "\n", + "# uncomment this line to change `train_data` as pytorch dataloader\n", + "# train_data = tsdata_train.to_torch_data_loader(roll=True, lookback=48, horizon=1)\n", + "\n", + "# uncomment this line to change `train_data` as numpy ndarray\n", + "# train_data = tsdata_train.roll(lookback=48, horizon=1).to_numpy()" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "id": "IswBKf39mexg" + }, + "source": [ + "## Training\n", + "\n", + "First we will create a `TCNForecaster`.\n" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "from bigdl.chronos.forecaster.tcn_forecaster import TCNForecaster\n", + "\n", + "forecaster = TCNForecaster(past_seq_len=48,\n", + " future_seq_len=1,\n", + " input_feature_num=1,\n", + " output_feature_num=1)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Then just call `fit` on the training data!\n", + "\n", + "There are some other parameters you may want to change, including `epochs` and `batch_size`. How change these hyperparameters might be tricky and highly based on experience. \n", + "\n", + "Here is a \"rule of thumb\" for users who are not that familiar with manual hyperparameter tuning: adjust `epochs` to make sure your mse training loss on scaled data (you can find it on the right side on progress bar, and \"mse\" is the default loss function) decreases under than 0.1 and leave `batch_size` to the default value." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "colab": { + "base_uri": "https://localhost:8080/" + }, + "id": "yc34x9dcmexg", + "outputId": "bba44274-e6d0-408a-bf9b-32d549fe1ea9" + }, + "outputs": [], + "source": [ + "forecaster.fit(train_data)" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "id": "ZiolCDSmmexj" + }, + "source": [ + "## Validation (optional)\n", + "\n", + "Overfitting is a common issue when it comes to time series analysis since the data are not always large enough, one (and probably the most effective) method to avoid overfitting is validate your model during the trianing process. `Forecaster.fit` API also provides a way to validate the forecaster and find the best stop point before the model suffers overfitting.\n", + "\n", + "As in following cases, we choose a validation_mode called \"best_epoch\" to load back the checkpoint with best validation loss on validation data." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "# comment this line if you want to try other formats\n", + "val_data = tsdata_val.to_torch_data_loader(roll=True, lookback=48, horizon=1)\n", + "\n", + "# uncomment this line to change `val_data` as numpy ndarray\n", + "# val_data = tsdata_val.roll(lookback=48, horizon=1).to_numpy()" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "colab": { + "base_uri": "https://localhost:8080/" + }, + "id": "o7jWojYNmexk", + "outputId": "eb4cc68f-4d38-410d-b007-c507da30b97f" + }, + "outputs": [], + "source": [ + "# create a new forecaster\n", + "forecaster = TCNForecaster(past_seq_len=48,\n", + " future_seq_len=1,\n", + " input_feature_num=1,\n", + " output_feature_num=1)\n", + "\n", + "# train the forecaster with validation data to avoid overfitting\n", + "forecaster.fit(train_data,\n", + " epochs=3,\n", + " validation_data=val_data,\n", + " validation_mode='best_epoch')" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Acceleration on intel CPU\n", + "\n", + "Chronos only support CPU (and transparent acceleration on Intel CPU) for training. Since time series data is not large, CPU training is enough for most cases.\n", + "\n", + "You may find there is no code needed in this section since the acceleration happens transparently (i.e. no specific code is needed for acceleration settings) inside the forecasters in Chronos. This includes **automatically** sets the\n", + "\n", + "1. better memory allocator\n", + "2. hardware-awared system variables for multithread utilization\n", + "3. multiprocess training on powerful CPU\n", + "4. usage of IPEX (intel pytorch extension) and intel optimized tensorflow." + ] + } + ], + "metadata": { + "colab": { + "collapsed_sections": [], + "name": "train_forecaster_on_one_node.ipynb", + "provenance": [] + }, + "kernelspec": { + "display_name": "Python 3.7.13 ('chronos')", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.7.13" + }, + "vscode": { + "interpreter": { + "hash": "f7cbcfcf124497a723b2fc91b0dad8cd6ed41af955928289a9d3478af9690021" + } + } + }, + "nbformat": 4, + "nbformat_minor": 1 +} diff --git a/docs/readthedocs/source/doc/Chronos/Howto/index.rst b/docs/readthedocs/source/doc/Chronos/Howto/index.rst new file mode 100644 index 00000000..0163c7c5 --- /dev/null +++ b/docs/readthedocs/source/doc/Chronos/Howto/index.rst @@ -0,0 +1,16 @@ +Chronos How-to Guides +========================= +How-to guides are bite-sized, executable examples where users could check when meeting with some specific topic during the usage. + +Forecasting +------------------------- +* `Train forcaster on single node `__ + + In this guidance, **we demonstrate how to train forecasters on one node**. In the training process, forecaster will learn the pattern (like the period, scale...) in history data. Although Chronos supports training on a cluster, it's highly recommeneded to try one node first before allocating a cluster to make life easier. + + +.. toctree:: + :maxdepth: 1 + :hidden: + + how_to_train_forecaster_on_one_node