Improving docs, examples, and tutorials of pytorch-forecasting

[julian-fong]

This list is a quick bucket list of items that can be potentially improved from what I've seen in the docs.

As requested by @yarnabrina, we should create simple examples, reducing complexity of the library as much as possible, to encourage users who are not too familiar with pytorch-forecasting or time series machine learning in general to try out the library. I think for example, the 'Example' inside https://pytorch-forecasting.readthedocs.io/en/stable/getting-started.html# is way too complicated, and will deter users from using the library because it is too complex to understand and read through as a first time user.

Thus for now, I'm proposing we

• refactor the main example inside the getting-started page
• improve upon the tutorials page that is currently setup in the library.

I think these two items can improved in the following way:

• Restructure the tutorials page into sections, with increasing 'complexity' of tutorials. That way, new users unexperience with the library will instantly be guided to the intro notebooks, while experience users familiar with the model will be directed to more complex notebooks, specific to their needs.

1. This first section will be the 'introduction' section, which will contain one extremely basic introductory tutorial with minimal code, featuring all the different modules (TimeSeriesDataset, different Models, Trainers, etc), but with little to no explanations. This basic tutorial is designed to essentially be a minimal walkthrough on how to use the library. The preceding tutorials will explain more in depth about each module. For example, we will have one tutorial explaining TimeSeriesDataset and so on.
2. The second section will be "Modelling tutorials", where most of the autoregressive models or forecasting model tutorials will be located here. For example, this and this.
3. The last section will be used for any other miscellaneous and additional tutorials, for example, this

• For the tutorial in the getting-started page, we can re-use the very first intro notebook that we create to provide an extremely simple tutorial to explain to the user how it works.

I am also proposing that we split the directory that is used to load the data into a new directory inside the root folder named datasets. This folder will be the primarily method to load datasets for tutorials or for modelling purposes. To reduce duplication, we can just import loading methods from the sktime library.

This will allow us to keep the examples directory standalone, and the files inside will be used to code up simple functions and variables that can be used inside tutorials.

[julian-fong]

@fkiraly FYI

[julian-fong]

also, I need to figure out what Model.from_dataset() does, and why it is necessary for it to be called this way in order to do training. It seems pretty counterintuitive that we need to load the model using a dataset, but it also doesnt seem to serve any purpose as we are passing the dataloaders inside the trainer function..

[madprogramer]

Hi, I just saw this issue.

I just created PR #1720 on predict_mode/TimeSeriesDataset.from_dataset().

I think that is probably connected.

[julian-fong]

@yarnabrina, @benHeid Any thoughts on above suggestions? I would like your input if possible :)

[yarnabrina]

I fully agree with your general step by step tutorial idea. The current one does not seem approachable for beginners.

I think in pydata I tried to start with just endogenous single series, then adding panel/hierarchy part, followed by hierarchy, then exogenous, etc. type of flow, so if you can also do that type of flow with pytorch-forecasting, that'll be great. As a first tutorial, I will probably not vary hyperparameters too much, but use the most common ones in the first case, and try to keep them similar in following steps if it make sense. Another thing that comes to my mind is I'll probably prefer to isolate the tuning part from usage without tuning part, because in my opinion it helps to get started with fit->predict flow common in most libraries first. These are of course just suggestions from my side, please feel free to adjust as you deem better.

In sktime we have the option to tell user how to check if all models are applicable for a section or not using tags, I think that's missing here. In future, adding a functionality for that may be useful.

---

I'll not make a comment about change of data folder. But I request you to keep that as part of different PR that new tutorials for sure, changing just path later in notebooks should be easy enough.

[benHeid]

I agree that we should do this, and I also agree to the comment of @yarnabrina.
Perhaps, we could do it similar as in sktime using multiple notebooks that indicate different chapters. I.e.,

1_introduction_to_pytorch_forecasting
2_.....