From ab7d47dd0aa4f0867dee9f4e9adf6eb2b71051f1 Mon Sep 17 00:00:00 2001 From: liangs6212 Date: Fri, 22 Jul 2022 23:23:53 +0800 Subject: [PATCH 01/15] how to guide from_tsdataset --- .../Overview/how-to-create-a-forecaster.md | 51 +++++++++++++++++++ 1 file changed, 51 insertions(+) create mode 100644 docs/readthedocs/source/doc/Chronos/Overview/how-to-create-a-forecaster.md diff --git a/docs/readthedocs/source/doc/Chronos/Overview/how-to-create-a-forecaster.md b/docs/readthedocs/source/doc/Chronos/Overview/how-to-create-a-forecaster.md new file mode 100644 index 00000000000..80485c72854 --- /dev/null +++ b/docs/readthedocs/source/doc/Chronos/Overview/how-to-create-a-forecaster.md @@ -0,0 +1,51 @@ +## How to create a Forecaster +### 1. Forecaster +Before creating a Forecaster,you need to understand the four parameters `past_seq_len`, `future_seq_len`, `input_feature_num`, `output_feature_num`, which represent the time step and feature column, As shown below. +![](../Image/forecast-RR.png "time series") + * **past_seq_len**: Sampled input length, represents the history time step. (i.e. lookback) + * **future_seq_len**: Sampled output length, represents the output time step.(i.e. horizon) + * **input_feature_num**: All feature column(s), including extra feature column(s) and target column(s). + * **output_feature_num**: Only target column(s). +After determining your above parameters, you can create a forecaster next. +```note +Some forecaster models may only require some parameters, such as +LSTMforecaster without specifying future_seq_len, because lstm is a single-step model. +NBeatsForecaster only needs to specify past_seq_len and future_seq_len. +``` + +### 2. create a forecaster. + We provide two methods for creating Forecaster. + #### 1. Create a Forecaster using Forecaster.from_tsdataset(Highly recommended) + > :note: `from_tsdataset` requires input of a TSDataset instance. TSDataset is a built-in time series preprocessing class, More info, Please refer to [how to use TSDataset and get_public_dataset](xxxx). + + If your tsdataset has used the `roll` or `to_torch_data_loader` methods, + you do not need to specify `past_seq_len` and `future_seq_len` for from_tsdataset, otherwise you must specify both. + The simplest usage of "from_tsdataset" is given below. More info, please refer to [from_tsdataset](xxxx). + ```python + from bigdl.chronos.forecaster import TCNForecaster + from bigdl.chronos.data import TSDataset + tsdataset = TSDataset.from_pandas(df, ...) # df is a pandas.DataFrame + tcn = TCNForecaster.from_tsdataset(tsdataset, + past_seq_len=past_seq_len, + future_seq_len=future_seq_len) + tcn.fit(tsdataset) + ``` + + #### 2. Create a forecaster directly + You can also create TCNForecaster directly and you can choose to use TSDataset or other custom data preprocessing methods. + ```python + from bigdl.chronos.forecaster import TCNForecaster + # prepare dataset + timeseries = ... + tcn = TCNForecaster(past_seq_len=48, + future_seq_len=5, + input_feature_num=2, + output_feature_num=2) + + tcn.fit(timeseries) + ``` + +### 3. further reading + training: After you have created the forecaster, you can train your model, Please refer to [how to train]() + distributed: When your data volume is large and it is difficult to complete on a single machine, we also provide distributed training, please refer to [train model distributed on a cluster]() + forecaster.load: \ No newline at end of file From d4ba3f99dae25f5ffa4264876000c950ac989294 Mon Sep 17 00:00:00 2001 From: liangs6212 Date: Thu, 4 Aug 2022 01:22:22 +0800 Subject: [PATCH 02/15] improve md --- .../Overview/how-to-create-a-forecaster.md | 51 --------------- .../Overview/how-to-create-forecaster.md | 63 +++++++++++++++++++ 2 files changed, 63 insertions(+), 51 deletions(-) delete mode 100644 docs/readthedocs/source/doc/Chronos/Overview/how-to-create-a-forecaster.md create mode 100644 docs/readthedocs/source/doc/Chronos/Overview/how-to-create-forecaster.md diff --git a/docs/readthedocs/source/doc/Chronos/Overview/how-to-create-a-forecaster.md b/docs/readthedocs/source/doc/Chronos/Overview/how-to-create-a-forecaster.md deleted file mode 100644 index 80485c72854..00000000000 --- a/docs/readthedocs/source/doc/Chronos/Overview/how-to-create-a-forecaster.md +++ /dev/null @@ -1,51 +0,0 @@ -## How to create a Forecaster -### 1. Forecaster -Before creating a Forecaster,you need to understand the four parameters `past_seq_len`, `future_seq_len`, `input_feature_num`, `output_feature_num`, which represent the time step and feature column, As shown below. -![](../Image/forecast-RR.png "time series") - * **past_seq_len**: Sampled input length, represents the history time step. (i.e. lookback) - * **future_seq_len**: Sampled output length, represents the output time step.(i.e. horizon) - * **input_feature_num**: All feature column(s), including extra feature column(s) and target column(s). - * **output_feature_num**: Only target column(s). -After determining your above parameters, you can create a forecaster next. -```note -Some forecaster models may only require some parameters, such as -LSTMforecaster without specifying future_seq_len, because lstm is a single-step model. -NBeatsForecaster only needs to specify past_seq_len and future_seq_len. -``` - -### 2. create a forecaster. - We provide two methods for creating Forecaster. - #### 1. Create a Forecaster using Forecaster.from_tsdataset(Highly recommended) - > :note: `from_tsdataset` requires input of a TSDataset instance. TSDataset is a built-in time series preprocessing class, More info, Please refer to [how to use TSDataset and get_public_dataset](xxxx). - - If your tsdataset has used the `roll` or `to_torch_data_loader` methods, - you do not need to specify `past_seq_len` and `future_seq_len` for from_tsdataset, otherwise you must specify both. - The simplest usage of "from_tsdataset" is given below. More info, please refer to [from_tsdataset](xxxx). - ```python - from bigdl.chronos.forecaster import TCNForecaster - from bigdl.chronos.data import TSDataset - tsdataset = TSDataset.from_pandas(df, ...) # df is a pandas.DataFrame - tcn = TCNForecaster.from_tsdataset(tsdataset, - past_seq_len=past_seq_len, - future_seq_len=future_seq_len) - tcn.fit(tsdataset) - ``` - - #### 2. Create a forecaster directly - You can also create TCNForecaster directly and you can choose to use TSDataset or other custom data preprocessing methods. - ```python - from bigdl.chronos.forecaster import TCNForecaster - # prepare dataset - timeseries = ... - tcn = TCNForecaster(past_seq_len=48, - future_seq_len=5, - input_feature_num=2, - output_feature_num=2) - - tcn.fit(timeseries) - ``` - -### 3. further reading - training: After you have created the forecaster, you can train your model, Please refer to [how to train]() - distributed: When your data volume is large and it is difficult to complete on a single machine, we also provide distributed training, please refer to [train model distributed on a cluster]() - forecaster.load: \ No newline at end of file diff --git a/docs/readthedocs/source/doc/Chronos/Overview/how-to-create-forecaster.md b/docs/readthedocs/source/doc/Chronos/Overview/how-to-create-forecaster.md new file mode 100644 index 00000000000..6016e4b41ad --- /dev/null +++ b/docs/readthedocs/source/doc/Chronos/Overview/how-to-create-forecaster.md @@ -0,0 +1,63 @@ +## How to create a Forecaster +### 1. Forecaster +Before creating a Forecaster,you need to understand the four parameters `past_seq_len`, `future_seq_len`, `input_feature_num`, `output_feature_num`, which represent the time step and feature column, As shown below. +![](../Image/forecast-RR.png "time series") + + * **past_seq_len**: Sampled input length, represents the history time step. (i.e. lookback) + * **future_seq_len**: Sampled output length, represents the output time step.(i.e. horizon) + * **input_feature_num**: All feature column(s), including extra feature column(s) and target column(s). + * **output_feature_num**: Only target column(s). + +After understanding these 4 parameters, the next step is to create a Forecaster. +```note +Some forecaster models may only require some parameters, such as +LSTMforecaster without specifying future_seq_len, because lstm is a single-step model. +``` + +### 2. create a forecaster. +We provide two methods for creating Forecaster. +#### 1. Create a Forecaster using Forecaster.from_tsdataset(Highly recommended) +`from_tsdataset` is a class method, so you can call `Forecsater.from_tsdataset` directly, then enter a `TSDataset` instance. +`TSDataset` is a built-in time series preprocessing class, more info please refer to [how to use TSDataset and get_public_dataset](xxxx). +If your tsdataset has used the `roll` or `to_torch_data_loader` methods, +you do not need to specify `past_seq_len` and `future_seq_len` for from_tsdataset, otherwise you must specify both. +You can also specify the hyperparameters of the model, such as lr, dropout etc. +The simplest usage of "from_tsdataset" is given below. More info, please refer to [from_tsdataset](xxxx). + +```python +from bigdl.chronos.forecaster import TCNForecaster +from bigdl.chronos.data import TSDataset +tsdataset = TSDataset.from_pandas(df, ...) # df is a pandas.DataFrame +# No call roll and to_torch_data_loader +tcn = TCNForecaster.from_tsdataset(tsdataset, + past_seq_len=48, + future_seq_len=5) + +tcn.fit(tsdataset) + +# Call roll or to_torch_dataloader, do not specify past_seq_len and future_seq_len +loader = tsdataset.to_torch_data_loader(...) +tcn = TCNForecaster.from_tsdataset(tsdataset) + +tcn.fit(loader) +``` + +#### 2. Create a forecaster directly +You can also create TCNForecaster directly. +```python +from bigdl.chronos.forecaster import TCNForecaster +# prepare dataset +timeseries = ... + +tcn = TCNForecaster(past_seq_len=48, + future_seq_len=5, + input_feature_num=2, + output_feature_num=2) + +tcn.fit(timeseries) +``` + +### 3. further reading +training: After you have created the forecaster, you can train your model, Please refer to [how to train]() +distributed: When your data volume is large and it is difficult to complete on a single machine, we also provide distributed training, please refer to [train model distributed on a cluster]() +forecaster.load: \ No newline at end of file From 9536fa1114e629e360e23b657d7590809fe94444 Mon Sep 17 00:00:00 2001 From: liangs6212 Date: Wed, 17 Aug 2022 18:05:09 +0800 Subject: [PATCH 03/15] remove redundant message --- .../Overview/how-to-create-forecaster.md | 28 +++++++++---------- 1 file changed, 13 insertions(+), 15 deletions(-) diff --git a/docs/readthedocs/source/doc/Chronos/Overview/how-to-create-forecaster.md b/docs/readthedocs/source/doc/Chronos/Overview/how-to-create-forecaster.md index 6016e4b41ad..331cf6f7898 100644 --- a/docs/readthedocs/source/doc/Chronos/Overview/how-to-create-forecaster.md +++ b/docs/readthedocs/source/doc/Chronos/Overview/how-to-create-forecaster.md @@ -15,14 +15,13 @@ LSTMforecaster without specifying future_seq_len, because lstm is a single-step ``` ### 2. create a forecaster. -We provide two methods for creating Forecaster. -#### 1. Create a Forecaster using Forecaster.from_tsdataset(Highly recommended) -`from_tsdataset` is a class method, so you can call `Forecsater.from_tsdataset` directly, then enter a `TSDataset` instance. -`TSDataset` is a built-in time series preprocessing class, more info please refer to [how to use TSDataset and get_public_dataset](xxxx). -If your tsdataset has used the `roll` or `to_torch_data_loader` methods, -you do not need to specify `past_seq_len` and `future_seq_len` for from_tsdataset, otherwise you must specify both. -You can also specify the hyperparameters of the model, such as lr, dropout etc. -The simplest usage of "from_tsdataset" is given below. More info, please refer to [from_tsdataset](xxxx). +We provide two ways to create a Forecaster. + +#### Create a Forecaster using Forecaster.from_tsdataset(Highly recommended) +`from_tsdataset` is a classmethod, so you can call `Forecsater.from_tsdataset`, then input a `TSDataset` instance. +`TSDataset` is a built-in time series preprocessing class. +If your tsdataset has used the `roll` or `to_torch_data_loader` methods, you do not need to specify `past_seq_len` and `future_seq_len` for from_tsdataset, otherwise you must specify both. +You can also specify the hyperparameters of the model, such as lr, dropout etc. The simplest usage of "from_tsdataset" is given below. ```python from bigdl.chronos.forecaster import TCNForecaster @@ -32,18 +31,17 @@ tsdataset = TSDataset.from_pandas(df, ...) # df is a pandas.DataFrame tcn = TCNForecaster.from_tsdataset(tsdataset, past_seq_len=48, future_seq_len=5) - tcn.fit(tsdataset) # Call roll or to_torch_dataloader, do not specify past_seq_len and future_seq_len loader = tsdataset.to_torch_data_loader(...) tcn = TCNForecaster.from_tsdataset(tsdataset) - tcn.fit(loader) ``` -#### 2. Create a forecaster directly -You can also create TCNForecaster directly. +#### Create a forecaster directly +You can also create TCNForecaster directly, the parameters mentioned above still need to be specified. + ```python from bigdl.chronos.forecaster import TCNForecaster # prepare dataset @@ -58,6 +56,6 @@ tcn.fit(timeseries) ``` ### 3. further reading -training: After you have created the forecaster, you can train your model, Please refer to [how to train]() -distributed: When your data volume is large and it is difficult to complete on a single machine, we also provide distributed training, please refer to [train model distributed on a cluster]() -forecaster.load: \ No newline at end of file +training: After you have created the forecaster, you can train your model. +distributed: When your data volume is large and it is difficult to complete on a single machine, we also provide distributed training. +load: When you have trained and saved the model locally, you can load a model. From 1a9442de111a5d394d2c1b8fcfae1a618780608a Mon Sep 17 00:00:00 2001 From: liangs6212 Date: Wed, 24 Aug 2022 14:52:45 +0800 Subject: [PATCH 04/15] fix known issues --- .../Howto/how-to-create-forecaster.ipynb | 146 ++++++++++++++++++ .../Overview/how-to-create-forecaster.md | 61 -------- 2 files changed, 146 insertions(+), 61 deletions(-) create mode 100644 docs/readthedocs/source/doc/Chronos/Howto/how-to-create-forecaster.ipynb delete mode 100644 docs/readthedocs/source/doc/Chronos/Overview/how-to-create-forecaster.md diff --git a/docs/readthedocs/source/doc/Chronos/Howto/how-to-create-forecaster.ipynb b/docs/readthedocs/source/doc/Chronos/Howto/how-to-create-forecaster.ipynb new file mode 100644 index 00000000000..eb1d819ca21 --- /dev/null +++ b/docs/readthedocs/source/doc/Chronos/Howto/how-to-create-forecaster.ipynb @@ -0,0 +1,146 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "# How to create a Forecaster" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Forecaster Introduction\n", + "Before creating a Forecaster, you need to understand the four parameters `past_seq_len`, `future_seq_len`, `input_feature_num`, `output_feature_num`, which represent the time step and feature column, As shown below.\n", + "![](../Image/forecast-RR.png \"time series\")\n", + " * **past_seq_len**: Sampled input length, represents the history time step. (i.e. lookback)\n", + " * **future_seq_len**: Sampled output length, represents the output time step.(i.e. horizon)\n", + " * **input_feature_num**: All feature column(s), including extra feature column(s) and target column(s).\n", + " * **output_feature_num**: Only target column(s)." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "After understanding these 4 parameters, the next step is to create a Forecaster.\n", + "\n", + "Tips: Some forecaster models may only require some parameters, such as\n", + "LSTMforecaster without specifying future_seq_len, because lstm is a single-step model.\n", + "More Forecaster info, please refer to [Time Series Forecasting OverView](https://bigdl.readthedocs.io/en/latest/doc/Chronos/Overview/forecasting.html#time-series-forecasting-overview)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Create a forecaster\n", + "We provide two ways to create a Forecaster.\n", + "* `Forecaster.from_tsdataset`(**Highly recommended**)\n", + "* Create a `Forecaster` directly" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Create a Forecaster using Forecaster.from_tsdataset(**Highly recommended**)\n", + "`from_tsdataset` is a classmethod, so you can call `Forecsater.from_tsdataset`, then input a `TSDataset` instance.\n", + "`TSDataset` is a built-in time series preprocessing class. More info, please refer to [here](https://bigdl.readthedocs.io/en/latest/doc/Chronos/Overview/quick-tour.html#tsdataset-xshardstsdataset).\n", + "\n", + "If your tsdataset has used the `roll` or `to_torch_data_loader` methods, you do not need to specify `past_seq_len` and `future_seq_len` for from_tsdataset, otherwise you must specify both.\n", + "You can also specify the hyperparameters of the model, such as lr, dropout etc." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "import pandas as pd\n", + "from bigdl.chronos.forecaster import TCNForecaster\n", + "from bigdl.chronos.data import TSDataset\n", + "\n", + "df = pd.read_csv(...)\n", + "tsdataset = TSDataset.from_pandas(df, ...) # df is a pandas.DataFrame\n", + "# No call roll and to_torch_data_loader\n", + "tcn = TCNForecaster.from_tsdataset(tsdataset,\n", + " past_seq_len=48,\n", + " future_seq_len=5)\n", + "tcn.fit(tsdataset)\n", + "\n", + "# Do not specify past_seq_len and future_seq_len, if roll or to_torch_dataloader has been called.\n", + "tsdataset.to_torch_data_loader(...)\n", + "tcn = TCNForecaster.from_tsdataset(tsdataset)\n", + "tcn.fit(tsdataset)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Create a forecaster directly\n", + "You can also create TCNForecaster directly, the parameters mentioned above still need to be specified." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "from bigdl.chronos.forecaster import TCNForecaster\n", + "# prepare dataset\n", + "timeseries = ...\n", + "\n", + "tcn = TCNForecaster(past_seq_len=48,\n", + " future_seq_len=5,\n", + " input_feature_num=2,\n", + " output_feature_num=2)\n", + "\n", + "tcn.fit(timeseries)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Further reading\n", + "training: After you have created the forecaster, you can train your model. Please refer to [here](https://bigdl.readthedocs.io/en/latest/doc/Chronos/Howto/how_to_train_forecaster_on_one_node.html).\n", + "\n", + "distributed: When your data volume is large and it is difficult to complete on a single machine, we also provide distributed training.\n", + "\n", + "load: When you have trained and saved the model locally, you can load a model.\n", + "\n" + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3 (ipykernel)", + "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.12" + }, + "vscode": { + "interpreter": { + "hash": "1a7f5d41b94c9ba67b8a1438ec071a63464312bab4ac0991ee31faebf1c9c228" + } + } + }, + "nbformat": 4, + "nbformat_minor": 2 +} diff --git a/docs/readthedocs/source/doc/Chronos/Overview/how-to-create-forecaster.md b/docs/readthedocs/source/doc/Chronos/Overview/how-to-create-forecaster.md deleted file mode 100644 index 331cf6f7898..00000000000 --- a/docs/readthedocs/source/doc/Chronos/Overview/how-to-create-forecaster.md +++ /dev/null @@ -1,61 +0,0 @@ -## How to create a Forecaster -### 1. Forecaster -Before creating a Forecaster,you need to understand the four parameters `past_seq_len`, `future_seq_len`, `input_feature_num`, `output_feature_num`, which represent the time step and feature column, As shown below. -![](../Image/forecast-RR.png "time series") - - * **past_seq_len**: Sampled input length, represents the history time step. (i.e. lookback) - * **future_seq_len**: Sampled output length, represents the output time step.(i.e. horizon) - * **input_feature_num**: All feature column(s), including extra feature column(s) and target column(s). - * **output_feature_num**: Only target column(s). - -After understanding these 4 parameters, the next step is to create a Forecaster. -```note -Some forecaster models may only require some parameters, such as -LSTMforecaster without specifying future_seq_len, because lstm is a single-step model. -``` - -### 2. create a forecaster. -We provide two ways to create a Forecaster. - -#### Create a Forecaster using Forecaster.from_tsdataset(Highly recommended) -`from_tsdataset` is a classmethod, so you can call `Forecsater.from_tsdataset`, then input a `TSDataset` instance. -`TSDataset` is a built-in time series preprocessing class. -If your tsdataset has used the `roll` or `to_torch_data_loader` methods, you do not need to specify `past_seq_len` and `future_seq_len` for from_tsdataset, otherwise you must specify both. -You can also specify the hyperparameters of the model, such as lr, dropout etc. The simplest usage of "from_tsdataset" is given below. - -```python -from bigdl.chronos.forecaster import TCNForecaster -from bigdl.chronos.data import TSDataset -tsdataset = TSDataset.from_pandas(df, ...) # df is a pandas.DataFrame -# No call roll and to_torch_data_loader -tcn = TCNForecaster.from_tsdataset(tsdataset, - past_seq_len=48, - future_seq_len=5) -tcn.fit(tsdataset) - -# Call roll or to_torch_dataloader, do not specify past_seq_len and future_seq_len -loader = tsdataset.to_torch_data_loader(...) -tcn = TCNForecaster.from_tsdataset(tsdataset) -tcn.fit(loader) -``` - -#### Create a forecaster directly -You can also create TCNForecaster directly, the parameters mentioned above still need to be specified. - -```python -from bigdl.chronos.forecaster import TCNForecaster -# prepare dataset -timeseries = ... - -tcn = TCNForecaster(past_seq_len=48, - future_seq_len=5, - input_feature_num=2, - output_feature_num=2) - -tcn.fit(timeseries) -``` - -### 3. further reading -training: After you have created the forecaster, you can train your model. -distributed: When your data volume is large and it is difficult to complete on a single machine, we also provide distributed training. -load: When you have trained and saved the model locally, you can load a model. From f8709a7ea4aeed45b5b4bac67998b40551295517 Mon Sep 17 00:00:00 2001 From: liangs6212 Date: Wed, 24 Aug 2022 15:16:18 +0800 Subject: [PATCH 05/15] add rst --- docs/readthedocs/source/doc/Chronos/Howto/index.rst | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/docs/readthedocs/source/doc/Chronos/Howto/index.rst b/docs/readthedocs/source/doc/Chronos/Howto/index.rst index 2a1d5c16ded..4fa27acc1df 100644 --- a/docs/readthedocs/source/doc/Chronos/Howto/index.rst +++ b/docs/readthedocs/source/doc/Chronos/Howto/index.rst @@ -2,6 +2,13 @@ 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. + +Create a Forecasting +------------------------- +* `Create a forecaster `__ + + In this guidance, we demonstrate **How to create a Forecaster**. Including two ways of creating a forecaster and an explanation of some important parameters. + Forecasting ------------------------- * `Train forecaster on single node `__ @@ -13,10 +20,11 @@ Forecasting In this guidance, we demonstrate **how to tune forecaster on single node**. In tuning process, forecaster will find the best hyperparameter combination among user-defined search space, which is a common process if users pursue a forecaster with higher accuracy. + .. toctree:: :maxdepth: 1 :hidden: + how-to-create-forecaster how_to_train_forecaster_on_one_node - how_to_tune_forecaster_model From f7ff0d71a1a49f3a396884849f445a6cec770d8f Mon Sep 17 00:00:00 2001 From: liangs6212 Date: Wed, 24 Aug 2022 15:56:24 +0800 Subject: [PATCH 06/15] move create-forecaster to new line --- docs/readthedocs/source/doc/Chronos/Howto/index.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/readthedocs/source/doc/Chronos/Howto/index.rst b/docs/readthedocs/source/doc/Chronos/Howto/index.rst index 4fa27acc1df..579f7db0427 100644 --- a/docs/readthedocs/source/doc/Chronos/Howto/index.rst +++ b/docs/readthedocs/source/doc/Chronos/Howto/index.rst @@ -20,7 +20,6 @@ Forecasting In this guidance, we demonstrate **how to tune forecaster on single node**. In tuning process, forecaster will find the best hyperparameter combination among user-defined search space, which is a common process if users pursue a forecaster with higher accuracy. - .. toctree:: :maxdepth: 1 :hidden: From 9c92a9ee7f2e4e2b7a943807bc3dde32a341f417 Mon Sep 17 00:00:00 2001 From: liangs6212 Date: Mon, 29 Aug 2022 14:44:34 +0800 Subject: [PATCH 07/15] fix known issue --- .../Howto/how-to-create-forecaster.ipynb | 72 +++++++++++++------ 1 file changed, 52 insertions(+), 20 deletions(-) diff --git a/docs/readthedocs/source/doc/Chronos/Howto/how-to-create-forecaster.ipynb b/docs/readthedocs/source/doc/Chronos/Howto/how-to-create-forecaster.ipynb index eb1d819ca21..6bb550b2f9c 100644 --- a/docs/readthedocs/source/doc/Chronos/Howto/how-to-create-forecaster.ipynb +++ b/docs/readthedocs/source/doc/Chronos/Howto/how-to-create-forecaster.ipynb @@ -1,5 +1,12 @@ { "cells": [ + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "![image.png](data:image/png;base64,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)" + ] + }, { "cell_type": "markdown", "metadata": {}, @@ -11,8 +18,8 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "## Forecaster Introduction\n", - "Before creating a Forecaster, you need to understand the four parameters `past_seq_len`, `future_seq_len`, `input_feature_num`, `output_feature_num`, which represent the time step and feature column, As shown below.\n", + "## Introduction to Forecaster Parameters\n", + "Before creating a Forecaster, you need to know the four parameters `past_seq_len`, `future_seq_len`, `input_feature_num`, `output_feature_num`, which represent the time step and feature column, As shown below.\n", "![](../Image/forecast-RR.png \"time series\")\n", " * **past_seq_len**: Sampled input length, represents the history time step. (i.e. lookback)\n", " * **future_seq_len**: Sampled output length, represents the output time step.(i.e. horizon)\n", @@ -24,13 +31,39 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "After understanding these 4 parameters, the next step is to create a Forecaster.\n", + "Once you know these 4 parameters, the next step is to create a Forecaster.\n", "\n", "Tips: Some forecaster models may only require some parameters, such as\n", - "LSTMforecaster without specifying future_seq_len, because lstm is a single-step model.\n", + "LSTMForecaster without specifying future_seq_len, because lstm is a single-step model. NBeatsForecaster is a univariate model.\n", + "\n", "More Forecaster info, please refer to [Time Series Forecasting OverView](https://bigdl.readthedocs.io/en/latest/doc/Chronos/Overview/forecasting.html#time-series-forecasting-overview)" ] }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Prepare Environments" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Before creating a forecaster, we need to install chronos and select pytorch as the deep learning backend." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "!pip install --pre --upgrade bigdl-chronos[pytorch]\n", + "!pip uninstall torchtext -y\n", + "exit()" + ] + }, { "cell_type": "markdown", "metadata": {}, @@ -50,6 +83,7 @@ "`TSDataset` is a built-in time series preprocessing class. More info, please refer to [here](https://bigdl.readthedocs.io/en/latest/doc/Chronos/Overview/quick-tour.html#tsdataset-xshardstsdataset).\n", "\n", "If your tsdataset has used the `roll` or `to_torch_data_loader` methods, you do not need to specify `past_seq_len` and `future_seq_len` for from_tsdataset, otherwise you must specify both.\n", + "\n", "You can also specify the hyperparameters of the model, such as lr, dropout etc." ] }, @@ -59,22 +93,18 @@ "metadata": {}, "outputs": [], "source": [ - "import pandas as pd\n", + "from bigdl.chronos.data.repo_dataset import get_public_dataset\n", "from bigdl.chronos.forecaster import TCNForecaster\n", - "from bigdl.chronos.data import TSDataset\n", "\n", - "df = pd.read_csv(...)\n", - "tsdataset = TSDataset.from_pandas(df, ...) # df is a pandas.DataFrame\n", - "# No call roll and to_torch_data_loader\n", + "\n", + "tsdataset = get_public_dataset('nyc_taxi', with_split=False) # df is a pandas.DataFrame\n", + "# `to_torch_data_loader` and `call` are not called\n", "tcn = TCNForecaster.from_tsdataset(tsdataset,\n", " past_seq_len=48,\n", - " future_seq_len=5)\n", - "tcn.fit(tsdataset)\n", - "\n", - "# Do not specify past_seq_len and future_seq_len, if roll or to_torch_dataloader has been called.\n", - "tsdataset.to_torch_data_loader(...)\n", - "tcn = TCNForecaster.from_tsdataset(tsdataset)\n", - "tcn.fit(tsdataset)" + " future_seq_len=5,\n", + " lr=1e-3,\n", + " dropout=0.1)\n", + "tcn.fit(tsdataset, epochs=5, batch_size=32)" ] }, { @@ -92,15 +122,17 @@ "outputs": [], "source": [ "from bigdl.chronos.forecaster import TCNForecaster\n", + "from bigdl.chronos.data.repo_dataset import get_public_dataset\n", "# prepare dataset\n", - "timeseries = ...\n", + "tsdataset = get_public_dataset('network_traffic', with_split=False)\n", + "tsdataset.roll(lookback=48, horizon=5)\n", "\n", "tcn = TCNForecaster(past_seq_len=48,\n", " future_seq_len=5,\n", " input_feature_num=2,\n", " output_feature_num=2)\n", "\n", - "tcn.fit(timeseries)" + "tcn.fit(tsdataset)" ] }, { @@ -112,7 +144,7 @@ "\n", "distributed: When your data volume is large and it is difficult to complete on a single machine, we also provide distributed training.\n", "\n", - "load: When you have trained and saved the model locally, you can load a model.\n", + "load: When you have trained and saved the model locally, you can use forecaster.load a model.\n", "\n" ] } @@ -133,7 +165,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.7.12" + "version": "3.7.13" }, "vscode": { "interpreter": { From 33505d158a067f0fdb21dd4cb17d5b92564796f8 Mon Sep 17 00:00:00 2001 From: liangs6212 Date: Mon, 29 Aug 2022 15:08:06 +0800 Subject: [PATCH 08/15] fix syntax error --- .../doc/Chronos/Howto/how-to-create-forecaster.ipynb | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/docs/readthedocs/source/doc/Chronos/Howto/how-to-create-forecaster.ipynb b/docs/readthedocs/source/doc/Chronos/Howto/how-to-create-forecaster.ipynb index 6bb550b2f9c..9c6f7765ecf 100644 --- a/docs/readthedocs/source/doc/Chronos/Howto/how-to-create-forecaster.ipynb +++ b/docs/readthedocs/source/doc/Chronos/Howto/how-to-create-forecaster.ipynb @@ -20,11 +20,13 @@ "source": [ "## Introduction to Forecaster Parameters\n", "Before creating a Forecaster, you need to know the four parameters `past_seq_len`, `future_seq_len`, `input_feature_num`, `output_feature_num`, which represent the time step and feature column, As shown below.\n", + "\n", "![](../Image/forecast-RR.png \"time series\")\n", - " * **past_seq_len**: Sampled input length, represents the history time step. (i.e. lookback)\n", - " * **future_seq_len**: Sampled output length, represents the output time step.(i.e. horizon)\n", - " * **input_feature_num**: All feature column(s), including extra feature column(s) and target column(s).\n", - " * **output_feature_num**: Only target column(s)." + "\n", + "* **past_seq_len**: Sampled input length, represents the history time step. (i.e. lookback)\n", + "* **future_seq_len**: Sampled output length, represents the output time step.(i.e. horizon)\n", + "* **input_feature_num**: All feature column(s), including extra feature column(s) and target column(s).\n", + "* **output_feature_num**: Only target column(s)." ] }, { @@ -70,6 +72,7 @@ "source": [ "## Create a forecaster\n", "We provide two ways to create a Forecaster.\n", + "\n", "* `Forecaster.from_tsdataset`(**Highly recommended**)\n", "* Create a `Forecaster` directly" ] @@ -79,6 +82,7 @@ "metadata": {}, "source": [ "### Create a Forecaster using Forecaster.from_tsdataset(**Highly recommended**)\n", + "\n", "`from_tsdataset` is a classmethod, so you can call `Forecsater.from_tsdataset`, then input a `TSDataset` instance.\n", "`TSDataset` is a built-in time series preprocessing class. More info, please refer to [here](https://bigdl.readthedocs.io/en/latest/doc/Chronos/Overview/quick-tour.html#tsdataset-xshardstsdataset).\n", "\n", From bc006a29c5bd8499cc158b65fa8e36525db34862 Mon Sep 17 00:00:00 2001 From: liangs6212 Date: Mon, 29 Aug 2022 15:15:02 +0800 Subject: [PATCH 09/15] fix syntax error again --- .../source/doc/Chronos/Howto/how-to-create-forecaster.ipynb | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/docs/readthedocs/source/doc/Chronos/Howto/how-to-create-forecaster.ipynb b/docs/readthedocs/source/doc/Chronos/Howto/how-to-create-forecaster.ipynb index 9c6f7765ecf..c3fd650e4b1 100644 --- a/docs/readthedocs/source/doc/Chronos/Howto/how-to-create-forecaster.ipynb +++ b/docs/readthedocs/source/doc/Chronos/Howto/how-to-create-forecaster.ipynb @@ -81,7 +81,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "### Create a Forecaster using Forecaster.from_tsdataset(**Highly recommended**)\n", + "### Forecaster.from_tsdataset\n", "\n", "`from_tsdataset` is a classmethod, so you can call `Forecsater.from_tsdataset`, then input a `TSDataset` instance.\n", "`TSDataset` is a built-in time series preprocessing class. More info, please refer to [here](https://bigdl.readthedocs.io/en/latest/doc/Chronos/Overview/quick-tour.html#tsdataset-xshardstsdataset).\n", @@ -100,8 +100,7 @@ "from bigdl.chronos.data.repo_dataset import get_public_dataset\n", "from bigdl.chronos.forecaster import TCNForecaster\n", "\n", - "\n", - "tsdataset = get_public_dataset('nyc_taxi', with_split=False) # df is a pandas.DataFrame\n", + "tsdataset = get_public_dataset('nyc_taxi', with_split=False)\n", "# `to_torch_data_loader` and `call` are not called\n", "tcn = TCNForecaster.from_tsdataset(tsdataset,\n", " past_seq_len=48,\n", From 3bf94e291419a6619a241756f6430c4da7e4ea4d Mon Sep 17 00:00:00 2001 From: liangs6212 Date: Mon, 29 Aug 2022 15:45:26 +0800 Subject: [PATCH 10/15] add open-colab icon --- .../doc/Chronos/Howto/how-to-create-forecaster.ipynb | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/docs/readthedocs/source/doc/Chronos/Howto/how-to-create-forecaster.ipynb b/docs/readthedocs/source/doc/Chronos/Howto/how-to-create-forecaster.ipynb index c3fd650e4b1..964a66d5f72 100644 --- a/docs/readthedocs/source/doc/Chronos/Howto/how-to-create-forecaster.ipynb +++ b/docs/readthedocs/source/doc/Chronos/Howto/how-to-create-forecaster.ipynb @@ -1,5 +1,12 @@ { "cells": [ + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/intel-analytics/BigDL/blob/main/docs/readthedocs/source/doc/Chronos/Howto/how-to-create-forecaster.ipynb)" + ] + }, { "cell_type": "markdown", "metadata": {}, From 12b761951247d6e4f16258ce3a454c7f92ecc8a1 Mon Sep 17 00:00:00 2001 From: liangs6212 Date: Tue, 30 Aug 2022 16:15:37 +0800 Subject: [PATCH 11/15] fix known issues --- .../Howto/how-to-create-forecaster.ipynb | 74 +++++++++---------- 1 file changed, 33 insertions(+), 41 deletions(-) diff --git a/docs/readthedocs/source/doc/Chronos/Howto/how-to-create-forecaster.ipynb b/docs/readthedocs/source/doc/Chronos/Howto/how-to-create-forecaster.ipynb index 964a66d5f72..6e80003eb38 100644 --- a/docs/readthedocs/source/doc/Chronos/Howto/how-to-create-forecaster.ipynb +++ b/docs/readthedocs/source/doc/Chronos/Howto/how-to-create-forecaster.ipynb @@ -25,27 +25,13 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "## Introduction to Forecaster Parameters\n", - "Before creating a Forecaster, you need to know the four parameters `past_seq_len`, `future_seq_len`, `input_feature_num`, `output_feature_num`, which represent the time step and feature column, As shown below.\n", + "## Introduction\n", "\n", - "![](../Image/forecast-RR.png \"time series\")\n", + "BigDL-Chronos (Chronos for short) is an application framework for building a fast, accurate and scalable time series analysis application.\n", "\n", - "* **past_seq_len**: Sampled input length, represents the history time step. (i.e. lookback)\n", - "* **future_seq_len**: Sampled output length, represents the output time step.(i.e. horizon)\n", - "* **input_feature_num**: All feature column(s), including extra feature column(s) and target column(s).\n", - "* **output_feature_num**: Only target column(s)." - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "Once you know these 4 parameters, the next step is to create a Forecaster.\n", - "\n", - "Tips: Some forecaster models may only require some parameters, such as\n", - "LSTMForecaster without specifying future_seq_len, because lstm is a single-step model. NBeatsForecaster is a univariate model.\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 to control.\n", "\n", - "More Forecaster info, please refer to [Time Series Forecasting OverView](https://bigdl.readthedocs.io/en/latest/doc/Chronos/Overview/forecasting.html#time-series-forecasting-overview)" + "In this guide, we will use the `TCNFecaster` and nyc_taxi datasets as examples to describe how to create a Forecaster." ] }, { @@ -59,7 +45,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Before creating a forecaster, we need to install chronos and select pytorch as the deep learning backend." + "Before creating a forecaster, we need to install chronos. chronos supports deep learning backend implemented by pytorch and tensorflow and machine learning methods based on arima and prophet." ] }, { @@ -68,8 +54,10 @@ "metadata": {}, "outputs": [], "source": [ - "!pip install --pre --upgrade bigdl-chronos[pytorch]\n", + "!pip install --pre --upgrade bigdl-chronos[pytorch] # Here we choose a deep learning model based on pytorch.\n", "!pip uninstall torchtext -y\n", + "# !pip install --pre --upgrade bigdl-chronos # Comment the installation of pytorch and uncomment these two lines, and change a small amount of code to complete the switch of backend.\n", + "# !pip install --pre --upgrade bigdl-nano[tensorflow] \n", "exit()" ] }, @@ -84,6 +72,22 @@ "* Create a `Forecaster` directly" ] }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Before creating a Forecaster, We need to know the four parameters `past_seq_len`, `future_seq_len`, `input_feature_num`, `output_feature_num`, which represent the time step and feature column, As shown below.\n", + "\n", + "\n", + "\n", + "* **past_seq_len**: Sampled input length, represents the history time step. (i.e. lookback)\n", + "* **future_seq_len**: Sampled output length, represents the output time step.(i.e. horizon)\n", + "* **input_feature_num**: All feature column(s), including extra feature column(s) and target column(s).\n", + "* **output_feature_num**: Only target column(s).\n", + "\n", + "More Forecaster info, please refer to [Time Series Forecasting OverView](https://bigdl.readthedocs.io/en/latest/doc/Chronos/Overview/forecasting.html#time-series-forecasting-overview)" + ] + }, { "cell_type": "markdown", "metadata": {}, @@ -93,9 +97,9 @@ "`from_tsdataset` is a classmethod, so you can call `Forecsater.from_tsdataset`, then input a `TSDataset` instance.\n", "`TSDataset` is a built-in time series preprocessing class. More info, please refer to [here](https://bigdl.readthedocs.io/en/latest/doc/Chronos/Overview/quick-tour.html#tsdataset-xshardstsdataset).\n", "\n", - "If your tsdataset has used the `roll` or `to_torch_data_loader` methods, you do not need to specify `past_seq_len` and `future_seq_len` for from_tsdataset, otherwise you must specify both.\n", + "If the `roll` or `to torch data_loader` method has been called by tsdataset, `past_seq_len` and `future_seq_len` do not need to be specified for from_tsdataset, otherwise both must be specified.\n", "\n", - "You can also specify the hyperparameters of the model, such as lr, dropout etc." + "We can also specify hyperparameters of the model such as lr, dropout etc." ] }, { @@ -104,17 +108,15 @@ "metadata": {}, "outputs": [], "source": [ - "from bigdl.chronos.data.repo_dataset import get_public_dataset\n", "from bigdl.chronos.forecaster import TCNForecaster\n", + "from bigdl.chronos.data.repo_dataset import get_public_dataset\n", + "# from bigdl.chronos.forecaster.tf import TCNForecaster # Based on tensorflow\n", "\n", "tsdataset = get_public_dataset('nyc_taxi', with_split=False)\n", - "# `to_torch_data_loader` and `call` are not called\n", + "\n", "tcn = TCNForecaster.from_tsdataset(tsdataset,\n", " past_seq_len=48,\n", - " future_seq_len=5,\n", - " lr=1e-3,\n", - " dropout=0.1)\n", - "tcn.fit(tsdataset, epochs=5, batch_size=32)" + " future_seq_len=5)" ] }, { @@ -132,17 +134,12 @@ "outputs": [], "source": [ "from bigdl.chronos.forecaster import TCNForecaster\n", - "from bigdl.chronos.data.repo_dataset import get_public_dataset\n", - "# prepare dataset\n", - "tsdataset = get_public_dataset('network_traffic', with_split=False)\n", - "tsdataset.roll(lookback=48, horizon=5)\n", + "# from bigdl.chronos.forecaster.tf import TCNForecaster\n", "\n", "tcn = TCNForecaster(past_seq_len=48,\n", " future_seq_len=5,\n", " input_feature_num=2,\n", - " output_feature_num=2)\n", - "\n", - "tcn.fit(tsdataset)" + " output_feature_num=2)" ] }, { @@ -150,12 +147,7 @@ "metadata": {}, "source": [ "## Further reading\n", - "training: After you have created the forecaster, you can train your model. Please refer to [here](https://bigdl.readthedocs.io/en/latest/doc/Chronos/Howto/how_to_train_forecaster_on_one_node.html).\n", - "\n", - "distributed: When your data volume is large and it is difficult to complete on a single machine, we also provide distributed training.\n", - "\n", - "load: When you have trained and saved the model locally, you can use forecaster.load a model.\n", - "\n" + "Train Forecaster: After we create the Forecaster, we can train the model through fit. About how-to-train-forecaster, please refer to [here](https://bigdl.readthedocs.io/en/latest/doc/Chronos/Howto/how_to_train_forecaster_on_one_node.html).\n" ] } ], From 5feb1f6e69e0ca5eeb055f69305dc43e5b6a24cc Mon Sep 17 00:00:00 2001 From: theaperdeng Date: Tue, 6 Sep 2022 22:21:31 +0800 Subject: [PATCH 12/15] fix some words --- .../Howto/how-to-create-forecaster.ipynb | 82 +++++++++++-------- 1 file changed, 47 insertions(+), 35 deletions(-) diff --git a/docs/readthedocs/source/doc/Chronos/Howto/how-to-create-forecaster.ipynb b/docs/readthedocs/source/doc/Chronos/Howto/how-to-create-forecaster.ipynb index 6e80003eb38..6423037c237 100644 --- a/docs/readthedocs/source/doc/Chronos/Howto/how-to-create-forecaster.ipynb +++ b/docs/readthedocs/source/doc/Chronos/Howto/how-to-create-forecaster.ipynb @@ -27,11 +27,9 @@ "source": [ "## Introduction\n", "\n", - "BigDL-Chronos (Chronos for short) is an application framework for building a fast, accurate and scalable time series analysis application.\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 to control.\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 to control.\n", - "\n", - "In this guide, we will use the `TCNFecaster` and nyc_taxi datasets as examples to describe how to create a Forecaster." + "In this guide, we will use the `TCNForecaster` and nyc_taxi datasets as examples to describe **how to create a Forecaster**." ] }, { @@ -45,7 +43,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Before creating a forecaster, we need to install chronos. chronos supports deep learning backend implemented by pytorch and tensorflow and machine learning methods based on arima and prophet." + "Before creating a forecaster, we need to install Chronos. Chronos supports deep learning backend implemented by pytorch and tensorflow and machine learning methods based on arima and prophet." ] }, { @@ -54,10 +52,15 @@ "metadata": {}, "outputs": [], "source": [ - "!pip install --pre --upgrade bigdl-chronos[pytorch] # Here we choose a deep learning model based on pytorch.\n", + "# uncomment following 1 lines for pytorch backend\n", + "!pip install --pre --upgrade bigdl-chronos[pytorch]\n", + "\n", + "# uncomment following 2 lines for tensorflow backend\n", + "# !pip install --pre --upgrade bigdl-chronos\n", + "# !pip install --pre --upgrade bigdl-nano[tensorflow]\n", + "\n", + "# installation trick on colab (no need to do these on your own environment)\n", "!pip uninstall torchtext -y\n", - "# !pip install --pre --upgrade bigdl-chronos # Comment the installation of pytorch and uncomment these two lines, and change a small amount of code to complete the switch of backend.\n", - "# !pip install --pre --upgrade bigdl-nano[tensorflow] \n", "exit()" ] }, @@ -68,8 +71,8 @@ "## Create a forecaster\n", "We provide two ways to create a Forecaster.\n", "\n", - "* `Forecaster.from_tsdataset`(**Highly recommended**)\n", - "* Create a `Forecaster` directly" + "* Create by `Forecaster.from_tsdataset`(**Recommended if valid**)\n", + "* Create by `Forecaster(...)` directly" ] }, { @@ -80,12 +83,26 @@ "\n", "\n", "\n", - "* **past_seq_len**: Sampled input length, represents the history time step. (i.e. lookback)\n", - "* **future_seq_len**: Sampled output length, represents the output time step.(i.e. horizon)\n", + "* **past_seq_len**: Sampled input length, represents the history time step length. (i.e. lookback)\n", + "* **future_seq_len**: Sampled output length, represents the output time step length.(i.e. horizon)\n", "* **input_feature_num**: All feature column(s), including extra feature column(s) and target column(s).\n", "* **output_feature_num**: Only target column(s).\n", "\n", - "More Forecaster info, please refer to [Time Series Forecasting OverView](https://bigdl.readthedocs.io/en/latest/doc/Chronos/Overview/forecasting.html#time-series-forecasting-overview)" + "More Forecaster info, please refer to [Time Series Forecasting OverView](https://bigdl.readthedocs.io/en/latest/doc/Chronos/Overview/forecasting.html#time-series-forecasting-overview)\n", + "\n", + "If you want to create a traditional statistic forecaster(e.g. [`ProphetForecaster`](https://bigdl.readthedocs.io/en/latest/doc/PythonAPI/Chronos/forecasters.html#prophetforecaster) or [`ARIMAForecaster`](https://bigdl.readthedocs.io/en/latest/doc/PythonAPI/Chronos/forecasters.html#arimaforecaster)), you may refer to their API doc directly since they are relatively easy and do not have required parameters to create them." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "# create a TSDataset\n", + "from bigdl.chronos.data.repo_dataset import get_public_dataset\n", + "\n", + "tsdataset = get_public_dataset('nyc_taxi', with_split=False)" ] }, { @@ -94,12 +111,9 @@ "source": [ "### Forecaster.from_tsdataset\n", "\n", - "`from_tsdataset` is a classmethod, so you can call `Forecsater.from_tsdataset`, then input a `TSDataset` instance.\n", - "`TSDataset` is a built-in time series preprocessing class. More info, please refer to [here](https://bigdl.readthedocs.io/en/latest/doc/Chronos/Overview/quick-tour.html#tsdataset-xshardstsdataset).\n", + "`from_tsdataset` is a classmethod, so you can call `Forecsater.from_tsdataset`, then input a `TSDataset` instance, where `TSDataset` is a built-in time series preprocessing class.\n", "\n", - "If the `roll` or `to torch data_loader` method has been called by tsdataset, `past_seq_len` and `future_seq_len` do not need to be specified for from_tsdataset, otherwise both must be specified.\n", - "\n", - "We can also specify hyperparameters of the model such as lr, dropout etc." + "If the `roll` or `to_torch_data_loader` method has been called by tsdataset, `past_seq_len` and `future_seq_len` do not need to be specified for from_tsdataset, otherwise both must be specified." ] }, { @@ -108,23 +122,32 @@ "metadata": {}, "outputs": [], "source": [ + "# uncomment following 1 lines for pytorch backend\n", "from bigdl.chronos.forecaster import TCNForecaster\n", - "from bigdl.chronos.data.repo_dataset import get_public_dataset\n", - "# from bigdl.chronos.forecaster.tf import TCNForecaster # Based on tensorflow\n", "\n", - "tsdataset = get_public_dataset('nyc_taxi', with_split=False)\n", + "# uncomment following 1 lines for tensorflow backend\n", + "# from bigdl.chronos.forecaster.tf import TCNForecaster\n", "\n", "tcn = TCNForecaster.from_tsdataset(tsdataset,\n", " past_seq_len=48,\n", " future_seq_len=5)" ] }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "> 📝 **Note**\n", + ">\n", + "> We recommened to use `Forecsater.from_tsdataset` if possible. While for some reasons, some forecasters (e.g. `ProphetForecaster` and `ARIMAForecaster`) does not support this API. Or maybe you want to process your data customizedly without using `TSDataset`, you may create a forecaster directly by calling `Forecaster(...)`." + ] + }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Create a forecaster directly\n", - "You can also create TCNForecaster directly, the parameters mentioned above still need to be specified." + "You can also create forecaster directly, the parameters mentioned above still need to be specified." ] }, { @@ -133,27 +156,16 @@ "metadata": {}, "outputs": [], "source": [ - "from bigdl.chronos.forecaster import TCNForecaster\n", - "# from bigdl.chronos.forecaster.tf import TCNForecaster\n", - "\n", "tcn = TCNForecaster(past_seq_len=48,\n", " future_seq_len=5,\n", " input_feature_num=2,\n", " output_feature_num=2)" ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "## Further reading\n", - "Train Forecaster: After we create the Forecaster, we can train the model through fit. About how-to-train-forecaster, please refer to [here](https://bigdl.readthedocs.io/en/latest/doc/Chronos/Howto/how_to_train_forecaster_on_one_node.html).\n" - ] } ], "metadata": { "kernelspec": { - "display_name": "Python 3 (ipykernel)", + "display_name": "Python 3.7.13 ('chronos')", "language": "python", "name": "python3" }, @@ -171,7 +183,7 @@ }, "vscode": { "interpreter": { - "hash": "1a7f5d41b94c9ba67b8a1438ec071a63464312bab4ac0991ee31faebf1c9c228" + "hash": "f7cbcfcf124497a723b2fc91b0dad8cd6ed41af955928289a9d3478af9690021" } } }, From ffde85d7796ae2fd59ee69386188a0399619dbca Mon Sep 17 00:00:00 2001 From: theaperdeng Date: Tue, 6 Sep 2022 22:23:36 +0800 Subject: [PATCH 13/15] fix typo --- .../source/doc/Chronos/Howto/how-to-create-forecaster.ipynb | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/readthedocs/source/doc/Chronos/Howto/how-to-create-forecaster.ipynb b/docs/readthedocs/source/doc/Chronos/Howto/how-to-create-forecaster.ipynb index 6423037c237..bd9dcd2d017 100644 --- a/docs/readthedocs/source/doc/Chronos/Howto/how-to-create-forecaster.ipynb +++ b/docs/readthedocs/source/doc/Chronos/Howto/how-to-create-forecaster.ipynb @@ -139,7 +139,7 @@ "source": [ "> 📝 **Note**\n", ">\n", - "> We recommened to use `Forecsater.from_tsdataset` if possible. While for some reasons, some forecasters (e.g. `ProphetForecaster` and `ARIMAForecaster`) does not support this API. Or maybe you want to process your data customizedly without using `TSDataset`, you may create a forecaster directly by calling `Forecaster(...)`." + "> We recommend to use `Forecsater.from_tsdataset` if possible. While for some reasons, some forecasters (e.g. `ProphetForecaster` and `ARIMAForecaster`) does not support this API. Or maybe you want to process your data customizedly without using `TSDataset`, you may create a forecaster directly by calling `Forecaster(...)`." ] }, { From 139161685e01def64c25007777d284b31c78bc8a Mon Sep 17 00:00:00 2001 From: liangs6212 Date: Wed, 7 Sep 2022 13:18:28 +0800 Subject: [PATCH 14/15] fix syntax error --- .../source/doc/Chronos/Howto/how-to-create-forecaster.ipynb | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/readthedocs/source/doc/Chronos/Howto/how-to-create-forecaster.ipynb b/docs/readthedocs/source/doc/Chronos/Howto/how-to-create-forecaster.ipynb index bd9dcd2d017..9b09ef421e3 100644 --- a/docs/readthedocs/source/doc/Chronos/Howto/how-to-create-forecaster.ipynb +++ b/docs/readthedocs/source/doc/Chronos/Howto/how-to-create-forecaster.ipynb @@ -90,7 +90,7 @@ "\n", "More Forecaster info, please refer to [Time Series Forecasting OverView](https://bigdl.readthedocs.io/en/latest/doc/Chronos/Overview/forecasting.html#time-series-forecasting-overview)\n", "\n", - "If you want to create a traditional statistic forecaster(e.g. [`ProphetForecaster`](https://bigdl.readthedocs.io/en/latest/doc/PythonAPI/Chronos/forecasters.html#prophetforecaster) or [`ARIMAForecaster`](https://bigdl.readthedocs.io/en/latest/doc/PythonAPI/Chronos/forecasters.html#arimaforecaster)), you may refer to their API doc directly since they are relatively easy and do not have required parameters to create them." + "If you want to create a traditional statistic forecaster(e.g. [ProphetForecaster](https://bigdl.readthedocs.io/en/latest/doc/PythonAPI/Chronos/forecasters.html#prophetforecaster) or [ARIMAForecaster](https://bigdl.readthedocs.io/en/latest/doc/PythonAPI/Chronos/forecasters.html#arimaforecaster)), you may refer to their API doc directly since they are relatively easy and do not have required parameters to create them." ] }, { @@ -165,7 +165,7 @@ ], "metadata": { "kernelspec": { - "display_name": "Python 3.7.13 ('chronos')", + "display_name": "Python 3.7.13 ('chronos-deps')", "language": "python", "name": "python3" }, @@ -183,7 +183,7 @@ }, "vscode": { "interpreter": { - "hash": "f7cbcfcf124497a723b2fc91b0dad8cd6ed41af955928289a9d3478af9690021" + "hash": "1a7f5d41b94c9ba67b8a1438ec071a63464312bab4ac0991ee31faebf1c9c228" } } }, From eb3b31fc3fcfc42ce51d03db045b2efcde52dbd6 Mon Sep 17 00:00:00 2001 From: theaperdeng Date: Wed, 7 Sep 2022 14:29:25 +0800 Subject: [PATCH 15/15] add some update --- .../Chronos/Howto/how-to-create-forecaster.ipynb | 16 +++++++++++++++- .../source/doc/Chronos/Howto/index.rst | 7 ++----- 2 files changed, 17 insertions(+), 6 deletions(-) diff --git a/docs/readthedocs/source/doc/Chronos/Howto/how-to-create-forecaster.ipynb b/docs/readthedocs/source/doc/Chronos/Howto/how-to-create-forecaster.ipynb index 9b09ef421e3..f1eee321e72 100644 --- a/docs/readthedocs/source/doc/Chronos/Howto/how-to-create-forecaster.ipynb +++ b/docs/readthedocs/source/doc/Chronos/Howto/how-to-create-forecaster.ipynb @@ -4,7 +4,21 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/intel-analytics/BigDL/blob/main/docs/readthedocs/source/doc/Chronos/Howto/how-to-create-forecaster.ipynb)" + "[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/intel-analytics/BigDL/blob/main/docs/readthedocs/source/doc/Chronos/Howto/how-to-create-forecaster.ipynb)\n", + "\n", + "\n" ] }, { diff --git a/docs/readthedocs/source/doc/Chronos/Howto/index.rst b/docs/readthedocs/source/doc/Chronos/Howto/index.rst index 579f7db0427..931904e7ac1 100644 --- a/docs/readthedocs/source/doc/Chronos/Howto/index.rst +++ b/docs/readthedocs/source/doc/Chronos/Howto/index.rst @@ -2,15 +2,12 @@ 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. - -Create a Forecasting +Forecasting ------------------------- * `Create a forecaster `__ - In this guidance, we demonstrate **How to create a Forecaster**. Including two ways of creating a forecaster and an explanation of some important parameters. + In this guidance, we demonstrate **how to create a Forecaster**. Including two ways of creating a forecaster and an explanation of some important parameters. -Forecasting -------------------------- * `Train forecaster 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.