Scenario tree construction

The current version of the package provides only the Forward Tree Construction algorithm (FTC). Support for additional construction algorithms is planned for future releases.

scentree.tree_construction.ftc.FTC

Bases: BaseModel

Obtain clusters accoring to the Forward Tree Construction algorithm (FTC).

Attributes:

Name	Type	Description
`scenarios`	`List[NDArray[float64]]`	List of scenarios.
`stage_ids`	`List[int]`	List of stages IDs of the stochastic problem.
`num_variables_per_stage`	`List[int]`	Number of random variables per each stage
`Computed`	`Attributes`	num_trees (Optional[int]): Number of generated trees. num_scenarios (Optional[int]): Total number of scenarios. scenario_ids (List[int]): Identifiers of the scenarios.

_scenario_index_map `class-attribute` `instance-attribute`

_scenario_index_map: Dict[int, int] = PrivateAttr(default_factory=dict)

model_config `class-attribute` `instance-attribute`

model_config = {'arbitrary_types_allowed': True}

num_scenarios `class-attribute` `instance-attribute`

num_scenarios: Optional[int] = None

num_trees `class-attribute` `instance-attribute`

num_trees: Optional[int] = None

num_variables_per_stage `instance-attribute`

num_variables_per_stage: List[int]

scenario_ids `class-attribute` `instance-attribute`

scenario_ids: List[int] = Field(default_factory=list)

scenarios `instance-attribute`

scenarios: List[NDArray[float64]]

stage_ids `instance-attribute`

stage_ids: List[int]

combine_tree_graph

combine_tree_graph(graph: Graph, node_scenario_map: NodeScenarioMap) -> Tree

Build a tree structure by combining a graph representation with scenario information.

Parameters:

Name	Type	Description	Default
`graph`	`Graph`	A graph structure.	required
`node_scenario_map`	`TreeInfoMap`	Mapping from (stage, representative) tuples to scenario ID lists.	required

Returns:

Name	Type	Description
`Tree`	`Tree`	A list of nodes representing the constructed tree structure.

compute_delta_norm_tree

compute_delta_norm_tree(scenarios: NDArray[float64], map_stages_columns: Dict[int, Tuple[int, int]], stage_id: int, Scen0: NDArray[float64], weights: NDArray[float64], r: float, selected_scenario_ids: Optional[List[int]] = None) -> float

Compute the weighted norm of the tree once it has been clustered at the given stage.

Parameters:

Name	Type	Description	Default
`scenarios`	`NDArray[float64]`	Array containing the data of the scenarios.	required
`map_stages_columns`	`Dict[int, Tuple[int, int]]`	Mapping between stages and columns.	required
`stage_id`	`int`	The stage ID.	required
`Scen0`	`NDArray[float64]`	The resulting data from the cluster process.	required
`weights`	`NDArray[float64]`	vector containing the weight of each scenario.	required
`r`	`float`	Exponent used in the weighted norm computation.	required
`selected_scenario_ids`	`Optional[List[int]]`	Subset of scenarios IDs to consider.	`None`

Returns:

Name	Type	Description
`float`	`float`	Weighteds norm of the difference between scenarios and tree at a given stage,

compute_distance_stage

compute_distance_stage(scenarios: NDArray[float64], stage_id: int, map_stages_columns: Dict[int, Tuple[int, int]]) -> NDArray[np.float64]

Compute the distance matrix for a given stage.

Parameters:

Name	Type	Description	Default
`scenarios`	`NDArray[float64]`	Array containing the data of the scenarios.	required
`stage_id`	`int`	The stage ID.	required
`map_stages_columns`	`Dict[int, Tuple[int, int]]`	Mapping between stages and columns.	required

Returns:

Type	Description
`NDArray[float64]`	NDArray[np.float64]: The pairwise distances matrix between scenarios for the given stage.

compute_stages_thresholds

compute_stages_thresholds(scenarios: NDArray[float64], map_stages_columns: Dict[int, Tuple[int, int]], full_stage_ids: List[int], probability_scenarios: NDArray[float64], r: float, initial_stage_id_to_cluster: Optional[int]) -> Dict[int, float]

