Metadata-Version: 2.4
Name: futureexpert
Version: 3.1.1
Summary: Forecasting has never been easier.
Author-email: prognostica GmbH <support@future-forecasting.de>
License: MIT
Project-URL: homepage, https://www.future-forecasting.de
Project-URL: source, https://github.com/discovertomorrow/futureexpert
Project-URL: tracker, https://github.com/discovertomorrow/futureexpert/issues
Project-URL: release notes, https://github.com/discovertomorrow/futureEXPERT/releases
Keywords: time-series,forecast,ml
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Software Development
Classifier: Typing :: Typed
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: authlib>=1.3.0
Requires-Dist: tenacity>=8.2.0
Requires-Dist: httpx>=0.27.2
Requires-Dist: matplotlib>=3.8.0
Requires-Dist: plotly>=5.24.1
Requires-Dist: pydantic<3.0.0,>=2.5.0
Requires-Dist: numpy<2.0.0,>=1.22.4
Requires-Dist: pandas>=1.4.3
Requires-Dist: python-dotenv
Requires-Dist: cachetools
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: ipytest; extra == "dev"
Requires-Dist: isort; extra == "dev"
Requires-Dist: mypy==1.0.*; extra == "dev"
Requires-Dist: autopep8; extra == "dev"
Requires-Dist: cloudpickle; extra == "dev"
Requires-Dist: pdoc3; extra == "dev"
Requires-Dist: types-pkg-resources==0.1.3; extra == "dev"
Requires-Dist: types-python-dateutil; extra == "dev"
Requires-Dist: types-toml; extra == "dev"
Requires-Dist: types-cachetools; extra == "dev"
Requires-Dist: jupyter==1.0.0; extra == "dev"
Requires-Dist: nbconvert==7.2.6; extra == "dev"
Requires-Dist: nbqa==1.5.3; extra == "dev"
Requires-Dist: python-dotenv; extra == "dev"
Requires-Dist: lxml; extra == "dev"
Dynamic: license-file

# futureEXPERT

_futureEXPERT_ is a flexible Python toolkit designed to significantly simplify the process of building professional forecasting solutions.
It is built upon a **Smart Build** principle: a clear division of tasks that makes powerful forecasting accessible with ease, even without a deep data science background.
* **You focus on the "what"**: Designing the solution tailored to your specific domain and requirements, connecting your data and integrating the results into your workflow.
* **_futureEXPERT_ handles the "how"**: The complex methodological and technical details, from data preparation to forecast generation, are abstracted away for you.


In case you don't want to use this Python client or access futureEXPERT via [API](https://expert.future-forecasting.de/apidoc), check out our frontend solutions [futureNOW](https://now.future-forecasting.de/) and [futureEXPERT Dashboard](https://expert.future-forecasting.de).


## Registration

