Demand Forecasting

The demand forecasting app is available in one modeling language as a Mixed Integer Problem (MIP) formulation of Least Absolute Deviation (LAD) regression. You can also choose to make customizations to the model by instantiating the app first.

OR-Tools
- Default solver: SCIP
- Marketplace subscription app IDs
  - Python: nextmv-dem.forecast.ortools

Bash

nextmv community clone -a python-ortools-demandforecasting

Once you have the code locally, you can customize the model, run it locally and deploy it to Nextmv Platform.

Input

The format for timestamps should look like the following: "2023-01-01T00:00:00".

The input schema is a JSON payload defining the timestamp and the historical demand to use for training the LAD regression model. Nextmv's tools are designed to operate directly on business data (in JSON) to produce decisions that are actionable by software systems. This makes decisions more interpretable and easier to test. It also makes integration with data warehouses and business intelligence platforms significantly easier. An input contains the following components:

Field name	Required	Data type	SI Unit	Description	Example
`timezone`	Yes	`string`	NA	Timezone	`{"timezone": "America/New_York"}`
`demands`	Yes	`array` of `demand`	NA	An array of historical demand.	See `demand`

Here you can find a sample .json with the input schema:

JSON

Demand

Demand is used in the input schema.

Field name	Required	Data type	Description	Example
`when`	Yes	`timestamp`	The start time of the demand block.	`{"when": "2019-11-15T09:00:00"}`
`date`	Yes	`string`	The date of the demand.	`{"date": "2023-01-01"}`
`block`	Yes	`string`	The time of day of the demand (see below).	`{"block": "morning"}`
`demand`	Yes	`integer`	The amount of demand.	`{"demand": "1"}`

The marketplace app defines the block start and end as follows:

Block	Start	End
morning	09:00	12:59
midday	13:00	16:59
evening	17:00	20:59
night	21:00	08:59

Output

The output schema defines the solution to the demand forecasting problem in JSON format. The output schema contains the following components.

Field name	Always present	Data type	SI Unit	Description	Example
`solutions`	Yes	`array` of `solution`	NA	Solutions to the demand forecasting problem.	`{"solutions": []}`
`statistics`	Yes	`statistics`	NA	Summary statistics of the solution.	`{"statistics": {"schema": 123}}`

JSON

Solution

Field name	Always present	Data type	SI Unit	Description	Example
`forecasted_demand`	Yes	`array` of forecasted demand	NA	Solution to the demand forecasting problem.	`{"forecasted_demand": []}`

Forecasted demand

Field name	Always present	Data type	SI Unit	Description	Example
`when`	Yes	`timestamp`	NA	The start time of the demand block.	`{"when": "2019-11-15T09:00:00"}`
`date`	Yes	`string`	NA	The date of the demand.	`{"date": "2023-01-01"}`
`block`	Yes	`string`	NA	The time of day of the demand.	`{"block": "morning"}`
`demand`	Yes	`integer`	NA	The amount of demand historically (if `include-past` option set to `true`).	`{"demand": "1"}`
`start_time`	Yes	`timestamp`	NA	The start time of the demand block.	`{"start_time": "2019-11-15T09:00:00"}`
`end_time`	Yes	`timestamp`	NA	The end time of the demand block.	`{"end_time": "2019-11-15T09:00:00"}`
`forecast`	Yes	`float`	NA	The forecasted demand.	`{"forecast": "1.2"}`
`count`	Yes	`integer`	NA	The ceiling of forecasted demand.	`{"count": "2"}`

Statistics

Field name	Always present	Data type	SI Unit	Description	Example
`result`	No	`result`	NA	Final result of the solutions.	See `result`
`run`	Yes	`run`	NA	Information about the run.	See `run`
`schema`	Yes	`string`	NA	Schema of the statistics.	`{"schema": "v1"}`

Here you can find additional definitions used in the statistics schema:

result

Field name	Always present	Data type	SI Unit	Description	Example
`duration`	Yes	`float`	`seconds`	Time duration to get to the final result.	`{"duration": 0.123}`
`value`	Yes	`float`	NA	Value of the final result.	`{"value": 0.123}`
`custom`	Yes	`any`	NA	Custom solver metrics.	See `custom`

run
Field name Always present Data type SI Unit Description Example
duration Yes float seconds Time duration of the run. {"duration": 0.123}

Field name	Always present	Data type	SI Unit	Description	Example
`duration`	Yes	`float`	`seconds`	Time duration of the run.	`{"duration": 0.123}`

custom

Field name	Always present	Data type	SI Unit	Description	Example
`constraints`	Yes	`int`	NA	Number of constraints.	`{"constraints": 123}`
`provider`	Yes	`string`	NA	Solver provider.	`{"provider": "highs"}`
`status`	Yes	`string`	NA	Solver status.	`{"status": "optimal"}`
`variables`	Yes	`int`	NA	Number of variables.	`{"variables": 123}`

Run options

These are the default options that are available with demand forecasting.

Bash (OR-Tools)

usage: main.py [options]

Options for main.py. Use command-line arguments (highest precedence) or
environment variables.

options:
  -h, --help            show this help message and exit
  -input INPUT, --input INPUT
                        [env var: INPUT] (default: ) (type: str): Path to
                        input file. Default is stdin.
  -output OUTPUT, --output OUTPUT
                        [env var: OUTPUT] (default: ) (type: str): Path to
                        output file. Default is stdout.
  -duration DURATION, --duration DURATION
                        [env var: DURATION] (default: 30) (type: int): Max
                        runtime duration (in seconds).
  -provider PROVIDER, --provider PROVIDER
                        [env var: PROVIDER] (default: SCIP) (type: str):
                        Solver provider.
  -include_past INCLUDE_PAST, --include_past INCLUDE_PAST
                        [env var: INCLUDE_PAST] (default: False) (type: bool):
                        Include past data in forecast.

A how-to guide for specifying the input and output schemas in demand forecasting.