Skip to content

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
class FlagTypeProtocol(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.
    """

    def __hash__(self) -> int:
        """Return stable hash value for use as dictionary key."""
        ...

    def __str__(self) -> str:
        """Return human-readable string representation."""
        ...

__hash__

__hash__() -> int

Return stable hash value for use as dictionary key.

Source code in src/mesqual/flag/flag.py
18
19
20
def __hash__(self) -> int:
    """Return stable hash value for use as dictionary key."""
    ...

__str__

__str__() -> str

Return human-readable string representation.

Source code in src/mesqual/flag/flag.py
22
23
24
def __str__(self) -> str:
    """Return human-readable string representation."""
    ...

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 of fetch.
  • Dataset.fetch_params: a dataset parameter. It is a setting of every fetch of that dataset class, for example comparison_type of 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 fetch.

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. None: parameters only, any value that validate accepts.

default Any

Parameters only. REQUIRED: the caller or the config must give a value.

validate Callable[[Any], None] | None

Parameters only. Raises ValueError for an invalid value, for open value sets.

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 _fetch the value solution='final' (default).
  • With param_defaults={'solution': 'first'} in the config, the same call gives solution='first'.
  • dataset.fetch(flag, solution='first') gives solution='first' (keyword argument).
  • dataset.fetch(flag, solution='best') raises ValueError.
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
@dataclass(frozen=True)
class Dimension:
    """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 of `fetch`.
    - `Dataset.fetch_params`: a dataset parameter. It is a setting of every
      fetch of that dataset class, for example `comparison_type` of 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: Name of the dimension. For a variant, also the placeholder in
            the flag name. For a parameter, the keyword argument of `fetch`.
        description: What the dimension selects.
        values: 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. `None`:
            parameters only, any value that `validate` accepts.
        default: Parameters only. `REQUIRED`: the caller or the config must
            give a value.
        validate: Parameters only. Raises `ValueError` for an invalid value,
            for open value sets.

    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 `_fetch` the value `solution='final'` (default).
        - With `param_defaults={'solution': 'first'}` in the config, the same
          call gives `solution='first'`.
        - `dataset.fetch(flag, solution='first')` gives `solution='first'`
          (keyword argument).
        - `dataset.fetch(flag, solution='best')` raises `ValueError`.
    """

    name: str
    description: str
    values: Mapping[Hashable, str] | Callable[[Dataset], Mapping[Hashable, str]] | None = None
    default: Any = REQUIRED
    validate: Callable[[Any], None] | None = None

    def __post_init__(self):
        if isinstance(self.values, Mapping):
            object.__setattr__(self, 'values', MappingProxyType(dict(self.values)))
        elif self.values is not None and not callable(self.values):
            raise TypeError(f'Dimension {self.name!r}: values must be a mapping, a function or None.')

    @property
    def is_resolved_per_dataset(self) -> bool:
        """`True` if the values come from a function of the dataset."""
        return self.values is not None and not isinstance(self.values, Mapping)

    @property
    def has_default(self) -> bool:
        """`True` if the dimension has a default value."""
        return self.default is not REQUIRED

    def values_for(self, dataset: Dataset | None = None) -> Mapping[Hashable, str] | None:
        """Return the allowed values with their descriptions.

        Args:
            dataset: Dataset that resolves values given as a function.

        Returns:
            The values, or `None` for an open parameter. No values if the
                values function fetches a flag that is not available on
                `dataset` (`FlagUnavailableError`).

        Raises:
            ValueError: The values are resolved per dataset and `dataset` is `None`.
        """
        return self._values_and_unavailable_error(dataset)[0]

    def _values_and_unavailable_error(
        self,
        dataset: Dataset | None,
    ) -> tuple[Mapping[Hashable, str] | None, FlagUnavailableError | None]:
        """The values, and the `FlagUnavailableError` that left them empty, else `None`."""
        if not self.is_resolved_per_dataset:
            return self.values, None
        if dataset is None:
            raise ValueError(f'Dimension {self.name!r} is resolved per dataset. Pass a dataset.')
        try:
            return MappingProxyType(dict(self.values(dataset))), None
        except FlagUnavailableError as error:
            logger.debug('Values of %r are empty on %s: %s', self.name, dataset.name, error)
            return MappingProxyType({}), error

    def check_value(self, value: Any, dataset: Dataset | None = None) -> None:
        """Raise `ValueError` if `value` is not allowed or the values of the dimension are unavailable.

        Args:
            value: Value to check.
            dataset: Dataset that resolves values given as a function.

        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:
            FlagUnavailableError: The values function fetches an unavailable
                flag. The reason names the dimension and that flag.
            ValueError: The value is not in `values`, or `validate` rejects it.
        """
        values, unavailable_error = self._values_and_unavailable_error(dataset)
        if unavailable_error is not None:
            reason = (
                f'values of {self.name!r} need the unavailable flag {unavailable_error.flag}: '
                f'{unavailable_error.reason}'
            )
            raise FlagUnavailableError(unavailable_error.flag, unavailable_error.dataset, reason) from unavailable_error
        if values is not None and not self._is_one_of(value, values):
            raise ValueError(f'{value!r} is not a value of {self.name!r}. Allowed: {list(values)}.')
        if self.validate is not None:
            self.validate(value)

    def resolve(self, given: Mapping[str, Any], dataset: Dataset | None = None) -> Any:
        """Return the value of this parameter: the value in `given`, else `default`, then check it.

        Args:
            given: Given values by parameter name. Other names are ignored.
            dataset: Dataset that resolves values given as a function. With
                `None` and such values, neither the values nor `validate`
                are checked.

        Returns:
            The value.

        Raises:
            FlagUnavailableError: The values function fetches an unavailable
                flag, as in `check_value`.
            ValueError: `given` has no value and the default is `REQUIRED`, or
                `check_value` rejects the value.

        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'
        """
        if self.name in given:
            value = given[self.name]
        elif self.has_default:
            value = self.default
        else:
            raise ValueError(f'parameter {self.name!r} is required.')
        if dataset is not None or not self.is_resolved_per_dataset:
            self.check_value(value, dataset)
        return value

    @staticmethod
    def _is_one_of(value: Any, values: Mapping[Hashable, str]) -> bool:
        if value not in values:
            return False
        if not (Dimension._is_bool(value) or value in (0, 1)):
            return True
        return any(v == value and Dimension._is_bool(v) == Dimension._is_bool(value) for v in values)

    @staticmethod
    def _is_bool(value: Any) -> bool:
        return isinstance(value, (bool, np.bool_))

    def describe_value(self, value: Hashable, dataset: Dataset | None = None) -> str:
        """Return the description of one value, or `''` for an open parameter."""
        values = self.values_for(dataset)
        return '' if values is None else values[value]

    def same_as(self, other: Dimension) -> bool:
        """`True` if both have the same name, values and default.

        Values given as a function compare by identity.
        """
        return (
            self.name == other.name
            and self._comparable(self.values) == self._comparable(other.values)
            and self.default == other.default
        )

    @staticmethod
    def _comparable(values: Any) -> Any:
        if isinstance(values, Mapping):
            return tuple(values.items())
        return id(values) if values is not None else None

is_resolved_per_dataset property

is_resolved_per_dataset: bool

True if the values come from a function of the dataset.

has_default property

has_default: bool

True if the dimension has a default value.

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 None for an open parameter. No values if the values function fetches a flag that is not available on dataset (FlagUnavailableError).

Raises:

Type Description
ValueError

The values are resolved per dataset and dataset is None.

Source code in src/mesqual/flag/dimension.py
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
def values_for(self, dataset: Dataset | None = None) -> Mapping[Hashable, str] | None:
    """Return the allowed values with their descriptions.

    Args:
        dataset: Dataset that resolves values given as a function.

    Returns:
        The values, or `None` for an open parameter. No values if the
            values function fetches a flag that is not available on
            `dataset` (`FlagUnavailableError`).

    Raises:
        ValueError: The values are resolved per dataset and `dataset` is `None`.
    """
    return self._values_and_unavailable_error(dataset)[0]

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 values, or validate rejects it.

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
def check_value(self, value: Any, dataset: Dataset | None = None) -> None:
    """Raise `ValueError` if `value` is not allowed or the values of the dimension are unavailable.

    Args:
        value: Value to check.
        dataset: Dataset that resolves values given as a function.

    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:
        FlagUnavailableError: The values function fetches an unavailable
            flag. The reason names the dimension and that flag.
        ValueError: The value is not in `values`, or `validate` rejects it.
    """
    values, unavailable_error = self._values_and_unavailable_error(dataset)
    if unavailable_error is not None:
        reason = (
            f'values of {self.name!r} need the unavailable flag {unavailable_error.flag}: '
            f'{unavailable_error.reason}'
        )
        raise FlagUnavailableError(unavailable_error.flag, unavailable_error.dataset, reason) from unavailable_error
    if values is not None and not self._is_one_of(value, values):
        raise ValueError(f'{value!r} is not a value of {self.name!r}. Allowed: {list(values)}.')
    if self.validate is not None:
        self.validate(value)

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 and such values, neither the values nor validate are checked.

None

Returns:

Type Description
Any

The value.

Raises:

Type Description
FlagUnavailableError

The values function fetches an unavailable flag, as in check_value.

ValueError

given has no value and the default is REQUIRED, or check_value rejects the value.

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
def resolve(self, given: Mapping[str, Any], dataset: Dataset | None = None) -> Any:
    """Return the value of this parameter: the value in `given`, else `default`, then check it.

    Args:
        given: Given values by parameter name. Other names are ignored.
        dataset: Dataset that resolves values given as a function. With
            `None` and such values, neither the values nor `validate`
            are checked.

    Returns:
        The value.

    Raises:
        FlagUnavailableError: The values function fetches an unavailable
            flag, as in `check_value`.
        ValueError: `given` has no value and the default is `REQUIRED`, or
            `check_value` rejects the value.

    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'
    """
    if self.name in given:
        value = given[self.name]
    elif self.has_default:
        value = self.default
    else:
        raise ValueError(f'parameter {self.name!r} is required.')
    if dataset is not None or not self.is_resolved_per_dataset:
        self.check_value(value, dataset)
    return value

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
def describe_value(self, value: Hashable, dataset: Dataset | None = None) -> str:
    """Return the description of one value, or `''` for an open parameter."""
    values = self.values_for(dataset)
    return '' if values is None else values[value]

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
def same_as(self, other: Dimension) -> bool:
    """`True` if both have the same name, values and default.

    Values given as a function compare by identity.
    """
    return (
        self.name == other.name
        and self._comparable(self.values) == self._comparable(other.values)
        and self.default == other.default
    )

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
class 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'}
    """

    __slots__ = ('_values',)

    def __init__(self, values: Mapping[str, Hashable]):
        object.__setattr__(self, '_values', dict(values))

    def __getattr__(self, name: str) -> Hashable:
        try:
            return self._values[name]
        except KeyError:
            raise AttributeError(f'No variant dimension {name!r}. Dimensions: {list(self._values)}.') from None

    def __setattr__(self, name: str, value: Any) -> None:
        raise AttributeError('VariantValues is read-only.')

    def as_dict(self) -> dict[str, Hashable]:
        """Return the values as a dict, dimension name to value."""
        return dict(self._values)

    def __eq__(self, other: object) -> bool:
        return isinstance(other, VariantValues) and self._values == other._values

    def __hash__(self) -> int:
        return hash(tuple(self._values.items()))

    def __repr__(self) -> str:
        return f'VariantValues({", ".join(f"{k}={v!r}" for k, v in self._values.items())})'

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
def as_dict(self) -> dict[str, Hashable]:
    """Return the values as a dict, dimension name to value."""
    return dict(self._values)

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 Level(None, 'dimension') of a model table.

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
@dataclass(frozen=True)
class FrameSchema:
    """Index and column levels of a flag result.

    The number and order of the levels is fixed per spec.

    Attributes:
        index: Levels of the row index.
        columns: 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 `Level(None, 'dimension')` of a model table.
        dtype: Optional dtype of the values.

    Examples:
        >>> SPREAD_SCHEMA = FrameSchema(
        ...     index=(Level('time', 'time'),),
        ...     columns=(Level('Country', 'object'), Level('partner_country', 'counterpart')),
        ... )
    """

    index: tuple[Level, ...]
    columns: tuple[Level, ...] = ()
    dtype: str | None = None

    def __post_init__(self):
        object.__setattr__(self, 'index', tuple(self.index))
        object.__setattr__(self, 'columns', tuple(self.columns))
        for level in self.index + self.columns:
            if not isinstance(level, Level):
                raise TypeError(f'Schema levels must be of type Level, got {level!r}.')

    @property
    def time_levels(self) -> tuple[Level, ...]:
        """The index levels with role `time`."""
        return tuple(level for level in self.index if level.role == 'time')

    def __str__(self) -> str:
        text = f'index ({", ".join(map(str, self.index))})'
        if self.columns:
            text += f', columns ({", ".join(map(str, self.columns))})'
        return text

time_levels property

time_levels: tuple[Level, ...]

The index levels with role time.

Level dataclass

One index or column level of a result.

Attributes:

Name Type Description
name str | None

Name of the level. None: the level is unnamed, as in pandas.

role str

Role of the level:

  • time: the time level.
  • object: the ids (names or numbers) of the objects of the flag.
  • counterpart: a second object of the same or another type that each value relates to, for example the partner area of a trade.
  • object_from, object_to: the two ends of an edge.
  • dimension: any other categorical level.
  • dataset: added by collections.
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
@dataclass(frozen=True)
class Level:
    """One index or column level of a result.

    Attributes:
        name: Name of the level. `None`: the level is unnamed, as in pandas.
        role: Role of the level:

            - `time`: the time level.
            - `object`: the ids (names or numbers) of the objects of the flag.
            - `counterpart`: a second object of the same or another type that
              each value relates to, for example the partner area of a trade.
            - `object_from`, `object_to`: the two ends of an edge.
            - `dimension`: any other categorical level.
            - `dataset`: added by collections.
    """

    ROLES: ClassVar[frozenset[str]] = frozenset(
        {'time', 'object', 'counterpart', 'object_from', 'object_to', 'dimension', 'dataset'}
    )

    name: str | None
    role: str

    def __post_init__(self):
        if self.role not in self.ROLES:
            raise ValueError(f'Level {self.name!r}: unknown role {self.role!r}. Roles: {sorted(self.ROLES)}.')

    def __str__(self) -> str:
        return f'{self.name}: {self.role}'

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 {placeholder} per variant dimension.

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 None for the default schema. Every spec class provides it, as a field or as a read-only property.

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
@dataclass(frozen=True, eq=False)
class FlagSpec:
    """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: Flag name, or a template with one `{placeholder}` per variant dimension.
        description: What the variable is, how it is computed, what to watch for.
        variants: Variant dimensions. Each value combination is a flag of its own.
        params: Parameter dimensions. A setting of the same flag, resolved at fetch.
        version: Bump by hand when the logic changes. Part of the version identity.
        schema: Index and column levels of the result, a function of the
            variant values that returns them, or `None` for the default
            schema. Every spec class provides it, as a field or as a
            read-only property.
    """

    item_type: ClassVar[ItemTypeEnum]

    name: str
    description: str
    variants: tuple[Dimension, ...] = ()
    params: tuple[Dimension, ...] = ()
    version: int = 1

    def __post_init__(self):
        object.__setattr__(self, 'variants', tuple(self.variants))
        object.__setattr__(self, 'params', tuple(self.params))
        self._check_required_fields()
        self._check_dimensions()
        self._check_placeholders()
        if not self.is_family:
            _ = self._variants_by_flag

    @property
    def schema(self) -> FrameSchema | Callable[[VariantValues], FrameSchema] | None:
        """Index and column levels of the result. Each spec class overrides it.

        Raises:
            NotImplementedError: The spec class does not provide a schema.
        """
        raise NotImplementedError(f'{type(self).__name__} does not provide a schema.')

    @property
    def is_family(self) -> bool:
        """`True` if a variant dimension resolves its values per dataset."""
        return any(d.is_resolved_per_dataset for d in self.variants)

    @property
    def dimensions(self) -> tuple[Dimension, ...]:
        """Variant and parameter dimensions, in this order."""
        return self.variants + self.params

    def expand(self, dataset: Dataset | None = None) -> list[str]:
        """Return the flag names of this spec.

        Args:
            dataset: Dataset that resolves variant values given as a function.
                Not needed for a spec without such values.

        Returns:
            One flag name per combination of variant values.

        Raises:
            ValueError: The spec is a flag family and `dataset` is `None`.
        """
        if not self.is_family:
            return list(self._variants_by_flag)
        return [self._fill(combination) for combination in self._combinations(dataset)]

    def static_flags(self) -> set[str]:
        """The flags of the spec, or an empty set for a flag family, whose values need a dataset."""
        return set() if self.is_family else set(self.expand())

    def covers(self, 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.
        """
        try:
            self.variant_of(flag)
        except KeyError:
            return False
        return True

    def variant_of(self, flag: Any) -> VariantValues:
        """Return the variant values of a flag of this spec.

        Args:
            flag: A flag of this spec.

        Returns:
            One attribute per variant dimension.

        Raises:
            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'
        """
        flag = str(flag)
        if not self.is_family:
            try:
                return self._variants_by_flag[flag]
            except KeyError:
                raise KeyError(f'Spec {self.name!r} does not cover flag {flag!r}.') from None
        match = self._family_pattern.fullmatch(flag)
        if match is None:
            raise KeyError(f'Spec {self.name!r} does not cover flag {flag!r}.')
        return VariantValues({d.name: self._static_value(d, match.group(d.name)) for d in self.variants})

    def check_variant_values(self, flag: Any, dataset: Dataset | None = None) -> None:
        """Raise `ValueError` if a family value of `flag` is not a value on `dataset`.

        Args:
            flag: A flag of this spec.
            dataset: Dataset that resolves the family values.

        Raises:
            FlagUnavailableError: The values function of a variant fetches an
                unavailable flag, as in `Dimension.check_value`.
            ValueError: A family value is not a value on `dataset`.
        """
        variant = self.variant_of(flag)
        for dimension in self.variants:
            if dimension.is_resolved_per_dataset:
                dimension.check_value(getattr(variant, dimension.name), dataset)

    def resolve_params(self, 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`.

        Args:
            given: Given values by parameter name. `None`: no values.
            dataset: Dataset that resolves values given as a function. With
                `None` and such values, neither the values nor `validate`
                are checked.

        Returns:
            One value per parameter of the spec, in the order of `params`.

        Raises:
            FlagUnavailableError: The values function of a parameter fetches
                an unavailable flag, as in `Dimension.check_value`.
            ValueError: `given` names a parameter that the spec does not
                declare, a `REQUIRED` parameter has no value, or a value is
                not allowed.

        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'].
        """
        given = given or {}
        names = [d.name for d in self.params]
        unknown = set(given) - set(names)
        if unknown:
            raise ValueError(f'Spec {self.name!r} declares no parameters {sorted(unknown)}. Parameters: {names}.')
        return {d.name: d.resolve(given, dataset) for d in self.params}

    def flag_description(self, 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.'
        """
        variant = self.variant_of(flag)
        parts = [self.description]
        for dimension in self.variants:
            label = dimension.name.replace('_', ' ').capitalize()
            parts.append(f'{label}: {dimension.describe_value(getattr(variant, dimension.name), dataset)}.')
        return ' '.join(parts)

    def same_as(self, 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.
        """
        if type(self) is not type(other) or self._identity() != other._identity():
            return False
        return all(a.same_as(b) for a, b in zip(self.dimensions, other.dimensions)) and (
            len(self.dimensions) == len(other.dimensions)
        )

    @classmethod
    def class_for(cls, 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'>
        """
        match item_type:
            case ItemTypeEnum.Model:
                return ModelFlagSpec
            case ItemTypeEnum.TimeSeries:
                return TimeSeriesFlagSpec
            case ItemTypeEnum.Other:
                return OtherFlagSpec
        raise ValueError(f'No spec class for item type {item_type!r}.')

    def declared_schema(self, flag: Any) -> FrameSchema | None:
        """Return the schema that the spec declares for a flag, or `None` for the default schema."""
        schema = self.schema
        if callable(schema):
            return schema(self.variant_of(flag))
        return schema

    def _identity(self) -> tuple:
        return (self.name, self.version) + tuple(self._class_identity())

    def _class_identity(self) -> tuple:
        return ()

    def _check_required_fields(self) -> None:
        for f in dataclasses.fields(self):
            if getattr(self, f.name) is REQUIRED:
                raise TypeError(f'{type(self).__name__} {self.name!r}: field {f.name!r} is required.')

    def _check_dimensions(self) -> None:
        names = [d.name for d in self.dimensions]
        duplicates = sorted({n for n in names if names.count(n) > 1})
        if duplicates:
            raise ValueError(f'Spec {self.name!r}: dimension names must be unique, got {duplicates} twice.')
        for dimension in self.variants:
            if dimension.values is None:
                raise ValueError(f'Spec {self.name!r}: variant {dimension.name!r} needs values.')
            if dimension.has_default or dimension.validate is not None:
                raise ValueError(f'Spec {self.name!r}: variant {dimension.name!r} takes no default or validate.')

    def _check_model_flag_placeholders(self) -> None:
        """Raise `ValueError` if a placeholder of a `model_flag` template is no variant dimension."""
        model_flag = getattr(self, 'model_flag', None)
        if model_flag is None:
            return
        placeholders = {name for _, name, _, _ in string.Formatter().parse(model_flag) if name is not None}
        unknown = placeholders - {d.name for d in self.variants}
        if unknown:
            raise ValueError(
                f'Spec {self.name!r}: model_flag {model_flag!r} has placeholders {sorted(unknown)} '
                f'that are no variant dimensions.'
            )

    def _check_placeholders(self) -> None:
        placeholders = [name for _, name, _, _ in string.Formatter().parse(self.name) if name is not None]
        expected = sorted(d.name for d in self.variants)
        if sorted(placeholders) != expected:
            raise ValueError(
                f'Spec {self.name!r}: placeholders {sorted(placeholders)} must match the variant dimensions {expected}.'
            )

    @cached_property
    def _variants_by_flag(self) -> Mapping[str, VariantValues]:
        variants_by_flag = {}
        for combination in self._combinations(None):
            flag = self._fill(combination)
            if flag in variants_by_flag:
                raise ValueError(f'Spec {self.name!r}: two variant combinations give the flag {flag!r}.')
            variants_by_flag[flag] = VariantValues(combination)
        return MappingProxyType(variants_by_flag)

    def _combinations(self, dataset: Dataset | None) -> list[dict[str, Hashable]]:
        names = [d.name for d in self.variants]
        value_lists = [list(d.values_for(dataset)) for d in self.variants]
        return [dict(zip(names, values)) for values in itertools.product(*value_lists)]

    def _fill(self, combination: Mapping[str, Hashable]) -> str:
        return self.name.format(**combination)

    @cached_property
    def _family_pattern(self) -> re.Pattern:
        dimensions = {d.name: d for d in self.variants}
        pattern = ''
        for literal, name, _, _ in string.Formatter().parse(self.name):
            pattern += re.escape(literal)
            if name is None:
                continue
            dimension = dimensions[name]
            if dimension.is_resolved_per_dataset:
                pattern += f'(?P<{name}>.+?)'
            else:
                options = sorted((re.escape(str(v)) for v in dimension.values), key=len, reverse=True)
                pattern += f'(?P<{name}>{"|".join(options)})'
        return re.compile(pattern)

    @staticmethod
    def _static_value(dimension: Dimension, text: str) -> Hashable:
        if dimension.is_resolved_per_dataset:
            return text
        return next(v for v in dimension.values if str(v) == text)

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.

is_family property

is_family: bool

True if a variant dimension resolves its values per dataset.

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 dataset is None.

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
def expand(self, dataset: Dataset | None = None) -> list[str]:
    """Return the flag names of this spec.

    Args:
        dataset: Dataset that resolves variant values given as a function.
            Not needed for a spec without such values.

    Returns:
        One flag name per combination of variant values.

    Raises:
        ValueError: The spec is a flag family and `dataset` is `None`.
    """
    if not self.is_family:
        return list(self._variants_by_flag)
    return [self._fill(combination) for combination in self._combinations(dataset)]

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
def static_flags(self) -> set[str]:
    """The flags of the spec, or an empty set for a flag family, whose values need a dataset."""
    return set() if self.is_family else set(self.expand())

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
def covers(self, 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.
    """
    try:
        self.variant_of(flag)
    except KeyError:
        return False
    return True

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
def variant_of(self, flag: Any) -> VariantValues:
    """Return the variant values of a flag of this spec.

    Args:
        flag: A flag of this spec.

    Returns:
        One attribute per variant dimension.

    Raises:
        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'
    """
    flag = str(flag)
    if not self.is_family:
        try:
            return self._variants_by_flag[flag]
        except KeyError:
            raise KeyError(f'Spec {self.name!r} does not cover flag {flag!r}.') from None
    match = self._family_pattern.fullmatch(flag)
    if match is None:
        raise KeyError(f'Spec {self.name!r} does not cover flag {flag!r}.')
    return VariantValues({d.name: self._static_value(d, match.group(d.name)) for d in self.variants})

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 Dimension.check_value.

ValueError

A family value is not a value on dataset.

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
def check_variant_values(self, flag: Any, dataset: Dataset | None = None) -> None:
    """Raise `ValueError` if a family value of `flag` is not a value on `dataset`.

    Args:
        flag: A flag of this spec.
        dataset: Dataset that resolves the family values.

    Raises:
        FlagUnavailableError: The values function of a variant fetches an
            unavailable flag, as in `Dimension.check_value`.
        ValueError: A family value is not a value on `dataset`.
    """
    variant = self.variant_of(flag)
    for dimension in self.variants:
        if dimension.is_resolved_per_dataset:
            dimension.check_value(getattr(variant, dimension.name), dataset)

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: no values.

None
dataset Dataset | None

Dataset that resolves values given as a function. With None and such values, neither the values nor validate are checked.

None

Returns:

Type Description
dict[str, Any]

One value per parameter of the spec, in the order of params.

Raises:

Type Description
FlagUnavailableError

The values function of a parameter fetches an unavailable flag, as in Dimension.check_value.

ValueError

given names a parameter that the spec does not declare, a REQUIRED parameter has no value, or a value is not allowed.

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
def resolve_params(self, 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`.

    Args:
        given: Given values by parameter name. `None`: no values.
        dataset: Dataset that resolves values given as a function. With
            `None` and such values, neither the values nor `validate`
            are checked.

    Returns:
        One value per parameter of the spec, in the order of `params`.

    Raises:
        FlagUnavailableError: The values function of a parameter fetches
            an unavailable flag, as in `Dimension.check_value`.
        ValueError: `given` names a parameter that the spec does not
            declare, a `REQUIRED` parameter has no value, or a value is
            not allowed.

    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'].
    """
    given = given or {}
    names = [d.name for d in self.params]
    unknown = set(given) - set(names)
    if unknown:
        raise ValueError(f'Spec {self.name!r} declares no parameters {sorted(unknown)}. Parameters: {names}.')
    return {d.name: d.resolve(given, dataset) for d in self.params}

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
def flag_description(self, 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.'
    """
    variant = self.variant_of(flag)
    parts = [self.description]
    for dimension in self.variants:
        label = dimension.name.replace('_', ' ').capitalize()
        parts.append(f'{label}: {dimension.describe_value(getattr(variant, dimension.name), dataset)}.')
    return ' '.join(parts)

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
def same_as(self, 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.
    """
    if type(self) is not type(other) or self._identity() != other._identity():
        return False
    return all(a.same_as(b) for a, b in zip(self.dimensions, other.dimensions)) and (
        len(self.dimensions) == len(other.dimensions)
    )

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
@classmethod
def class_for(cls, 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'>
    """
    match item_type:
        case ItemTypeEnum.Model:
            return ModelFlagSpec
        case ItemTypeEnum.TimeSeries:
            return TimeSeriesFlagSpec
        case ItemTypeEnum.Other:
            return OtherFlagSpec
    raise ValueError(f'No spec class for item type {item_type!r}.')

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
def declared_schema(self, flag: Any) -> FrameSchema | None:
    """Return the schema that the spec declares for a flag, or `None` for the default schema."""
    schema = self.schema
    if callable(schema):
        return schema(self.variant_of(flag))
    return schema

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 'Node'. Also the column level name of the linked time series.

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 Edge only: the two memberships that hold the ends, in line direction.

visualization_type VisualizationTypeEnum | None

None: follows from the topology type.

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
@dataclass(frozen=True, eq=False)
class ModelFlagSpec(FlagSpec):
    """The model table of one object type: one row per object.

    Attributes:
        index: Name of the index level, for example `'Node'`. Also the column
            level name of the linked time series.
        topology_type: Role of the objects in the network topology.
        memberships: Column to the model flag it refers to. The single source
            of object relations; mesqual does not detect them from column names.
        edge_ends: Topology type `Edge` only: the two memberships that hold
            the ends, in line direction.
        visualization_type: `None`: follows from the topology type.

    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'),
        ... )
    """

    item_type: ClassVar[ItemTypeEnum] = ItemTypeEnum.Model

    index: str = REQUIRED
    topology_type: TopologyTypeEnum = REQUIRED
    memberships: Mapping[str, str] = field(default_factory=dict)
    edge_ends: tuple[str, str] | None = None
    visualization_type: VisualizationTypeEnum | None = None

    def __post_init__(self):
        object.__setattr__(self, 'memberships', MappingProxyType(dict(self.memberships)))
        if self.edge_ends is not None:
            object.__setattr__(self, 'edge_ends', tuple(self.edge_ends))
        super().__post_init__()
        if not isinstance(self.topology_type, TopologyTypeEnum):
            raise TypeError(f'Spec {self.name!r}: topology_type must be a TopologyTypeEnum.')
        self._check_edge_ends()

    @property
    def schema(self) -> 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)
        """
        return FrameSchema(index=(Level(self.index, 'object'),), columns=(Level(None, 'dimension'),))

    def _check_edge_ends(self) -> None:
        if self.edge_ends is None:
            return
        if self.topology_type is not TopologyTypeEnum.Edge:
            raise ValueError(f'Spec {self.name!r}: edge_ends needs the topology type Edge.')
        if len(self.edge_ends) != 2 or any(end not in self.memberships for end in self.edge_ends):
            raise ValueError(f'Spec {self.name!r}: edge_ends must name two memberships.')
        if self.memberships[self.edge_ends[0]] != self.memberships[self.edge_ends[1]]:
            raise ValueError(f'Spec {self.name!r}: both edge_ends must refer to the same model flag.')

    def _class_identity(self) -> tuple:
        return self.index, self.topology_type, tuple(sorted(self.memberships.items())), self.edge_ends

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. None: the columns are not objects, for example a system total. The spec then declares schema. It may be a template with placeholders of the variant dimensions: with a variant area_layer resolved per dataset, '{area_layer}.Model' links each flag to the model flag of its layer, so the flag takes topology type and column level from the layer model.

unit Unit

Unit of the values. NaU and MissingUnit are not allowed.

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. None: the default schema.

fill_value float | None

Value for objects or rows that one side lacks, in sums and comparisons. None: no fill.

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
@dataclass(frozen=True, eq=False)
class TimeSeriesFlagSpec(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:
        model_flag: Linked model flag. `None`: the columns are not objects,
            for example a system total. The spec then declares `schema`.
            It may be a template with placeholders of the variant
            dimensions: with a variant `area_layer` resolved per dataset,
            `'{area_layer}.Model'` links each flag to the model flag of its
            layer, so the flag takes topology type and column level from
            the layer model.
        unit: Unit of the values. `NaU` and `MissingUnit` are not allowed.
        quantity_type: Set only for an ambiguous unit, and required there.
            Else the unit decides.
        schema: Index and column levels of the result, or a function of the
            variant values that returns them. `None`: the default schema.
        fill_value: Value for objects or rows that one side lacks, in sums and
            comparisons. `None`: no fill.

    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,
        ... )
    """

    item_type: ClassVar[ItemTypeEnum] = ItemTypeEnum.TimeSeries

    model_flag: str | None = REQUIRED
    unit: Units.Unit = REQUIRED
    quantity_type: QuantityTypeEnum | None = None
    schema: FrameSchema | Callable[[VariantValues], FrameSchema] | None = None
    fill_value: float | None = None

    def __post_init__(self):
        super().__post_init__()
        self._check_unit()
        if self.model_flag is None and self.schema is None:
            raise ValueError(f'Spec {self.name!r}: a time series spec without model_flag must declare a schema.')
        self._check_model_flag_placeholders()
        if isinstance(self.schema, FrameSchema) and len(self.schema.time_levels) != 1:
            raise ValueError(f'Spec {self.name!r}: the schema needs exactly one index level with role time.')

    def _check_unit(self) -> None:
        if not isinstance(self.unit, Units.Unit) or self.unit in (Units.NaU, Units.MissingUnit):
            raise ValueError(f'Spec {self.name!r}: a time series spec needs a unit, got {self.unit!r}.')
        ambiguous = Units.get_quantity_type_enum(self.unit) is QuantityTypeEnum.AMBIGUOUS
        if ambiguous and self.quantity_type not in (QuantityTypeEnum.INTENSIVE, QuantityTypeEnum.EXTENSIVE):
            raise ValueError(
                f'Spec {self.name!r}: the unit {self.unit} is ambiguous. Set quantity_type to INTENSIVE or EXTENSIVE.'
            )
        if not ambiguous and self.quantity_type is not None:
            raise ValueError(
                f'Spec {self.name!r}: the unit {self.unit} decides the quantity type. Remove quantity_type.'
            )

    def _class_identity(self) -> tuple:
        return self.model_flag, self.unit, self.quantity_type, self.fill_value

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
@dataclass(frozen=True, eq=False)
class OtherFlagSpec(FlagSpec):
    """Any other table, for example algorithm results per run.

    Attributes:
        schema: Index and column levels of the result, or a function of the
            variant values that returns them. Required.
        unit: Optional unit of the values.
    """

    item_type: ClassVar[ItemTypeEnum] = ItemTypeEnum.Other

    schema: FrameSchema | Callable[[VariantValues], FrameSchema] = REQUIRED
    unit: Units.Unit | None = None

    def _class_identity(self) -> tuple:
        return (self.unit,)

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 'Region'. It fills the layer placeholder of layer specs.

index str

Label of the object level, for example 'Region': the index level of the layer model and the column level of the layer time series. All flags of the layer share it.

base_model str

Model flag of the grouped objects, for example 'Node.Model'.

layer_model str

Model flag of the areas, for example 'Region.Model'. The target of exactly one membership of base_model.

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
@dataclass(frozen=True)
class AreaLayer:
    """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: Layer name, for example `'Region'`. It fills the layer
            placeholder of layer specs.
        index: Label of the object level, for example `'Region'`: the
            index level of the layer model and the column level of the layer
            time series. All flags of the layer share it.
        base_model: Model flag of the grouped objects, for example `'Node.Model'`.
        layer_model: Model flag of the areas, for example `'Region.Model'`.
            The target of exactly one membership of `base_model`.
        description: 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.',
        ... )
    """

    name: str
    index: str
    base_model: str
    layer_model: str
    description: str

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 'RegionBorder'. It fills the border layer placeholder of layer specs.

index str

Label of the object level, for example 'RegionBorder': the index level of the border model and the column level of the border time series.

area_layer str

Name of the area layer, for example 'Region'.

edge_model str

Model flag of the edges that cross borders, for example 'Line.Model'.

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
@dataclass(frozen=True)
class BorderLayer:
    """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: Layer name, for example `'RegionBorder'`. It fills the
            border layer placeholder of layer specs.
        index: Label of the object level, for example `'RegionBorder'`:
            the index level of the border model and the column level of the
            border time series.
        area_layer: Name of the area layer, for example `'Region'`.
        edge_model: Model flag of the edges that cross borders, for example `'Line.Model'`.
        description: What the borders are.
    """

    name: str
    index: str
    area_layer: str
    edge_model: str
    description: str

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
class LayerSet:
    """The area and border layers of a dataset, looked up by name.

    Args:
        area_layers: The area layers.
        border_layers: The border layers.

    Raises:
        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.
    """

    def __init__(self, area_layers: Iterable[AreaLayer] = (), border_layers: Iterable[BorderLayer] = ()):
        self._area_layers = tuple(area_layers)
        self._border_layers = tuple(border_layers)
        self._by_name: dict[str, AreaLayer | BorderLayer] = {}
        for layer in self._area_layers + self._border_layers:
            if self._by_name.setdefault(layer.name, layer) is not layer:
                raise AmbiguousOverrideError(f'Two layers have the name {layer.name!r}.')
        for layer in self._border_layers:
            if not isinstance(self._by_name.get(layer.area_layer), AreaLayer):
                raise ValueError(f'Border layer {layer.name!r}: no area layer {layer.area_layer!r}.')

    @classmethod
    def union(cls, layer_sets: Iterable[LayerSet]) -> LayerSet:
        """Return one set with the layers of several sets.

        Raises:
            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.
        """
        by_name: dict[str, AreaLayer | BorderLayer] = {}
        for layer_set in layer_sets:
            for layer in layer_set.area_layers + layer_set.border_layers:
                if by_name.setdefault(layer.name, layer) != layer:
                    raise AmbiguousOverrideError(f'Two different layers have the name {layer.name!r}.')
        layers = by_name.values()
        return cls(
            [layer for layer in layers if isinstance(layer, AreaLayer)],
            [layer for layer in layers if isinstance(layer, BorderLayer)],
        )

    @property
    def area_layers(self) -> tuple[AreaLayer, ...]:
        """The area layers, in registration order."""
        return self._area_layers

    @property
    def border_layers(self) -> tuple[BorderLayer, ...]:
        """The border layers, in registration order."""
        return self._border_layers

    def get(self, name: str) -> AreaLayer | BorderLayer:
        """Return the layer with this name.

        Raises:
            KeyError: No layer has this name.
        """
        try:
            return self._by_name[name]
        except KeyError:
            raise KeyError(f'No layer {name!r}. Layers: {list(self._by_name)}.') from None

    def area_layer_of(self, border_layer: BorderLayer) -> AreaLayer:
        """Return the area layer of a border layer."""
        return self._by_name[border_layer.area_layer]

    def __bool__(self) -> bool:
        return bool(self._by_name)

    def __repr__(self) -> str:
        return f'LayerSet({list(self._by_name)})'

area_layers property

area_layers: tuple[AreaLayer, ...]

The area layers, in registration order.

border_layers property

border_layers: tuple[BorderLayer, ...]

The border layers, in registration order.

union classmethod

union(layer_sets: Iterable[LayerSet]) -> LayerSet

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
@classmethod
def union(cls, layer_sets: Iterable[LayerSet]) -> LayerSet:
    """Return one set with the layers of several sets.

    Raises:
        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.
    """
    by_name: dict[str, AreaLayer | BorderLayer] = {}
    for layer_set in layer_sets:
        for layer in layer_set.area_layers + layer_set.border_layers:
            if by_name.setdefault(layer.name, layer) != layer:
                raise AmbiguousOverrideError(f'Two different layers have the name {layer.name!r}.')
    layers = by_name.values()
    return cls(
        [layer for layer in layers if isinstance(layer, AreaLayer)],
        [layer for layer in layers if isinstance(layer, BorderLayer)],
    )

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
def get(self, name: str) -> AreaLayer | BorderLayer:
    """Return the layer with this name.

    Raises:
        KeyError: No layer has this name.
    """
    try:
        return self._by_name[name]
    except KeyError:
        raise KeyError(f'No layer {name!r}. Layers: {list(self._by_name)}.') from None

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
def area_layer_of(self, border_layer: BorderLayer) -> AreaLayer:
    """Return the area layer of a border layer."""
    return self._by_name[border_layer.area_layer]

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. None: the layer 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. None: the base schema with the object level renamed to the index of 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 name.

aggregation_params tuple[Dimension, ...]

Parameters of the aggregation, given as params. The interpreter passes them to aggregate, not to the base fetch.

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
@dataclass(frozen=True, eq=False)
class LayerFlagSpec(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:
        base: The base spec.
        aggregation: The aggregation to the layer.
        model_flag: Template of the linked model flag. `None`: the layer
            model flag.
        schema: Index and column levels of the result, or a function of the
            variant values and the layer. `None`: the base schema with the
            object level renamed to the `index` of the layer.
        consumes: Variant dimensions of the base that the aggregation
            resolves itself. They are not in the spec name.
        layer_placeholder: Name of the layer dimension and of its
            placeholder in `name`.
        aggregation_params: Parameters of the aggregation, given as
            `params`. The interpreter passes them to `aggregate`, not to
            the base fetch.
    """

    topology_type: ClassVar[TopologyTypeEnum]
    BASE_TOPOLOGY_TYPES: ClassVar[tuple[TopologyTypeEnum, ...]]
    LAYER_KIND: ClassVar[str]

    base: FlagSpec = REQUIRED
    aggregation: Any = REQUIRED
    model_flag: str | None = None
    schema: FrameSchema | Callable[[VariantValues, AreaLayer | BorderLayer], FrameSchema] | None = None
    consumes: tuple[str, ...] = ()
    layer_placeholder: str = REQUIRED
    variants: tuple[Dimension, ...] = field(default=(), init=False)
    aggregation_params: tuple[Dimension, ...] = field(default=(), init=False)

    def __post_init__(self):
        self._check_required_fields()
        self._check_base()
        object.__setattr__(self, 'consumes', tuple(self.consumes))
        base_dimensions = {d.name for d in self.base.dimensions}
        unknown = set(self.consumes) - {d.name for d in self.base.variants}
        if unknown:
            raise ValueError(f'Spec {self.name!r}: consumes {sorted(unknown)}, which are no variants of the base.')
        if self.layer_placeholder in base_dimensions:
            raise ValueError(
                f'Spec {self.name!r}: the layer placeholder {self.layer_placeholder!r} is a dimension of the base. '
                f'Set another layer_placeholder.'
            )
        layer_dimension = Dimension(
            self.layer_placeholder, f'{self.LAYER_KIND.capitalize()} layer.', _LayerValues(self)
        )
        resolved_here = (*self.consumes, self._base_layer_placeholder)
        kept = tuple(d for d in self.base.variants if d.name not in resolved_here)
        object.__setattr__(self, 'aggregation_params', tuple(self.params))
        object.__setattr__(self, 'params', self.base.params + self.aggregation_params)
        object.__setattr__(self, 'variants', (layer_dimension,) + kept)
        super().__post_init__()
        self._check_model_flag_placeholders()
        self.aggregation.check_spec(self)

    def _check_base(self) -> None:
        raise NotImplementedError

    def on_base(self, base: FlagSpec) -> LayerFlagSpec:
        """Return this spec built on another base: the parameters of `base`, then the aggregation parameters."""
        return replace(self, base=base, params=self.aggregation_params)

    @property
    def _base_layer_placeholder(self) -> str | None:
        """The layer dimension of a layer base, else `None`.

        A layer base is a border spec for an area spec, an area spec for a
        border spec. The interpreter resolves its layer dimension from the
        layer of the flag.
        """
        return self.base.layer_placeholder if isinstance(self.base, LayerFlagSpec) else None

    @property
    def _has_layer_base(self) -> bool:
        """`True` if the base is a layer spec (`_base_layer_placeholder`)."""
        return self._base_layer_placeholder is not None

    @property
    def item_type(self) -> ItemTypeEnum:
        """Item type of the base."""
        return self.base.item_type

    @property
    def unit(self) -> Units.Unit | None:
        """Unit of the base. `None` for a model base."""
        return getattr(self.base, 'unit', None)

    @property
    def quantity_type(self) -> QuantityTypeEnum | None:
        """Quantity type of the base, set only for an ambiguous unit."""
        return getattr(self.base, 'quantity_type', None)

    @property
    def fill_value(self) -> float | None:
        """`fill_value` of the base."""
        return getattr(self.base, 'fill_value', None)

    @property
    def visualization_type(self) -> None:
        """`None`: the visualization type follows from the topology type."""
        return None

    @property
    def is_model(self) -> bool:
        """`True` if the base is a model flag, so the layer flags are the layer model flags."""
        return self.base.item_type is ItemTypeEnum.Model

    @property
    def layer_dimension(self) -> Dimension:
        """The layer dimension."""
        return self.variants[0]

    def layer_name_of(self, flag: Any) -> str:
        """Return the layer name of a flag of this spec."""
        return getattr(self.variant_of(flag), self.layer_placeholder)

    def expand_on_layers(self, layer_names: Iterable[str]) -> list[str] | None:
        """Return the flag names for the given layers, or `None` if another variant dimension needs a dataset."""
        if any(d.is_resolved_per_dataset for d in self.variants[1:]):
            return None
        names = [d.name for d in self.variants]
        value_lists = [list(layer_names)] + [list(d.values) for d in self.variants[1:]]
        return [self._fill(dict(zip(names, values))) for values in itertools.product(*value_lists)]

    def declared_schema(self, flag: Any, layer: AreaLayer | BorderLayer | None = None) -> FrameSchema | None:
        """Return the declared schema for a flag, or `None` for the default schema.

        Raises:
            ValueError: The schema is a function and `layer` is `None`.
        """
        if not callable(self.schema):
            return self.schema
        if layer is None:
            raise ValueError(f'Spec {self.name!r}: the schema is a function of the layer. Pass the layer.')
        return self.schema(self.variant_of(flag), layer)

    def flag_description(self, 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.
        """
        variant = self.variant_of(flag)
        parts = [self.description, f'Base: {self.base.description}']
        if dataset is not None:
            parts.append(f'Layer: {self.layer_dimension.describe_value(self.layer_name_of(flag), dataset)}')
        for dimension in self.variants[1:]:
            label = dimension.name.replace('_', ' ').capitalize()
            parts.append(f'{label}: {dimension.describe_value(getattr(variant, dimension.name), dataset)}.')
        return ' '.join(parts)

    def same_as(self, 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).
        """
        if type(self) is not type(other) or self._identity() != other._identity():
            return False
        own, theirs = self.aggregation_params, other.aggregation_params
        return (
            self.base.same_as(other.base) and len(own) == len(theirs) and all(a.same_as(b) for a, b in zip(own, theirs))
        )

    def _class_identity(self) -> tuple:
        return self.aggregation, self.model_flag, self.consumes, self.layer_placeholder

    def _check_base_model_flag(self) -> None:
        if isinstance(self.base, TimeSeriesFlagSpec) and self.base.model_flag is None:
            raise ValueError(f'Spec {self.name!r}: base {self.base.name!r} has no model flag.')

item_type property

item_type: ItemTypeEnum

Item type of the base.

unit property

unit: Unit | None

Unit of the base. None for a model base.

quantity_type property

quantity_type: QuantityTypeEnum | None

Quantity type of the base, set only for an ambiguous unit.

fill_value property

fill_value: float | None

fill_value of the base.

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.

layer_dimension property

layer_dimension: Dimension

The layer dimension.

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
def on_base(self, base: FlagSpec) -> LayerFlagSpec:
    """Return this spec built on another base: the parameters of `base`, then the aggregation parameters."""
    return replace(self, base=base, params=self.aggregation_params)

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
def layer_name_of(self, flag: Any) -> str:
    """Return the layer name of a flag of this spec."""
    return getattr(self.variant_of(flag), self.layer_placeholder)

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
def expand_on_layers(self, layer_names: Iterable[str]) -> list[str] | None:
    """Return the flag names for the given layers, or `None` if another variant dimension needs a dataset."""
    if any(d.is_resolved_per_dataset for d in self.variants[1:]):
        return None
    names = [d.name for d in self.variants]
    value_lists = [list(layer_names)] + [list(d.values) for d in self.variants[1:]]
    return [self._fill(dict(zip(names, values))) for values in itertools.product(*value_lists)]

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 layer is None.

Source code in src/mesqual/flag/layer_spec.py
172
173
174
175
176
177
178
179
180
181
182
def declared_schema(self, flag: Any, layer: AreaLayer | BorderLayer | None = None) -> FrameSchema | None:
    """Return the declared schema for a flag, or `None` for the default schema.

    Raises:
        ValueError: The schema is a function and `layer` is `None`.
    """
    if not callable(self.schema):
        return self.schema
    if layer is None:
        raise ValueError(f'Spec {self.name!r}: the schema is a function of the layer. Pass the layer.')
    return self.schema(self.variant_of(flag), layer)

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
def flag_description(self, 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.
    """
    variant = self.variant_of(flag)
    parts = [self.description, f'Base: {self.base.description}']
    if dataset is not None:
        parts.append(f'Layer: {self.layer_dimension.describe_value(self.layer_name_of(flag), dataset)}')
    for dimension in self.variants[1:]:
        label = dimension.name.replace('_', ' ').capitalize()
        parts.append(f'{label}: {dimension.describe_value(getattr(variant, dimension.name), dataset)}.')
    return ' '.join(parts)

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
def same_as(self, 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).
    """
    if type(self) is not type(other) or self._identity() != other._identity():
        return False
    own, theirs = self.aggregation_params, other.aggregation_params
    return (
        self.base.same_as(other.base) and len(own) == len(theirs) and all(a.same_as(b) for a, b in zip(own, theirs))
    )

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 AreaAggregation.

layer_placeholder str

Name of the layer dimension. Default 'area_layer'.

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
@dataclass(frozen=True, eq=False)
class AreaFlagSpec(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:
        aggregation: An `AreaAggregation`.
        layer_placeholder: Name of the layer dimension. Default `'area_layer'`.

    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.',
        ... )
    """

    topology_type: ClassVar[TopologyTypeEnum] = TopologyTypeEnum.Area
    BASE_TOPOLOGY_TYPES: ClassVar[tuple[TopologyTypeEnum, ...]] = (
        TopologyTypeEnum.Node,
        TopologyTypeEnum.NodeConnectedElement,
    )
    LAYER_KIND: ClassVar[str] = 'area'

    aggregation: AreaAggregation = REQUIRED
    layer_placeholder: str = 'area_layer'

    def _check_base(self) -> None:
        if not isinstance(self.base, (ModelFlagSpec, TimeSeriesFlagSpec, BorderFlagSpec)):
            raise TypeError(f'Spec {self.name!r}: the base must be a model, time series or border spec.')
        self._check_base_model_flag()

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 BorderAggregation.

layer_placeholder str

Name of the layer dimension. Default 'border_layer'.

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
@dataclass(frozen=True, eq=False)
class BorderFlagSpec(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:
        aggregation: A `BorderAggregation`.
        layer_placeholder: Name of the layer dimension. Default `'border_layer'`.

    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.',
        ... )
    """

    topology_type: ClassVar[TopologyTypeEnum] = TopologyTypeEnum.Border
    BASE_TOPOLOGY_TYPES: ClassVar[tuple[TopologyTypeEnum, ...]] = (TopologyTypeEnum.Edge,)
    LAYER_KIND: ClassVar[str] = 'border'

    aggregation: BorderAggregation = REQUIRED
    layer_placeholder: str = 'border_layer'

    def _check_base(self) -> None:
        if not isinstance(self.base, (ModelFlagSpec, TimeSeriesFlagSpec, AreaFlagSpec)):
            raise TypeError(f'Spec {self.name!r}: the base must be a model, time series or area spec.')
        self._check_base_model_flag()

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
class LayerVariantValues(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.

    Args:
        values: The variant values, with the layer of the base.
        base_name: The name of the base spec.

    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'
    """

    __slots__ = ('_base_name',)

    def __init__(self, values: Mapping[str, Hashable], base_name: str):
        super().__init__(values)
        object.__setattr__(self, '_base_name', base_name)

    def base_flag(self, **changes: Hashable) -> str:
        """Return the base flag for these variant values, with some values changed.

        Args:
            **changes: Values of base dimensions to change, and the values
                of the dimensions that the spec consumes.

        Raises:
            ValueError: A dimension of the base name has no value.
        """
        try:
            return self._base_name.format(**{**self.as_dict(), **changes})
        except KeyError as missing:
            raise ValueError(f'Base flag {self._base_name!r} needs a value for {missing}.') from None

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
def base_flag(self, **changes: Hashable) -> str:
    """Return the base flag for these variant values, with some values changed.

    Args:
        **changes: Values of base dimensions to change, and the values
            of the dimensions that the spec consumes.

    Raises:
        ValueError: A dimension of the base name has no value.
    """
    try:
        return self._base_name.format(**{**self.as_dict(), **changes})
    except KeyError as missing:
        raise ValueError(f'Base flag {self._base_name!r} needs a value for {missing}.') from None

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
class 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.

    Args:
        specs: Specs to add.
        layers: The area and border layers.

    Raises:
        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'>
    """

    def __init__(self, specs: Iterable[FlagSpec] = (), layers: LayerSet = LayerSet()):
        self._specs: dict[str, FlagSpec] = {}
        self._spec_by_flag: dict[str, FlagSpec] = {}
        self._layers = layers
        self._references_checked = False
        for spec in specs:
            self.add_spec(spec)

    @classmethod
    def union(cls, indexes: Iterable[FlagIndex]) -> FlagIndex:
        """Build one index with the specs and layers of several indexes.

        Args:
            indexes: The indexes to combine.

        Returns:
            A new index.

        Raises:
            ValueError: Two indexes have specs with the same name that are not
                the same (`FlagSpec.same_as`).
            AmbiguousOverrideError: Two indexes have different layers with the
                same name.
        """
        indexes = tuple(indexes)
        union = cls(layers=LayerSet.union(index.layers for index in indexes))
        for index in indexes:
            for spec in index.specs:
                existing = union._specs.get(spec.name)
                if existing is None:
                    union.add_spec(spec)
                elif existing is not spec and not existing.same_as(spec):
                    raise ValueError(f'Two different specs for {spec.name!r}. Specs with one name must be the same.')
        return union

    @property
    def specs(self) -> tuple[FlagSpec, ...]:
        """All specs of this index."""
        return tuple(self._specs.values())

    @property
    def static_flags(self) -> set[str]:
        """Flag names of all specs except the flag families, whose values need a dataset."""
        return set(self._spec_by_flag)

    @property
    def parameter_names(self) -> set[str]:
        """Names of all parameters that a spec of this index declares."""
        return {d.name for spec in self._specs.values() for d in spec.params}

    @property
    def layers(self) -> LayerSet:
        """The area and border layers of this index."""
        return self._layers

    def add_spec(self, spec: FlagSpec) -> None:
        """Add a spec.

        Args:
            spec: The spec to add.

        Raises:
            AmbiguousOverrideError: Another spec gives one of the flag names.
        """
        existing = self._specs.get(spec.name)
        if existing is spec:
            return
        if existing is not None:
            raise AmbiguousOverrideError(f'Two specs declare {spec.name!r}.')
        flags = self._checked_flags_of(spec, self._spec_by_flag)
        self._specs[spec.name] = spec
        self._spec_by_flag.update(dict.fromkeys(flags, spec))
        self._references_checked = False

    def static_flags_of(self, 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.
        """
        if isinstance(spec, LayerFlagSpec):
            return spec.expand_on_layers(layer.name for layer in self.get_layers(spec))
        return None if spec.is_family else spec.expand()

    def _checked_flags_of(self, spec: FlagSpec, spec_by_flag: dict[str, FlagSpec]) -> list[str]:
        flags = self.static_flags_of(spec) or []
        for flag in flags:
            if flag in spec_by_flag:
                raise AmbiguousOverrideError(
                    f'Specs {spec.name!r} and {spec_by_flag[flag].name!r} both give the flag {flag!r}.'
                )
        return flags

    def register_new_flag(self, flag: str, item_type: ItemTypeEnum, description: str = '', **fields: Any) -> FlagSpec:
        """Build a base spec of the class for `item_type` and add it.

        Args:
            flag: Flag name.
            item_type: Item type; selects `ModelFlagSpec`, `TimeSeriesFlagSpec` or `OtherFlagSpec`.
            description: Description of the flag.
            **fields: Further fields of the spec class, for example `unit`,
                `model_flag`, `index`, `topology_type` or `memberships`.

        Returns:
            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'},
            ... )
        """
        spec = FlagSpec.class_for(item_type)(name=flag, description=description, **fields)
        self.add_spec(spec)
        return spec

    def get_spec_by_name(self, name: str) -> FlagSpec | None:
        """Return the spec with this name (a flag name or a template), or `None`."""
        return self._specs.get(name)

    def has_spec(self, flag: Any) -> bool:
        """`True` if a spec declares the flag."""
        try:
            self.get_spec(flag)
        except UnknownFlagError:
            return False
        return True

    def get_spec(self, flag: Any) -> FlagSpec:
        """Return the spec that declares the flag.

        Raises:
            UnknownFlagError: No spec declares the flag.
            AmbiguousOverrideError: Two flag family specs cover the flag.
        """
        flag = str(flag)
        spec = self._spec_by_flag.get(flag)
        if spec is not None:
            return spec
        covering = [s for s in self._specs.values() if s.is_family and self._family_covers(s, flag)]
        if len(covering) > 1:
            raise AmbiguousOverrideError(f'Specs {[s.name for s in covering]} all cover the flag {flag!r}.')
        if not covering:
            raise UnknownFlagError(f'No flag spec declares the flag {flag!r}.')
        return covering[0]

    def _family_covers(self, spec: FlagSpec, flag: str) -> bool:
        if not spec.covers(flag):
            return False
        if isinstance(spec, LayerFlagSpec):
            return spec.layer_name_of(flag) in {layer.name for layer in self.get_layers(spec)}
        return True

    def check_references(self, 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_model` to
          its `layer_model` (`get_mapping_column`).
        - The edge model of each border layer has `edge_ends` that refer to
          the base model of its area layer (`get_edge_ends`).
        - The base model of each layer spec is a `ModelFlagSpec` with a
          topology type that fits the spec class: `Node` or
          `NodeConnectedElement` for an area spec, `Edge` for a border spec.
        - Each `model_flag` of a time series or layer spec names a model
          spec: a `ModelFlagSpec`, or a layer spec on a model base (a layer
          model flag). A `model_flag` template is checked for each flag of
          the spec. The template of a flag family is checked only with a
          `dataset` that 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.

        Args:
            dataset: The dataset that gives the values of the flag families.

        Raises:
            ValueError: A reference is not valid.
        """
        if self._references_checked and dataset is None:
            return
        for area_layer in self._layers.area_layers:
            self.get_mapping_column(area_layer)
        for border_layer in self._layers.border_layers:
            self.get_edge_ends(border_layer)
        for spec in self._specs.values():
            if isinstance(spec, LayerFlagSpec):
                self._check_layer_spec_base_model(spec)
            if getattr(spec, 'model_flag', None) is not None:
                self._check_model_flags(spec, self._flags_to_check(spec, dataset))
        self._references_checked = True

    def _flags_to_check(self, spec: FlagSpec, dataset: Dataset | None) -> list:
        flags = self.static_flags_of(spec)
        if flags is not None:
            return flags
        if not _has_placeholders(spec.model_flag):
            return [None]
        return [] if dataset is None else spec.expand(dataset)

    def _check_layer_spec_base_model(self, spec: LayerFlagSpec) -> None:
        if isinstance(spec.base, LayerFlagSpec):
            return
        model_flag = self._base_model_flag(spec)
        model_spec = self._spec_or_none(model_flag)
        allowed = [t.value for t in spec.BASE_TOPOLOGY_TYPES]
        if not isinstance(model_spec, ModelFlagSpec):
            raise ValueError(f'Spec {spec.name!r}: the base model {model_flag!r} names no ModelFlagSpec.')
        if model_spec.topology_type not in spec.BASE_TOPOLOGY_TYPES:
            raise ValueError(
                f'Spec {spec.name!r}: the base model {model_flag!r} has the topology type '
                f'{model_spec.topology_type.value}. Allowed: {allowed}.'
            )

    def _check_model_flags(self, spec: FlagSpec, flags: list) -> None:
        for flag in flags:
            model_flag = spec.model_flag if flag is None else self._fill_model_flag(spec, flag)
            if not self._is_model_spec(self._spec_or_none(model_flag)):
                raise ValueError(
                    f'Spec {spec.name!r}: model_flag {model_flag!r} names no ModelFlagSpec or layer model spec.'
                )

    @staticmethod
    def _is_model_spec(spec: FlagSpec | None) -> bool:
        return spec is not None and spec.item_type is ItemTypeEnum.Model

    @staticmethod
    def _fill_model_flag(spec: FlagSpec, flag: Any) -> str:
        if not _has_placeholders(spec.model_flag):
            return spec.model_flag
        return spec.model_flag.format(**spec.variant_of(flag).as_dict())

    def _spec_or_none(self, flag: Any) -> FlagSpec | None:
        try:
            return self.get_spec(flag)
        except UnknownFlagError:
            return None

    def get_item_type(self, 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."""
        return self.get_spec(flag).item_type

    def get_model_spec(self, 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.
        """
        model_flag = self.get_linked_model_flag(flag)
        return None if model_flag is None else self.get_spec(model_flag)

    def get_linked_model_flag(self, 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).
        """
        spec = self.get_spec(flag)
        if spec.item_type is ItemTypeEnum.Model:
            return str(flag)
        if isinstance(spec, LayerFlagSpec):
            if spec.model_flag is not None:
                return self._fill_model_flag(spec, flag)
            return self.get_layer_model_flag(self.get_layer(flag))
        if isinstance(spec, TimeSeriesFlagSpec) and spec.model_flag is not None:
            return self._fill_model_flag(spec, flag)
        return getattr(spec, 'model_flag', None)

    def get_unit(self, flag: Any) -> Units.Unit | None:
        """Return the unit of a flag from its spec. A model flag has no unit (`None`)."""
        return getattr(self.get_spec(flag), 'unit', None)

    def get_fill_value(self, flag: Any) -> float | None:
        """Return the `fill_value` of a flag from its spec, `None` if the spec has none."""
        return getattr(self.get_spec(flag), 'fill_value', None)

    def get_quantity_type_enum(self, 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.
        """
        spec = self.get_spec(flag)
        quantity_type = getattr(spec, 'quantity_type', None)
        if quantity_type is not None:
            return quantity_type
        unit = getattr(spec, 'unit', None)
        return QuantityTypeEnum.UNKNOWN if unit is None else Units.get_quantity_type_enum(unit)

    def get_topology_type(self, 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`.
        """
        spec = self.get_spec(flag)
        if isinstance(spec, LayerFlagSpec):
            return spec.topology_type
        model_spec = self.get_model_spec(flag)
        return TopologyTypeEnum.Other if model_spec is None else model_spec.topology_type

    def get_visualization_type(self, flag: Any) -> VisualizationTypeEnum:
        """Return the visualization type: the one of the model spec, else the one of the topology type."""
        if not isinstance(self.get_spec(flag), LayerFlagSpec):
            model_spec = self.get_model_spec(flag)
            if model_spec is not None and model_spec.visualization_type is not None:
                return model_spec.visualization_type
        return self.get_topology_type(flag).visualization_type

    def get_schema(self, 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:
            ValueError: A time series schema without exactly one time level.
        """
        spec = self.get_spec(flag)
        if isinstance(spec, LayerFlagSpec):
            schema = self._layer_schema(spec, flag)
        else:
            schema = spec.declared_schema(flag)
            if schema is None:
                schema = self._default_schema(flag)
        if spec.item_type is ItemTypeEnum.TimeSeries and len(schema.time_levels) != 1:
            raise ValueError(f'Flag {flag!r}: a time series schema needs exactly one index level with role time.')
        return schema

    def _default_schema(self, flag: Any) -> FrameSchema:
        level = self.get_object_level(self.get_linked_model_flag(flag))
        return FrameSchema(index=(Level('time', 'time'),), columns=(Level(level, 'object'),))

    def _layer_schema(self, spec: LayerFlagSpec, flag: Any) -> FrameSchema:
        layer = self.get_layer(flag)
        declared = spec.declared_schema(flag, layer)
        if declared is not None:
            return declared
        base_schema = self.get_schema(self.get_base_flag(flag))
        return FrameSchema(
            index=_rename_object_levels(base_schema.index, layer.index),
            columns=_rename_object_levels(base_schema.columns, layer.index),
            dtype=base_schema.dtype,
        )

    def get_base_flag(self, flag: Any) -> str:
        """Return the base flag of a layer flag. A consumed dimension takes its first value.

        Raises:
            ValueError: The flag is not a layer flag, or a consumed dimension
                has values resolved per dataset.
        """
        spec = self._layer_spec(flag)
        defaults = {}
        for dimension in spec.base.variants:
            if dimension.name in spec.consumes:
                if dimension.is_resolved_per_dataset:
                    raise ValueError(
                        f'Spec {spec.name!r}: the consumed dimension {dimension.name!r} has values resolved per '
                        f'dataset, so the index cannot name a base flag for {flag!r}.'
                    )
                defaults[dimension.name] = next(iter(dimension.values_for(None)))
        return self.get_layer_variant(flag).base_flag(**defaults)

    def get_layer_variant(self, 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:
            ValueError: The flag is not a layer flag.
        """
        spec = self._layer_spec(flag)
        values = spec.variant_of(flag).as_dict()
        base_layer = self.get_base_layer(spec, self._layers.get(values[spec.layer_placeholder]))
        if base_layer is not None:
            values[spec._base_layer_placeholder] = base_layer.name
        return LayerVariantValues(values, spec.base.name)

    def _layer_spec(self, flag: Any) -> LayerFlagSpec:
        spec = self.get_spec(flag)
        if not isinstance(spec, LayerFlagSpec):
            raise ValueError(f'{flag!r} is not a flag of a layer spec.')
        return spec

    def get_object_level(self, 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.
        """
        spec = self.get_spec(model_flag)
        if isinstance(spec, LayerFlagSpec):
            return self.get_layer(model_flag).index
        return spec.index

    def get_memberships(self, model_flag: Any) -> dict[str, str]:
        """Return the membership columns of a model flag: column to the model flag it refers to.

        Raises:
            ValueError: The flag is not declared by a `ModelFlagSpec`.
        """
        spec = self.get_spec(model_flag)
        if not isinstance(spec, ModelFlagSpec):
            raise ValueError(f'{model_flag!r} is not a model flag with memberships.')
        return dict(spec.memberships)

    def get_referencing_columns(self, 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')]
        """
        target = str(model_flag)
        pairs = []
        for spec in self._specs.values():
            if isinstance(spec, ModelFlagSpec):
                for flag in spec.expand() if not spec.is_family else []:
                    pairs += [(flag, column) for column, ref in spec.memberships.items() if ref == target]
        return pairs

    def get_mapping_column(self, layer: AreaLayer) -> str:
        """Return the membership column of `layer.base_model` whose target is `layer.layer_model`.

        Raises:
            ValueError: The base model has no `ModelFlagSpec`, or not exactly
                one membership to the layer model.
        """
        if not isinstance(self._spec_or_none(layer.base_model), ModelFlagSpec):
            raise ValueError(f'Area layer {layer.name!r}: base_model {layer.base_model!r} names no ModelFlagSpec.')
        columns = [c for c, target in self.get_memberships(layer.base_model).items() if target == layer.layer_model]
        if len(columns) != 1:
            raise ValueError(
                f'Area layer {layer.name!r}: {layer.base_model!r} needs exactly one membership to '
                f'{layer.layer_model!r}, found {columns}.'
            )
        return columns[0]

    def get_edge_ends(self, layer: BorderLayer) -> tuple[str, str]:
        """Return the `edge_ends` of the edge model of a border layer.

        Raises:
            ValueError: The edge model has no `edge_ends`, or its ends do not
                refer to the base model of the area layer.
        """
        spec = self._spec_or_none(layer.edge_model)
        if not isinstance(spec, ModelFlagSpec) or spec.edge_ends is None:
            raise ValueError(f'Border layer {layer.name!r}: edge model {layer.edge_model!r} declares no edge_ends.')
        base_model = self._layers.area_layer_of(layer).base_model
        if spec.memberships[spec.edge_ends[0]] != base_model:
            raise ValueError(
                f'Border layer {layer.name!r}: the edge_ends of {layer.edge_model!r} refer to '
                f'{spec.memberships[spec.edge_ends[0]]!r}, not to the base model {base_model!r} of the area layer.'
            )
        return spec.edge_ends

    def get_layers(self, spec: FlagSpec) -> list[AreaLayer | BorderLayer]:
        """Return the layers of a layer spec. Any other spec has none.

        - `AreaFlagSpec` on a node base: the area layers whose `base_model`
          is the model flag of the base.
        - `AreaFlagSpec` on a border base: the area layers with exactly one
          border layer among the layers of the base.
        - `BorderFlagSpec` on an edge base: the border layers whose
          `edge_model` is the model flag of the base.
        - `BorderFlagSpec` on an area base: the border layers whose area
          layer is a layer of the base.

        Raises:
            ValueError: An area layer has two border layers among the layers
                of a border base.
        """
        if isinstance(spec, AreaFlagSpec) and spec._has_layer_base:
            return [area for area in self._layers.area_layers if self._border_layer_for(spec, area) is not None]
        if isinstance(spec, AreaFlagSpec):
            return [layer for layer in self._layers.area_layers if layer.base_model == self._base_model_flag(spec)]
        if isinstance(spec, BorderFlagSpec) and spec._has_layer_base:
            names = {layer.name for layer in self.get_layers(spec.base)}
            return [layer for layer in self._layers.border_layers if layer.area_layer in names]
        if isinstance(spec, BorderFlagSpec):
            return [layer for layer in self._layers.border_layers if layer.edge_model == self._base_model_flag(spec)]
        return []

    def _border_layer_for(self, spec: AreaFlagSpec, area_layer: AreaLayer) -> BorderLayer | None:
        matches = [layer for layer in self.get_layers(spec.base) if layer.area_layer == area_layer.name]
        if len(matches) > 1:
            raise ValueError(
                f'Spec {spec.name!r}: area layer {area_layer.name!r} has two border layers among the layers of the '
                f'base: {[m.name for m in matches]}.'
            )
        return matches[0] if matches else None

    @staticmethod
    def _base_model_flag(spec: LayerFlagSpec) -> str:
        base = spec.base
        return base.name if isinstance(base, ModelFlagSpec) else base.model_flag

    def get_layer(self, flag: Any) -> AreaLayer | BorderLayer:
        """Return the layer of a layer flag.

        Raises:
            ValueError: The flag is not a layer flag.
        """
        return self._layers.get(self._layer_spec(flag).layer_name_of(flag))

    def get_base_layer(self, 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`.
        """
        if isinstance(spec, AreaFlagSpec) and spec._has_layer_base:
            return self._border_layer_for(spec, layer)
        if isinstance(spec, BorderFlagSpec) and spec._has_layer_base:
            return self._layers.area_layer_of(layer)
        return None

    def get_layer_model_flag(self, 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.
        """
        if isinstance(layer, AreaLayer):
            return layer.layer_model
        return self._border_model_flag(layer)

    def _border_model_flag(self, layer: BorderLayer) -> str | None:
        for spec in self._specs.values():
            if isinstance(spec, BorderFlagSpec) and spec.is_model and layer in self.get_layers(spec):
                return spec.name.format(**{spec.layer_placeholder: layer.name})
        return None

    def get_all_timeseries_flags_for_model_flag(self, dataset: Dataset, flag: Any) -> set[str]:
        """Return the accepted time series flags of `dataset` whose model flag is `flag`."""
        return {
            f
            for f in dataset.accepted_flags
            if self.get_item_type(f) == ItemTypeEnum.TimeSeries and self.get_linked_model_flag(f) == flag
        }

    def get_flag_from_string(self, flag_string: str) -> str:
        """Return the flag for a string. Flags are strings."""
        return flag_string

specs property

specs: tuple[FlagSpec, ...]

All specs of this index.

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.

layers property

layers: LayerSet

The area and border layers of this index.

union classmethod

union(indexes: Iterable[FlagIndex]) -> FlagIndex

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 (FlagSpec.same_as).

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
@classmethod
def union(cls, indexes: Iterable[FlagIndex]) -> FlagIndex:
    """Build one index with the specs and layers of several indexes.

    Args:
        indexes: The indexes to combine.

    Returns:
        A new index.

    Raises:
        ValueError: Two indexes have specs with the same name that are not
            the same (`FlagSpec.same_as`).
        AmbiguousOverrideError: Two indexes have different layers with the
            same name.
    """
    indexes = tuple(indexes)
    union = cls(layers=LayerSet.union(index.layers for index in indexes))
    for index in indexes:
        for spec in index.specs:
            existing = union._specs.get(spec.name)
            if existing is None:
                union.add_spec(spec)
            elif existing is not spec and not existing.same_as(spec):
                raise ValueError(f'Two different specs for {spec.name!r}. Specs with one name must be the same.')
    return union

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
def add_spec(self, spec: FlagSpec) -> None:
    """Add a spec.

    Args:
        spec: The spec to add.

    Raises:
        AmbiguousOverrideError: Another spec gives one of the flag names.
    """
    existing = self._specs.get(spec.name)
    if existing is spec:
        return
    if existing is not None:
        raise AmbiguousOverrideError(f'Two specs declare {spec.name!r}.')
    flags = self._checked_flags_of(spec, self._spec_by_flag)
    self._specs[spec.name] = spec
    self._spec_by_flag.update(dict.fromkeys(flags, spec))
    self._references_checked = False

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
def static_flags_of(self, 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.
    """
    if isinstance(spec, LayerFlagSpec):
        return spec.expand_on_layers(layer.name for layer in self.get_layers(spec))
    return None if spec.is_family else spec.expand()

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 ModelFlagSpec, TimeSeriesFlagSpec or OtherFlagSpec.

required
description str

Description of the flag.

''
**fields Any

Further fields of the spec class, for example unit, model_flag, index, topology_type or memberships.

{}

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
def register_new_flag(self, flag: str, item_type: ItemTypeEnum, description: str = '', **fields: Any) -> FlagSpec:
    """Build a base spec of the class for `item_type` and add it.

    Args:
        flag: Flag name.
        item_type: Item type; selects `ModelFlagSpec`, `TimeSeriesFlagSpec` or `OtherFlagSpec`.
        description: Description of the flag.
        **fields: Further fields of the spec class, for example `unit`,
            `model_flag`, `index`, `topology_type` or `memberships`.

    Returns:
        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'},
        ... )
    """
    spec = FlagSpec.class_for(item_type)(name=flag, description=description, **fields)
    self.add_spec(spec)
    return spec

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
def get_spec_by_name(self, name: str) -> FlagSpec | None:
    """Return the spec with this name (a flag name or a template), or `None`."""
    return self._specs.get(name)

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
def has_spec(self, flag: Any) -> bool:
    """`True` if a spec declares the flag."""
    try:
        self.get_spec(flag)
    except UnknownFlagError:
        return False
    return True

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
def get_spec(self, flag: Any) -> FlagSpec:
    """Return the spec that declares the flag.

    Raises:
        UnknownFlagError: No spec declares the flag.
        AmbiguousOverrideError: Two flag family specs cover the flag.
    """
    flag = str(flag)
    spec = self._spec_by_flag.get(flag)
    if spec is not None:
        return spec
    covering = [s for s in self._specs.values() if s.is_family and self._family_covers(s, flag)]
    if len(covering) > 1:
        raise AmbiguousOverrideError(f'Specs {[s.name for s in covering]} all cover the flag {flag!r}.')
    if not covering:
        raise UnknownFlagError(f'No flag spec declares the flag {flag!r}.')
    return covering[0]

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_model to its layer_model (get_mapping_column).
  • The edge model of each border layer has edge_ends that refer to the base model of its area layer (get_edge_ends).
  • The base model of each layer spec is a ModelFlagSpec with a topology type that fits the spec class: Node or NodeConnectedElement for an area spec, Edge for a border spec.
  • Each model_flag of a time series or layer spec names a model spec: a ModelFlagSpec, or a layer spec on a model base (a layer model flag). A model_flag template is checked for each flag of the spec. The template of a flag family is checked only with a dataset that 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
def check_references(self, 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_model` to
      its `layer_model` (`get_mapping_column`).
    - The edge model of each border layer has `edge_ends` that refer to
      the base model of its area layer (`get_edge_ends`).
    - The base model of each layer spec is a `ModelFlagSpec` with a
      topology type that fits the spec class: `Node` or
      `NodeConnectedElement` for an area spec, `Edge` for a border spec.
    - Each `model_flag` of a time series or layer spec names a model
      spec: a `ModelFlagSpec`, or a layer spec on a model base (a layer
      model flag). A `model_flag` template is checked for each flag of
      the spec. The template of a flag family is checked only with a
      `dataset` that 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.

    Args:
        dataset: The dataset that gives the values of the flag families.

    Raises:
        ValueError: A reference is not valid.
    """
    if self._references_checked and dataset is None:
        return
    for area_layer in self._layers.area_layers:
        self.get_mapping_column(area_layer)
    for border_layer in self._layers.border_layers:
        self.get_edge_ends(border_layer)
    for spec in self._specs.values():
        if isinstance(spec, LayerFlagSpec):
            self._check_layer_spec_base_model(spec)
        if getattr(spec, 'model_flag', None) is not None:
            self._check_model_flags(spec, self._flags_to_check(spec, dataset))
    self._references_checked = True

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
def get_item_type(self, 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."""
    return self.get_spec(flag).item_type

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
def get_model_spec(self, 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.
    """
    model_flag = self.get_linked_model_flag(flag)
    return None if model_flag is None else self.get_spec(model_flag)

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
def get_linked_model_flag(self, 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).
    """
    spec = self.get_spec(flag)
    if spec.item_type is ItemTypeEnum.Model:
        return str(flag)
    if isinstance(spec, LayerFlagSpec):
        if spec.model_flag is not None:
            return self._fill_model_flag(spec, flag)
        return self.get_layer_model_flag(self.get_layer(flag))
    if isinstance(spec, TimeSeriesFlagSpec) and spec.model_flag is not None:
        return self._fill_model_flag(spec, flag)
    return getattr(spec, 'model_flag', None)

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
def get_unit(self, flag: Any) -> Units.Unit | None:
    """Return the unit of a flag from its spec. A model flag has no unit (`None`)."""
    return getattr(self.get_spec(flag), 'unit', None)

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
def get_fill_value(self, flag: Any) -> float | None:
    """Return the `fill_value` of a flag from its spec, `None` if the spec has none."""
    return getattr(self.get_spec(flag), 'fill_value', None)

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
def get_quantity_type_enum(self, 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.
    """
    spec = self.get_spec(flag)
    quantity_type = getattr(spec, 'quantity_type', None)
    if quantity_type is not None:
        return quantity_type
    unit = getattr(spec, 'unit', None)
    return QuantityTypeEnum.UNKNOWN if unit is None else Units.get_quantity_type_enum(unit)

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
def get_topology_type(self, 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`.
    """
    spec = self.get_spec(flag)
    if isinstance(spec, LayerFlagSpec):
        return spec.topology_type
    model_spec = self.get_model_spec(flag)
    return TopologyTypeEnum.Other if model_spec is None else model_spec.topology_type

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
def get_visualization_type(self, flag: Any) -> VisualizationTypeEnum:
    """Return the visualization type: the one of the model spec, else the one of the topology type."""
    if not isinstance(self.get_spec(flag), LayerFlagSpec):
        model_spec = self.get_model_spec(flag)
        if model_spec is not None and model_spec.visualization_type is not None:
            return model_spec.visualization_type
    return self.get_topology_type(flag).visualization_type

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
def get_schema(self, 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:
        ValueError: A time series schema without exactly one time level.
    """
    spec = self.get_spec(flag)
    if isinstance(spec, LayerFlagSpec):
        schema = self._layer_schema(spec, flag)
    else:
        schema = spec.declared_schema(flag)
        if schema is None:
            schema = self._default_schema(flag)
    if spec.item_type is ItemTypeEnum.TimeSeries and len(schema.time_levels) != 1:
        raise ValueError(f'Flag {flag!r}: a time series schema needs exactly one index level with role time.')
    return schema

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
def get_base_flag(self, flag: Any) -> str:
    """Return the base flag of a layer flag. A consumed dimension takes its first value.

    Raises:
        ValueError: The flag is not a layer flag, or a consumed dimension
            has values resolved per dataset.
    """
    spec = self._layer_spec(flag)
    defaults = {}
    for dimension in spec.base.variants:
        if dimension.name in spec.consumes:
            if dimension.is_resolved_per_dataset:
                raise ValueError(
                    f'Spec {spec.name!r}: the consumed dimension {dimension.name!r} has values resolved per '
                    f'dataset, so the index cannot name a base flag for {flag!r}.'
                )
            defaults[dimension.name] = next(iter(dimension.values_for(None)))
    return self.get_layer_variant(flag).base_flag(**defaults)

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
def get_layer_variant(self, 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:
        ValueError: The flag is not a layer flag.
    """
    spec = self._layer_spec(flag)
    values = spec.variant_of(flag).as_dict()
    base_layer = self.get_base_layer(spec, self._layers.get(values[spec.layer_placeholder]))
    if base_layer is not None:
        values[spec._base_layer_placeholder] = base_layer.name
    return LayerVariantValues(values, spec.base.name)

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
def get_object_level(self, 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.
    """
    spec = self.get_spec(model_flag)
    if isinstance(spec, LayerFlagSpec):
        return self.get_layer(model_flag).index
    return spec.index

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 ModelFlagSpec.

Source code in src/mesqual/flag/flag_index.py
461
462
463
464
465
466
467
468
469
470
def get_memberships(self, model_flag: Any) -> dict[str, str]:
    """Return the membership columns of a model flag: column to the model flag it refers to.

    Raises:
        ValueError: The flag is not declared by a `ModelFlagSpec`.
    """
    spec = self.get_spec(model_flag)
    if not isinstance(spec, ModelFlagSpec):
        raise ValueError(f'{model_flag!r} is not a model flag with memberships.')
    return dict(spec.memberships)

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
def get_referencing_columns(self, 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')]
    """
    target = str(model_flag)
    pairs = []
    for spec in self._specs.values():
        if isinstance(spec, ModelFlagSpec):
            for flag in spec.expand() if not spec.is_family else []:
                pairs += [(flag, column) for column, ref in spec.memberships.items() if ref == target]
    return pairs

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 ModelFlagSpec, or not exactly one membership to the layer model.

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
def get_mapping_column(self, layer: AreaLayer) -> str:
    """Return the membership column of `layer.base_model` whose target is `layer.layer_model`.

    Raises:
        ValueError: The base model has no `ModelFlagSpec`, or not exactly
            one membership to the layer model.
    """
    if not isinstance(self._spec_or_none(layer.base_model), ModelFlagSpec):
        raise ValueError(f'Area layer {layer.name!r}: base_model {layer.base_model!r} names no ModelFlagSpec.')
    columns = [c for c, target in self.get_memberships(layer.base_model).items() if target == layer.layer_model]
    if len(columns) != 1:
        raise ValueError(
            f'Area layer {layer.name!r}: {layer.base_model!r} needs exactly one membership to '
            f'{layer.layer_model!r}, found {columns}.'
        )
    return columns[0]

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 edge_ends, or its ends do not refer to the base model of the area layer.

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
def get_edge_ends(self, layer: BorderLayer) -> tuple[str, str]:
    """Return the `edge_ends` of the edge model of a border layer.

    Raises:
        ValueError: The edge model has no `edge_ends`, or its ends do not
            refer to the base model of the area layer.
    """
    spec = self._spec_or_none(layer.edge_model)
    if not isinstance(spec, ModelFlagSpec) or spec.edge_ends is None:
        raise ValueError(f'Border layer {layer.name!r}: edge model {layer.edge_model!r} declares no edge_ends.')
    base_model = self._layers.area_layer_of(layer).base_model
    if spec.memberships[spec.edge_ends[0]] != base_model:
        raise ValueError(
            f'Border layer {layer.name!r}: the edge_ends of {layer.edge_model!r} refer to '
            f'{spec.memberships[spec.edge_ends[0]]!r}, not to the base model {base_model!r} of the area layer.'
        )
    return spec.edge_ends

get_layers

get_layers(spec: FlagSpec) -> list[AreaLayer | BorderLayer]

Return the layers of a layer spec. Any other spec has none.

  • AreaFlagSpec on a node base: the area layers whose base_model is the model flag of the base.
  • AreaFlagSpec on a border base: the area layers with exactly one border layer among the layers of the base.
  • BorderFlagSpec on an edge base: the border layers whose edge_model is the model flag of the base.
  • BorderFlagSpec on 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
def get_layers(self, spec: FlagSpec) -> list[AreaLayer | BorderLayer]:
    """Return the layers of a layer spec. Any other spec has none.

    - `AreaFlagSpec` on a node base: the area layers whose `base_model`
      is the model flag of the base.
    - `AreaFlagSpec` on a border base: the area layers with exactly one
      border layer among the layers of the base.
    - `BorderFlagSpec` on an edge base: the border layers whose
      `edge_model` is the model flag of the base.
    - `BorderFlagSpec` on an area base: the border layers whose area
      layer is a layer of the base.

    Raises:
        ValueError: An area layer has two border layers among the layers
            of a border base.
    """
    if isinstance(spec, AreaFlagSpec) and spec._has_layer_base:
        return [area for area in self._layers.area_layers if self._border_layer_for(spec, area) is not None]
    if isinstance(spec, AreaFlagSpec):
        return [layer for layer in self._layers.area_layers if layer.base_model == self._base_model_flag(spec)]
    if isinstance(spec, BorderFlagSpec) and spec._has_layer_base:
        names = {layer.name for layer in self.get_layers(spec.base)}
        return [layer for layer in self._layers.border_layers if layer.area_layer in names]
    if isinstance(spec, BorderFlagSpec):
        return [layer for layer in self._layers.border_layers if layer.edge_model == self._base_model_flag(spec)]
    return []

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
def get_layer(self, flag: Any) -> AreaLayer | BorderLayer:
    """Return the layer of a layer flag.

    Raises:
        ValueError: The flag is not a layer flag.
    """
    return self._layers.get(self._layer_spec(flag).layer_name_of(flag))

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
def get_base_layer(self, 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`.
    """
    if isinstance(spec, AreaFlagSpec) and spec._has_layer_base:
        return self._border_layer_for(spec, layer)
    if isinstance(spec, BorderFlagSpec) and spec._has_layer_base:
        return self._layers.area_layer_of(layer)
    return None

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
def get_layer_model_flag(self, 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.
    """
    if isinstance(layer, AreaLayer):
        return layer.layer_model
    return self._border_model_flag(layer)

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
def get_all_timeseries_flags_for_model_flag(self, dataset: Dataset, flag: Any) -> set[str]:
    """Return the accepted time series flags of `dataset` whose model flag is `flag`."""
    return {
        f
        for f in dataset.accepted_flags
        if self.get_item_type(f) == ItemTypeEnum.TimeSeries and self.get_linked_model_flag(f) == flag
    }

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
def get_flag_from_string(self, flag_string: str) -> str:
    """Return the flag for a string. Flags are strings."""
    return flag_string

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
class UnknownFlagError(KeyError, ValueError):
    """Raised when no flag spec declares a flag.

    A subclass of both `KeyError` and `ValueError`, so code that catches either keeps working.
    """

    def __str__(self) -> str:
        return str(self.args[0]) if self.args else ''

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
class AmbiguousOverrideError(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.
    """

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 Dataset.availability(flag).reason.

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
class FlagUnavailableError(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`.

    Args:
        flag: The flag.
        dataset: The name of the dataset.
        reason: Why the flag is not available, as in `Dataset.availability(flag).reason`.

    Attributes:
        flag: The flag.
        dataset: The name of the dataset.
        reason: Why the flag is not available.
    """

    def __init__(self, flag: str, dataset: str, reason: str):
        super().__init__(f'Flag {flag} is not available on dataset {dataset}: {reason}')
        self.flag = flag
        self.dataset = dataset
        self.reason = reason

    def __reduce__(self):
        return type(self), (self.flag, self.dataset, self.reason)

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 AreaFlagSpec, for example params.

{}

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
def 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.

    Args:
        bases: The base specs.
        aggregation: The area aggregation of all specs.
        name: Function of the base spec that returns the name of the area spec.
        description: Description of all specs, or a function of the base spec.
        **fields: Further fields of `AreaFlagSpec`, for example `params`.

    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}']
    """
    return tuple(
        AreaFlagSpec(
            name=name(base),
            base=base,
            aggregation=aggregation,
            description=description(base) if callable(description) else description,
            **fields,
        )
        for base in bases
    )