Skip to content

MESQUAL Folium-Visualizable Data Item

visualizable_data_item

VisualizableDataItem

Bases: ABC

Abstract interface for data items that can be visualized on maps.

Defines the contract for all data items that can be processed by the folium visualization system. Provides attribute access, tooltip data generation, and text representation for map elements.

This abstraction enables polymorphic handling of different data sources (model DataFrames, KPI objects, custom data) within the visualization pipeline while maintaining consistent interface expectations.

Source code in submodules/mesqual/mesqual/visualizations/folium_viz_system/visualizable_data_item.py 
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
class VisualizableDataItem(ABC):
    """
    Abstract interface for data items that can be visualized on maps.

    Defines the contract for all data items that can be processed by the
    folium visualization system. Provides attribute access, tooltip data
    generation, and text representation for map elements.

    This abstraction enables polymorphic handling of different data sources
    (model DataFrames, KPI objects, custom data) within the visualization
    pipeline while maintaining consistent interface expectations.
    """

    def __init__(self, **kwargs):
        for k, v in kwargs.items():
            setattr(self, k, v)

    @abstractmethod
    def get_name(self) -> str:
        """Get a representative name for the object."""
        pass

    @abstractmethod
    def get_text_representation(self) -> str:
        """Get a representative text for the object."""
        pass

    @abstractmethod
    def get_tooltip_data(self) -> dict:
        """Get data for tooltip display."""
        pass

    @abstractmethod
    def get_object_attribute(self, attribute: str) -> Any:
        """Get value for styling from specified column."""
        pass

    @abstractmethod
    def object_has_attribute(self, attribute: str) -> bool:
        pass

get_name abstractmethod 

get_name() -> str

Get a representative name for the object.

Source code in submodules/mesqual/mesqual/visualizations/folium_viz_system/visualizable_data_item.py 
27
28
29
30
@abstractmethod
def get_name(self) -> str:
    """Get a representative name for the object."""
    pass

get_text_representation abstractmethod 

get_text_representation() -> str

Get a representative text for the object.

Source code in submodules/mesqual/mesqual/visualizations/folium_viz_system/visualizable_data_item.py 
32
33
34
35
@abstractmethod
def get_text_representation(self) -> str:
    """Get a representative text for the object."""
    pass

get_tooltip_data abstractmethod 

get_tooltip_data() -> dict

Get data for tooltip display.

Source code in submodules/mesqual/mesqual/visualizations/folium_viz_system/visualizable_data_item.py 
37
38
39
40
@abstractmethod
def get_tooltip_data(self) -> dict:
    """Get data for tooltip display."""
    pass

get_object_attribute abstractmethod 

get_object_attribute(attribute: str) -> Any

Get value for styling from specified column.

Source code in submodules/mesqual/mesqual/visualizations/folium_viz_system/visualizable_data_item.py 
42
43
44
45
@abstractmethod
def get_object_attribute(self, attribute: str) -> Any:
    """Get value for styling from specified column."""
    pass

ModelDataItem

Bases: VisualizableDataItem

Visualizable data item for model DataFrame rows.

Wraps pandas Series objects (DataFrame rows) to provide the VisualizableDataItem interface. Commonly used for visualizing static model data like network topology, geographic boundaries, or reference datasets.

Handles attribute access from DataFrame columns, provides meaningful object naming, and generates informative tooltips from available data.

Parameters:

Name Type Description Default
object_data Series

Pandas Series representing a DataFrame row

 required
object_type str | Any

Optional type identifier for the object

 None
**kwargs

Additional attributes to set on the data item

 {}

Examples:

Typical usage in generators:

>>> for _, row in model_df.iterrows():
...     data_item = ModelDataItem(row, object_type='BiddingZone')
...     generator.generate(data_item, feature_group)

Access pattern:

>>> data_item.get_object_attribute('geometry')  # From DataFrame column
>>> data_item.get_name()  # Object identifier
>>> data_item.get_tooltip_data()  # All available data for tooltip
Source code in submodules/mesqual/mesqual/visualizations/folium_viz_system/visualizable_data_item.py 
 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
class ModelDataItem(VisualizableDataItem):
    """
    Visualizable data item for model DataFrame rows.

    Wraps pandas Series objects (DataFrame rows) to provide the VisualizableDataItem
    interface. Commonly used for visualizing static model data like network
    topology, geographic boundaries, or reference datasets.

    Handles attribute access from DataFrame columns, provides meaningful object
    naming, and generates informative tooltips from available data.

    Args:
        object_data: Pandas Series representing a DataFrame row
        object_type: Optional type identifier for the object
        **kwargs: Additional attributes to set on the data item

    Examples:
        Typical usage in generators:
        >>> for _, row in model_df.iterrows():
        ...     data_item = ModelDataItem(row, object_type='BiddingZone')
        ...     generator.generate(data_item, feature_group)

        Access pattern:
        >>> data_item.get_object_attribute('geometry')  # From DataFrame column
        >>> data_item.get_name()  # Object identifier
        >>> data_item.get_tooltip_data()  # All available data for tooltip
    """
    OBJECT_NAME_COLUMNS = ['name', 'object_id', 'index', 'object_name']

    def __init__(self, object_data: pd.Series, object_type: str | Any = None, **kwargs):
        self.object_data = object_data
        self.object_id = object_data.name
        self.object_type = object_type
        self.name_attributes = self.OBJECT_NAME_COLUMNS + [self.object_type]
        super().__init__(**kwargs)

    def get_name(self) -> str:
        return str(self.object_id)

    def get_text_representation(self) -> str:
        return self.get_name()

    def get_tooltip_data(self) -> dict:
        data = {'ID': self.object_id}
        for col, value in self.object_data.items():
            if pd.notna(value):
                value_str = str(value)
                if len(value_str) > 50:
                    value_str = value_str[:47] + "..."
                data[col] = value_str
        return data

    def get_object_attribute(self, attribute: str) -> Any:
        if (attribute in self.name_attributes) and (attribute not in self.object_data):
            return self.get_name()
        return self.object_data.get(attribute)

    def object_has_attribute(self, attribute: str) -> bool:
        return (attribute in self.object_data) or (attribute in self.name_attributes)