Compute stage-specific clustering thresholds for scenarios.

For each stage, a threshold is computed as the weighted distance between the closest scenario and all other scenarios in that stage. The first step identifies the closest scenario based on initial_stage_id_to_cluster, which is then used to calculate distances to the remaining scenarios.

Parameters:

Name	Type	Description	Default
`scenarios`	`NDArray[float64]`	Array containing the data of the scenarios.	required
`map_stages_columns`	`Dict[int, Tuple[int, int]]`	Mapping between stages and columns.	required
`full_stage_ids`	`List[int]`	List of stages of the stochastic problem.	required
`probability_scenarios`	`NDArray[float64]`	Probability of each scenario.	required
`r`	`float`	Exponent used in the weighted norm computation.	required
`initial_stage_id_to_cluster`	`Optional[int]`	Stage ID from which clustering starts.	required

Returns:

Type	Description
`Dict[int, float]`	Dict[int, float]: Mapping from stage ID to threshold value for clustering.

compute_weighted_norm `staticmethod`

compute_weighted_norm(x: NDArray[float64], weights: NDArray[float64], r: float, compute_r_root: bool = True) -> float

Compute weighted norm.

Parameters:

Name	Type	Description	Default
`x`	`NDArray[float64]`	vector containing the data.	required
`weights`	`NDArray[float64]`	vector containing the weights.	required
`r`	`float`	the exponent.	required
`compute_r_root`	`bool`	if the r-root is computed at the end. Default to True.	`True`

Returns:

Name	Type	Description
`float`	`float`	The weighted norm of `x` according to `weight` and exponent `r`.

fill_attributes

fill_attributes() -> Self

Automatically fill computed attributes after model initialization.

It sets the following attributes based on the input scenarios:

num_trees: Number of trees (equal to the number of scenarios).
num_scenarios: Number of rows in each scenario.
scenario_ids: Sequential identifiers for each scenario (starting from 1).

Returns:

Name	Type	Description
`Self`	`Self`	The model instance (`self`) with updated attributes.

filter_edges_by_vertex

filter_edges_by_vertex(graph: Graph, stage_id: int, representative_id: int, by_current: bool = True) -> List[Tuple[int, int]]

Return edges connected to a vertex defined by stage and representative.

Parameters:

Name	Type	Description	Default
`graph`	`Graph`	The graph representing the tree.	required
`stage_id`	`int`	The stage ID.	required
`representative_id`	`int`	The representative ID.	required
`by_current`	`bool`	If True, match edges where the vertex is the target (child). If False, match edges where the vertex is the source (parent).	`True`

Returns:

Type	Description
`List[Tuple[int, int]]`	List[Tuple[int, int]]: List of edges matching the given vertex.

generate_scenario_trees

generate_scenario_trees(r: float = 2.0, initial_stage_id_to_cluster: Optional[int] = None) -> ScenarioTrees

Build the scenario trees.

Parameters:

Name	Type	Description	Default
`r`	`float`	Exponent used in the weighted norm computation. Default to 2.	`2.0`
`initial_stage_id_to_cluster`	`Optional[int]`	Stage ID from which clustering starts. Default to None, which means that no clustering is performed.	`None`

Raises:

Type	Description
`ValueError`	If `initial_stage_id_to_cluster` is not a valid stage_id.
`ValueError`	If `r` is negative or zero.

Returns: List[Tree]: The trees.

get_representative

get_representative(distance: NDArray[float64], weights: NDArray[float64], selected_scenario_ids: List[int], r: float) -> int

Return the representative scenario for a given step in a stage.

Parameters:

Name	Type	Description	Default
`distance`	`NDArray[float64]`	The pairwise distances matrix between scenarios.	required
`weights`	`NDArray[float64]`	vector containing the weight of each scenario.	required
`selected_scenario_ids`	`List[int]`	List of scenario IDs considered for representative selection.	required
`r`	`float`	Exponent used in the weighted norm computation.	required

Returns:

Name	Type	Description
`int`	`int`	The chosen representative.

get_vertex_id

