Skip to content

Membership Property Enrichers

MembershipTagging

Bases: Enum

How enriched property names are tagged when added to target DataFrames.

  • NONE: Property names remain unchanged (may cause conflicts with existing columns)
  • PREFIX: Property names get the membership name as prefix (e.g., 'node_voltage' from 'voltage')
  • SUFFIX: Property names get the membership name as suffix (e.g., 'voltage_node' from 'voltage')
Source code in src/mesqual/energy_data_handling/model_handling/membership_property_enrichers.py
14
15
16
17
18
19
20
21
22
23
24
class MembershipTagging(Enum):
    """How enriched property names are tagged when added to target DataFrames.

    - NONE: Property names remain unchanged (may cause conflicts with existing columns)
    - PREFIX: Property names get the membership name as prefix (e.g., 'node_voltage' from 'voltage')
    - SUFFIX: Property names get the membership name as suffix (e.g., 'voltage_node' from 'voltage')
    """

    NONE = 'none'
    PREFIX = 'prefix'
    SUFFIX = 'suffix'

MembershipPropertyEnricher

Adds the properties of the model objects that a frame refers to.

The membership columns of the target DataFrame come from the memberships of its model flag spec (FlagIndex.get_memberships), for example the column node of Generator.Model. The enricher adds all properties of the referenced model objects. A NaN membership gives NaN properties.

Parameters:

Name Type Description Default
membership_tag_separator str

Separator used between membership name and property when PREFIX or SUFFIX tagging is applied

'_'

Examples:

>>> generators = dataset.fetch('Generator.Model')
>>> enricher = MembershipPropertyEnricher()
>>> enriched = enricher.append_properties(generators, dataset, 'Generator.Model', MembershipTagging.PREFIX)
>>> list(enriched.columns)
['node', 'fuel', 'capacity', 'node_country', 'node_voltage', 'node_base_price', 'node_location']
>>> enriched[['node', 'node_country', 'node_voltage']].iloc[:2]
          node node_country  node_voltage
Generator
G1          N1           C1         380.0
G2          N1           C1         380.0
Source code in src/mesqual/energy_data_handling/model_handling/membership_property_enrichers.py
 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
