Skip to content

MESQUAL Folium Area Visualization System

viz_areas

ResolvedAreaFeature dataclass

Bases: ResolvedFeature

Resolved visual properties for area/polygon map elements.

Container for all computed styling properties of polygon visualizations, including fill colors, border styles, and interactive behaviors. Used by AreaGenerator to create folium GeoJson polygons.

Source code in submodules/mesqual/mesqual/visualizations/folium_viz_system/viz_areas.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
@dataclass
class ResolvedAreaFeature(ResolvedFeature):
    """
    Resolved visual properties for area/polygon map elements.

    Container for all computed styling properties of polygon visualizations,
    including fill colors, border styles, and interactive behaviors.
    Used by AreaGenerator to create folium GeoJson polygons.
    """

    @property
    def geometry(self) -> Polygon | MultiPolygon:
        return self.get('geometry')

    @property
    def fill_color(self) -> str:
        return self.get('fill_color')

    @property
    def border_color(self) -> str:
        return self.get('border_color')

    @property
    def border_width(self) -> float:
        return self.get('border_width')

    @property
    def fill_opacity(self) -> float:
        return min(self.get('fill_opacity'), 1.0)

    @property
    def highlight_border_width(self) -> float:
        highlight_border_width = self.get('highlight_border_width')
        if highlight_border_width is None:
            return self.border_width
        return highlight_border_width

    @property
    def highlight_fill_opacity(self) -> float:
        return min(self.get('highlight_fill_opacity'), 1.0)

AreaFeatureResolver

Bases: FeatureResolver[ResolvedAreaFeature]

Resolves visual properties for polygon/area map elements.

Specialized feature resolver for area visualizations that handles polygon geometries, fill colors, border styling, and opacity settings. Commonly used for visualizing bidding zones, geographic regions, or any spatial areas with associated data values.

Parameters:

Name Type Description Default
fill_color PropertyMapper | str

Area fill color (static value or PropertyMapper)

 '#D2D2D2'
border_color PropertyMapper | str

Border/stroke color (static value or PropertyMapper)

'white'
border_width PropertyMapper | float

Border width in pixels (static value or PropertyMapper)

 2.0
fill_opacity PropertyMapper | float

Fill transparency 0-1 (static value or PropertyMapper)

 0.8
highlight_border_width PropertyMapper | float

Border width on hover (defaults to border_width)

 None
highlight_fill_opacity PropertyMapper | float

Fill opacity on hover (defaults to 1.0)

 1.0
tooltip PropertyMapper | str | bool

Tooltip content (True for auto-generated, False for none)

 True
popup PropertyMapper | Popup | bool

Popup content (True/False/PropertyMapper)

 False
geometry PropertyMapper | Polygon

Polygon geometry (defaults to 'geometry' attribute)

 None
**property_mappers PropertyMapper | Any

Additional custom property mappings

 {}

Examples:

Basic area visualization:

>>> resolver = AreaFeatureResolver(
...     fill_color='#FF0000',
...     border_color='white',
...     fill_opacity=0.8
... )

Data-driven coloring:

>>> color_scale = SegmentedContinuousColorscale(...)
>>> resolver = AreaFeatureResolver(
...     fill_color=PropertyMapper.from_kpi_value(color_scale),
...     fill_opacity=PropertyMapper.from_item_attr('confidence', lambda c: 0.3 + 0.6 * c)
... )
Source code in submodules/mesqual/mesqual/visualizations/folium_viz_system/viz_areas.py 
 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
