Flag and FlagIndex References¶
flag
¶
Flag specs, their dimensions and schemas, area and border layers, and the flag index that looks them up.
REQUIRED
module-attribute
¶
REQUIRED = _Required()
Marker for a spec field or a parameter default that has no default value.
FlagTypeProtocol
¶
Bases: Protocol
Protocol for mesqual flag types.
Flags must be hashable (usable as dict keys) and convertible to strings.
Compatible types include strings, enums, and custom classes with __hash__ and __str__.
Examples of flag types:
- Strings, for example
'Generator.Model'or'Node.Results.price'. - Enum members.
- Custom classes that implement the protocol.
Source code in src/mesqual/flag/flag.py
4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 | |
__hash__
¶
__hash__() -> int
Return stable hash value for use as dictionary key.
Source code in src/mesqual/flag/flag.py
18 19 20 | |
__str__
¶
__str__() -> str
Return human-readable string representation.
Source code in src/mesqual/flag/flag.py
22 23 24 | |
Dimension
dataclass
¶
One dimension: a variant of a flag spec, or a parameter of a flag spec or a dataset class.
The place of the dimension decides its role:
FlagSpec(variants=...): a variant. It is a placeholder in the flag name, and each value is a flag of its own.FlagSpec(params=...): a flag parameter. It is a setting of one flag, given as a keyword argument offetch.Dataset.fetch_params: a dataset parameter. It is a setting of every fetch of that dataset class, for examplecomparison_typeof a comparison.
A parameter of both kinds resolves the same way: the keyword argument of
fetch, then param_defaults of the effective config, then default.
A value outside values raises ValueError.
Attributes:
| Name | Type | Description |
|---|---|---|
name |
str
|
Name of the dimension. For a variant, also the placeholder in
the flag name. For a parameter, the keyword argument of |
description |
str
|
What the dimension selects. |
values |
Mapping[Hashable, str] | Callable[[Dataset], Mapping[Hashable, str]] | None
|
Allowed values, each with a short description. A function of
the dataset gives values per dataset (a flag family). A function
that fetches an unavailable flag gives no values. |
default |
Any
|
Parameters only. |
validate |
Callable[[Any], None] | None
|
Parameters only. Raises |
Examples:
A variant dimension and a parameter:
>>> FUEL_TYPE = Dimension('fuel_type', 'Fuel type of the supply.', {
... 'res': 'renewable sources',
... 'coal': 'coal plants',
... 'gas': 'gas plants',
... })
>>> SOLUTION = Dimension('solution', 'Solution of the run to read.', {
... 'first': 'the first solution of the run',
... 'final': 'the final solution of the run',
... }, default='final')
The synthetic platform has SOLUTION in the params of the spec of
'Node.Results.price':
dataset.fetch(flag)gives_fetchthe valuesolution='final'(default).- With
param_defaults={'solution': 'first'}in the config, the same call givessolution='first'. dataset.fetch(flag, solution='first')givessolution='first'(keyword argument).dataset.fetch(flag, solution='best')raisesValueError.
Source code in src/mesqual/flag/dimension.py
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 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 | |
is_resolved_per_dataset
property
¶
is_resolved_per_dataset: bool
True if the values come from a function of the dataset.
values_for
¶
values_for(dataset: Dataset | None = None) -> Mapping[Hashable, str] | None
Return the allowed values with their descriptions.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
dataset
|
Dataset | None
|
Dataset that resolves values given as a function. |
None
|
Returns:
| Type | Description |
|---|---|
Mapping[Hashable, str] | None
|
The values, or |
Raises:
| Type | Description |
|---|---|
ValueError
|
The values are resolved per dataset and |
Source code in src/mesqual/flag/dimension.py
118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 | |
check_value
¶
check_value(value: Any, dataset: Dataset | None = None) -> None
Raise ValueError if value is not allowed or the values of the dimension are unavailable.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
value
|
Any
|
Value to check. |
required |
dataset
|
Dataset | None
|
Dataset that resolves values given as a function. |
None
|
A bool or numpy.bool_ matches only a bool or numpy.bool_
value, and a number matches only a number that is not a boolean. So False is not a value of a dimension
with the values 0 and 1.
Raises:
| Type | Description |
|---|---|
FlagUnavailableError
|
The values function fetches an unavailable flag. The reason names the dimension and that flag. |
ValueError
|
The value is not in |
Source code in src/mesqual/flag/dimension.py
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 | |
resolve
¶
resolve(given: Mapping[str, Any], dataset: Dataset | None = None) -> Any
Return the value of this parameter: the value in given, else default, then check it.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
given
|
Mapping[str, Any]
|
Given values by parameter name. Other names are ignored. |
required |
dataset
|
Dataset | None
|
Dataset that resolves values given as a function. With
|
None
|
Returns:
| Type | Description |
|---|---|
Any
|
The value. |
Raises:
| Type | Description |
|---|---|
FlagUnavailableError
|
The values function fetches an unavailable
flag, as in |
ValueError
|
|
Examples:
solution of the node price has the values 'first' and 'final', default 'final':
>>> solution = dataset.flag_index.get_spec('Node.Results.price').params[0]
>>> solution.resolve({})
'final'
>>> solution.resolve({'solution': 'first'})
'first'
Source code in src/mesqual/flag/dimension.py
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 208 209 210 211 212 | |
describe_value
¶
describe_value(value: Hashable, dataset: Dataset | None = None) -> str
Return the description of one value, or '' for an open parameter.
Source code in src/mesqual/flag/dimension.py
226 227 228 229 | |
same_as
¶
same_as(other: Dimension) -> bool
True if both have the same name, values and default.
Values given as a function compare by identity.
Source code in src/mesqual/flag/dimension.py
231 232 233 234 235 236 237 238 239 240 | |
VariantValues
¶
The variant values of one flag, with one attribute per dimension.
A wrong attribute raises AttributeError.
Examples:
>>> flow_spec = dataset.flag_index.get_spec('Line.Results.flow_sent_net')
>>> variant = flow_spec.variant_of('Line.Results.flow_sent_net')
>>> variant.side, variant.direction
('sent', 'net')
>>> variant.as_dict()
{'side': 'sent', 'direction': 'net'}
Source code in src/mesqual/flag/dimension.py
249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 | |
as_dict
¶
as_dict() -> dict[str, Hashable]
Return the values as a dict, dimension name to value.
Source code in src/mesqual/flag/dimension.py
277 278 279 | |
FrameSchema
dataclass
¶
Index and column levels of a flag result.
The number and order of the levels is fixed per spec.
Attributes:
| Name | Type | Description |
|---|---|---|
index |
tuple[Level, ...]
|
Levels of the row index. |
columns |
tuple[Level, ...]
|
Levels of the columns. Empty for a Series. A frame has at
least one column level, also when its column names are free,
for example |
dtype |
str | None
|
Optional dtype of the values. |
Examples:
>>> SPREAD_SCHEMA = FrameSchema(
... index=(Level('time', 'time'),),
... columns=(Level('Country', 'object'), Level('partner_country', 'counterpart')),
... )
Source code in src/mesqual/flag/schema.py
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 | |
Level
dataclass
¶
One index or column level of a result.
Attributes:
| Name | Type | Description |
|---|---|---|
name |
str | None
|
Name of the level. |
role |
str
|
Role of the level:
|
Source code in src/mesqual/flag/schema.py
9 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 | |
FlagSpec
dataclass
¶
Common fields of the base specs ModelFlagSpec, TimeSeriesFlagSpec and OtherFlagSpec.
Not used directly. The item type follows from the class.
A spec name is a flag name, or a template with one {placeholder} per
variant dimension. mesqual only fills in the placeholders; it never parses
flag names. Everything mesqual needs to know about a flag comes from the
fields of its spec.
Specs use identity for == and hash, because they can hold functions.
same_as compares the content.
Attributes:
| Name | Type | Description |
|---|---|---|
name |
str
|
Flag name, or a template with one |
description |
str
|
What the variable is, how it is computed, what to watch for. |
variants |
tuple[Dimension, ...]
|
Variant dimensions. Each value combination is a flag of its own. |
params |
tuple[Dimension, ...]
|
Parameter dimensions. A setting of the same flag, resolved at fetch. |
version |
int
|
Bump by hand when the logic changes. Part of the version identity. |
schema |
FrameSchema | Callable[[VariantValues], FrameSchema] | None
|
Index and column levels of the result, a function of the
variant values that returns them, or |
Source code in src/mesqual/flag/flag_spec.py
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 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 | |
schema
property
¶
schema: FrameSchema | Callable[[VariantValues], FrameSchema] | None
Index and column levels of the result. Each spec class overrides it.
Raises:
| Type | Description |
|---|---|
NotImplementedError
|
The spec class does not provide a schema. |
dimensions
property
¶
dimensions: tuple[Dimension, ...]
Variant and parameter dimensions, in this order.
expand
¶
expand(dataset: Dataset | None = None) -> list[str]
Return the flag names of this spec.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
dataset
|
Dataset | None
|
Dataset that resolves variant values given as a function. Not needed for a spec without such values. |
None
|
Returns:
| Type | Description |
|---|---|
list[str]
|
One flag name per combination of variant values. |
Raises:
| Type | Description |
|---|---|
ValueError
|
The spec is a flag family and |
Source code in src/mesqual/flag/flag_spec.py
85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 | |
static_flags
¶
static_flags() -> set[str]
The flags of the spec, or an empty set for a flag family, whose values need a dataset.
Source code in src/mesqual/flag/flag_spec.py
102 103 104 | |
covers
¶
covers(flag: Any) -> bool
True if flag is one of the flags of this spec.
For a flag family, the values of the family dimensions are not checked; that needs the dataset.
Source code in src/mesqual/flag/flag_spec.py
106 107 108 109 110 111 112 113 114 115 116 | |
variant_of
¶
variant_of(flag: Any) -> VariantValues
Return the variant values of a flag of this spec.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
flag
|
Any
|
A flag of this spec. |
required |
Returns:
| Type | Description |
|---|---|
VariantValues
|
One attribute per variant dimension. |
Raises:
| Type | Description |
|---|---|
KeyError
|
The spec does not cover the flag. |
Examples:
>>> flow_spec = dataset.flag_index.get_spec('Line.Results.flow_sent_net')
>>> flow_spec.variant_of('Line.Results.flow_sent_net').direction
'net'
Source code in src/mesqual/flag/flag_spec.py
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 | |
check_variant_values
¶
check_variant_values(flag: Any, dataset: Dataset | None = None) -> None
Raise ValueError if a family value of flag is not a value on dataset.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
flag
|
Any
|
A flag of this spec. |
required |
dataset
|
Dataset | None
|
Dataset that resolves the family values. |
None
|
Raises:
| Type | Description |
|---|---|
FlagUnavailableError
|
The values function of a variant fetches an
unavailable flag, as in |
ValueError
|
A family value is not a value on |
Source code in src/mesqual/flag/flag_spec.py
146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 | |
resolve_params
¶
resolve_params(given: Mapping[str, Any] | None = None, dataset: Dataset | None = None) -> dict[str, Any]
Return the resolved flag parameters: per parameter the given value, else its default, then the check.
Each parameter resolves with Dimension.resolve. A config default, for
example param_defaults of a dataset config, is not part of the spec:
the caller adds it to given. The variant values of a flag family are
checked with check_variant_values.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
given
|
Mapping[str, Any] | None
|
Given values by parameter name. |
None
|
dataset
|
Dataset | None
|
Dataset that resolves values given as a function. With
|
None
|
Returns:
| Type | Description |
|---|---|
dict[str, Any]
|
One value per parameter of the spec, in the order of |
Raises:
| Type | Description |
|---|---|
FlagUnavailableError
|
The values function of a parameter fetches
an unavailable flag, as in |
ValueError
|
|
Examples:
The node price has the parameter solution (values 'first' and
'final', default 'final'):
>>> price_spec = dataset.flag_index.get_spec('Node.Results.price')
>>> price_spec.resolve_params()
{'solution': 'final'}
>>> price_spec.resolve_params({'solution': 'first'})
{'solution': 'first'}
>>> price_spec.resolve_params({'solution': 'best'})
Traceback (most recent call last):
ValueError: 'best' is not a value of 'solution'. Allowed: ['first', 'final'].
>>> price_spec.resolve_params({'scenario': 'low'})
Traceback (most recent call last):
ValueError: Spec 'Node.Results.price' declares no parameters ['scenario']. Parameters: ['solution'].
Source code in src/mesqual/flag/flag_spec.py
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 208 | |
flag_description
¶
flag_description(flag: Any, dataset: Dataset | None = None) -> str
Return the description of one flag: the spec description and one line per variant.
Examples:
>>> flow_spec = dataset.flag_index.get_spec('Line.Results.flow_received_net')
>>> flow_spec.flag_description('Line.Results.flow_received_net')
'Power flow on the line. Side: where the flow leaves the line, after losses. Direction: up minus down.'
Source code in src/mesqual/flag/flag_spec.py
210 211 212 213 214 215 216 217 218 219 220 221 222 223 | |
same_as
¶
same_as(other: FlagSpec) -> bool
True if both specs declare the same thing.
Two specs are the same when their class, name, dimensions (names, values and defaults), version and the fields of their class are equal.
Source code in src/mesqual/flag/flag_spec.py
225 226 227 228 229 230 231 232 233 234 235 | |
class_for
classmethod
¶
class_for(item_type: ItemTypeEnum) -> type[FlagSpec]
Return the base spec class for an item type.
Examples:
>>> from mesqual.enums import ItemTypeEnum
>>> FlagSpec.class_for(ItemTypeEnum.Model)
<class 'mesqual.flag.flag_spec.ModelFlagSpec'>
Source code in src/mesqual/flag/flag_spec.py
237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 | |
declared_schema
¶
declared_schema(flag: Any) -> FrameSchema | None
Return the schema that the spec declares for a flag, or None for the default schema.
Source code in src/mesqual/flag/flag_spec.py
255 256 257 258 259 260 | |
ModelFlagSpec
dataclass
¶
Bases: FlagSpec
The model table of one object type: one row per object.
Attributes:
| Name | Type | Description |
|---|---|---|
index |
str
|
Name of the index level, for example |
topology_type |
TopologyTypeEnum
|
Role of the objects in the network topology. |
memberships |
Mapping[str, str]
|
Column to the model flag it refers to. The single source of object relations; mesqual does not detect them from column names. |
edge_ends |
tuple[str, str] | None
|
Topology type |
visualization_type |
VisualizationTypeEnum | None
|
|
Examples:
>>> from mesqual.enums import TopologyTypeEnum
>>> LINE_MODEL_SPEC = ModelFlagSpec(
... name='Line.Model',
... index='Line',
... topology_type=TopologyTypeEnum.Edge,
... description='Lines between two nodes.',
... memberships={'node_from': 'Node.Model', 'node_to': 'Node.Model'},
... edge_ends=('node_from', 'node_to'),
... )
Source code in src/mesqual/flag/flag_spec.py
346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 | |
schema
property
¶
schema: FrameSchema
The levels of the model table: one index level index with role object, one unnamed column level.
The columns are of several kinds, for example properties of the objects and memberships. No one name fits them all, so the level is unnamed.
Examples:
>>> dataset.flag_index.get_spec('Line.Model').schema
FrameSchema(index=(Level(name='Line', role='object'),), columns=(Level(name=None, role='dimension'),), dtype=None)
TimeSeriesFlagSpec
dataclass
¶
Bases: FlagSpec
A time series: one time index level, usually one column per object of model_flag.
The topology type and the column level come from the spec of the model flag.
Attributes:
| Name | Type | Description |
|---|---|---|
model_flag |
str | None
|
Linked model flag. |
unit |
Unit
|
Unit of the values. |
quantity_type |
QuantityTypeEnum | None
|
Set only for an ambiguous unit, and required there. Else the unit decides. |
schema |
FrameSchema | Callable[[VariantValues], FrameSchema] | None
|
Index and column levels of the result, or a function of the
variant values that returns them. |
fill_value |
float | None
|
Value for objects or rows that one side lacks, in sums and
comparisons. |
Examples:
>>> from mesqual.flag import Dimension
>>> from mesqual.units import Units
>>> NODE_SUPPLY_SPEC = TimeSeriesFlagSpec(
... name='Node.Results.supply_{fuel_type}',
... description='Supply at the node.',
... unit=Units.MW,
... model_flag='Node.Model',
... variants=(Dimension('fuel_type', 'Fuel type.', {'res': 'renewable sources', 'coal': 'coal', 'gas': 'gas'}),),
... fill_value=0,
... )
Source code in src/mesqual/flag/flag_spec.py
416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 | |
OtherFlagSpec
dataclass
¶
Bases: FlagSpec
Any other table, for example algorithm results per run.
Attributes:
| Name | Type | Description |
|---|---|---|
schema |
FrameSchema | Callable[[VariantValues], FrameSchema]
|
Index and column levels of the result, or a function of the variant values that returns them. Required. |
unit |
Unit | None
|
Optional unit of the values. |
Source code in src/mesqual/flag/flag_spec.py
485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 | |
AreaLayer
dataclass
¶
A grouping of the objects of one model flag into areas, for example nodes into countries.
The area of an object is the value of its membership column to layer_model.
The column name appears only in the memberships of the base_model spec.
Attributes:
| Name | Type | Description |
|---|---|---|
name |
str
|
Layer name, for example |
index |
str
|
Label of the object level, for example |
base_model |
str
|
Model flag of the grouped objects, for example |
layer_model |
str
|
Model flag of the areas, for example |
description |
str
|
What the areas are. |
Examples:
>>> REGION = AreaLayer(
... name='Region',
... index='Region',
... base_model='Node.Model',
... layer_model='Region.Model',
... description='Regions, each a group of nodes through the node column region.',
... )
Source code in src/mesqual/flag/layers.py
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 | |
BorderLayer
dataclass
¶
The borders between the areas of one area layer, with the edges that cross them.
The ends of an edge come from edge_ends of the edge_model spec. Both
ends must refer to the base_model of the area layer. A border joins two
areas; the two areas need not be geographic neighbours.
Attributes:
| Name | Type | Description |
|---|---|---|
name |
str
|
Layer name, for example |
index |
str
|
Label of the object level, for example |
area_layer |
str
|
Name of the area layer, for example |
edge_model |
str
|
Model flag of the edges that cross borders, for example |
description |
str
|
What the borders are. |
Source code in src/mesqual/flag/layers.py
46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 | |
LayerSet
¶
The area and border layers of a dataset, looked up by name.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
area_layers
|
Iterable[AreaLayer]
|
The area layers. |
()
|
border_layers
|
Iterable[BorderLayer]
|
The border layers. |
()
|
Raises:
| Type | Description |
|---|---|
AmbiguousOverrideError
|
Two layers have the same name. They would give the same flag names. |
ValueError
|
A border layer names an area layer that is not in the set. |
Source code in src/mesqual/flag/layers.py
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 | |
border_layers
property
¶
border_layers: tuple[BorderLayer, ...]
The border layers, in registration order.
union
classmethod
¶
Return one set with the layers of several sets.
Raises:
| Type | Description |
|---|---|
AmbiguousOverrideError
|
Two sets have different layers with the same name. They would give the same flag names. |
ValueError
|
A border layer names an area layer that is not in any set. |
Source code in src/mesqual/flag/layers.py
96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 | |
get
¶
get(name: str) -> AreaLayer | BorderLayer
Return the layer with this name.
Raises:
| Type | Description |
|---|---|
KeyError
|
No layer has this name. |
Source code in src/mesqual/flag/layers.py
126 127 128 129 130 131 132 133 134 135 | |
area_layer_of
¶
area_layer_of(border_layer: BorderLayer) -> AreaLayer
Return the area layer of a border layer.
Source code in src/mesqual/flag/layers.py
137 138 139 | |
LayerFlagSpec
dataclass
¶
Bases: FlagSpec
Common fields of AreaFlagSpec and BorderFlagSpec. Not used directly.
A layer spec names a base spec and an aggregation. Item type, unit,
quantity type and fill_value come from the base, the topology type
from the class.
The layer is a variant dimension named layer_placeholder, resolved per
dataset from the registered layers. The other variant dimensions are the
ones of the base, without consumes. params holds the base parameters
followed by the parameters of the aggregation (aggregation_params).
Attributes:
| Name | Type | Description |
|---|---|---|
base |
FlagSpec
|
The base spec. |
aggregation |
Any
|
The aggregation to the layer. |
model_flag |
str | None
|
Template of the linked model flag. |
schema |
FrameSchema | Callable[[VariantValues, AreaLayer | BorderLayer], FrameSchema] | None
|
Index and column levels of the result, or a function of the
variant values and the layer. |
consumes |
tuple[str, ...]
|
Variant dimensions of the base that the aggregation resolves itself. They are not in the spec name. |
layer_placeholder |
str
|
Name of the layer dimension and of its
placeholder in |
aggregation_params |
tuple[Dimension, ...]
|
Parameters of the aggregation, given as
|
Source code in src/mesqual/flag/layer_spec.py
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 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 | |
quantity_type
property
¶
quantity_type: QuantityTypeEnum | None
Quantity type of the base, set only for an ambiguous unit.
visualization_type
property
¶
visualization_type: None
None: the visualization type follows from the topology type.
is_model
property
¶
is_model: bool
True if the base is a model flag, so the layer flags are the layer model flags.
on_base
¶
on_base(base: FlagSpec) -> LayerFlagSpec
Return this spec built on another base: the parameters of base, then the aggregation parameters.
Source code in src/mesqual/flag/layer_spec.py
106 107 108 | |
layer_name_of
¶
layer_name_of(flag: Any) -> str
Return the layer name of a flag of this spec.
Source code in src/mesqual/flag/layer_spec.py
160 161 162 | |
expand_on_layers
¶
expand_on_layers(layer_names: Iterable[str]) -> list[str] | None
Return the flag names for the given layers, or None if another variant dimension needs a dataset.
Source code in src/mesqual/flag/layer_spec.py
164 165 166 167 168 169 170 | |
declared_schema
¶
declared_schema(flag: Any, layer: AreaLayer | BorderLayer | None = None) -> FrameSchema | None
Return the declared schema for a flag, or None for the default schema.
Raises:
| Type | Description |
|---|---|
ValueError
|
The schema is a function and |
Source code in src/mesqual/flag/layer_spec.py
172 173 174 175 176 177 178 179 180 181 182 | |
flag_description
¶
flag_description(flag: Any, dataset: Dataset | None = None) -> str
Return the description of one flag.
The spec description, the base description, the layer description (with a dataset only) and one line per other variant.
Source code in src/mesqual/flag/layer_spec.py
184 185 186 187 188 189 190 191 192 193 194 195 196 197 | |
same_as
¶
same_as(other: FlagSpec) -> bool
True if both specs declare the same thing.
The class, name, version, model_flag, consumes, layer_placeholder
and the aggregation parameters are equal, the base specs are the same
and the aggregations are equal (same type and fields).
Source code in src/mesqual/flag/layer_spec.py
199 200 201 202 203 204 205 206 207 208 209 210 211 | |
AreaFlagSpec
dataclass
¶
Bases: LayerFlagSpec
A variable on area layers: a base spec and an area aggregation.
The base is a node or node-connected spec (a model spec with topology
type Node or NodeConnectedElement, or a time series spec on such a
model), or a border spec. On a node base, the layers are the area layers
whose base_model is the model flag of the base. On a border base, the
layers are the area layers with exactly one border layer among the
layers of the base. FlagIndex.check_references checks the topology
type of the base model.
Attributes:
| Name | Type | Description |
|---|---|---|
aggregation |
AreaAggregation
|
An |
layer_placeholder |
str
|
Name of the layer dimension. Default |
Examples:
>>> from mesqual.layer_flags import WeightedMean
>>> AREA_PRICE_SPEC = AreaFlagSpec(
... name='{area_layer}.Results.price',
... base=dataset.flag_index.get_spec('Node.Results.price'),
... aggregation=WeightedMean(weight='Node.Results.demand_total'),
... description='Mean of the node prices of the area, weighted by the total node demand.',
... )
Source code in src/mesqual/flag/layer_spec.py
221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 | |
BorderFlagSpec
dataclass
¶
Bases: LayerFlagSpec
A variable on border layers: a base spec and a border aggregation.
The base is an edge spec (a model spec with topology type Edge, or a
time series spec on such a model), or an area spec. On an edge base,
the layers are the border layers whose edge_model is the model flag of
the base. On an area base, the layers are the border layers whose area
layer is a layer of the base. FlagIndex.check_references checks the
topology type of the base model.
Attributes:
| Name | Type | Description |
|---|---|---|
aggregation |
BorderAggregation
|
A |
layer_placeholder |
str
|
Name of the layer dimension. Default |
Examples:
>>> from mesqual.layer_flags import BorderFlowSum
>>> BORDER_FLOW_SPEC = BorderFlagSpec(
... name='{border_layer}.Results.flow_{side}_{direction}',
... base=dataset.flag_index.get_spec('Line.Results.flow_sent_net'),
... aggregation=BorderFlowSum(),
... description='Sum of the line flows across the border, in border direction.',
... )
Source code in src/mesqual/flag/layer_spec.py
263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 | |
LayerVariantValues
¶
Bases: VariantValues
Variant values of a layer flag, as an aggregation gets them.
Besides the variant values of the flag, it holds the layer placeholder
of the base for an area spec on a border base (border_layer) and for a
border spec on an area base (area_layer). base_flag builds base flag
names, so an aggregation never needs the flag grammar of the platform.
FlagIndex.get_layer_variant builds it.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
values
|
Mapping[str, Hashable]
|
The variant values, with the layer of the base. |
required |
base_name
|
str
|
The name of the base spec. |
required |
Examples:
>>> variant = dataset.flag_index.get_layer_variant('CountryBorder.Results.flow_sent_up')
>>> variant.direction
'up'
>>> variant.base_flag(direction='down')
'Line.Results.flow_sent_down'
Source code in src/mesqual/flag/layer_spec.py
342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 | |
base_flag
¶
base_flag(**changes: Hashable) -> str
Return the base flag for these variant values, with some values changed.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
**changes
|
Hashable
|
Values of base dimensions to change, and the values of the dimensions that the spec consumes. |
{}
|
Raises:
| Type | Description |
|---|---|
ValueError
|
A dimension of the base name has no value. |
Source code in src/mesqual/flag/layer_spec.py
369 370 371 372 373 374 375 376 377 378 379 380 381 382 | |
FlagIndex
¶
Lookup from a flag name to its flag spec, and the getters that read the spec.
The flag index has no implicit rules: every answer comes from a spec. A
flag without a spec raises UnknownFlagError, a subclass of KeyError
and ValueError.
A dataset builds its flag index from its flag_specs; a platform dataset
collects the specs of all its interpreters and its area and border
layers; a collection uses the union of the indexes of its children.
The flags of a layer spec (AreaFlagSpec, BorderFlagSpec) come from
the layers of the index: one flag per matching layer and variant value.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
specs
|
Iterable[FlagSpec]
|
Specs to add. |
()
|
layers
|
LayerSet
|
The area and border layers. |
LayerSet()
|
Raises:
| Type | Description |
|---|---|
AmbiguousOverrideError
|
Two specs give the same flag name. |
Examples:
>>> index = FlagIndex([dataset.flag_index.get_spec(flag) for flag in ('Node.Model', 'Node.Results.price')])
>>> print(index.get_unit('Node.Results.price'))
EUR_per_MWh
>>> index.get_topology_type('Node.Results.price')
<TopologyTypeEnum.Node: 'Node'>
Source code in src/mesqual/flag/flag_index.py
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 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 | |
static_flags
property
¶
static_flags: set[str]
Flag names of all specs except the flag families, whose values need a dataset.
parameter_names
property
¶
parameter_names: set[str]
Names of all parameters that a spec of this index declares.
union
classmethod
¶
Build one index with the specs and layers of several indexes.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
indexes
|
Iterable[FlagIndex]
|
The indexes to combine. |
required |
Returns:
| Type | Description |
|---|---|
FlagIndex
|
A new index. |
Raises:
| Type | Description |
|---|---|
ValueError
|
Two indexes have specs with the same name that are not
the same ( |
AmbiguousOverrideError
|
Two indexes have different layers with the same name. |
Source code in src/mesqual/flag/flag_index.py
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 | |
add_spec
¶
add_spec(spec: FlagSpec) -> None
Add a spec.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
spec
|
FlagSpec
|
The spec to add. |
required |
Raises:
| Type | Description |
|---|---|
AmbiguousOverrideError
|
Another spec gives one of the flag names. |
Source code in src/mesqual/flag/flag_index.py
104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 | |
static_flags_of
¶
static_flags_of(spec: FlagSpec) -> list[str] | None
Return the flags of a spec, or None for a flag family whose values need a dataset.
The flags of a layer spec come from the layers of this index.
Source code in src/mesqual/flag/flag_index.py
123 124 125 126 127 128 129 130 | |
register_new_flag
¶
register_new_flag(flag: str, item_type: ItemTypeEnum, description: str = '', **fields: Any) -> FlagSpec
Build a base spec of the class for item_type and add it.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
flag
|
str
|
Flag name. |
required |
item_type
|
ItemTypeEnum
|
Item type; selects |
required |
description
|
str
|
Description of the flag. |
''
|
**fields
|
Any
|
Further fields of the spec class, for example |
{}
|
Returns:
| Type | Description |
|---|---|
FlagSpec
|
The new spec. |
Examples:
>>> from mesqual.enums import ItemTypeEnum, TopologyTypeEnum
>>> index = FlagIndex([dataset.flag_index.get_spec('Node.Model')])
>>> spec = index.register_new_flag(
... 'Generator.Model', ItemTypeEnum.Model, 'Generators.',
... index='Generator', topology_type=TopologyTypeEnum.NodeConnectedElement,
... memberships={'node': 'Node.Model'},
... )
Source code in src/mesqual/flag/flag_index.py
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 | |
get_spec_by_name
¶
get_spec_by_name(name: str) -> FlagSpec | None
Return the spec with this name (a flag name or a template), or None.
Source code in src/mesqual/flag/flag_index.py
167 168 169 | |
has_spec
¶
has_spec(flag: Any) -> bool
True if a spec declares the flag.
Source code in src/mesqual/flag/flag_index.py
171 172 173 174 175 176 177 | |
get_spec
¶
get_spec(flag: Any) -> FlagSpec
Return the spec that declares the flag.
Raises:
| Type | Description |
|---|---|
UnknownFlagError
|
No spec declares the flag. |
AmbiguousOverrideError
|
Two flag family specs cover the flag. |
Source code in src/mesqual/flag/flag_index.py
179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 | |
check_references
¶
check_references(dataset: Dataset | None = None) -> None
Check the references between the specs and layers of this index.
- Each area layer has exactly one membership of its
base_modelto itslayer_model(get_mapping_column). - The edge model of each border layer has
edge_endsthat refer to the base model of its area layer (get_edge_ends). - The base model of each layer spec is a
ModelFlagSpecwith a topology type that fits the spec class:NodeorNodeConnectedElementfor an area spec,Edgefor a border spec. - Each
model_flagof a time series or layer spec names a model spec: aModelFlagSpec, or a layer spec on a model base (a layer model flag). Amodel_flagtemplate is checked for each flag of the spec. The template of a flag family is checked only with adatasetthat gives the family values.
A platform dataset and a link collection run the check at construction, on their full index. Any other dataset runs it in its outermost fetch. Without a dataset, the result is kept until a spec is added.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
dataset
|
Dataset | None
|
The dataset that gives the values of the flag families. |
None
|
Raises:
| Type | Description |
|---|---|
ValueError
|
A reference is not valid. |
Source code in src/mesqual/flag/flag_index.py
204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 | |
get_item_type
¶
get_item_type(flag: Any) -> ItemTypeEnum
Return the item type of a flag. It follows from the class of its spec, or from the base of a layer spec.
Source code in src/mesqual/flag/flag_index.py
290 291 292 | |
get_model_spec
¶
get_model_spec(flag: Any) -> FlagSpec | None
Return the model spec of a flag: its own spec for a model flag, the spec of its model flag for a
time series flag, else None.
The model spec is a ModelFlagSpec, or a layer spec on a model base.
Source code in src/mesqual/flag/flag_index.py
294 295 296 297 298 299 300 301 | |
get_linked_model_flag
¶
get_linked_model_flag(flag: Any) -> str | None
Return the model flag of a flag.
A model flag returns itself, a time series flag its model_flag
(can be None), any other flag None. A model_flag template is
filled with the variant values of the flag, for example
'{area_layer}.Model' gives 'Country.Model'.
A layer flag on a model base returns itself. Any other layer
flag returns its filled model_flag, else the layer model flag:
layer_model of an area layer, or the flag of the border spec on
a model base for a border layer (None if no such spec exists).
Source code in src/mesqual/flag/flag_index.py
303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 | |
get_unit
¶
get_unit(flag: Any) -> Unit | None
Return the unit of a flag from its spec. A model flag has no unit (None).
Source code in src/mesqual/flag/flag_index.py
327 328 329 | |
get_fill_value
¶
get_fill_value(flag: Any) -> float | None
Return the fill_value of a flag from its spec, None if the spec has none.
Source code in src/mesqual/flag/flag_index.py
331 332 333 | |
get_quantity_type_enum
¶
get_quantity_type_enum(flag: Any) -> QuantityTypeEnum
Return the quantity type of a flag.
The spec value for an ambiguous unit, else the type of the unit.
UNKNOWN for a flag without unit.
Source code in src/mesqual/flag/flag_index.py
335 336 337 338 339 340 341 342 343 344 345 346 | |
get_topology_type
¶
get_topology_type(flag: Any) -> TopologyTypeEnum
Return the topology type of a flag.
A model spec declares it; a time series spec takes it from the spec of
its model flag; a layer spec has Area or Border from its class;
any other flag, and a time series without model flag, has Other.
Source code in src/mesqual/flag/flag_index.py
348 349 350 351 352 353 354 355 356 357 358 359 | |
get_visualization_type
¶
get_visualization_type(flag: Any) -> VisualizationTypeEnum
Return the visualization type: the one of the model spec, else the one of the topology type.
Source code in src/mesqual/flag/flag_index.py
361 362 363 364 365 366 367 | |
get_schema
¶
get_schema(flag: Any) -> FrameSchema
Return the index and column levels of the result of a flag.
A spec schema wins. A model spec always has its schema
(ModelFlagSpec.schema). Default for a time series spec: one index level
time with role time and one column level, the object level of its
model flag, with role object. Default for a layer spec: the schema
of the base flag with the object level renamed to the index of the layer.
Raises:
| Type | Description |
|---|---|
ValueError
|
A time series schema without exactly one time level. |
Source code in src/mesqual/flag/flag_index.py
369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 | |
get_base_flag
¶
get_base_flag(flag: Any) -> str
Return the base flag of a layer flag. A consumed dimension takes its first value.
Raises:
| Type | Description |
|---|---|
ValueError
|
The flag is not a layer flag, or a consumed dimension has values resolved per dataset. |
Source code in src/mesqual/flag/flag_index.py
408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 | |
get_layer_variant
¶
get_layer_variant(flag: Any) -> LayerVariantValues
Return the variant values of a layer flag, with the layer of its base flag.
For an area spec on a border base, the values also hold the border
layer of the base (border_layer); for a border spec on an area
base, the area layer of the base (area_layer).
Raises:
| Type | Description |
|---|---|
ValueError
|
The flag is not a layer flag. |
Source code in src/mesqual/flag/flag_index.py
427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 | |
get_object_level
¶
get_object_level(model_flag: Any) -> str
Return the label of the object level of a model flag.
The index of a ModelFlagSpec, or the index of the layer of a
layer model flag.
Source code in src/mesqual/flag/flag_index.py
450 451 452 453 454 455 456 457 458 459 | |
get_memberships
¶
get_memberships(model_flag: Any) -> dict[str, str]
Return the membership columns of a model flag: column to the model flag it refers to.
Raises:
| Type | Description |
|---|---|
ValueError
|
The flag is not declared by a |
Source code in src/mesqual/flag/flag_index.py
461 462 463 464 465 466 467 468 469 470 | |
get_referencing_columns
¶
get_referencing_columns(model_flag: Any) -> list[tuple[str, str]]
Return all (model flag, column) pairs whose membership refers to model_flag.
Examples:
>>> dataset.flag_index.get_referencing_columns('Node.Model')
[('Line.Model', 'node_from'), ('Line.Model', 'node_to'), ('Generator.Model', 'node'), ('Demand.Model', 'node')]
Source code in src/mesqual/flag/flag_index.py
472 473 474 475 476 477 478 479 480 481 482 483 484 485 | |
get_mapping_column
¶
get_mapping_column(layer: AreaLayer) -> str
Return the membership column of layer.base_model whose target is layer.layer_model.
Raises:
| Type | Description |
|---|---|
ValueError
|
The base model has no |
Source code in src/mesqual/flag/flag_index.py
487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 | |
get_edge_ends
¶
get_edge_ends(layer: BorderLayer) -> tuple[str, str]
Return the edge_ends of the edge model of a border layer.
Raises:
| Type | Description |
|---|---|
ValueError
|
The edge model has no |
Source code in src/mesqual/flag/flag_index.py
504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 | |
get_layers
¶
get_layers(spec: FlagSpec) -> list[AreaLayer | BorderLayer]
Return the layers of a layer spec. Any other spec has none.
AreaFlagSpecon a node base: the area layers whosebase_modelis the model flag of the base.AreaFlagSpecon a border base: the area layers with exactly one border layer among the layers of the base.BorderFlagSpecon an edge base: the border layers whoseedge_modelis the model flag of the base.BorderFlagSpecon an area base: the border layers whose area layer is a layer of the base.
Raises:
| Type | Description |
|---|---|
ValueError
|
An area layer has two border layers among the layers of a border base. |
Source code in src/mesqual/flag/flag_index.py
522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 | |
get_layer
¶
get_layer(flag: Any) -> AreaLayer | BorderLayer
Return the layer of a layer flag.
Raises:
| Type | Description |
|---|---|
ValueError
|
The flag is not a layer flag. |
Source code in src/mesqual/flag/flag_index.py
563 564 565 566 567 568 569 | |
get_base_layer
¶
get_base_layer(spec: LayerFlagSpec, layer: AreaLayer | BorderLayer) -> AreaLayer | BorderLayer | None
Return the layer of the base flag of a layer flag on layer.
The border layer of an area layer for an area spec on a border base,
the area layer of a border layer for a border spec on an area base,
else None.
Source code in src/mesqual/flag/flag_index.py
571 572 573 574 575 576 577 578 579 580 581 582 | |
get_layer_model_flag
¶
get_layer_model_flag(layer: AreaLayer | BorderLayer) -> str | None
Return the model flag of the areas or borders of a layer.
layer_model of an area layer. For a border layer, the flag of the
border spec on a model base (for example BorderModel()) on that
layer, or None if the index has no such spec.
Source code in src/mesqual/flag/flag_index.py
584 585 586 587 588 589 590 591 592 593 | |
get_all_timeseries_flags_for_model_flag
¶
get_all_timeseries_flags_for_model_flag(dataset: Dataset, flag: Any) -> set[str]
Return the accepted time series flags of dataset whose model flag is flag.
Source code in src/mesqual/flag/flag_index.py
601 602 603 604 605 606 607 | |
get_flag_from_string
¶
get_flag_from_string(flag_string: str) -> str
Return the flag for a string. Flags are strings.
Source code in src/mesqual/flag/flag_index.py
609 610 611 | |
UnknownFlagError
¶
Bases: KeyError, ValueError
Raised when no flag spec declares a flag.
A subclass of both KeyError and ValueError, so code that catches either keeps working.
Source code in src/mesqual/flag/exceptions.py
4 5 6 7 8 9 10 11 | |
AmbiguousOverrideError
¶
Bases: ValueError
Raised when more than one interpreter, override or spec claims the same flag or interpreter.
Two overrides of one interpreter on one class or on sibling classes, two answering interpreters with one spec name, or two specs that give one flag name raise this error.
Source code in src/mesqual/flag/exceptions.py
14 15 16 17 18 19 20 | |
FlagUnavailableError
¶
Bases: ValueError
A flag is not available on a dataset.
fetch raises it for an accepted flag whose availability is False. It
is a subclass of ValueError. Dimension.check_value raises it when the
values function of a flag family fetches an unavailable flag. For the
values of such a family, see Dimension.values_for.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
flag
|
str
|
The flag. |
required |
dataset
|
str
|
The name of the dataset. |
required |
reason
|
str
|
Why the flag is not available, as in |
required |
Attributes:
| Name | Type | Description |
|---|---|---|
flag |
The flag. |
|
dataset |
The name of the dataset. |
|
reason |
Why the flag is not available. |
Source code in src/mesqual/flag/exceptions.py
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 | |
area_flag_specs
¶
area_flag_specs(bases: Iterable[FlagSpec], aggregation: AreaAggregation, name: Callable[[FlagSpec], str], description: str | Callable[[FlagSpec], str], **fields: Any) -> tuple[AreaFlagSpec, ...]
Build one AreaFlagSpec per base spec with the same aggregation.
The platform still lists the result explicitly on an interpreter.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
bases
|
Iterable[FlagSpec]
|
The base specs. |
required |
aggregation
|
AreaAggregation
|
The area aggregation of all specs. |
required |
name
|
Callable[[FlagSpec], str]
|
Function of the base spec that returns the name of the area spec. |
required |
description
|
str | Callable[[FlagSpec], str]
|
Description of all specs, or a function of the base spec. |
required |
**fields
|
Any
|
Further fields of |
{}
|
Examples:
>>> from mesqual.layer_flags import Sum
>>> AREA_SUM_SPECS = area_flag_specs(
... bases=tuple(dataset.flag_index.get_spec(flag) for flag in ('Node.Results.demand_total', 'Node.Results.generation_gas')),
... aggregation=Sum(),
... name=lambda base: base.name.replace('Node.', '{area_layer}.'),
... description='Sum over the nodes of the area.',
... )
>>> [spec.name for spec in AREA_SUM_SPECS]
['{area_layer}.Results.demand_{product}', '{area_layer}.Results.generation_{fuel}']
Source code in src/mesqual/flag/layer_spec.py
301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 | |