class MembershipPropertyEnricher:
    """Adds the properties of the model objects that a frame refers to.

    The membership columns of the target DataFrame come from the
    `memberships` of its model flag spec (`FlagIndex.get_memberships`), for
    example the column `node` of `Generator.Model`. The enricher adds all
    properties of the referenced model objects. A NaN membership gives NaN
    properties.

    Args:
        membership_tag_separator: Separator used between membership name and property
            when PREFIX or SUFFIX tagging is applied

    Examples:
        >>> generators = dataset.fetch('Generator.Model')
        >>> enricher = MembershipPropertyEnricher()
        >>> enriched = enricher.append_properties(generators, dataset, 'Generator.Model', MembershipTagging.PREFIX)
        >>> list(enriched.columns)
        ['node', 'fuel', 'capacity', 'node_country', 'node_voltage', 'node_base_price', 'node_location']
        >>> enriched[['node', 'node_country', 'node_voltage']].iloc[:2]
                  node node_country  node_voltage
        Generator
        G1          N1           C1         380.0
        G2          N1           C1         380.0
    """

    def __init__(self, membership_tag_separator: str = '_'):
        """
        Initialize the membership property enricher.

        Args:
            membership_tag_separator: Character(s) used to separate membership names
                                     from property names in PREFIX/SUFFIX modes
        """
        self._membership_tag_separator = membership_tag_separator

    def identify_membership_columns(self, model_flag: str, column_names: list[str], dataset: Dataset) -> list[str]:
        """
        Return the columns of the frame that the model spec of `model_flag` declares as memberships.

        Args:
            model_flag: Model flag of the target DataFrame.
            column_names: Column names of the target DataFrame.
            dataset: Dataset whose flag index has the model spec.

        Returns:
            The membership columns that the frame has, in the order of `column_names`.

        Examples:
            >>> generators = dataset.fetch('Generator.Model')
            >>> MembershipPropertyEnricher().identify_membership_columns('Generator.Model', generators.columns, dataset)
            ['node']
        """
        memberships = dataset.flag_index.get_memberships(model_flag)
        return [col for col in column_names if col in memberships]

    def append_properties(
        self,
        target_df: pd.DataFrame,
        dataset: Dataset,
        model_flag: str,
        membership_tagging: MembershipTagging = MembershipTagging.NONE,
    ) -> pd.DataFrame:
        """
        Enriches target DataFrame with properties from all linked model objects.

        Identifies all membership columns and adds the properties of the
        referenced model objects.

        A NaN membership gets NaN properties. A referenced object that is
        missing from the source DataFrame gets NaN properties, and a warning is
        logged.

        Args:
            target_df: DataFrame to enrich (e.g., generator, line, storage data)
            dataset: Dataset containing linked model DataFrames with properties
            model_flag: Model flag of `target_df`. Its spec declares the memberships.
            membership_tagging: Strategy for naming enriched properties to avoid conflicts

        Returns:
            Enhanced DataFrame with all properties from linked model objects added.
                Original columns are preserved, new columns added based on memberships.
        """
        membership_columns = self.identify_membership_columns(model_flag, target_df.columns, dataset)
        result_df = target_df.copy()

        for column in membership_columns:
            result_df = self.append_single_membership_properties(
                result_df, dataset, model_flag, column, membership_tagging
            )

        return result_df

    def append_single_membership_properties(
        self,
        target_df: pd.DataFrame,
        dataset: Dataset,
        model_flag: str,
        membership_column: str,
        membership_tagging: MembershipTagging = MembershipTagging.NONE,
    ) -> pd.DataFrame:
        """
        Enriches target DataFrame with properties from a specific membership relationship.

        This method provides fine-grained control over property enrichment by handling
        a single membership column. Useful when custom logic is needed for specific
        relationships or when processing memberships sequentially with different
        tagging strategies.

        The memberships of the model spec of `model_flag` give the model flag
        that the column refers to. A left join keeps all target records and
        adds the available properties.

        A referenced object that is missing from the source DataFrame gets NaN
        properties, and a warning is logged.

        Args:
            target_df: DataFrame to enrich (must contain the membership column)
            dataset: Dataset with access to linked model DataFrames
            model_flag: Model flag of `target_df`.
            membership_column: Name of column containing object references (e.g., 'node', 'fuel_type')
            membership_tagging: Strategy for naming enriched properties

        Returns:
            DataFrame with properties from the linked model objects added.
                All original rows preserved; NaN memberships result in NaN properties.
        """
        source_flag = dataset.flag_index.get_memberships(model_flag)[membership_column]
        source_df = dataset.fetch(source_flag)

        membership_objects = target_df[membership_column].dropna().unique()
        missing_objects = set(membership_objects) - set(source_df.index)

        if missing_objects:
            self._log_missing_objects_warning(missing_objects, membership_column)

        source_properties = source_df.copy()

        match membership_tagging:
            case MembershipTagging.PREFIX:
                source_properties = source_properties.add_prefix(f'{membership_column}{self._membership_tag_separator}')
            case MembershipTagging.SUFFIX:
                source_properties = source_properties.add_suffix(f'{self._membership_tag_separator}{membership_column}')

        result_df = target_df.merge(source_properties, left_on=membership_column, right_index=True, how='left')

        return result_df

    def _log_missing_objects_warning(self, missing_objects: set, membership_column: str, max_show: int = 5):
        """
        Logs warning about missing objects in the source DataFrame.

        In energy system modeling, missing references can indicate data quality
        issues, model inconsistencies, or incomplete datasets. This method provides
        informative warnings to help identify and resolve such issues.

        Args:
            missing_objects: Set of object identifiers missing from source DataFrame
            membership_column: Name of the membership column being processed
            max_show: Maximum number of missing objects to display in the warning
        """
        num_missing = len(missing_objects)
        warning_suffix = ', and more' if num_missing > max_show else ''
        logger.warning(
            f'{num_missing} objects missing in source dataframe for {membership_column}: '
            f'{list(missing_objects)[:max_show]}{warning_suffix}.'
        )

__init__

__init__(membership_tag_separator: str = '_')

Initialize the membership property enricher.

Parameters:

Name Type Description Default
membership_tag_separator str

Character(s) used to separate membership names from property names in PREFIX/SUFFIX modes

'_'
Source code in src/mesqual/energy_data_handling/model_handling/membership_property_enrichers.py
53
54
55
56
57
58
59
60
61
def __init__(self, membership_tag_separator: str = '_'):
    """
    Initialize the membership property enricher.

    Args:
        membership_tag_separator: Character(s) used to separate membership names
                                 from property names in PREFIX/SUFFIX modes
    """
    self._membership_tag_separator = membership_tag_separator

identify_membership_columns

identify_membership_columns(model_flag: str, column_names: list[str], dataset: Dataset) -> list[str]

