Sinapsis Time Series Forecasting

Monorepo with packages to perform time series forecasting, preprocessing, and data loading.

🐍 Installation • 📦 Packages • 📚 Usage example • 🌐 Webapp • 📙 Documentation • 🔍 License

🐍 Installation

This monorepo currently consists of the following packages to handle time-series data:

• sinapsis-darts-forecasting

Install using your package manager of choice. We encourage the use of uv

Example with uv:

  uv pip install sinapsis-darts-forecasting --extra-index-url https://pypi.sinapsis.tech

or with raw pip:

  pip install sinapsis-darts-forecasting --extra-index-url https://pypi.sinapsis.tech

Important

Templates in each package may require extra dependencies. For development, we recommend installing the package with all the optional dependencies:

with uv:

  uv pip install sinapsis-darts-forecasting[all] --extra-index-url https://pypi.sinapsis.tech

or with raw pip:

  pip install sinapsis-darts-forecasting[all] --extra-index-url https://pypi.sinapsis.tech

Tip

You can also install all the packages within this project:

  uv pip install sinapsis-time-series-forecasting[all] --extra-index-url https://pypi.sinapsis.tech

📦 Packages

Packages summary

• Sinapsis Darts Forecasting
  • Dataframe Loader
    Convert a pandas Dataframe into a Darts TimeSeries object.
  • Darts Transforms
    Apply several data transformations using Darts transformers to different sources in the time series packet.
  • Darts Models
    Fit and predict data inside the container using Darts baseline, statistical, machine learning and deep learning models.

Tip

Use CLI command sinapsis info --all-template-names to show a list with all the available Template names installed with Sinapsis Time Series Forecasting.

Tip

Use CLI command sinapsis info --example-template-config TEMPLATE_NAME to produce an example Agent config for the Template specified in TEMPLATE_NAME.

For example, for XGBModelWrapper use sinapsis info --example-template-config XGBModelWrapper to produce the following example config:

agent:
  name: my_test_agent
templates:
- template_name: InputTemplate
  class_name: InputTemplate
  attributes: {}
- template_name: XGBModelWrapper
  class_name: XGBModelWrapper
  template_input: InputTemplate
  attributes:
    forecast_horizon: 10
    xgbmodel_init:
      lags: null
      lags_past_covariates: null
      lags_future_covariates: null
      output_chunk_length: 1
      output_chunk_shift: 0
      add_encoders: null
      likelihood: null
      quantiles: null
      random_state: null
      multi_models: true
      use_static_covariates: true

📚 Usage example

Below is an example configuration for **Sinapsis Darts Forecasting** using an XGBoost model. This setup extracts pandas DataFrames from the time series packet attributes and converts them into `TimeSeries` objects, using the `Date` column as the time index. Missing dates are filled with a daily frequency, and any missing values are interpolated using a linear method. The model is then trained and used to generate predictions with a forecast horizon of 100 days, with several configurable hyperparameters.

Example agent config

agent:
  name: XGBLSTMForecastingAgent
  description: ''

templates:

- template_name: InputTemplate
  class_name: InputTemplate
  attributes: {}

- template_name: TimeSeriesDataframeLoader
  class_name: TimeSeriesDataframeLoader
  template_input: InputTemplate
  attributes:
    apply_to: ["content", "past_covariates", "future_covariates"]
    from_dataframe_kwargs:
      time_col: "Date"
      fill_missing_dates: True
      freq: "D"

- template_name: MissingValuesFiller
  class_name: MissingValuesFillerWrapper
  template_input: TimeSeriesDataframeLoader
  attributes:
    method: "transform"
    missingvaluesfiller_init: {}
    apply_to: ["content", "past_covariates", "future_covariates"]
    transform_kwargs:
      method: "linear"

- template_name: TimeSeries
  class_name: XGBModelWrapper
  template_input: MissingValuesFiller
  attributes:
    forecast_horizon: 100
    xgbmodel_init:
      lags: 30
      lags_past_covariates: 30
      output_chunk_length: 100
      random_state: 42
      n_estimators: 200
      learning_rate: 0.1
      max_depth: 6

To run, simply use:

sinapsis run name_of_the_config.yml

🌐 Webapp

The webapp provides an intuitive interface for data loading, preprocessing, and forecasting. The webapp supports CSV file uploads, visualization of historical data, and forecasting.

Note

Kaggle offers a variety of datasets for forecasting. In this-link from Kaggle, you can find a Bitcoin historical dataset. You can download it to use it in the app. Past and future covariates datasets are optional for the analysis.

Important

Note that if you use another dataset, you need to change the attributes of the TimeSeriesDataframeLoader

Important

To run the app you first need to clone this repository:

git clone [email protected]:Sinapsis-ai/sinapsis-time-series-forecasting.git
cd sinapsis-time-series-forecasting

Note

If you'd like to enable external app sharing in Gradio, export GRADIO_SHARE_APP=True

🐳 Docker

IMPORTANT This docker image depends on the sinapsis-nvidia:base image. Please refer to the official sinapsis instructions to Build with Docker.

1. Build the sinapsis-time-series-forecasting image:

docker compose -f docker/compose.yaml build

2. Start the app container:

docker compose -f docker/compose_apps.yaml up sinapsis-darts-forecasting-gradio -d

3. Check the status:

docker logs -f sinapsis-darts-forecasting-gradio

3. The logs will display the URL to access the webapp, e.g.:

NOTE: The url can be different, check the output of logs

Running on local URL:  http://127.0.0.1:7860

4. To stop the app:

docker compose -f docker/compose_apps.yaml down

💻 UV

To run the webapp using the uv package manager, please:

1. Create the virtual environment and sync the dependencies:

uv sync --frozen

2. Install the wheel:

uv pip install sinapsis-time-series-forecasting[all] --extra-index-url https://pypi.sinapsis.tech

3. Run the webapp:

uv run webapps/darts_time_series_gradio_app.py

4. The terminal will display the URL to access the webapp, e.g.:

NOTE: The url can be different, check the output of the terminal

Running on local URL:  http://127.0.0.1:7860

📙 Documentation

Documentation for this and other sinapsis packages is available on the sinapsis website

Tutorials for different projects within sinapsis are available at sinapsis tutorials page

🔍 License

This project is licensed under the AGPLv3 license, which encourages open collaboration and sharing. For more details, please refer to the LICENSE file.

For commercial use, please refer to our official Sinapsis website for information on obtaining a commercial license.