get_vertex_id(graph: Graph, stage_id: int, representative_id: int) -> int

Get the identifier of a vertex given the stage and the representative.

Parameters:

Name	Type	Description	Default
`graph`	`Graph`	The graph representing the tree.	required
`stage_id`	`int`	the stage.	required
`representative_id`	`int`	Representative scenario ID associated with the vertex.	required

Raises:

Type	Description
`ValueError`	If no matching vertex is found.

Returns:

Name	Type	Description
`int`	`int`	The identifier of the vertex.

map_scenarios_to_representatives

map_scenarios_to_representatives(representative_ids: List[int], selected_scenario_ids: List[int], distance: NDArray[float64]) -> Dict[int, int]

Relates scenario ids and representatives.

Parameters:

Name	Type	Description	Default
`representative_ids`	`List[int]`	List of representative scenario IDs.	required
`selected_scenario_ids`	`List[int]`	List of scenario IDs to assign.	required
`distance`	`NDArray[float64]`	The pairwise distances matrix between scenarios.	required

Raises:

Type	Description
`ValueError`	If there is a mismatch in the shape of objects.

Returns:

Type	Description
`Dict[int, int]`	Dict[int, int]: dictionary containing the relationship.

mapping_stages_columns

mapping_stages_columns() -> Dict[int, Tuple[int, int]]

Return the column indices for each stage.

Each stage is mapped to a tuple containing the starting and ending column indices in the overall variable array.

Returns:

Type	Description
`Dict[int, Tuple[int, int]]`	Dict[int, Tuple[int, int]]: Mapping from `stage_id` to `(start_column, end_column)`.

update_data

update_data(scenarios: NDArray[float64], Scen0: NDArray[float64], closest_representative: Dict[int, int], selected_scenario_ids: List[int], map_stages_columns: Dict[int, Tuple[int, int]], stage_id: int) -> None

Update the data once the cluster is obtained.

Parameters:

Name	Type	Description	Default
`scenarios`	`NDArray[float64]`	Array containing the data of the scenarios.	required
`Scen0`	`NDArray[float64]`	The resulting data from the cluster process.	required
`closest_representative`	`Dict[int, int]`	dictionary containing the relationship scenario - representative.	required
`selected_scenario_ids`	`List[int]`	List of scenario IDs considered for representative selection.	required
`map_stages_columns`	`Dict[int, Tuple[int, int]]`	Mapping between stages and columns.	required
`stage_id`	`int`	The stage ID.	required

update_graph

update_graph(graph: Graph) -> None

Update the graph that keeps the relationship between scenario IDs and their representatives.

Parameters:

Name	Type	Description	Default
`graph`	`Graph`	The graph.	required

update_non_clustering_stages

update_non_clustering_stages(scenarios: NDArray[float64], map_stages_columns: Dict[int, Tuple[int, int]], full_stage_ids: List[int], prob_scenarios_stages: NDArray[float64], initial_stage_id_to_cluster: Optional[int], node_scenario_map: NodeScenarioMap, representatives: Dict[int, List[int]], Scen0: NDArray[float64], graph: Graph) -> None

Populate data structures for stages that are not clustered.

This method updates the tree-like structure (node_scenario_map), representatives, scenario matrix (Scen0), probability matrix, and graph structure for stages that are not subject to clustering (i.e., stages before initial_stage_id_to_cluster).

Parameters:

Name	Type	Description	Default
`scenarios`	`NDArray[float64]`	Array containing the data of the scenarios.	required
`map_stages_columns`	`Dict[int, Tuple[int, int]]`	Mapping between stages and columns.	required
`full_stage_ids`	`List[int]`	List of stages of the stochastic problem.	required
`prob_scenarios_stages`	`NDArray[float64]`	Matrix containing the probability of each scenario at each stage.	required
`initial_stage_id_to_cluster`	`Optional[int]`	Stage ID from which clustering starts.	required
`node_scenario_map`	`NodeScenarioMap`	Dictionary storing clusters for each stage.	required
`representatives`	`Dict[int, List[int]]`	Representative scenarios for each stage.	required
`Scen0`	`NDArray[float64]`	The resulting data from the cluster process.	required
`graph`	`Graph`	The graph representing the tree.	required