KPIDataItem

Bases: VisualizableDataItem

Visualizable data item for KPI objects.

Wraps MESQUAL KPI objects to provide the VisualizableDataItem interface. Combines KPI values with associated model object information for rich map visualization of computed energy system metrics.

Handles attribute access from both KPI values and underlying model objects, provides formatted value representations, and generates enhanced tooltips showing both KPI information and object details.

Parameters:

Name Type Description Default
kpi KPI

MESQUAL KPI object with computed value and metadata

 required
kpi_collection KPICollection

Optional KPI collection for context

 None
**kwargs

Additional attributes to set on the data item

 {}

Examples:

Typical usage in visualizers:

>>> for kpi in kpi_collection:
...     data_item = KPIDataItem(kpi, kpi_collection)
...     generator.generate(data_item, feature_group)

Access patterns:

>>> data_item.kpi.value  # Direct KPI value access
>>> data_item.get_object_attribute('geometry')  # From model object
>>> data_item.get_object_attribute('kpi_value')  # Alias for KPI value
>>> data_item.get_text_representation()  # Formatted value string
Source code in submodules/mesqual/mesqual/visualizations/folium_viz_system/visualizable_data_item.py 
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
class KPIDataItem(VisualizableDataItem):
    """
    Visualizable data item for KPI objects.

    Wraps MESQUAL KPI objects to provide the VisualizableDataItem interface.
    Combines KPI values with associated model object information for rich
    map visualization of computed energy system metrics.

    Handles attribute access from both KPI values and underlying model objects,
    provides formatted value representations, and generates enhanced tooltips
    showing both KPI information and object details.

    Args:
        kpi: MESQUAL KPI object with computed value and metadata
        kpi_collection: Optional KPI collection for context
        **kwargs: Additional attributes to set on the data item

    Examples:
        Typical usage in visualizers:
        >>> for kpi in kpi_collection:
        ...     data_item = KPIDataItem(kpi, kpi_collection)
        ...     generator.generate(data_item, feature_group)

        Access patterns:
        >>> data_item.kpi.value  # Direct KPI value access
        >>> data_item.get_object_attribute('geometry')  # From model object
        >>> data_item.get_object_attribute('kpi_value')  # Alias for KPI value
        >>> data_item.get_text_representation()  # Formatted value string
    """

    KPI_VALUE_COLUMNS = ['kpi_value', 'value', 'kpi']

    def __init__(self, kpi: KPI, kpi_collection: KPICollection = None, **kwargs):
        self.kpi = kpi
        self.kpi_collection = kpi_collection
        self._object_info = kpi.get_attributed_object_info_from_model()
        self._model_item = ModelDataItem(self._object_info)
        super().__init__(**kwargs)

    def get_name(self) -> str:
        return str(self.kpi.name)

    def get_text_representation(self) -> str:
        """
        Get formatted text representation of the KPI value.

        Returns:
            Formatted string representation of the KPI value
        """
        return f"{self.kpi.value:.1f}"  # TODO: use pretty formatting and quantities etc.

    def get_tooltip_data(self) -> dict:
        kpi_data = {
            'KPI': self.kpi.get_kpi_name_with_dataset_name(),
            'Value': str(self.kpi.quantity),
        }
        model_data = self._model_item.get_tooltip_data()
        return {**kpi_data, **model_data}

    def get_object_attribute(self, attribute: str) -> Any:
        if (attribute in self.KPI_VALUE_COLUMNS) and (not self._model_item.object_has_attribute(attribute)):
            return self.kpi.value
        return self._model_item.get_object_attribute(attribute)

    def object_has_attribute(self, attribute: str) -> bool:
        if attribute in self.KPI_VALUE_COLUMNS:
            return True
        return self._model_item.object_has_attribute(attribute)

get_text_representation 

get_text_representation() -> str

Get formatted text representation of the KPI value.

Returns:

Type Description
str

Formatted string representation of the KPI value
Source code in submodules/mesqual/mesqual/visualizations/folium_viz_system/visualizable_data_item.py 
155
156
157
158
159
160
161
162
def get_text_representation(self) -> str:
    """
    Get formatted text representation of the KPI value.

    Returns:
        Formatted string representation of the KPI value
    """
    return f"{self.kpi.value:.1f}"  # TODO: use pretty formatting and quantities etc.