Area and AreaBorder Model-DF Generators¶
AreaModelGenerator
¶
Bases: GeoModelGeneratorBase, AreaMembership
Area model from the area of each node: one row per area.
The model has the node count and a representative point per area.
generate_area_model takes the point from the node locations.
enhance_with_geometry adds only the area geometries and keeps the
existing points.
Attributes:
| Name | Type | Description |
|---|---|---|
node_model_df |
DataFrame
|
Node-level data with area assignments |
area_column |
str
|
Column name containing area identifiers |
geo_location_column |
str
|
Column name containing geographic Point objects |
Examples:
>>> generator = AreaModelGenerator(dataset.fetch('Node.Model'), 'country')
>>> generator.generate_area_model()
node_count projection_point
country
C1 2.0 POINT (6.3888 47.0112)
C2 2.0 POINT (10.3888 47.0112)
Source code in src/mesqual/energy_data_handling/area_accounting/area_model_generator.py
9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 | |
__init__
¶
__init__(node_model_df: DataFrame, area_column: str, geo_location_column: str = None)
Initialize the area model generator.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
node_model_df
|
DataFrame
|
DataFrame containing node-level data with area assignments. Must contain area_column with area identifiers for each node. May contain geographic Point objects for spatial analysis. |
required |
area_column
|
str
|
Column name in node_model_df containing area assignments (e.g., 'country', 'bidding_zone', 'market_region', 'control_area'). |
required |
geo_location_column
|
str
|
Column name containing geographic Point objects for representative point calculation. If None, automatically detects column containing Point geometries. |
None
|
Raises:
| Type | Description |
|---|---|
ValueError
|
If area_column is not found in node_model_df columns. |
Source code in src/mesqual/energy_data_handling/area_accounting/area_model_generator.py
31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 | |
generate_base_area_model_from_area_names_in_node_model_df
¶
generate_base_area_model_from_area_names_in_node_model_df() -> DataFrame
Generate base area model DataFrame from unique area names in node data.
Creates a minimal area model DataFrame containing only the unique area identifiers found in the node model data. This forms the foundation for building area models.
Returns:
| Type | Description |
|---|---|
DataFrame
|
pd.DataFrame: Base area model with area identifiers as index. Contains no additional columns - serves as starting point for enhancement with node counts, geographic data, etc. |
Note
Nodes without an area (AreaMembership.has_area) add no area
to the generated model.
Source code in src/mesqual/energy_data_handling/area_accounting/area_model_generator.py
63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 | |
ensure_completeness_of_area_model_df
¶
ensure_completeness_of_area_model_df(area_model_df: DataFrame) -> DataFrame
Ensure area model contains all areas present in node data.
Validates and extends an existing area model DataFrame to include any areas found in the node data that might be missing from the provided area model. This is useful when working with predefined area models that may not cover all areas in the dataset.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
area_model_df
|
DataFrame
|
Existing area model DataFrame to validate and extend. |
required |
Returns:
| Type | Description |
|---|---|
DataFrame
|
pd.DataFrame: Complete area model containing all areas from node data. Existing data is preserved, new areas are added with NaN values for existing columns. |
Examples:
>>> generator = AreaModelGenerator(dataset.fetch('Node.Model'), 'country')
>>> partial = pd.DataFrame({'max_price': [3000.0]}, index=pd.Index(['C1'], name='country'))
>>> generator.ensure_completeness_of_area_model_df(partial)
max_price
country
C1 3000.0
C2 NaN
Source code in src/mesqual/energy_data_handling/area_accounting/area_model_generator.py
84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 | |
enhance_area_model_df_by_adding_node_count_per_area
¶
enhance_area_model_df_by_adding_node_count_per_area(area_model_df: DataFrame, node_count_column_name: str = 'node_count') -> DataFrame
Enhance area model by adding node count statistics per area.
Aggregates the number of nodes assigned to each area and adds this information to the area model DataFrame.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
area_model_df
|
DataFrame
|
Base area model DataFrame to enhance. |
required |
node_count_column_name
|
str
|
Name for the new node count column. Defaults to 'node_count'. |
'node_count'
|
Returns:
| Type | Description |
|---|---|
DataFrame
|
pd.DataFrame: Enhanced area model with node count column added. Existing data is preserved, node counts are added for all areas. Areas not present in node data will have NaN node counts. |
Source code in src/mesqual/energy_data_handling/area_accounting/area_model_generator.py
115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 | |
enhance_area_model_df_by_adding_representative_geo_point
¶
enhance_area_model_df_by_adding_representative_geo_point(area_model_df: DataFrame | GeoDataFrame, target_column_name: str = 'projection_point', round_point_decimals: int = 4) -> DataFrame
Enhance area model by adding representative geographic points for labeling and KPI printing in map visualizations.
An area that already has a point keeps it. If the model has a
geometry column, the point comes from the polygon of the area; an
area without a polygon gets no point. Else the point comes from the
locations of the nodes of the area (geo_location_column).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
area_model_df
|
DataFrame | GeoDataFrame
|
Area model DataFrame to enhance. Can be regular DataFrame or GeoDataFrame with 'geometry' column. |
required |
target_column_name
|
str
|
Name for the new representative point column. Defaults to 'projection_point'. |
'projection_point'
|
round_point_decimals
|
int
|
Number of decimal places for coordinate rounding. Set to None to disable rounding. Defaults to 4. |
4
|
Returns:
| Type | Description |
|---|---|
DataFrame
|
pd.DataFrame: Enhanced area model with representative points added. Points are added as Shapely Point objects suitable for mapping and spatial analysis. |
Raises:
| Type | Description |
|---|---|
TypeError
|
If geo_location_column contains non-Point objects. |
Source code in src/mesqual/energy_data_handling/area_accounting/area_model_generator.py
140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 | |
generate_area_model
¶
generate_area_model() -> DataFrame
Generate complete area model with node counts and representative points.
One row per area of the node model, with the node count and the representative point of the node locations.
Returns:
| Type | Description |
|---|---|
DataFrame
|
pd.DataFrame: Complete area model. Index contains area identifiers, columns are 'node_count' and 'projection_point'. 'projection_point' is None where no node location is available. |
Source code in src/mesqual/energy_data_handling/area_accounting/area_model_generator.py
201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 | |
enhance_with_geometry
¶
enhance_with_geometry(area_model_df: DataFrame, area_gdf: GeoDataFrame) -> GeoDataFrame
Add the area polygons of a GeoDataFrame to the area model.
Areas are matched by index. The result is a GeoDataFrame.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
area_model_df
|
DataFrame
|
Area model DataFrame to enhance with geometry. |
required |
area_gdf
|
GeoDataFrame
|
GeoDataFrame containing area polygon geometries. Must have 'geometry' column with Polygon or MultiPolygon objects. Areas are matched by index values. |
required |
Returns:
| Type | Description |
|---|---|
GeoDataFrame
|
gpd.GeoDataFrame: Enhanced area model as GeoDataFrame with geometry column. All original data is preserved, geometry column is added for areas that exist in both DataFrames. Missing geometries are set to None. |
Examples:
>>> generator = AreaModelGenerator(dataset.fetch('Node.Model'), 'country')
>>> areas = generator.enhance_with_geometry(generator.generate_area_model(), dataset.fetch('Country.Model'))
>>> areas['geometry'].tolist()
[<POLYGON ((9 46, 9 50, 5 50, 5 46, 9 46))>, <POLYGON ((13 46, 13 50, 9 50, 9 46, 13 46))>]
Source code in src/mesqual/energy_data_handling/area_accounting/area_model_generator.py
217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 | |
Border models: the borders between areas from the line topology, with naming conventions and geometry.
AreaBorderNamingConventions
¶
Standardized naming conventions for energy system area borders.
This class provides consistent naming patterns for borders between energy system areas (countries, bidding zones, market regions). It ensures standardized naming across different analysis workflows and supports bidirectional relationship management.
It gives:
- Border names in both directions (A - B and B - A) and the opposite border of a border.
- Canonical border names: the area names in alphabetical order.
- The column names of the border model, configurable per instance.
Attributes:
| Name | Type | Description |
|---|---|---|
area_column |
str
|
Name of the area column. |
border_identifier |
str
|
Name of the border column. Default: '{area_column}_border'. |
source_area_identifier |
str
|
Name of the source area column. Default:
|
target_area_identifier |
str
|
Name of the target area column. Default:
|
JOIN_AREA_NAMES_BY |
str
|
Separator for area names in border identifiers |
OPPOSITE_BORDER_IDENTIFIER |
str
|
Column name for opposite border references |
CANONICAL_BORDER_IDENTIFIER |
str
|
Column name for the canonical border of each border: the border with the area names in alphabetical order |
IS_CANONICAL_IDENTIFIER |
str
|
Column name for the boolean that is True where the border is its canonical border |
Examples:
>>> conventions = AreaBorderNamingConventions('country')
>>> conventions.get_area_border_name('C1', 'C2')
'C1 - C2'
>>> conventions.get_opposite_area_border_name('C1 - C2')
'C2 - C1'
>>> conventions.get_canonical_border('C2 - C1')
'C1 - C2'
>>> conventions.border_identifier
'country_border'
Source code in src/mesqual/energy_data_handling/area_accounting/border_model_generator.py
16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 | |
__init__
¶
__init__(area_column: str, border_identifier: str = None, source_area_identifier: str = None, target_area_identifier: str = None)
Initialize border naming conventions.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
area_column
|
str
|
Name of the area column (e.g., 'country', 'bidding_zone') |
required |
border_identifier
|
str
|
Custom name for border identifier column. Defaults to '{area_column}_border' |
None
|
source_area_identifier
|
str
|
Name of the source area column.
Defaults to |
None
|
target_area_identifier
|
str
|
Name of the target area column.
Defaults to |
None
|
Source code in src/mesqual/energy_data_handling/area_accounting/border_model_generator.py
67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 | |
get_area_border_name
¶
get_area_border_name(area_from: str, area_to: str) -> str
Generate standardized border name from source and target areas.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
area_from
|
str
|
Source area identifier (e.g., 'DE', 'FR_North') |
required |
area_to
|
str
|
Target area identifier (e.g., 'FR', 'DE_South') |
required |
Returns:
| Name | Type | Description |
|---|---|---|
str |
str
|
Formatted border name using the configured separator (e.g. 'DE - FR', 'FR_North - DE_South') |
Source code in src/mesqual/energy_data_handling/area_accounting/border_model_generator.py
90 91 92 93 94 95 96 97 98 99 100 | |
decompose_area_border_name_to_areas
¶
decompose_area_border_name_to_areas(border_name: str) -> tuple[str, str]
Extract source and target area names from border identifier.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
border_name
|
str
|
Border name in standard format (e.g., 'DE - FR') |
required |
Returns:
| Type | Description |
|---|---|
tuple[str, str]
|
Tuple[str, str]: Source and target area names |
Raises:
| Type | Description |
|---|---|
ValueError
|
If border_name doesn't contain the expected separator |
Examples:
>>> AreaBorderNamingConventions('country').decompose_area_border_name_to_areas('C1 - C2')
('C1', 'C2')
Source code in src/mesqual/energy_data_handling/area_accounting/border_model_generator.py
102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 | |
get_opposite_area_border_name
¶
get_opposite_area_border_name(border_name: str) -> str
Generate the opposite direction border name.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
border_name
|
str
|
Original border name (e.g., 'DE - FR') |
required |
Returns:
| Name | Type | Description |
|---|---|---|
str |
str
|
Opposite direction border name (e.g., 'FR - DE') |
Source code in src/mesqual/energy_data_handling/area_accounting/border_model_generator.py
121 122 123 124 125 126 127 128 129 130 131 | |
get_canonical_border
¶
get_canonical_border(border_name: str) -> str
Return the canonical border of a border.
The canonical border has the area names in alphabetical order. A border and its opposite border have the same canonical border. Use it to identify a pair of borders regardless of direction, or to match borders of opposite direction.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
border_name
|
str
|
Border name in any direction (e.g., 'FR - DE' or 'DE - FR') |
required |
Returns:
| Name | Type | Description |
|---|---|---|
str |
str
|
Canonical border name (e.g., 'DE - FR') |
Source code in src/mesqual/energy_data_handling/area_accounting/border_model_generator.py
133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 | |
AreaBorderModelGenerator
¶
Bases: AreaBorderNamingConventions, AreaMembership
Border model from the lines and the area of each node.
line_areas maps the two ends of each line to their areas
(AreaMembership.edge_areas), in the columns source_area_identifier
and target_area_identifier (default area_from and area_to). A line
between two different areas gives two borders, one per direction. A line
inside one area, or with an end without area, gives no border. The
borders follow the order of the lines. Each border has its source and
target area, its opposite border, its canonical border and
is_canonical (AreaBorderNamingConventions).
Attributes:
| Name | Type | Description |
|---|---|---|
line_model_df |
DataFrame
|
Line model, one row per line. |
node_model_df |
DataFrame
|
Node model with the area column. |
node_from_col |
str
|
Column of |
node_to_col |
str
|
Column of |
line_areas |
DataFrame
|
The source and target area per line. |
Examples:
>>> generator = AreaBorderModelGenerator(
... dataset.fetch('Node.Model'), dataset.fetch('Line.Model'), 'country', 'node_from', 'node_to'
... )
>>> generator.generate_area_border_model()
area_from area_to opposite_border canonical_border is_canonical
country_border
C1 - C2 C1 C2 C2 - C1 C1 - C2 True
C2 - C1 C2 C1 C1 - C2 C1 - C2 False
Source code in src/mesqual/energy_data_handling/area_accounting/border_model_generator.py
151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 | |
__init__
¶
__init__(node_model_df: DataFrame, line_model_df: DataFrame, area_column: str, node_from_col: str, node_to_col: str, border_identifier: str = None, source_area_identifier: str = None, target_area_identifier: str = None)
Initialize the area border model generator.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
node_model_df
|
DataFrame
|
DataFrame containing node-level data with area assignments. Must contain area_column with area identifiers for each node. |
required |
line_model_df
|
DataFrame
|
DataFrame containing transmission line topology data. Must contain node_from_col and node_to_col with node identifiers. |
required |
area_column
|
str
|
Column name in node_model_df containing area assignments (e.g., 'country', 'bidding_zone', 'market_region') |
required |
node_from_col
|
str
|
Column name in line_model_df for source node identifiers |
required |
node_to_col
|
str
|
Column name in line_model_df for target node identifiers |
required |
border_identifier
|
str
|
Custom border column name (optional) |
None
|
source_area_identifier
|
str
|
Name of the source area column.
Defaults to |
None
|
target_area_identifier
|
str
|
Name of the target area column.
Defaults to |
None
|
Raises:
| Type | Description |
|---|---|
ValueError
|
If required columns are not found in input DataFrames,
or if |
Source code in src/mesqual/energy_data_handling/area_accounting/border_model_generator.py
181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 | |
generate_area_border_model
¶
generate_area_border_model() -> DataFrame
Generate the border model.
Analyzes transmission line topology to identify borders between areas, creating a DataFrame with directional relationships, naming conventions, and reference data for further analysis.
The generated model includes:
- Border identifiers in both directions (A - B and B - A).
- Source and target area columns.
- The opposite border of each border.
canonical_border: the border of the pair with the area names in alphabetical order.is_canonical: True where the border is its canonical border.
Returns:
| Type | Description |
|---|---|
DataFrame
|
pd.DataFrame: Border model indexed by border identifiers (index
name |
Source code in src/mesqual/energy_data_handling/area_accounting/border_model_generator.py
242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 | |
get_area_graph
¶
get_area_graph() -> Graph
Generate NetworkX graph representation of area connectivity.
Creates an undirected graph where nodes represent areas and edges represent borders. This is useful for network analysis, path finding, and connectivity studies in multi-area energy systems.
Returns:
| Type | Description |
|---|---|
Graph
|
nx.Graph: Undirected graph with areas as nodes and borders as edges. Graph may contain multiple disconnected components if areas are not fully interconnected. |
Examples:
>>> generator = AreaBorderModelGenerator(
... dataset.fetch('Node.Model'), dataset.fetch('Line.Model'), 'country', 'node_from', 'node_to'
... )
>>> list(generator.get_area_graph().edges())
[('C1', 'C2')]
Source code in src/mesqual/energy_data_handling/area_accounting/border_model_generator.py
304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 | |
enhance_with_geometry
¶
enhance_with_geometry(border_model_df: DataFrame, area_geometry_calculator: AreaBorderGeometryCalculator) -> DataFrame
Enhance border model with geometric properties for visualization.
Uses the AreaBorderGeometryCalculator to add a representative point, a direction angle and a line geometry to each border.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
border_model_df
|
DataFrame
|
Border model DataFrame to enhance |
required |
area_geometry_calculator
|
AreaBorderGeometryCalculator
|
Configured geometry calculator with area polygon data for geometric computations |
required |
Returns:
| Type | Description |
|---|---|
DataFrame
|
pd.DataFrame: The border model with the columns |
Examples:
>>> import geopandas as gpd
>>> from mesqual.energy_data_handling.area_accounting import AreaBorderGeometryCalculator
>>> generator = AreaBorderModelGenerator(
... dataset.fetch('Node.Model'), dataset.fetch('Line.Model'), 'country', 'node_from', 'node_to'
... )
>>> countries = gpd.GeoDataFrame(dataset.fetch('Country.Model'), crs='EPSG:4326')
>>> borders = generator.enhance_with_geometry(generator.generate_area_border_model(), AreaBorderGeometryCalculator(countries))
>>> borders[['azimuth_angle', 'areas_touch']]
azimuth_angle areas_touch
country_border
C1 - C2 90.0 True
C2 - C1 270.0 True
Note
The geometry may fail for some borders, for example for a missing
area geometry. Such a border gets NaN in the geometry columns, and
the failure is logged at WARNING. The other borders get their
geometry. The result always has the geometry columns.
Source code in src/mesqual/energy_data_handling/area_accounting/border_model_generator.py
327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 | |
AreaBorderGeometryCalculator
¶
Bases: GeoModelGeneratorBase
Geometry of the border between two areas, for maps of border variables.
Areas that touch have a physical border: the shared boundary line.
Areas that do not touch, for example across the sea, have a logical
border: the straight line between the boundaries of the largest polygons
of the two areas, on the line between their representative points. If
this line crosses other areas, the line of NonCrossingPathFinder
replaces it when the finder finds one; the finder states its rule. For
each border, the calculator gives a line, a point for labels and arrows,
and the azimuth angle of the direction from the first to the second area.
Attributes:
| Name | Type | Description |
|---|---|---|
area_model_gdf |
GeoDataFrame
|
GeoDataFrame with area polygon geometries |
non_crossing_path_finder |
NonCrossingPathFinder
|
Path finder for logical borders |
Examples:
>>> import geopandas as gpd
>>> countries = gpd.GeoDataFrame(dataset.fetch('Country.Model'), crs='EPSG:4326')
>>> calculator = AreaBorderGeometryCalculator(countries)
>>> calculator.calculate_border_geometry('C1', 'C2')
{'projection_point': <POINT (9 48)>, 'azimuth_angle': 90.0, 'geo_line_string': <LINESTRING (9 50, 9 46)>, 'areas_touch': True}
Two areas that do not touch get a logical border:
>>> from shapely.geometry import box
>>> islands = gpd.GeoDataFrame(geometry=[box(0, 0, 1, 1), box(3, 0, 4, 1)], index=['A', 'B'], crs='EPSG:4326')
>>> AreaBorderGeometryCalculator(islands).calculate_border_geometry('A', 'B')['geo_line_string']
<LINESTRING (1 0.5, 3 0.5)>
Source code in src/mesqual/energy_data_handling/area_accounting/border_model_geometry_calculator.py
13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 | |
GEOMETRY_COLUMNS
class-attribute
¶
GEOMETRY_COLUMNS: tuple[str, ...] = (PROJECTION_POINT_IDENTIFIER, AZIMUTH_ANGLE_IDENTIFIER, BORDER_AREAS_TOUCH_IDENTIFIER, BORDER_LINE_STRING_IDENTIFIER)
The keys of calculate_border_geometry, in this order.
__init__
¶
__init__(area_model_gdf: GeoDataFrame, non_crossing_path_finder: NonCrossingPathFinder = None)
Initialize the border geometry calculator.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
area_model_gdf
|
GeoDataFrame
|
GeoDataFrame containing area geometries with polygon boundaries. Index should contain area identifiers (e.g., country codes, bidding zone names). Must contain valid polygon geometries in 'geometry' column. Without a CRS, the polygons are lon/lat coordinates in EPSG:4326. The path of a border between areas that do not touch needs the CRS. |
required |
non_crossing_path_finder
|
NonCrossingPathFinder
|
Optional custom path finder for logical borders. If None, creates default NonCrossingPathFinder with standard parameters. |
None
|
Invalid geometries are cleaned with buffer(0). If area_model_gdf
has a CRS, the cleaning changes it in place.
Source code in src/mesqual/energy_data_handling/area_accounting/border_model_geometry_calculator.py
56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 | |
calculate_border_geometry
¶
calculate_border_geometry(area_from: str, area_to: str) -> dict[str, Point | float | LineString | bool]
Calculate the geometric properties of an area border.
The steps:
- Detect if the areas share a physical boundary (touching or intersecting).
- For physical borders: extract the shared boundary line.
- For logical borders: compute a connection path.
- Calculate the representative point for labels and arrows.
- Compute the azimuth angle for arrow icons.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
area_from
|
str
|
Source area identifier (must exist in area_model_gdf index) |
required |
area_to
|
str
|
Target area identifier (must exist in area_model_gdf index) |
required |
Returns:
| Name | Type | Description |
|---|---|---|
dict |
dict[str, Point | float | LineString | bool]
|
The border geometry with the keys |
Raises:
| Type | Description |
|---|---|
KeyError
|
If area_from or area_to not found in area_model_gdf |
Source code in src/mesqual/energy_data_handling/area_accounting/border_model_geometry_calculator.py
96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 | |
areas_touch
¶
areas_touch(area_from: str, area_to: str) -> bool
Check if two areas share a common physical (geographic) border.
Uses Shapely's touches() method to determine if area boundaries intersect without overlapping. This is the standard definition of physical adjacency for energy market regions.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
area_from
|
str
|
Source area identifier |
required |
area_to
|
str
|
Target area identifier |
required |
Returns:
| Name | Type | Description |
|---|---|---|
bool |
bool
|
True if areas share a common boundary, False otherwise |
Source code in src/mesqual/energy_data_handling/area_accounting/border_model_geometry_calculator.py
141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 | |
areas_intersect
¶
areas_intersect(area_from: str, area_to: str) -> bool
Check if two areas have any geometric intersection.
Uses Shapely's intersects() method to check for any form of geometric intersection, including touching, overlapping, or containment. This is broader than the touches() check and handles edge cases in geographic data.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
area_from
|
str
|
Source area identifier |
required |
area_to
|
str
|
Target area identifier |
required |
Returns:
| Name | Type | Description |
|---|---|---|
bool |
bool
|
True if areas have any geometric intersection, False otherwise |
Note
This method is used as a fallback for areas_touch() to handle geographic data with small overlaps or slight topology inconsistencies that are common in real-world boundary datasets.
Source code in src/mesqual/energy_data_handling/area_accounting/border_model_geometry_calculator.py
159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 | |
get_area_border_midpoint_and_angle
¶
get_area_border_midpoint_and_angle(area_from: str, area_to: str) -> tuple[Point, float]
Calculate representative point and directional angle for border.
The point and angle place directional indicators such as arrows and labels.
For a physical border, the point is the midpoint of the shared boundary line, and the angle is perpendicular to the boundary, toward the target area. For a logical border, the point is the midpoint of the connection line, and the angle follows the connection from source to target.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
area_from
|
str
|
Source area identifier |
required |
area_to
|
str
|
Target area identifier |
required |
Returns:
| Type | Description |
|---|---|
tuple[Point, float]
|
tuple[Point, float]: Representative point and directional angle in degrees. Angle range: 0-360 degrees, where 0° is North, 90° is East. |
Source code in src/mesqual/energy_data_handling/area_accounting/border_model_geometry_calculator.py
182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 | |
get_area_geometry
¶
get_area_geometry(area: str) -> Polygon | MultiPolygon
Retrieve and validate geometry for a specified area.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
area
|
str
|
Area identifier that must exist in area_model_gdf index |
required |
Returns:
| Type | Description |
|---|---|
Polygon | MultiPolygon
|
Union[Polygon, MultiPolygon]: Cleaned geometry with buffer(0) applied to ensure validity for geometric operations |
Raises:
| Type | Description |
|---|---|
KeyError
|
If area is not found in area_model_gdf |
Note
The buffer(0) operation ensures geometric validity for complex calculations, which is essential for reliable border analysis.
Source code in src/mesqual/energy_data_handling/area_accounting/border_model_geometry_calculator.py
217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 | |
get_straight_line_between_areas
¶
get_straight_line_between_areas(area_from: str, area_to: str) -> LineString
Return the line of the logical border between two areas that do not touch.
The line runs on the line between the representative points of the
largest polygons of the two areas, from boundary to boundary. If it
crosses other areas, the line of NonCrossingPathFinder replaces it
when the finder finds one; the finder states its rule. The results
are cached per pair of areas; the line of B to A is the reversed line
of A to B.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
area_from
|
str
|
Source area identifier |
required |
area_to
|
str
|
Target area identifier |
required |
Returns:
| Name | Type | Description |
|---|---|---|
LineString |
LineString
|
Connection line between the area boundaries. Line endpoints touch the area boundaries, not the centroids. |
Raises:
| Type | Description |
|---|---|
ValueError
|
If areas are touching (should use physical border instead) |
Source code in src/mesqual/energy_data_handling/area_accounting/border_model_geometry_calculator.py
236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 | |
NonCrossingPathFinder
¶
Shortest line between two polygons that does not cross the buffered other areas.
The finder samples points on the boundaries of both polygons and tests
every pair of points. It buffers the other areas by min_clearance and
rejects a line that crosses the boundary of a buffered area. A line that
lies wholly inside a buffer is accepted, and it can cross that area. The
number of tested lines is num_points squared.
Attributes:
| Name | Type | Description |
|---|---|---|
num_points |
int
|
Number of boundary points to sample per area |
min_clearance |
float
|
Buffer distance around other areas, in EPSG:3857 (Web Mercator) units if the areas have a geographic CRS, where one unit is about cos(latitude) meters on the ground, else in the units of their CRS. |
show_progress |
bool
|
Whether to display progress bars for long operations |
Examples:
>>> import geopandas as gpd
>>> from shapely.geometry import box
>>> finder = NonCrossingPathFinder(num_points=20, min_clearance=10_000, show_progress=False)
>>> obstacle = gpd.GeoDataFrame(geometry=[box(1.5, -1, 2.5, 0.5)], crs='EPSG:4326')
>>> path = finder.find_shortest_path(box(0, 0, 1, 1), box(3, 0, 4, 1), obstacle)
>>> [round(value, 1) for value in path.bounds] # the line passes above the obstacle
[1.0, 0.6, 3.0, 0.6]
Source code in src/mesqual/energy_data_handling/area_accounting/border_model_geometry_calculator.py
672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 | |
__init__
¶
__init__(num_points: int = 100, min_clearance: float = 50000, show_progress: bool = True)
Initialize the non-crossing path finder.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
num_points
|
int
|
Number of boundary points to sample per polygon. Higher values improve path quality but increase computation time. Typical range: 50-500 depending on precision requirements. |
100
|
min_clearance
|
float
|
Buffer distance around other areas, in EPSG:3857 (Web Mercator) units if the areas have a geographic CRS, where one unit is about cos(latitude) meters on the ground, else in the units of their CRS. |
50000
|
show_progress
|
bool
|
Whether to display progress bars during computation. Useful for long-running operations with high num_points values. |
True
|
Source code in src/mesqual/energy_data_handling/area_accounting/border_model_geometry_calculator.py
699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 | |
find_shortest_path
¶
find_shortest_path(polygon1: Polygon, polygon2: Polygon, other_areas: GeoDataFrame, name: str = None) -> LineString | None
Return the shortest line between two polygons that the finder accepts.
The run time grows with the number of tested lines times the number of other areas.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
polygon1
|
Polygon
|
Source polygon geometry |
required |
polygon2
|
Polygon
|
Target polygon geometry |
required |
other_areas
|
GeoDataFrame
|
GeoDataFrame of the areas to buffer and not cross |
required |
name
|
str
|
Optional name for progress tracking display |
None
|
Returns:
| Type | Description |
|---|---|
LineString | None
|
LineString or None: Shortest accepted line, or None if no line is accepted |
Raises:
| Type | Description |
|---|---|
ValueError
|
If |
Source code in src/mesqual/energy_data_handling/area_accounting/border_model_geometry_calculator.py
717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 | |
GeoModelGeneratorBase
¶
Base class for generating geometric models with representative points.
This class provides common functionality for working with geometric representations of energy system areas, including methods for computing representative points within polygons and multipolygons. It's designed to support energy market analysis where spatial aggregation of nodes into areas is required.
The class supports two methods for computing representative points:
- 'polylabel': The pole of inaccessibility, the point inside the polygon farthest from its boundary
- 'representative_point': Uses Shapely's built-in representative point method
Attributes:
| Name | Type | Description |
|---|---|---|
REPRESENTATIVE_POINT_METHOD |
str
|
Method used for computing representative points ('polylabel' or 'representative_point') |
Source code in src/mesqual/energy_data_handling/area_accounting/model_generator_base.py
7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 | |
get_representative_area_point
¶
get_representative_area_point(geom: Polygon | MultiPolygon) -> Point
Get a representative point for a polygon or multipolygon geometry.
This method computes a point that is guaranteed to be inside the geometry and is suitable for label placement or other visualization purposes in energy system maps. For MultiPolygons, it operates on the largest constituent.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
geom
|
Polygon | MultiPolygon
|
A Shapely Polygon or MultiPolygon geometry representing an energy system area (e.g., bidding zone, market region) |
required |
Returns:
| Name | Type | Description |
|---|---|---|
Point |
Point
|
A Shapely Point guaranteed to be inside the input geometry, suitable for map labels or representative location analysis |
Raises:
| Type | Description |
|---|---|
ValueError
|
If REPRESENTATIVE_POINT_METHOD is not supported |
Examples:
>>> from shapely.geometry import box
>>> GeoModelGeneratorBase().get_representative_area_point(box(0, 0, 10, 10))
<POINT (5 5)>
Source code in src/mesqual/energy_data_handling/area_accounting/model_generator_base.py
27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 | |
Area membership of nodes and edges: the one rule for which node belongs to which area.
AreaMembership
¶
Common parent of the area calculators and the area and border model generators: the area of each node.
A node has an area if has_area is True for the value in its area
column. A node without an area belongs to no area and is on no border.
edge_areas maps the two ends of each edge to their areas with the same
rule. A subclass sets node_model_df and area_column.
Attributes:
| Name | Type | Description |
|---|---|---|
node_model_df |
DataFrame
|
Node model, one row per node. |
area_column |
str
|
Column of |
Source code in src/mesqual/energy_data_handling/area_accounting/area_membership.py
6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 | |
has_area
staticmethod
¶
has_area(areas: Series) -> Series
Return True per object whose area is set: neither NaN nor None nor an empty string.
Examples:
>>> AreaMembership.has_area(pd.Series({'n1': 'A', 'n2': None, 'n3': ''})).tolist()
[True, False, False]
Source code in src/mesqual/energy_data_handling/area_accounting/area_membership.py
25 26 27 28 29 30 31 32 33 | |
edge_areas
classmethod
¶
edge_areas(edges: DataFrame, area_of_node: Series, end_from: str, end_to: str, area_from: str = AREA_FROM, area_to: str = AREA_TO) -> DataFrame
Return the area of the first end and the area of the second end per edge.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
edges
|
DataFrame
|
The edge model, one row per edge. |
required |
area_of_node
|
Series
|
The area of each node, indexed by node. |
required |
end_from
|
str
|
The column of |
required |
end_to
|
str
|
The column of |
required |
area_from
|
str
|
The name of the result column with the area of the first end. |
AREA_FROM
|
area_to
|
str
|
The name of the result column with the area of the second end. |
AREA_TO
|
Returns:
| Type | Description |
|---|---|
DataFrame
|
One row per edge with the two columns |
Raises:
| Type | Description |
|---|---|
ValueError
|
If |
Examples:
>>> nodes, lines = dataset.fetch('Node.Model'), dataset.fetch('Line.Model')
>>> AreaMembership.edge_areas(lines, nodes['country'], 'node_from', 'node_to')
area_from area_to
Line
L1 C1 C2
L2 C2 C1
L3 C1 C1
L4 C1 C2
L5 C2 C2
Source code in src/mesqual/energy_data_handling/area_accounting/area_membership.py
35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 | |
crosses_border
staticmethod
¶
crosses_border(edge_areas: DataFrame) -> Series
Return True per edge that is on a border: both areas are set and differ.
An edge from area A to area B is on the border A - B, in border direction, and on the border B - A, against it.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
edge_areas
|
DataFrame
|
Two columns per edge, as |
required |
Source code in src/mesqual/energy_data_handling/area_accounting/area_membership.py
88 89 90 91 92 93 94 95 96 97 98 99 100 101 | |
get_node_areas
¶
get_node_areas() -> Series
Return the area of each node that has one, indexed by node.
Raises:
| Type | Description |
|---|---|
ValueError
|
If |
Source code in src/mesqual/energy_data_handling/area_accounting/area_membership.py
103 104 105 106 107 108 109 110 111 | |