update_probability

update_probability(probability_matrix: NDArray[float64], stage_ids: List[int], stage_id: int, node_scenario_map: NodeScenarioMap, representatives: Dict[int, List[int]]) -> None

Update scenario probabilities at a given stage after clustering.

Parameters:

Name	Type	Description	Default
`probability_matrix`	`NDArray[float64]`	Probability matrix for all scenarios and all stages.	required
`stage_ids`	`List[int]`	List containing all stage IDs.	required
`stage_id`	`int`	The stage ID.	required
`node_scenario_map`	`NodeScenarioMap`	Dictionary storing clusters for each stage.	required
`representatives`	`Dict[int, List[int]]`	Representative scenario IDs for each stage.	required

update_stage

update_stage(scenarios: NDArray[float64], map_stages_columns: Dict[int, Tuple[int, int]], stage_ids: List[int], stage_id: int, representatives: Dict[int, List[int]], node_scenario_map: NodeScenarioMap, graph: Graph, Scen0: NDArray[float64], prob_scenarios_stages: NDArray[float64], distance_stage: NDArray[float64]) -> None

Update a whole stage so that the norm is lower than the treshold.

Parameters:

Name	Type	Description	Default
`scenarios`	`NDArray[float64]`	Array containing the data of the scenarios.	required
`map_stages_columns`	`Dict[int, Tuple[int, int]]`	Mapping between stages and columns.	required
`stage_ids`	`List[int]`	List containing all stage IDs.	required
`stage_id`	`int`	the stage ID.	required
`representatives`	`Dict[int, List[int]]`	Representative scenario IDs for each stage.	required
`node_scenario_map`	`NodeScenarioMap`	Dictionary storing clusters for each stage.	required
`graph`	`Graph`	The graph representing the tree.	required
`Scen0`	`NDArray[float64]`	The resulting data from the cluster process.	required
`prob_scenarios_stages`	`NDArray[float64]`	Matrix containing the probability of each scenario at each stage.	required
`distance_stage`	`NDArray[float64]`	(NDArray[np.float64]): Matrix distance for the given stage_id.	required

validate_consistency

validate_consistency() -> Self

Ensure that stage_ids and num_variables_per_stage have the same length.

Raises:

Type	Description
`ValueError`	If `stage_ids` and `num_variables_per_stage` do not have the same length.

Returns:

Name	Type	Description
`Self`	`Self`	The model instance (`self`) if validation passes.

validate_scenarios

validate_scenarios() -> Self

Validate that all scenarios have the same number of rows.

Raises:

Type	Description
`ValueError`	If the number of rows in any scenario does not match the first scenario.

Returns:

Name	Type	Description
`Self`	`Self`	The model instance (`self`) if validation passes.

Scenario tree construction

scentree.tree_construction.ftc.FTC

_scenario_index_map class-attribute instance-attribute

model_config class-attribute instance-attribute

num_scenarios class-attribute instance-attribute

num_trees class-attribute instance-attribute

num_variables_per_stage instance-attribute

scenario_ids class-attribute instance-attribute

scenarios instance-attribute

stage_ids instance-attribute

combine_tree_graph

compute_delta_norm_tree

compute_distance_stage

compute_stages_thresholds

compute_weighted_norm staticmethod

fill_attributes

filter_edges_by_vertex

generate_scenario_trees

get_representative

get_vertex_id

map_scenarios_to_representatives

mapping_stages_columns

update_data

update_graph

update_non_clustering_stages

update_probability

update_stage

validate_consistency

validate_scenarios

_scenario_index_map `class-attribute` `instance-attribute`

model_config `class-attribute` `instance-attribute`

num_scenarios `class-attribute` `instance-attribute`

num_trees `class-attribute` `instance-attribute`

num_variables_per_stage `instance-attribute`

scenario_ids `class-attribute` `instance-attribute`

scenarios `instance-attribute`

stage_ids `instance-attribute`

compute_weighted_norm `staticmethod`