Return the columns of the frame that the model spec of model_flag declares as memberships.

Parameters:

Name Type Description Default
model_flag str

Model flag of the target DataFrame.

required
column_names list[str]

Column names of the target DataFrame.

required
dataset Dataset

Dataset whose flag index has the model spec.

required

Returns:

Type Description
list[str]

The membership columns that the frame has, in the order of column_names.

Examples:

>>> generators = dataset.fetch('Generator.Model')
>>> MembershipPropertyEnricher().identify_membership_columns('Generator.Model', generators.columns, dataset)
['node']
Source code in src/mesqual/energy_data_handling/model_handling/membership_property_enrichers.py
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
def identify_membership_columns(self, model_flag: str, column_names: list[str], dataset: Dataset) -> list[str]:
    """
    Return the columns of the frame that the model spec of `model_flag` declares as memberships.

    Args:
        model_flag: Model flag of the target DataFrame.
        column_names: Column names of the target DataFrame.
        dataset: Dataset whose flag index has the model spec.

    Returns:
        The membership columns that the frame has, in the order of `column_names`.

    Examples:
        >>> generators = dataset.fetch('Generator.Model')
        >>> MembershipPropertyEnricher().identify_membership_columns('Generator.Model', generators.columns, dataset)
        ['node']
    """
    memberships = dataset.flag_index.get_memberships(model_flag)
    return [col for col in column_names if col in memberships]

append_properties

append_properties(target_df: DataFrame, dataset: Dataset, model_flag: str, membership_tagging: MembershipTagging = NONE) -> DataFrame

Enriches target DataFrame with properties from all linked model objects.

Identifies all membership columns and adds the properties of the referenced model objects.

A NaN membership gets NaN properties. A referenced object that is missing from the source DataFrame gets NaN properties, and a warning is logged.

Parameters:

Name Type Description Default
target_df DataFrame

DataFrame to enrich (e.g., generator, line, storage data)

required
dataset Dataset

Dataset containing linked model DataFrames with properties

required
model_flag str

Model flag of target_df. Its spec declares the memberships.

required
membership_tagging MembershipTagging

Strategy for naming enriched properties to avoid conflicts

NONE

Returns:

Type Description
DataFrame

Enhanced DataFrame with all properties from linked model objects added. Original columns are preserved, new columns added based on memberships.

Source code in src/mesqual/energy_data_handling/model_handling/membership_property_enrichers.py
 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
def append_properties(
    self,
    target_df: pd.DataFrame,
    dataset: Dataset,
    model_flag: str,
    membership_tagging: MembershipTagging = MembershipTagging.NONE,
) -> pd.DataFrame:
    """
    Enriches target DataFrame with properties from all linked model objects.

    Identifies all membership columns and adds the properties of the
    referenced model objects.

    A NaN membership gets NaN properties. A referenced object that is
    missing from the source DataFrame gets NaN properties, and a warning is
    logged.

    Args:
        target_df: DataFrame to enrich (e.g., generator, line, storage data)
        dataset: Dataset containing linked model DataFrames with properties
        model_flag: Model flag of `target_df`. Its spec declares the memberships.
        membership_tagging: Strategy for naming enriched properties to avoid conflicts

    Returns:
        Enhanced DataFrame with all properties from linked model objects added.
            Original columns are preserved, new columns added based on memberships.
    """
    membership_columns = self.identify_membership_columns(model_flag, target_df.columns, dataset)
    result_df = target_df.copy()

    for column in membership_columns:
        result_df = self.append_single_membership_properties(
            result_df, dataset, model_flag, column, membership_tagging
        )

    return result_df

append_single_membership_properties

append_single_membership_properties(target_df: DataFrame, dataset: Dataset, model_flag: str, membership_column: str, membership_tagging: MembershipTagging = NONE) -> DataFrame

Enriches target DataFrame with properties from a specific membership relationship.

This method provides fine-grained control over property enrichment by handling a single membership column. Useful when custom logic is needed for specific relationships or when processing memberships sequentially with different tagging strategies.

The memberships of the model spec of model_flag give the model flag that the column refers to. A left join keeps all target records and adds the available properties.

A referenced object that is missing from the source DataFrame gets NaN properties, and a warning is logged.

Parameters:

Name Type Description Default
target_df DataFrame

DataFrame to enrich (must contain the membership column)

required
dataset Dataset

Dataset with access to linked model DataFrames

required
model_flag str

Model flag of target_df.

required
membership_column str

Name of column containing object references (e.g., 'node', 'fuel_type')

