KPI & Attributes¶
KPI
dataclass
¶
Single computed KPI with value and rich metadata.
Represents a scalar metric, for example the mean price of country C1 in scenario base, with all context needed for filtering, visualization, and unit conversion.
Attributes:
| Name | Type | Description |
|---|---|---|
value |
float | int
|
The computed scalar value |
attributes |
KPIAttributes
|
Rich metadata container |
dataset |
Dataset
|
Reference to source dataset for lazy model access |
Source code in src/mesqual/kpis/kpi.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 | |
quantity
property
¶
quantity: Quantity
Return value as pint Quantity with unit.
Returns:
| Type | Description |
|---|---|
Quantity
|
Quantity with value and unit |
Raises:
| Type | Description |
|---|---|
ValueError
|
Neither the KPI nor the flag spec gives a unit. |
name
property
¶
name: str
Generate human-readable unique name.
Returns:
| Type | Description |
|---|---|
str
|
KPI name (custom or auto-generated) |
get_object_info_from_model
¶
get_object_info_from_model() -> Series
Lazy fetch of object metadata from Model flag.
Returns:
| Type | Description |
|---|---|
Series
|
Series with object properties from model DataFrame |
Source code in src/mesqual/kpis/kpi.py
106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 | |
get_kpi_name_with_dataset_name
¶
get_kpi_name_with_dataset_name() -> str
Get KPI name with dataset name for visualization tooltips.
Returns:
| Type | Description |
|---|---|
str
|
Name including dataset (e.g., "market_price Mean [base_scenario]") |
Source code in src/mesqual/kpis/kpi.py
129 130 131 132 133 134 135 136 137 138 139 | |
to_dict
¶
to_dict(primitive_values: bool = True) -> dict
Export KPI as flat dictionary for tables.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
primitive_values
|
bool
|
If True, convert objects to strings for serialization |
True
|
Returns:
| Type | Description |
|---|---|
dict
|
Dictionary with all KPI data |
Source code in src/mesqual/kpis/kpi.py
141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 | |
__repr__
¶
__repr__() -> str
String representation of KPI.
Source code in src/mesqual/kpis/kpi.py
158 159 160 | |
KPIAttributes
dataclass
¶
Rich metadata container for KPI instances.
Stores all context needed for filtering, grouping, visualization, and unit conversion of KPI values.
Attributes:
| Name | Type | Description |
|---|---|---|
flag |
FlagTypeProtocol
|
Variable flag, for example |
model_flag |
FlagTypeProtocol | None
|
Associated model flag, for example |
object_name |
Hashable | None
|
Specific object identifier, for example |
aggregation |
Aggregation | None
|
Aggregation applied (e.g., Aggregations.Mean) |
dataset_name |
str
|
Name of the dataset |
dataset_type |
Type[Dataset]
|
Type of dataset ('scenario', 'comparison', etc.) |
value_comparison |
ValueComparison | None
|
Comparison operation for comparison KPIs |
arithmetic_operation |
ArithmeticValueOperation | None
|
Arithmetic operation for derived KPIs |
reference_dataset_name |
str | None
|
Reference dataset for comparisons |
variation_dataset_name |
str | None
|
Variation dataset for comparisons |
name_prefix |
str
|
Custom prefix for KPI name |
name_suffix |
str
|
Custom suffix for KPI name |
custom_name |
str | None
|
Complete custom name override |
unit |
Unit | None
|
Physical unit of the KPI value |
target_unit |
Unit | None
|
Target unit for conversion |
dataset_attributes |
dict[str, Any]
|
Additional attributes from dataset (e.g., scenario attributes) |
extra_attributes |
dict[str, Any]
|
Extra attributes set by user (e.g. for filtering / grouping purposes) |
Source code in src/mesqual/kpis/attributes.py
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 | |
as_dict
¶
as_dict(primitive_values: bool = True) -> dict[str, Any]
Export attributes as dictionary for filtering.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
primitive_values
|
bool
|
If True, convert objects to strings for serialization |
True
|
Returns:
| Type | Description |
|---|---|
dict[str, Any]
|
Dictionary representation of attributes |
Source code in src/mesqual/kpis/attributes.py
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 | |
get
¶
get(key: str, default: Any = None) -> Any
Dict-like get interface for compatibility.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
key
|
str
|
Attribute key to retrieve |
required |
default
|
Any
|
Default value if key not found |
None
|
Returns:
| Type | Description |
|---|---|
Any
|
Attribute value or default |
Source code in src/mesqual/kpis/attributes.py
118 119 120 121 122 123 124 125 126 127 128 129 | |