Skip to content

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 src/mesqual/visualizations/folium_viz_system/visualizable_data_item.py
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
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: Any):
        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, **kwargs) -> 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 src/mesqual/visualizations/folium_viz_system/visualizable_data_item.py
34
35
36
37
@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 src/mesqual/visualizations/folium_viz_system/visualizable_data_item.py
39
40
41
42
@abstractmethod
def get_text_representation(self) -> str:
    """Get a representative text for the object."""
    pass

get_tooltip_data abstractmethod

get_tooltip_data(**kwargs) -> dict

Get data for tooltip display.

Source code in src/mesqual/visualizations/folium_viz_system/visualizable_data_item.py
44
45
46
47
@abstractmethod
def get_tooltip_data(self, **kwargs) -> 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 src/mesqual/visualizations/folium_viz_system/visualizable_data_item.py
49
50
51
52
@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.

The attributes are the values of the row. The name is the row index.

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 Any

Additional attributes to set on the data item

{}

Examples:

>>> item = ModelDataItem(dataset.fetch('Country.Model').loc['C1'], object_type='Country')
>>> item.get_name()
'C1'
>>> item.get_tooltip_data()
{'ID': 'C1', 'name': 'Country 1'}
>>> item.get_object_attribute('geometry')
<POLYGON ((9 46, 9 50, 5 50, 5 46, 9 46))>

The generators wrap each row of a model DataFrame in a ModelDataItem.