required
membership_tagging MembershipTagging

Strategy for naming enriched properties

NONE

Returns:

Type Description
DataFrame

DataFrame with properties from the linked model objects added. All original rows preserved; NaN memberships result in NaN properties.

Source code in src/mesqual/energy_data_handling/model_handling/membership_property_enrichers.py
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
def append_single_membership_properties(
    self,
    target_df: pd.DataFrame,
    dataset: Dataset,
    model_flag: str,
    membership_column: str,
    membership_tagging: MembershipTagging = MembershipTagging.NONE,
) -> pd.DataFrame:
    """
    Enriches target DataFrame with properties from a specific membership relationship.

    This method provides fine-grained control over property enrichment by handling
    a single membership column. Useful when custom logic is needed for specific
    relationships or when processing memberships sequentially with different
    tagging strategies.

    The memberships of the model spec of `model_flag` give the model flag
    that the column refers to. A left join keeps all target records and
    adds the available properties.

    A referenced object that is missing from the source DataFrame gets NaN
    properties, and a warning is logged.

    Args:
        target_df: DataFrame to enrich (must contain the membership column)
        dataset: Dataset with access to linked model DataFrames
        model_flag: Model flag of `target_df`.
        membership_column: Name of column containing object references (e.g., 'node', 'fuel_type')
        membership_tagging: Strategy for naming enriched properties

    Returns:
        DataFrame with properties from the linked model objects added.
            All original rows preserved; NaN memberships result in NaN properties.
    """
    source_flag = dataset.flag_index.get_memberships(model_flag)[membership_column]
    source_df = dataset.fetch(source_flag)

    membership_objects = target_df[membership_column].dropna().unique()
    missing_objects = set(membership_objects) - set(source_df.index)

    if missing_objects:
        self._log_missing_objects_warning(missing_objects, membership_column)

    source_properties = source_df.copy()

    match membership_tagging:
        case MembershipTagging.PREFIX:
            source_properties = source_properties.add_prefix(f'{membership_column}{self._membership_tag_separator}')
        case MembershipTagging.SUFFIX:
            source_properties = source_properties.add_suffix(f'{self._membership_tag_separator}{membership_column}')

    result_df = target_df.merge(source_properties, left_on=membership_column, right_index=True, how='left')

    return result_df

DirectionalMembershipPropertyEnricher

Adds the properties of both ends of directional memberships, such as node_from and node_to.

A pair is two membership columns with the same base name and the from and to identifiers (default: '_from' and '_to'), which refer to the same model flag. The enricher adds the properties of each end, tagged with the direction.

Parameters:

Name Type Description Default
from_identifier str

Suffix/prefix identifying 'from' direction (default: '_from')

'_from'
to_identifier str

Suffix/prefix identifying 'to' direction (default: '_to')

'_to'
membership_tag_separator str

Separator for property name construction

'_'

Examples:

>>> lines = dataset.fetch('Line.Model')
>>> enricher = DirectionalMembershipPropertyEnricher()
>>> enricher.identify_from_to_columns('Line.Model', lines.columns, dataset)
['node']
>>> enriched = enricher.append_properties(lines, dataset, 'Line.Model', MembershipTagging.NONE)
>>> enriched[['node_from', 'country_from', 'node_to', 'country_to']].iloc[:2]
     node_from country_from node_to country_to
