Folium Custom KPI Group Generator¶
custom_kpi_group_generator
¶
CustomKPIGroupGenerator
¶
Bases: ABC
Base class for custom KPI groups and generator routing.
Use it when the attribute grouping of KPICollectionMapVisualizer does not
fit. A subclass defines two things in one place:
create_kpi_groups_with_names: the KPIs of each feature group, and its name.get_generators_for_kpi: the generators for each KPI.
generate_and_add_feature_groups_to_map then builds the feature groups and
adds them to the map.
Typical uses:
- Overlapping groups: the same KPI is in more than one feature group, for example flows with prices and flows with net positions.
- Different styles per KPI type, for example areas for prices and arrows for flows.
- Feature group names that are not a composition of KPI attributes.
Examples:
One feature group for each of the scenarios base and high_demand,
with areas for the prices and arrows for the border flows:
>>> import folium
>>> from mesqual.kpis import Aggregations, FlagAggKPIBuilder
>>> from mesqual.visualizations.folium_viz_system import AreaGenerator, ArrowIconGenerator
>>> definitions = (
... FlagAggKPIBuilder()
... .for_flags(['Country.Results.price', 'CountryBorder.Results.flow_sent_net'])
... .with_aggregation(Aggregations.Mean)
... .build()
... )
>>> study.scen.add_kpis_from_definitions_to_all_child_datasets(definitions)
>>> class PricesAndFlows(CustomKPIGroupGenerator):
... def __init__(self):
... self.areas = AreaGenerator()
... self.arrows = ArrowIconGenerator()
...
... def create_kpi_groups_with_names(self, source):
... kpis = source.get_merged_kpi_collection()
... return [(name, kpis.filter(dataset_name=name)) for name in ['base', 'high_demand']]
...
... def get_generators_for_kpi(self, kpi):
... if kpi.attributes.flag == 'Country.Results.price':
... return [self.areas]
... return [self.arrows]
>>> m = folium.Map(location=[48, 9], zoom_start=6)
>>> feature_groups = PricesAndFlows().generate_and_add_feature_groups_to_map(study.scen, m)
>>> [fg.layer_name for fg in feature_groups]
['base', 'high_demand']
Source code in src/mesqual/visualizations/folium_viz_system/custom_kpi_group_generator.py
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 | |
create_kpi_groups_with_names
abstractmethod
¶
create_kpi_groups_with_names(source: KPICollection | StudyManager | DatasetCollection | Any) -> list[tuple[str, KPICollection]]
Return the feature groups as (name, KPIs) pairs.
The source is what the caller passes to
generate_and_add_feature_groups_to_map, for example a KPICollection, a
StudyManager or a DatasetCollection. A KPI can be in more than one
group; it is then drawn once per group. The order of the list is the order
in the layer control. Return an empty list if there are no groups.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
source
|
KPICollection | StudyManager | DatasetCollection | Any
|
Source of the KPIs. |
required |
Returns:
| Type | Description |
|---|---|
list[tuple[str, KPICollection]]
|
List of |
Examples:
One group per dataset of a DatasetCollection:
def create_kpi_groups_with_names(self, source):
return [(dataset.name, dataset.kpi_collection) for dataset in source.dataset_iterator]
Source code in src/mesqual/visualizations/folium_viz_system/custom_kpi_group_generator.py
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 | |
get_generators_for_kpi
abstractmethod
¶
get_generators_for_kpi(kpi: KPI) -> list[FoliumObjectGenerator]
Return the generators for one KPI.
The method is called for each KPI of each group. Route by the KPI
attributes, such as flag, dataset_name, aggregation or object_name.
The generators draw in the order of the list, so a line after an area
is drawn over it. Markers, such as text overlays and arrow icons, are
always above areas and lines. An empty list skips the KPI.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
kpi
|
KPI
|
The KPI. |
required |
Returns:
| Type | Description |
|---|---|
list[FoliumObjectGenerator]
|
List of |
Source code in src/mesqual/visualizations/folium_viz_system/custom_kpi_group_generator.py
97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 | |
generate_and_add_feature_groups_to_map
¶
generate_and_add_feature_groups_to_map(source: KPICollection | StudyManager | DatasetCollection | Any, map_obj: Map, show: Literal['first', 'last', 'all', 'none'] = 'first', overlay: bool = False, **data_item_kwargs: Any) -> list[FeatureGroup]
Generate the feature groups and add them to the map.
For each group of create_kpi_groups_with_names, the method creates a
folium FeatureGroup, wraps each KPI in a KPIDataItem, applies the
generators of get_generators_for_kpi and adds the group to the map. A
generator that raises an error for a KPI is skipped for that KPI. The
example is in CustomKPIGroupGenerator.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
source
|
KPICollection | StudyManager | DatasetCollection | Any
|
Source of the KPIs, passed to |
required |
map_obj
|
Map
|
Folium map to add the feature groups to. |
required |
show
|
Literal['first', 'last', 'all', 'none']
|
Feature groups visible at the start: |
'first'
|
overlay
|
bool
|
Whether the feature groups are overlays in the layer control. |
False
|
**data_item_kwargs
|
Any
|
Arguments for each |
{}
|
Returns:
| Type | Description |
|---|---|
list[FeatureGroup]
|
The feature groups added to the map. |
Source code in src/mesqual/visualizations/folium_viz_system/custom_kpi_group_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 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 | |