Source code in src/mesqual/visualizations/folium_viz_system/visualizable_data_item.py
 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
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.

    The attributes are the values of the row. The name is the row index.

    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:
        >>> item = ModelDataItem(dataset.fetch('Country.Model').loc['C1'], object_type='Country')
        >>> item.get_name()
        'C1'
        >>> item.get_tooltip_data()
        {'ID': 'C1', 'name': 'Country 1'}
        >>> item.get_object_attribute('geometry')
        <POLYGON ((9 46, 9 50, 5 50, 5 46, 9 46))>

        The generators wrap each row of a model DataFrame in a `ModelDataItem`.
    """

    OBJECT_NAME_COLUMNS = ['name', 'object_id', 'index', 'object_name']

    def __init__(self, object_data: pd.Series, object_type: str | Any = None, **kwargs: Any):
        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, **kwargs) -> dict:
        """Return the ID and the column values of the row, as text.

        Leaves out missing values and geometries. Cuts a value longer than 50
        characters to 47 characters and `...`.
        """
        data = {'ID': self.object_id}
        for col, value in self.object_data.items():
            if isinstance(value, BaseGeometry):
                continue
            if not is_missing(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)

get_tooltip_data

get_tooltip_data(**kwargs) -> dict

Return the ID and the column values of the row, as text.

Leaves out missing values and geometries. Cuts a value longer than 50 characters to 47 characters and ....

Source code in src/mesqual/visualizations/folium_viz_system/visualizable_data_item.py
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
def get_tooltip_data(self, **kwargs) -> dict:
    """Return the ID and the column values of the row, as text.

    Leaves out missing values and geometries. Cuts a value longer than 50
    characters to 47 characters and `...`.
    """
    data = {'ID': self.object_id}
    for col, value in self.object_data.items():
        if isinstance(value, BaseGeometry):
            continue
        if not is_missing(value):
            value_str = str(value)
            if len(value_str) > 50:
                value_str = value_str[:47] + '...'
            data[col] = value_str
    return data

KPIDataItem

Bases: VisualizableDataItem

Visualizable data item for KPI objects.

Wraps a KPI for the map. get_object_attribute reads the attributes of the model object of the KPI; kpi_value, value and kpi give the KPI value when the model object has no attribute of that name. The text is the KPI value in its pretty unit.

Parameters:

Name Type Description Default
kpi KPI

KPI with its value and attributes

required
kpi_collection KPICollection

Optional KPI collection for context

None
**kwargs Any

Additional attributes to set on the data item

{}

Examples:

>>> from mesqual.kpis import Aggregations, FlagAggKPIBuilder
>>> dataset.add_kpis_from_definitions(
...     FlagAggKPIBuilder().for_flag('Country.Results.price').with_aggregation(Aggregations.Mean).build()
... )
>>> item = KPIDataItem(dataset.kpi_collection.filter(object_name='C1')[0], dataset.kpi_collection)
>>> print(round(item.get_object_attribute('kpi_value'), 2))
42.1
>>> item.get_object_attribute('name')
'Country 1'
>>> item.get_text_representation()
'42.1 €/MWh'

The generators wrap each KPI of a collection in a KPIDataItem.

Source code in src/mesqual/visualizations/folium_viz_system/visualizable_data_item.py
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
class KPIDataItem(VisualizableDataItem):
    """
    Visualizable data item for KPI objects.

    Wraps a KPI for the map. `get_object_attribute` reads the attributes of the
    model object of the KPI; `kpi_value`, `value` and `kpi` give the KPI value
    when the model object has no attribute of that name. The text is the KPI
    value in its pretty unit.

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

    Examples:
        >>> from mesqual.kpis import Aggregations, FlagAggKPIBuilder
        >>> dataset.add_kpis_from_definitions(
        ...     FlagAggKPIBuilder().for_flag('Country.Results.price').with_aggregation(Aggregations.Mean).build()
        ... )
        >>> item = KPIDataItem(dataset.kpi_collection.filter(object_name='C1')[0], dataset.kpi_collection)
        >>> print(round(item.get_object_attribute('kpi_value'), 2))
        42.1
        >>> item.get_object_attribute('name')
        'Country 1'
        >>> item.get_text_representation()
        '42.1 €/MWh'

        The generators wrap each KPI of a collection in a `KPIDataItem`.
    """

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

    def __init__(self, kpi: KPI, kpi_collection: KPICollection = None, **kwargs: Any):
        self.kpi = kpi
        self.kpi_collection = kpi_collection
        self._object_info = kpi.get_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, converter: QuantityToTextConverter = None) -> str:
        """
        Get formatted text representation of the KPI value.

        Args:
            converter: Optional QuantityToTextConverter for custom formatting

        Returns:
            Formatted string representation of the KPI value
        """

        if converter is not None:
            return converter.convert(self.kpi.quantity)

        q = Units.get_quantity_in_pretty_unit(self.kpi.quantity)
        text = Units.get_pretty_text_for_quantity(q)
        return text

    def get_tooltip_data(self, converter: QuantityToTextConverter = None) -> dict:
        kpi_data = {
            'KPI': self.kpi.get_kpi_name_with_dataset_name(),
            'Value': self.get_text_representation(converter),
        }
        _MAX_MODEL_DATA_LEN = 3
        model_data = self._model_item.get_tooltip_data()
        model_data = dict(list(model_data.items())[:_MAX_MODEL_DATA_LEN])
        if len(model_data) > _MAX_MODEL_DATA_LEN:
            model_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(converter: QuantityToTextConverter = None) -> str

Get formatted text representation of the KPI value.

Parameters:

Name Type Description Default
converter QuantityToTextConverter

Optional QuantityToTextConverter for custom formatting

None

Returns:

Type Description
str

Formatted string representation of the KPI value

Source code in src/mesqual/visualizations/folium_viz_system/visualizable_data_item.py
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
def get_text_representation(self, converter: QuantityToTextConverter = None) -> str:
    """
    Get formatted text representation of the KPI value.

    Args:
        converter: Optional QuantityToTextConverter for custom formatting

    Returns:
        Formatted string representation of the KPI value
    """

    if converter is not None:
        return converter.convert(self.kpi.quantity)

    q = Units.get_quantity_in_pretty_unit(self.kpi.quantity)
    text = Units.get_pretty_text_for_quantity(q)
    return text