Line
L1          N1           C1      N2         C2
L2          N2           C2      N3         C1
Source code in src/mesqual/energy_data_handling/model_handling/membership_property_enrichers.py
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
class DirectionalMembershipPropertyEnricher:
    """Adds the properties of both ends of directional memberships, such as `node_from` and `node_to`.

    A pair is two membership columns with the same base name and the from
    and to identifiers (default: '_from' and '_to'), which refer to the same
    model flag. The enricher adds the properties of each end, tagged with the
    direction.

    Args:
        from_identifier: Suffix/prefix identifying 'from' direction (default: '_from')
        to_identifier: Suffix/prefix identifying 'to' direction (default: '_to')
        membership_tag_separator: Separator for property name construction

    Examples:
        >>> lines = dataset.fetch('Line.Model')
        >>> enricher = DirectionalMembershipPropertyEnricher()
        >>> enricher.identify_from_to_columns('Line.Model', lines.columns, dataset)
        ['node']
        >>> enriched = enricher.append_properties(lines, dataset, 'Line.Model', MembershipTagging.NONE)
        >>> enriched[['node_from', 'country_from', 'node_to', 'country_to']].iloc[:2]
             node_from country_from node_to country_to
        Line
        L1          N1           C1      N2         C2
        L2          N2           C2      N3         C1
    """

    def __init__(
        self,
        from_identifier: str = '_from',
        to_identifier: str = '_to',
        membership_tag_separator: str = '_',
    ):
        """
        Initialize the directional membership property enricher.

        Args:
            from_identifier: String identifying source/origin columns (e.g., '_from', 'source_')
            to_identifier: String identifying destination/target columns (e.g., '_to', 'dest_')
            membership_tag_separator: Character(s) separating membership names from properties
        """
        self._from_identifier = from_identifier
        self._to_identifier = to_identifier
        self._membership_tag_separator = membership_tag_separator
        self._tag_finder = CommonBaseKeyFinder(from_identifier, to_identifier)

    def identify_from_to_columns(self, model_flag: str, column_names: list[str], dataset: Dataset) -> list[str]:
        """
        Identifies base names for directional membership column pairs.

        Analyzes column names to find base membership types that have both 'from'
        and 'to' variants. For example, identifies 'node' as a base when both
        'node_from' and 'node_to' columns exist and the model spec of
        `model_flag` declares both as memberships to the same model flag.

        Args:
            model_flag: Model flag of the target DataFrame.
            column_names: List of column names from the target DataFrame
            dataset: Dataset whose flag index has the model spec

        Returns:
            List of base column names that have both from/to variants
        """
        memberships = dataset.flag_index.get_memberships(model_flag)
        potential_columns = self._tag_finder.get_keys_for_which_all_association_tags_appear(column_names)
        return [col for col in potential_columns if self._directional_target(col, memberships, column_names)]

    def _directional_target(self, base_column: str, memberships: dict[str, str], column_names) -> str | None:
        """The model flag that both directional columns of `base_column` refer to, else `None`."""
        targets = {
            memberships.get(self._get_full_column_name(base_column, tag, column_names))
            for tag in (self._from_identifier, self._to_identifier)
        }
        return targets.pop() if len(targets) == 1 else None

    def append_properties(
        self,
        target_df: pd.DataFrame,
        dataset: Dataset,
        model_flag: str,
        membership_tagging: MembershipTagging = MembershipTagging.NONE,
    ) -> pd.DataFrame:
        """
        Enriches DataFrame with properties from all directional relationships.

        Identifies all from/to column pairs and adds the properties of the
        objects at both ends, for example the countries of the nodes of a line.

        Each directional relationship results in two sets of enriched properties:
        one for the 'from' direction and one for the 'to' direction, clearly
        distinguished by directional suffixes.

        A referenced object that is missing from the source DataFrame gets NaN
        properties, and a warning is logged.

        Args:
            target_df: DataFrame with directional relationships (e.g., transmission lines)
            dataset: Dataset containing model objects and their properties
            model_flag: Model flag of `target_df`. Its spec declares the memberships.
            membership_tagging: Strategy for property naming (applied before directional tags)

        Returns:
            Enhanced DataFrame with directional properties added. Original data preserved,
                new columns follow pattern: [prefix_]property_name[_suffix]_direction
        """
        membership_base_columns = self.identify_from_to_columns(model_flag, target_df.columns, dataset)
        result_df = target_df.copy()

        for base_column in membership_base_columns:
            result_df = self.append_directional_properties(
                result_df, dataset, model_flag, base_column, membership_tagging
            )

        return result_df

    def append_directional_properties(
        self,
        target_df: pd.DataFrame,
        dataset: Dataset,
        model_flag: str,
        base_column: str,
        membership_tagging: MembershipTagging = MembershipTagging.NONE,
    ) -> pd.DataFrame:
        """
        Enriches the frame with the properties of the model flag that both directional columns refer to.

        Args:
            target_df: DataFrame containing the directional columns.
            dataset: Dataset with the referenced model flag.
            model_flag: Model flag of `target_df`. Its spec declares the memberships.
            base_column: Base membership name (e.g., 'node' for 'node_from'/'node_to').
            membership_tagging: Property naming strategy (applied before directional tags).

        Raises:
            ValueError: The two directional columns are not memberships to the same model flag.
        """
        memberships = dataset.flag_index.get_memberships(model_flag)
        source_flag = self._directional_target(base_column, memberships, target_df.columns)
        if source_flag is None:
            raise ValueError(
                f'{model_flag}: the directional columns of {base_column!r} are no memberships to one model flag.'
            )
        source_df = dataset.fetch(source_flag)
        return self.append_directional_properties_in_source_to_target_df(
            target_df,
            source_df,
            base_column,
            membership_tagging,
        )

    def append_directional_properties_in_source_to_target_df(
        self,
        target_df: pd.DataFrame,
        source_df: pd.DataFrame,
        base_column: str,
        membership_tagging: MembershipTagging = MembershipTagging.NONE,
    ) -> pd.DataFrame:
        """
        Enriches DataFrame with properties from a directional relationship.

        Handles a single from/to membership pair by adding the corresponding model
        DataFrame's properties with directional tags.

        The method processes both directions (from/to) for the specified base column,
        adding properties with appropriate directional suffixes. A NaN
        membership gets NaN properties. A referenced object that is missing
        from the source DataFrame gets NaN properties, and a warning is logged.

        Args:
            target_df: DataFrame containing the directional columns
            source_df: DataFrame containing the properties
            base_column: Base membership name (e.g., 'node' for 'node_from'/'node_to')
            membership_tagging: Property naming strategy (applied before directional tags)

        Returns:
            DataFrame with directional properties added for the specified relationship.
                Properties follow naming pattern: [prefix_]property[_suffix]_direction
        """
        result_df = target_df.copy()
        for tag in [self._from_identifier, self._to_identifier]:
            membership_column = self._get_full_column_name(base_column, tag, target_df.columns)

            if membership_column not in target_df.columns:
                continue

            membership_objects = target_df[membership_column].dropna().unique()
            missing_objects = set(membership_objects) - set(source_df.index)

            if missing_objects:
                self._log_missing_objects_warning(missing_objects, membership_column)

            source_properties = source_df.copy()

            match membership_tagging:
                case MembershipTagging.PREFIX:
                    source_properties = source_properties.add_prefix(f'{base_column}{self._membership_tag_separator}')
                case MembershipTagging.SUFFIX:
                    source_properties = source_properties.add_suffix(f'{self._membership_tag_separator}{base_column}')

            source_properties = source_properties.add_suffix(tag)

            result_df = result_df.merge(source_properties, left_on=membership_column, right_index=True, how='left')
        return result_df

    def _get_full_column_name(self, base_column: str, tag: str, df_columns: list[str]) -> str:
        """
        Determines the actual column name for a directional membership.

        Returns `{base_column}{tag}` if it is a column, else `{tag}{base_column}`.

        Args:
            base_column: Base membership name (e.g., 'node')
            tag: Directional identifier (e.g., '_from', '_to')
            df_columns: List of actual column names in the DataFrame

        Returns:
            Actual column name found in the DataFrame
        """
        test_suffix = f'{base_column}{tag}'
        return test_suffix if test_suffix in df_columns else f'{tag}{base_column}'

    def _log_missing_objects_warning(self, missing_objects: set, membership_column: str, max_show: int = 5):
        num_missing = len(missing_objects)
        warning_suffix = ', and more' if num_missing > max_show else ''
        logger.warning(
            f'{num_missing} objects missing in source dataframe for {membership_column}: '
            f'{list(missing_objects)[:max_show]}{warning_suffix}.'
        )