class AreaFeatureResolver(FeatureResolver[ResolvedAreaFeature]):
    """
    Resolves visual properties for polygon/area map elements.

    Specialized feature resolver for area visualizations that handles polygon
    geometries, fill colors, border styling, and opacity settings. Commonly
    used for visualizing bidding zones, geographic regions, or any spatial
    areas with associated data values.

    Args:
        fill_color: Area fill color (static value or PropertyMapper)
        border_color: Border/stroke color (static value or PropertyMapper)  
        border_width: Border width in pixels (static value or PropertyMapper)
        fill_opacity: Fill transparency 0-1 (static value or PropertyMapper)
        highlight_border_width: Border width on hover (defaults to border_width)
        highlight_fill_opacity: Fill opacity on hover (defaults to 1.0)
        tooltip: Tooltip content (True for auto-generated, False for none)
        popup: Popup content (True/False/PropertyMapper)
        geometry: Polygon geometry (defaults to 'geometry' attribute)
        **property_mappers: Additional custom property mappings

    Examples:
        Basic area visualization:
        >>> resolver = AreaFeatureResolver(
        ...     fill_color='#FF0000',
        ...     border_color='white',
        ...     fill_opacity=0.8
        ... )

        Data-driven coloring:
        >>> color_scale = SegmentedContinuousColorscale(...)
        >>> resolver = AreaFeatureResolver(
        ...     fill_color=PropertyMapper.from_kpi_value(color_scale),
        ...     fill_opacity=PropertyMapper.from_item_attr('confidence', lambda c: 0.3 + 0.6 * c)
        ... )
    """
    def __init__(
            self,
            fill_color: PropertyMapper | str = '#D2D2D2',
            border_color: PropertyMapper | str = 'white',
            border_width: PropertyMapper | float = 2.0,
            fill_opacity: PropertyMapper | float = 0.8,
            highlight_border_width: PropertyMapper | float = None,
            highlight_fill_opacity: PropertyMapper | float = 1.0,
            tooltip: PropertyMapper | str | bool = True,
            popup: PropertyMapper | folium.Popup | bool = False,
            geometry: PropertyMapper | Polygon = None,
            **property_mappers: PropertyMapper | Any,
    ):
        mappers = dict(
            fill_color=fill_color,
            border_color=border_color,
            border_width=border_width,
            fill_opacity=fill_opacity,
            highlight_border_width=highlight_border_width,
            highlight_fill_opacity=highlight_fill_opacity,
            tooltip=tooltip,
            popup=popup,
            geometry=self._explicit_or_fallback(geometry, self._default_geometry_mapper()),
            **property_mappers
        )
        super().__init__(feature_type=ResolvedAreaFeature, **mappers)

AreaGenerator

Bases: FoliumObjectGenerator[AreaFeatureResolver]

Generates folium GeoJson polygon objects for area visualizations.

Creates interactive map polygons from data items with computed styling properties. Handles polygon and multipolygon geometries, applies styling, and adds tooltips/popups for user interaction.

Commonly used for visualizing: - Bidding zones colored by electricity prices - Geographic regions sized by population or economic data
- Network areas colored by KPI values - Administrative boundaries with associated statistics

Examples:

Basic usage pattern:

>>> color_scale = SegmentedContinuousColorscale(...)
>>> generator = AreaGenerator(
...     AreaFeatureResolver(
...         fill_color=PropertyMapper.from_kpi_value(color_scale),
...         tooltip=True
...     )
... )
>>> fg = folium.FeatureGroup('Bidding Zones')
>>> generator.generate_objects_for_kpi_collection(price_kpis, fg)
>>> fg.add_to(map)

Combined with other generators:

