# Timeseries Forecast ## Model Scenario {% embed url="" %} Watch a video on how to build a Time Series forecast based on demo dataset {% endembed %} A **Timeseries Forecast Model** is designed to predict future values by analyzing historical time-related data. To utilize this model, your dataset must include both time-based and numerical columns. In this tutorial, we'll cover the fundamentals of the **Model Scenario** to help you achieve optimal results.

*** ### Target Column For the **Target Column**, select a numeric value you want to predict. It's crucial to have values by day, week, or year. If some dates are repeated, you can aggregate them by taking their sum, average, etc.

*** ### Sequence and Time dimension setup Next, you can choose a **Sequence Identifier Field** to group fields and generate an independent time series and forecast forecast for each group. Keep in mind, these values shouldn't be unique; they must form a series and there is maximum of 500 unique values allowed as sequence identifier. If you don't want to generate independent time series for each group, you can leave this option empty.

*** Then, select the **Time/Date Column**, specifying the column containing time-related values. The **Time Interval** represents the data frequency—choose daily for daily data, yearly for annual data, etc. With **Forecast Horizon**, decide how many days, weeks, or years you want to predict from the last date in your dataset. If your dataset includes external factors that influence the target—such as marketing spend, weather, or pricing—you can add them as regressors. Simply select up to 5 additional columns in the *Regressors* field. These values will help the model better understand patterns and improve forecast accuracy. More info can be found in the [Regressors](https://docs.graphite-note.com/graphite-note-documentation/graphite-note-models/advanced-ml-model-settings/regressors) section. > :warning: Note: Since you’ve selected additional regressors for this model, predictions can’t be generated directly within the app interface. This is because the model requires future values for each regressor to make accurate predictions. Providing this data manually can be impractical, especially for large datasets. Instead, please use our Prediction API to submit your regressor values and generate forecasts programmatically.

*** The model performs well with seasonal data patterns. If your data shows a linear growth trend, select "additive" for **Seasonality Mode**; for exponential growth, select "multiplicative." For example, if you see annual patterns, set **Yearly Seasonality** to True. (TIP: Plotting your data beforehand can help you understand these patterns.) If you're unsure, the model will attempt to detect seasonality automatically.

For daily or hourly intervals, you can access **Advanced Parameters** to add special dates, weekends, holidays, or limit the target value. *** ### Advanced Parameters We are constantly enhancing our platform with new features and improving existing models. For your daily data, we've introduced some new capabilities that can significantly boost forecast accuracy. Now, you can limit your target predictions, remove outliers, and include country holidays and special events.

Selecting advanced parameters like special dates and holidays

To set prediction limits, enter the minimum and maximum values for your target variable. For example, if you're predicting daily temperatures and know the maximum is 40°C, enter that value to prevent the model from predicting higher temperatures. This helps the model recognize the appropriate range of the **Target Column**. Additionally, you can use the **Remove Days of the Week** feature to exclude certain days from your predictions. *** ### Country holidays and special dates We added parameters for country holidays and special dates to improve model accuracy. Large deviations can occur around holidays, where stores see more customers than usual. By informing the model about these holidays, you can achieve more balanced and accurate predictions. To add holidays in Graphite Note, navigate to the advanced section of the **Model Scenario** and select the relevant country or countries.

Similarly, you can add promotions or events that affect your data by enabling **Add special dates** option. Enter the promotion name, start date, duration, and future dates. This ensures the model accounts for these events in future predictions.

Combining these parameters provides more accurate results. The more information the model receives, the better the predictions. *** ### Removing data points In addition to adding holidays and special events, you can delete specific data points from your dataset. In Graphite Note, enter the start and end dates of the period you want to remove. For single-day periods, enter the same start and end date. You can remove multiple periods if necessary. Understanding your data and identifying outliers or irrelevant periods is crucial for accurate predictions. Removing these dates can help eliminate biases and improve model accuracy.

By following these steps, you can harness the full potential of your **Timeseries Forecast Model**, providing valuable insights and more accurate predictions for your business. Now it's your turn to do some modeling and explore your results! *** ### Training model After setting all parameters it is time to **Run Scenario** and train **Machine Learning** model.\ \ Before you do, you can choose to toggle Enable Model Results Dataset. This option creates a dedicated dataset that compares the model’s historical predictions with actual values, enabling detailed seasonality, trend analysis, and performance evaluation. These results will be accessible in the Performance tab once the model has finished training.

*** The training duration may vary depending on the data volume, typically ranging from 1 to 10 minutes. The training will utilize 80% of the data to train various machine learning models and the remaining 20% to test these models and calculate relevant scores. Once completed, you will receive information about the best model based on the F1 value and details about training time.

*** ## Model Performance To interpret the results after running your model, you will be taken to Performance tab. Here, on the Overivew screen, you can see the overall model performance post-training. Model evaluation metrics such as F1 Score, Accuracy, AUC, Precision, and Recall are displayed to assess the performance of classification models. On the performance tab, you can explore six different views that provide insights related to model training and results: Overview, [Model Fit](#model-fit), [Trend](#trend),[ Seasonality](#seasonality),[ Special Dates](#special-dates), and [Details](#details). *** ### Overview The Overview screen provides a summary of your time series model’s forecasting accuracy. It displays key performance metrics to help you quickly assess how well the model predicts your target variable (e.g., *sales*). The following metrics are shown: * R-Squared – Indicates how much of the variance in your target variable is explained by the model (closer to 100% is better). * MAPE (Mean Absolute Percentage Error) – Shows the average percentage error between predicted and actual values (lower is better). * MAE (Mean Absolute Error) – Represents the average absolute difference between predicted and actual values. * RMSE (Root Mean Squared Error) – Measures the average magnitude of the prediction error, giving more weight to large errors.
* ```

``` These metrics offer a quick and easy way to understand how reliable your forecast is, before diving deeper into model fit, trends, seasonality, and special date effects. *** ### Model Fit The **Model Fit Tab** displays a graph with actual and predicted values. The primary prediction is shown with a yellow line, and the uncertainty interval is illustrated with a yellow shaded area. This visualization helps assess the model's performance. If you used the **Sequence Identifier Field**, you can choose which value to analyze in each **Model Result**.

*** ### Trend Trends and seasonality are key characteristics of time-series data that should be analyzed. The **Trend Tab** displays a graph illustrating the global trend that Graphite Note has detected from your historical data.

*** ### Seasonality Seasonality represents the repeating patterns or cycles of behavior over time. Depending on your **Time Interval**, you can find one or two graphs in the **Seasonality Tab**. For daily data, one graph shows weekly patterns, while the other shows yearly patterns. For weekly and monthly data, the graph highlights recurring patterns throughout the year.

Seasonality graph showing patterns in historical data

*** ### Special Dates The Special Dates graph shows the percentage effects of the special dates and holidays in historical and future data. Special Dates are only supported for the Daily Time interval set in the scenario.

*** ### Details **Details tab** shows the results of the predictive model, presented in a table format. Each record includes the predicted label, predicted probability, and predicted correctness, offering insights into the model's predictions, confidence, and accuracy for each data point. Dataset test results can be exporetd into Excel by clicking on the XLSX button in the right corner.

Model results in a dataset that can be exported to Excel

*** ## Take actions with Timeseries forecast After building and analyzing a time series forecasting model in Graphite Note, the Predict function allows you to apply the model to real-world use cases. This enables you to forecast future values based on historical patterns and known sequences, helping you plan more effectively and make proactive business decisions. There are two ways to use prediction in **Time Series Forecast** models: * [What-If Scenario Predictions](#what-if-scenario-predictions) * [API Predictions](#api-predictions) #### **What-If Scenario Predictions** In the Predict screen, you can select a specific sequence ID (such as a product, store, or region) and define a forecast period using start and end dates. After submitting your selection, Graphite Note generates a forecast for that time range, showing predicted values in tabular format. This is useful for: * Exploring how trends will evolve for specific time series * Planning inventory, staffing, or production based on expected values * Reviewing changes over different time periods or entities

{% hint style="info" %} ⚠️ Important: If your model includes additional regressors, predictions cannot be generated through the app interface. This is because the model requires future values for each regressor, which must be supplied at the time of prediction. To generate predictions with regressors, please use the Graphite Note Prediction API, where you can programmatically provide the necessary inputs. {% endhint %} #### API Predictions For time series forecasting models, Graphite Note also supports predictions via the Prediction API. This is ideal for integrating forecasts into dashboards, external systems, or automated workflows.

API request definition that can be used to set up API call from third party tool

Instead of using the interface manually, you send a simple API request with three key inputs: * startDate: The beginning of the forecast period * endDate: The end of the forecast period * sequenceID: The identifier for the time series you want to forecast (e.g., “Product A” ) This API makes it easy to fetch forecasts programmatically and use them wherever you need, whether that’s a planning tool, a custom app, or a business report. For full details, visit the [Prediction API documentation](https://docs.graphite-note.com/api/predict). {% hint style="info" %} Timeseries predictions can be made only with API Prediction request v1. {% endhint %} *** ### Create Notebook You can share your prediction results with your team using the Notebook feature. With Notebooks, users can also run their own predictions on your Timerseries Forecast model. Notebooks allow you to create various visualizations with detailed descriptions. You can plot model results for better understanding and enable users to make their own predictions. For more information, refer to the [Data Storytelling section](https://docs.graphite-note.com/graphite-note-documentation/notebooks).