__init__

__init__(from_identifier: str = '_from', to_identifier: str = '_to', membership_tag_separator: str = '_')

Initialize the directional membership property enricher.

Parameters:

Name Type Description Default
from_identifier str

String identifying source/origin columns (e.g., 'from', 'source')

'_from'
to_identifier str

String identifying destination/target columns (e.g., 'to', 'dest')

'_to'
membership_tag_separator str

Character(s) separating membership names from properties

'_'
Source code in src/mesqual/energy_data_handling/model_handling/membership_property_enrichers.py
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
def __init__(
    self,
    from_identifier: str = '_from',
    to_identifier: str = '_to',
    membership_tag_separator: str = '_',
):
    """
    Initialize the directional membership property enricher.

    Args:
        from_identifier: String identifying source/origin columns (e.g., '_from', 'source_')
        to_identifier: String identifying destination/target columns (e.g., '_to', 'dest_')
        membership_tag_separator: Character(s) separating membership names from properties
    """
    self._from_identifier = from_identifier
    self._to_identifier = to_identifier
    self._membership_tag_separator = membership_tag_separator
    self._tag_finder = CommonBaseKeyFinder(from_identifier, to_identifier)

identify_from_to_columns

identify_from_to_columns(model_flag: str, column_names: list[str], dataset: Dataset) -> list[str]

Identifies base names for directional membership column pairs.

Analyzes column names to find base membership types that have both 'from' and 'to' variants. For example, identifies 'node' as a base when both 'node_from' and 'node_to' columns exist and the model spec of model_flag declares both as memberships to the same model flag.