If you do not have an account for [future](https://now.future-forecasting.de) yet, click [here](https://launch.future-forecasting.de/) to register for a free account.

## Installation

In order to use futureEXPERT, you need a Python environment with Python 3.9 or higher.

The futureEXPERT package can be directly installed with `pip` from our GitHub repository.

```
pip install -U futureexpert
```

## Getting started

If you want to explore the workflow of futureEXPERT without diving directly into code, check out our [dashboard](https://expert.future-forecasting.de). It visually guides you through the capabilities of the futureEXPERT client. While it does not contain the full capabilities of the library, it offers a hands-on way to experience what futureEXPERT can do.

To get started with futureEXPERT we recommend checking out the jupyter notebook [getting started](https://github.com/discovertomorrow/futureexpert/blob/main/notebooks/getting_started.ipynb) to help you with your first steps. Also check our [quick start video tutorial](https://www.future-forecasting.de/video/getting-started/).

## Modules

futureEXPERT provides six modules that cover every step from data preparation to forecast generation.

- *CHECK-IN*: Prepares your time series data. This module validates, cleans, and transforms your input data to ensure it's ready for forecasting.
- *POOL*: Provides a library of curated external variables (e.g., economic indicators, weather data). You can search this continuously updated collection to find useful covariates for your forecast.
- *ASSOCIATOR*: Creates clusters of similar time series patterns and trend behaviour of a set of time series.
- *MATCHER*: Ranks covariates to find the most impactful ones for your data. It takes your own covariates or variables from the *POOL*, determines their optimal time lag, and measures their predictive value against a baseline model.
- *FORECAST*: Generates the final forecast. This module automatically selects the best model (from statistical, ML, and AI methods) for each time series and can incorporate the top-performing covariates identified by *MATCHER*.
- *SHAPER*: Enables "what if" analyses. It generates a base forecast along with best-case and worst-case scenarios by letting experts shape their assumptions about influencing variables — from the *POOL* or imported via *CHECK-IN*.

## Workflows

These modules support two main workflows for generating forecasts.

### Forecasting with or without covariates

```mermaid
flowchart LR
    CHECK-IN --> ASSOCIATOR -.-> MATCHER -.-> FORECAST
    POOL -.-> ASSOCIATOR
    classDef optional stroke-dasharray: 5 5
    class POOL,ASSOCIATOR,MATCHER optional
```

The simplest version of this workflow only needs *CHECK-IN* → *FORECAST* and is described in the jupyter notebook [getting started](https://github.com/discovertomorrow/futureexpert/blob/main/notebooks/getting_started.ipynb).

### Scenario-based Forecasting

```mermaid
flowchart LR
    CHECK-IN --> SHAPER
    POOL -.-> SHAPER
    classDef optional stroke-dasharray: 5 5
    class POOL optional
```

Experts shape their assumptions about covariates — from the *POOL* or imported via *CHECK-IN* — and *SHAPER* generates a base forecast along with best-case and worst-case scenarios.

## Ready-made use case templates

Utilize our use case templates to get started with your own business application right away.

- [Demand Planning](https://github.com/discovertomorrow/futureexpert/blob/main/use_cases/demand_planning/demand_planning.ipynb)
- [Sales Forecasting](https://github.com/discovertomorrow/futureexpert/blob/main/use_cases/sales_forecasting/sales_forecasting.ipynb)

## Advanced usage

- [checkin configuration options](https://github.com/discovertomorrow/futureexpert/blob/main/notebooks/checkin_configuration_options.ipynb) - Different options to prepare your data to time series.
- [AI-assisted Data Transformation for CHECK-IN](https://github.com/discovertomorrow/futureexpert/blob/main/notebooks/ai_assisted_data_transformation_for_checkin.ipynb)
- [Advanced workflow FORECAST](https://github.com/discovertomorrow/futureexpert/blob/main/notebooks/advanced_workflow.ipynb) - For more control about the single steps for generating a forecast.
- [Using open orders for FORECAST](https://github.com/discovertomorrow/futureexpert/blob/main/notebooks/forecast_with_open_orders.ipynb) - Create forecasts with minimum constraints per forecast step.
- [Using covariates for FORECAST](https://github.com/discovertomorrow/futureexpert/blob/main/notebooks/forecast_with_covariates.ipynb) - Create forecasts with covariates by using your own data of influencing factors.
- [Using covariates - MATCHER and FORECAST](https://github.com/discovertomorrow/futureexpert/blob/main/notebooks/cov_matcher_and_forecast.ipynb?ref_type=heads) - Using covariates: Leverage MATCHER to identify predictive covariates, get ranking of all covariates with the best time lag & incorporate the result into your FORECAST.
- [Hierarchically consistent forecasting](https://github.com/discovertomorrow/futureexpert/blob/main/notebooks/make_forecasts_consistent.ipynb) - How to make forecasts consistent over hierachical levels.
- [Using covariates from POOL](https://github.com/discovertomorrow/futureexpert/blob/main/notebooks/using_covariates_from_POOL.ipynb) - How to use potential influencing factors from POOL.
- [Cluster time series with ASSOCIATOR](https://github.com/discovertomorrow/futureexpert/blob/main/notebooks/associator.ipynb) - Identifying clusters of similar time series patterns and trend behaviour.
- [Build scenarios with SHAPER](https://github.com/discovertomorrow/futureexpert/blob/main/notebooks/shaper.ipynb) - Create scenario-based forecasts by defining how covariates (influencing variables) evolve in the future.
- [Working with results](https://github.com/discovertomorrow/futureexpert/blob/main/notebooks/working_with_results.ipynb) - Overview of forecast result functions (e.g. export, plotting) and how to use them; further detailed information about the results (e.g. summary of forecasting methods).

Further details about available configuration parameters can be found in the [client's API documentation](https://discovertomorrow.github.io/futureEXPERT).

## Video tutorials

Check out our video tutorials for a quick introduction to various aspects of futureEXPERT.

- [Quickstart](https://www.future-forecasting.de/en/video/quickstart-with-future-creating-forecasts/): First Forecasts in Minutes
- [CHECK-IN](https://www.future-forecasting.de/en/video/preparing-time-series-with-check-in/) your data and create time series for your forecasting use case.
- Forecasting Workflow without Code: The [futureEXPERT Dashboard](https://www.future-forecasting.de/en/video/expert-dashboard/)
- [AI-assisted Data Transformation](https://www.future-forecasting.de/en/video/data-preparation-with-ai/) for easily preparing your data for CHECK-IN
- [Build Custom Forecast Pipelines with futureEXPERT & Copilot](https://www.future-forecasting.de/en/video/custom-forecasting-configuration-with-github-copilot/)

## Contributing

You can report issues or send pull requests in our [GitHub project](https://github.com/discovertomorrow/futureexpert).

## Wiki for prognostica employees

Further information for prognostica employees can be found [here](https://git.prognostica.de/prognostica/future/futureapp/futureexpert/-/wikis/home)
