Scenario fan generator

This class is responsible for generating scenario fans. It supports both single and multiple scenario fan generation.

scentree.fan_generator.stage_manager.StageManager

Bases: BaseModel

Orchestrates the generation of a scenario fan from historical data and model estimates.

The StageManager is responsible for transforming historical time series data into a stochastic representation of future uncertainty. It performs preprocessing, dimensionality reduction, residual modeling, scenario generation, and reconstruction back to the original feature space.

model_config class-attribute instance-attribute

model_config = {'arbitrary_types_allowed': True}

clip_matrix_values

clip_matrix_values(X: NDArray, value_ranges: Optional[List[Bounds]]) -> NDArray

Clip the values of a given matrix.

Parameters:

Name	Type	Description	Default
X	NDArray	Matrix to be clipped.	required
value_ranges	Optional[List[Bounds]]	Bounds used to clip X.	required

fill_with_constant_values

fill_with_constant_values(initial_stochastic_stage_id: int, scenarios: List[NDArray[float64]], predicted_values: List[NDArray[float64]], observed_values: Optional[List[NDArray[float64]]], stage_ids: List[int], build_in_sample_fans: bool, num_variables_per_stage: List[int]) -> List[NDArray[np.float64]]

Fill the deterministic stages of the generated scenarios with constant values derived from either observed or predicted values.

For all stages before initial_stochastic_stage_id, the values are fixed across all scenarios in the fan.

Parameters:

Name	Type	Description	Default
initial_stochastic_stage_id	int	Identifier of the first stochastic stage.	required
scenarios	List[NDArray[float64]]	Generated scenarios for each fan.	required
predicted_values	List[NDArray[float64]]	Predicted values associated with each fan.	required
observed_values	Optional[List[NDArray[float64]]]	Observed values associated with each fan. Used only when build_in_sample_fans is True.	required
stage_ids	List[int]	Ordered list of stage identifiers.	required
build_in_sample_fans	bool	Whether to use observed values instead of predicted values.	required
num_variables_per_stage	List[int]	Number of variables associated with each stage.	required

Returns:

Type	Description
List[NDArray[float64]]	List[NDArray[np.float64]]: Scenarios where all variables belonging to stages before initial_stochastic_stage_id are fixed to constant values.

generate_scenario_fans

generate_scenario_fans(X: NDArray[float64], num_fans: int, num_scenarios: int, stage_ids: Optional[List[int]] = None, num_variables_per_stage: Optional[List[int]] = None, initial_stochastic_stage_id: Optional[int] = None, build_in_sample_fans: bool = True, value_ranges: Optional[List[Bounds]] = None, seed: Optional[int] = None) -> ScenarioFanData

Orchestrates the scenario fan generation process from historical data.

Parameters:

Name	Type	Description	Default
X	NDArray[float64]	Historical data.	required
num_fans	int	Number of fans to generate.	required
num_scenarios	int	Number of scenarios to generate.	required
stage_ids	Optional[List[int]]	Stages of the stochastic problem.	None
num_variables_per_stage	Optional[List[int]]	number of random variables involved in each stage.	None
initial_stochastic_stage_id	Optional[List[int]]	First stage that is random. Previous stages are considered observed, i.e., fixed.	None
build_in_sample_fans	bool	Whether to build in-sample fans or out-sample fans. Default to True, meaning that in sample fans are built.	True
value_ranges	Optional[List[Bounds]]	Optional lower and upper bounds for each variable in X.	None
seed	Optional[int]	Seed needed in case reproducibility is required.	None

Raises:

Type

Description

ValueError

If the length of value_ranges does not match the number of columns in X. If a value range is invalid, i.e. the lower bound is greater than the upper bound. If initial_stochastic_stage_id is provided but stage_ids is None. If initial_stochastic_stage_id is not present in stage_ids. If initial_stochastic_stage_id is provided but num_variables_per_stage is None. If the length of num_variables_per_stage does not match the length of stage_ids.

Returns:

Name	Type	Description
ScenarioFanData	ScenarioFanData	A container with: - scenarios: generated scenarios - predicted_values: model predictions - observed_values: optional observed values

get_scenarios

get_scenarios(residuals: NDArray[float64], estimated_values: NDArray[float64], num_fans: int, num_scenarios: int, seed: Optional[int] = None) -> List[NDArray[np.float64]]

Obtain the scenarios given all components that are needed.

Parameters:

Name	Type	Description	Default
residuals	NDArray[float64]	Matrix containing historical residuals.	required
estimated_values	NDArray[float64]	Estimated values.	required
num_fans	int	Number of fans to provide.	required
num_scenarios	int	Number of scenarios to generate the fan.	required
seed	Optional[int]	Seed needed in case reproducibility is required.	None

Returns:

Type	Description
List[NDArray[float64]]	List[NDArray[np.float64]]: List containing the scenarios.