Parameters:

Name Type Description Default
model_flag str

Model flag of the target DataFrame.

required
column_names list[str]

List of column names from the target DataFrame

required
dataset Dataset

Dataset whose flag index has the model spec

required

Returns:

Type Description
list[str]

List of base column names that have both from/to variants

Source code in src/mesqual/energy_data_handling/model_handling/membership_property_enrichers.py
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
def identify_from_to_columns(self, model_flag: str, column_names: list[str], dataset: Dataset) -> list[str]:
    """
    Identifies base names for directional membership column pairs.

    Analyzes column names to find base membership types that have both 'from'
    and 'to' variants. For example, identifies 'node' as a base when both
    'node_from' and 'node_to' columns exist and the model spec of
    `model_flag` declares both as memberships to the same model flag.

    Args:
        model_flag: Model flag of the target DataFrame.
        column_names: List of column names from the target DataFrame
        dataset: Dataset whose flag index has the model spec

    Returns:
        List of base column names that have both from/to variants
    """
    memberships = dataset.flag_index.get_memberships(model_flag)
    potential_columns = self._tag_finder.get_keys_for_which_all_association_tags_appear(column_names)
    return [col for col in potential_columns if self._directional_target(col, memberships, column_names)]

append_properties

append_properties(target_df: DataFrame, dataset: Dataset, model_flag: str, membership_tagging: MembershipTagging = NONE) -> DataFrame

Enriches DataFrame with properties from all directional relationships.

Identifies all from/to column pairs and adds the properties of the objects at both ends, for example the countries of the nodes of a line.

Each directional relationship results in two sets of enriched properties: one for the 'from' direction and one for the 'to' direction, clearly distinguished by directional suffixes.

A referenced object that is missing from the source DataFrame gets NaN properties, and a warning is logged.

Parameters:

Name Type Description Default
target_df DataFrame

DataFrame with directional relationships (e.g., transmission lines)

required
dataset Dataset

Dataset containing model objects and their properties

required
model_flag str

Model flag of target_df. Its spec declares the memberships.

required
membership_tagging MembershipTagging

Strategy for property naming (applied before directional tags)

NONE

Returns:

Type Description
DataFrame

Enhanced DataFrame with directional properties added. Original data preserved, new columns follow pattern: [prefix_]property_name[_suffix]_direction

Source code in src/mesqual/energy_data_handling/model_handling/membership_property_enrichers.py
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
def append_properties(
    self,
    target_df: pd.DataFrame,
    dataset: Dataset,
    model_flag: str,
    membership_tagging: MembershipTagging = MembershipTagging.NONE,
) -> pd.DataFrame:
    """
    Enriches DataFrame with properties from all directional relationships.

    Identifies all from/to column pairs and adds the properties of the
    objects at both ends, for example the countries of the nodes of a line.

    Each directional relationship results in two sets of enriched properties:
    one for the 'from' direction and one for the 'to' direction, clearly
    distinguished by directional suffixes.

    A referenced object that is missing from the source DataFrame gets NaN
    properties, and a warning is logged.

    Args:
        target_df: DataFrame with directional relationships (e.g., transmission lines)
        dataset: Dataset containing model objects and their properties
        model_flag: Model flag of `target_df`. Its spec declares the memberships.
        membership_tagging: Strategy for property naming (applied before directional tags)

    Returns:
        Enhanced DataFrame with directional properties added. Original data preserved,
            new columns follow pattern: [prefix_]property_name[_suffix]_direction
    """
    membership_base_columns = self.identify_from_to_columns(model_flag, target_df.columns, dataset)
    result_df = target_df.copy()

    for base_column in membership_base_columns:
        result_df = self.append_directional_properties(
            result_df, dataset, model_flag, base_column, membership_tagging
        )

    return result_df

append_directional_properties

append_directional_properties(target_df: DataFrame, dataset: Dataset, model_flag: str, base_column: str, membership_tagging: MembershipTagging = NONE) -> DataFrame

Enriches the frame with the properties of the model flag that both directional columns refer to.

Parameters:

Name Type Description Default
target_df DataFrame

DataFrame containing the directional columns.

required
dataset Dataset

Dataset with the referenced model flag.

required
model_flag str

Model flag of target_df. Its spec declares the memberships.

required
base_column str

Base membership name (e.g., 'node' for 'node_from'/'node_to').

required
membership_tagging MembershipTagging

Property naming strategy (applied before directional tags).

NONE