>>> # Areas for zones, lines for interconnectors
>>> area_gen = AreaGenerator(...)
>>> line_gen = LineGenerator(...)
>>> 
>>> area_gen.generate_objects_for_model_df(zones_df, feature_group)
>>> line_gen.generate_objects_for_model_df(borders_df, feature_group)
Source code in submodules/mesqual/mesqual/visualizations/folium_viz_system/viz_areas.py 
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
class AreaGenerator(FoliumObjectGenerator[AreaFeatureResolver]):
    """
    Generates folium GeoJson polygon objects for area visualizations.

    Creates interactive map polygons from data items with computed styling
    properties. Handles polygon and multipolygon geometries, applies styling,
    and adds tooltips/popups for user interaction.

    Commonly used for visualizing:
    - Bidding zones colored by electricity prices
    - Geographic regions sized by population or economic data  
    - Network areas colored by KPI values
    - Administrative boundaries with associated statistics

    Examples:
        Basic usage pattern:
        >>> color_scale = SegmentedContinuousColorscale(...)
        >>> generator = AreaGenerator(
        ...     AreaFeatureResolver(
        ...         fill_color=PropertyMapper.from_kpi_value(color_scale),
        ...         tooltip=True
        ...     )
        ... )
        >>> fg = folium.FeatureGroup('Bidding Zones')
        >>> generator.generate_objects_for_kpi_collection(price_kpis, fg)
        >>> fg.add_to(map)

        Combined with other generators:
        >>> # Areas for zones, lines for interconnectors
        >>> area_gen = AreaGenerator(...)
        >>> line_gen = LineGenerator(...)
        >>> 
        >>> area_gen.generate_objects_for_model_df(zones_df, feature_group)
        >>> line_gen.generate_objects_for_model_df(borders_df, feature_group)
    """
    """Generates folium GeoJson objects for area geometries."""

    def _feature_resolver_type(self) -> Type[AreaFeatureResolver]:
        return AreaFeatureResolver

    def generate(self, data_item: VisualizableDataItem, feature_group: folium.FeatureGroup) -> None:
        """
        Generate and add a folium GeoJson polygon to the feature group.

        Args:
            data_item: Data item containing polygon geometry and associated data
            feature_group: Folium feature group to add the polygon to
        """
        style = self.feature_resolver.resolve_feature(data_item)

        geometry = style.geometry
        if not isinstance(geometry, (Polygon, MultiPolygon)):
            return

        style_dict = {
            'fillColor': style.fill_color,
            'color': style.border_color,
            'weight': style.border_width,
            'fillOpacity': style.fill_opacity
        }

        highlight_dict = style_dict.copy()
        highlight_dict['weight'] = style.highlight_border_width
        highlight_dict['fillOpacity'] = style.highlight_fill_opacity

        geojson_data = {
            "type": "Feature",
            "geometry": geometry.__geo_interface__,
            "properties": {"tooltip": style.tooltip}
        }

        folium.GeoJson(
            geojson_data,
            style_function=lambda x, s=style_dict: s,
            highlight_function=lambda x, h=highlight_dict: h,
            tooltip=folium.GeoJsonTooltip(fields=['tooltip'], aliases=[''], sticky=True) if style.tooltip else None,
            popup=style.popup
        ).add_to(feature_group)

generate 

generate(data_item: VisualizableDataItem, feature_group: FeatureGroup) -> None

Generate and add a folium GeoJson polygon to the feature group.

Parameters:

Name Type Description Default
data_item VisualizableDataItem

Data item containing polygon geometry and associated data

 required
feature_group FeatureGroup

Folium feature group to add the polygon to

 required
Source code in submodules/mesqual/mesqual/visualizations/folium_viz_system/viz_areas.py 
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
def generate(self, data_item: VisualizableDataItem, feature_group: folium.FeatureGroup) -> None:
    """
    Generate and add a folium GeoJson polygon to the feature group.

    Args:
        data_item: Data item containing polygon geometry and associated data
        feature_group: Folium feature group to add the polygon to
    """
    style = self.feature_resolver.resolve_feature(data_item)

    geometry = style.geometry
    if not isinstance(geometry, (Polygon, MultiPolygon)):
        return

    style_dict = {
        'fillColor': style.fill_color,
        'color': style.border_color,
        'weight': style.border_width,
        'fillOpacity': style.fill_opacity
    }

    highlight_dict = style_dict.copy()
    highlight_dict['weight'] = style.highlight_border_width
    highlight_dict['fillOpacity'] = style.highlight_fill_opacity

    geojson_data = {
        "type": "Feature",
        "geometry": geometry.__geo_interface__,
        "properties": {"tooltip": style.tooltip}
    }

    folium.GeoJson(
        geojson_data,
        style_function=lambda x, s=style_dict: s,
        highlight_function=lambda x, h=highlight_dict: h,
        tooltip=folium.GeoJsonTooltip(fields=['tooltip'], aliases=[''], sticky=True) if style.tooltip else None,
        popup=style.popup
    ).add_to(feature_group)