[DOC] Update docs to describe 0.4.0 API

[DOC] Update docs to describe 0.4.0 API

.gitignore

@@ -3,6 +3,8 @@
 examples/personal
 notebooks/*
 .vscode/*
+combined_files.txt
+x.py
 poetry.lock
 x.py
 

.pre-commit-config.yaml

@@ -23,6 +23,7 @@ repos:
       - id: check-merge-conflict
       - id: check-symlinks
       - id: check-yaml
+        args: ['--unsafe']
       - id: debug-statements
       - id: end-of-file-fixer
       - id: fix-encoding-pragma

docs/README.md

@@ -8,78 +8,65 @@
 [![PyPI version](https://badge.fury.io/py/prophetverse.svg)](https://badge.fury.io/py/prophetverse)
 [![codecov](https://codecov.io/gh/felipeangelimvieira/prophetverse/graph/badge.svg?token=O37PGJI3ZX)](https://codecov.io/gh/felipeangelimvieira/prophetverse)
 
-Prophetverse leverages the theory behind the Prophet model for time series forecasting and expands it into a more general framework, enabling custom priors and non-linear effects for exogenous variables. Built on top of [sktime](https://www.sktime.net/en/stable/) and [numpyro](https://num.pyro.ai/en/stable/), Prophetverse aims to provide a flexible and easy-to-use library for time series forecasting with a focus on interpretability and customizability. It is particularly useful for Marketing Mix Modeling, where understanding the effect of different marketing channels on sales is crucial.
+Prophetverse leverages the theory behind the Prophet model for time series forecasting and expands it into __a more general framework__, enabling custom priors, non-linear effects for exogenous variables and other likelihoods. Built on top of [sktime](https://www.sktime.net/en/stable/) and [numpyro](https://num.pyro.ai/en/stable/), Prophetverse aims to provide a flexible and easy-to-use library for time series forecasting with a focus on interpretability and customizability. It is particularly useful for Marketing Mix Modeling, where understanding the effect of different marketing channels on sales is crucial.
 
-### Features
-
-
-
-
-✅ Univariate and multivariate forecasting
-
-📊 Gamma-likelihood and Negative Binomial likelihood for count data
 
-🎲 Custom prior distributions for exogenous variables
+<div class="grid cards" markdown>
 
-🎯 Non-linear and customizable effects for exogenous variables
+-   :material-clock-fast:{ .lg .middle } __Set up in 5 minutes__
 
-🔗 Shared coefficients between timeseries (multi-variate model)
+    ---
 
-🌐 Sktime interface
+    Install `Prophetverse` with `pip` and get up
+    and forecasting in minutes
 
-📈 Capacity parameter of logistic trend as a random variable, and customizable trends.
+    [:octicons-arrow-right-24: Getting started](getting-started)
 
-✨ MCMC and MAP inference
+-   :material-school:{ .lg .middle } __Theory__
 
+    ---
 
+    Understand the idea behind the model and how it works
 
-## Installation
+    [:octicons-arrow-right-24: Read the post](the-theory)
 
-To install with pip:
+-   :material-file:{ .lg .middle } __Examples__
 
-```bash
-pip install prophetverse
-```
+    ---
 
-Or with poetry:
+    Go the example gallery and see how to use the model, and its features!
 
-```bash
-poetry add prophetverse
-```
+    [:octicons-arrow-right-24: Examples](examples/univariate)
 
+-   :material-book:{ .lg .middle } __Reference__
 
-## Differences between this Prophet and the original one
+    ---
 
-The main differences with the original Prophet model are:
+    Take a look at the API Reference to see all the available options
 
-### Logistic trend
+    [:octicons-arrow-right-24: Reference](reference/sktime/prophetverse/)
 
-In this implementation, the capacity is modeled as a random variable and is assumed to be constant. In the original model, it was necessary to pass the capacity as a hyperparameter, but we often don't know the maximum value. One example is forecasting the number of new users of a product. We may not know surely what the maximum number of new users is, and may be particularly interested in it.
 
-### Gamma and Negative Binomial likelihoods
+</div>
 
-The original model only supports Gaussian likelihood. This implementation supports Gamma and Negative Binomial likelihoods, which are useful for count data. 
 
-### Custom priors
 
-Users can set different prior distributions for the model parameters and define custom relationships between the exogenous variables and their effects on the mean. For example, one may want to force a positive effect of a variable on the mean, and use a HalfNormal prior for the coefficient and a `prophetverse.effects.LinearEffect` for the effect (see examples for more details).
 
-I believe this is one of the most important features of this library. It opens the door to a lot of applications, such as Marketing Mix Modeling, which has the objective of understanding the effect of different marketing channels on sales. A saturating effect, such as a Hill Function, can be used to model the diminishing returns of a given channel.
-
-### Changepoints
-
-The changepoint interval is used instead of the changepoint number. Motivation: as the time series evolve, a given changepoint number may have different meanings. For example, a changepoint number of 10 may be too much for a series with 100 observations but too little for a series with 1000 observations. The changepoint interval may avoid this problem and avoid the need of tuning this hyperparameter frequently.
-
-### Scaling
-
-The time series is scaled internally as it is in the original model to provide more stable hyperparameters. However, exogenous variables must be scaled by the user. For that, you can use sktime's transformers and pass them to the `feature_transformer` argument of the model. 
-
-### Seasonality
+### Features
 
-The Fourier terms for seasonality must be passed as exogenous variables in the `feature_transformer` argument, see [FourierFeatures](https://www.sktime.net/en/stable/api_reference/auto_generated/sktime.transformations.series.fourier.FourierFeatures.html) for a ready-to-use transformer. Also, check the examples in this documentation.
+Prophetverse is similar to the original Prophet model in many aspects, but it has some differences and new features. The following table summarizes the main features of Prophetverse and compares them with the original Prophet model:
 
-### Multivariate model
 
-For the hierarchical model, the forecast is done in a bottom-up fashion. All series parameters are inferred simultaneously, and a multivariate normal likelihood is used (with LKJ prior for the correlation matrix). In the future, forecasts with OLS reconciliation may be implemented.
 
-This model is also useful if you want to share coefficients of exogenous variables between time series. For example, if you have a dataset with multiple time series of sales of different products, you may want to share the effect of a given marketing channel between them. This is also possible with this implementation.
+| Feature                         | Prophetverse                                                                                                               | Original Prophet                         | Motivation |
+|---------------------------------|----------------------------------------------------------------------------------------------------------------------------|------------------------------------------| ----------------------------------------- |
+| **Logistic trend**              | Capacity as a random variable                           | Capacity as a hyperparameter, user input required             | The capacity is usually unknown by the users. Having it as a variable is useful for Total Addressable Market inference |
+| **Custom trend**               | Customizable trend functions                                                                                                | Not available                            | Users can create custom trends and leverage their knowledge about the timeseries to enhance long-term accuracy |
+| **Likelihoods**                 | Gaussian, Gamma and Negative Binomial                                                                                                | Gaussian only                            | Gaussian likelihood fails to provide good forecasts to positive-only and count data (sales, for example) |
+| **Custom priors**               | Supports custom priors for model parameters and exogenous variables                                                        | Not supported                            | Forcing positive coefficients, using prior knowledge to model the timeseries|
+| **Custom exogenous effects**              | Non-linear and customizable effects for exogenous variables, shared coefficients between time series                       | Not available                            | Users can create any kind of relationship between exogenous variables and the timeseries, which can be useful for Marketing Mix Modeling and other applications. |
+| **Changepoints**                | Uses changepoint interval                                                                                                  | Uses changepoint number                  | The changepoint number is not stable in the sense that, when the size of timeseries increases, its impact on forecast changes. Think about setting a changepoint number when timeseries has 6 months, and forecasting in future with 2 years of data (4x time original size). Re-tuning would be required. Prophetverse is expected to be more stable |
+| **Scaling**                     | Time series scaled internally, exogenous variables scaled by the user                                                      | Time series scaled internally            | Scaling `y` is needed to enhance user experience with hyperparameters. On the other hand, not scaling the exogenous variables provide more control to the user and they can leverage sktime's transformers to handle that. |
+| **Seasonality**                 | Fourier terms for seasonality passed as exogenous variables                                                                | Built-in seasonality handling            | Setting up seasonality requires almost zero effort by using `LinearFourierSeasonality` in Prophetverse. The idea is to allow the user to create custom seasonalities easily, without hardcoding it in the code. |
+| **Multivariate model**          | Hierarchical model with multivariate normal likelihood and LKJ prior, bottom-up forecast                                    | Not available                            | Having shared coefficients, using global information to enhance individual forecast.|| **Inference methods**           | MCMC and MAP                                                                                                               | MCMC and MAP                            | |
+| **Implementation** | Numpyro | Stan

docs/deprecation.md

@@ -1 +1,30 @@
-# Deprecation policy
+# Deprecation policy
+
+!!! note
+    Deprecation policy of Prophetverse takes place for versions `>=0.4.0`.
+
+
+## Versioning
+
+Prophetverse follows the [Semantic Versioning](https://semver.org/) scheme, which means that the version number is composed of three parts: `MAJOR.MINOR.PATCH`. However, we do not plan to release any `MAJOR` version until
+a large user base is built and the library is considered stable.
+
+### How breaking changes in Prophetverse API are released
+
+Breaking changes and deprecations are released in a two-step process:
+
+1. A new minor version is released with warnings to inform the users about the
+upcoming breaking changes. A `FutureWarning` is used to indicate the version in which 
+the change will be efective.
+2. The next minor version is released with the breaking changes and the deprecations
+are removed.
+
+For example, if we are in version 0.4.0 and a breaking change is introduced to enhance
+user experience, version 0.5.0 will keep the behaviour of 0.4.0 but will be released
+with a `FutureWarning`. 0.6.0 will be released with the breaking change and the warning
+will be removed.
+
+We will try to follow this policy as much as possible, but there may be cases where
+we need to make exceptions. In any case, we will always try to minimize the impact on
+the users. The larger the user base, the more we will try to avoid breaking changes.
+If any change affects your code, please let us know and we will do our best to help you.