Raises:

Type Description
ValueError

The two directional columns are not memberships to the same model flag.

Source code in src/mesqual/energy_data_handling/model_handling/membership_property_enrichers.py
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
def append_directional_properties(
    self,
    target_df: pd.DataFrame,
    dataset: Dataset,
    model_flag: str,
    base_column: str,
    membership_tagging: MembershipTagging = MembershipTagging.NONE,
) -> pd.DataFrame:
    """
    Enriches the frame with the properties of the model flag that both directional columns refer to.

    Args:
        target_df: DataFrame containing the directional columns.
        dataset: Dataset with the referenced model flag.
        model_flag: Model flag of `target_df`. Its spec declares the memberships.
        base_column: Base membership name (e.g., 'node' for 'node_from'/'node_to').
        membership_tagging: Property naming strategy (applied before directional tags).

    Raises:
        ValueError: The two directional columns are not memberships to the same model flag.
    """
    memberships = dataset.flag_index.get_memberships(model_flag)
    source_flag = self._directional_target(base_column, memberships, target_df.columns)
    if source_flag is None:
        raise ValueError(
            f'{model_flag}: the directional columns of {base_column!r} are no memberships to one model flag.'
        )
    source_df = dataset.fetch(source_flag)
    return self.append_directional_properties_in_source_to_target_df(
        target_df,
        source_df,
        base_column,
        membership_tagging,
    )

append_directional_properties_in_source_to_target_df

append_directional_properties_in_source_to_target_df(target_df: DataFrame, source_df: DataFrame, base_column: str, membership_tagging: MembershipTagging = NONE) -> DataFrame

Enriches DataFrame with properties from a directional relationship.

Handles a single from/to membership pair by adding the corresponding model DataFrame's properties with directional tags.

The method processes both directions (from/to) for the specified base column, adding properties with appropriate directional suffixes. A NaN membership gets NaN properties. A referenced object that is missing from the source DataFrame gets NaN properties, and a warning is logged.

Parameters:

Name Type Description Default
target_df DataFrame

DataFrame containing the directional columns

required
source_df DataFrame

DataFrame containing the properties

required
base_column str

Base membership name (e.g., 'node' for 'node_from'/'node_to')

required
membership_tagging MembershipTagging

Property naming strategy (applied before directional tags)

NONE

Returns:

Type Description
DataFrame

DataFrame with directional properties added for the specified relationship. Properties follow naming pattern: [prefix_]property[_suffix]_direction

Source code in src/mesqual/energy_data_handling/model_handling/membership_property_enrichers.py
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
def append_directional_properties_in_source_to_target_df(
    self,
    target_df: pd.DataFrame,
    source_df: pd.DataFrame,
    base_column: str,
    membership_tagging: MembershipTagging = MembershipTagging.NONE,
) -> pd.DataFrame:
    """
    Enriches DataFrame with properties from a directional relationship.

    Handles a single from/to membership pair by adding the corresponding model
    DataFrame's properties with directional tags.

    The method processes both directions (from/to) for the specified base column,
    adding properties with appropriate directional suffixes. A NaN
    membership gets NaN properties. A referenced object that is missing
    from the source DataFrame gets NaN properties, and a warning is logged.

    Args:
        target_df: DataFrame containing the directional columns
        source_df: DataFrame containing the properties
        base_column: Base membership name (e.g., 'node' for 'node_from'/'node_to')
        membership_tagging: Property naming strategy (applied before directional tags)

    Returns:
        DataFrame with directional properties added for the specified relationship.
            Properties follow naming pattern: [prefix_]property[_suffix]_direction
    """
    result_df = target_df.copy()
    for tag in [self._from_identifier, self._to_identifier]:
        membership_column = self._get_full_column_name(base_column, tag, target_df.columns)

        if membership_column not in target_df.columns:
            continue

        membership_objects = target_df[membership_column].dropna().unique()
        missing_objects = set(membership_objects) - set(source_df.index)

        if missing_objects:
            self._log_missing_objects_warning(missing_objects, membership_column)

        source_properties = source_df.copy()

        match membership_tagging:
            case MembershipTagging.PREFIX:
                source_properties = source_properties.add_prefix(f'{base_column}{self._membership_tag_separator}')
            case MembershipTagging.SUFFIX:
                source_properties = source_properties.add_suffix(f'{self._membership_tag_separator}{base_column}')

        source_properties = source_properties.add_suffix(tag)

        result_df = result_df.merge(source_properties, left_on=membership_column, right_index=True, how='left')
    return result_df