triplets.cgmes_tools module

triplets.cgmes_tools.darw_relations_graph(reference_data, ID_COLUMN, notebook=False)

Create a temporary HTML file to visualize relations in a CGMES dataset.

Parameters:

• reference_data (pandas.DataFrame) – Triplet dataset containing reference data for visualization.

• ID_COLUMN (str) – Column name containing IDs (e.g., ‘ID’).

• notebook (bool, optional) – If True, render the graph for Jupyter notebook (default is False).

Returns:

File path to the generated HTML file (if notebook=False) or the Network object (if notebook=True).

Return type:

str or pyvis.network.Network

Notes

• Uses pyvis for visualization with a hierarchical layout.

• Nodes include object data in hover tooltips.

Examples

>>> file_path = darw_relations_graph(data, 'ID')

triplets.cgmes_tools.draw_relations(data, UUID, notebook=False, levels=2)

Visualize all relations (incoming and outgoing) for a specific UUID in a CGMES dataset.

Parameters:

• data (pandas.DataFrame) – Triplet dataset containing CGMES data.

• UUID (str) – UUID of the object to visualize relations for.

• notebook (bool, optional) – If True, render the graph for Jupyter notebook (default is False).

• levels (int, optional) – Number of levels to traverse for relations (default is 2).

Returns:

File path to the generated HTML file (if notebook=False) or the Network object (if notebook=True).

Return type:

str or pyvis.network.Network

Examples

>>> file_path = draw_relations(data, 'uuid1', levels=3)

triplets.cgmes_tools.draw_relations_from(data, UUID, notebook=False)

Visualize relations originating from a specific UUID in a CGMES dataset.

Parameters:

• data (pandas.DataFrame) – Triplet dataset containing CGMES data.

• UUID (str) – UUID of the object to visualize outgoing relations for.

• notebook (bool, optional) – If True, render the graph for Jupyter notebook (default is False).

Returns:

File path to the generated HTML file (if notebook=False) or the Network object (if notebook=True).

Return type:

str or pyvis.network.Network

Examples

>>> file_path = draw_relations_from(data, 'uuid1')

triplets.cgmes_tools.draw_relations_to(data, UUID, notebook=False)

Visualize relations pointing to a specific UUID in a CGMES dataset.

Parameters:

• data (pandas.DataFrame) – Triplet dataset containing CGMES data.

• UUID (str) – UUID of the object to visualize incoming relations for.

• notebook (bool, optional) – If True, render the graph for Jupyter notebook (default is False).

Returns:

File path to the generated HTML file (if notebook=False) or the Network object (if notebook=True).

Return type:

str or pyvis.network.Network

Examples

>>> file_path = draw_relations_to(data, 'uuid1')

triplets.cgmes_tools.filter_dataframe_by_dataframe(data, filter_data, filter_column_name)

Filter a CGMES triplet dataset using IDs from another DataFrame.

Parameters:

• data (pandas.DataFrame) – Triplet dataset containing CGMES data.

• filter_data (pandas.DataFrame) – DataFrame containing IDs to filter by.

• filter_column_name (str) – Column name in filter_data containing IDs (e.g., ‘PowerTransformer.ID’).

Returns:

Filtered DataFrame with columns [‘ID_<class_name>’, ‘KEY’, ‘VALUE’].

Return type:

pandas.DataFrame

Examples

>>> filtered = filter_dataframe_by_dataframe(data, filter_df, 'PowerTransformer.ID')

triplets.cgmes_tools.generate_instances_ID(dependencies={'EQ': ['EQBD'], 'EQBD': [], 'SSH': ['EQ'], 'SV': ['TPBD', 'TP', 'SSH'], 'TP': ['EQ'], 'TPBD': ['EQBD']})

Generate UUIDs for each profile defined in the dependencies dictionary.

Parameters:

dependencies (dict, optional) – Dictionary mapping profile names to lists of dependent profile names. Defaults to a predefined CGMES profile dependencies dictionary.

Returns:

Dictionary with profile names as keys and generated UUIDs as values.

Return type:

dict

Examples

>>> generate_instances_ID()
{'EQ': '123e4567-e89b-12d3-a456-426614174000', ...}

triplets.cgmes_tools.get_EIC_to_mRID_map(data, type)

Map Energy Identification Codes (EIC) to mRIDs for a specific object type.

Parameters:

• data (pandas.DataFrame) – Triplet dataset containing CGMES data.

• type (str) – Object type to filter (e.g., ‘PowerTransformer’).

Returns:

DataFrame with columns [‘mRID’, ‘EIC’] mapping EICs to mRIDs.

Return type:

pandas.DataFrame

Notes

• Filters data for objects of the specified type with ‘IdentifiedObject.energyIdentCodeEic’ key.

• TODO: Add support for type=None to return all types and include type in result.

Examples

>>> eic_map = get_EIC_to_mRID_map(data, 'PowerTransformer')
>>> print(eic_map)
   mRID                                  EIC
0  uuid1  10X1001A1001A021

triplets.cgmes_tools.get_GeneratingUnits(data)

Retrieve a table of GeneratingUnits from a CGMES dataset.

Parameters:

data (pandas.DataFrame) – Triplet dataset containing CGMES data.

Returns:

DataFrame containing GeneratingUnit data, filtered by ‘GeneratingUnit.maxOperatingP’.

Return type:

pandas.DataFrame

Examples

>>> units = get_GeneratingUnits(data)
>>> print(units)
   ID  GeneratingUnit.maxOperatingP  ...

triplets.cgmes_tools.get_dangling_references(data, detailed=False)

Identify dangling references in a CGMES dataset.

Parameters:

• data (pandas.DataFrame) – Triplet dataset containing CGMES data.

• detailed (bool, optional) – If True, return detailed DataFrame of dangling references; otherwise, return counts of dangling reference types (default is False).

Returns:

If detailed=True, a DataFrame with dangling references; otherwise, a Series with counts of dangling reference keys.

Return type:

pandas.DataFrame or pandas.Series

Notes

• Identifies references using the CGMES convention (e.g., keys with ‘.<CapitalLetter>’).

• A dangling reference is one where the referenced ID does not exist in the dataset.

Examples

>>> dangling = get_dangling_references(data, detailed=True)

triplets.cgmes_tools.get_diff_between_model_parts(UUID_1, UUID_2)

Identify differences between two CGMES model parts based on their UUIDs.

Parameters:

• UUID_1 (str) – UUID of the first model part.

• UUID_2 (str) – UUID of the second model part.

Returns:

DataFrame containing triplets that differ between the two model parts.

Return type:

pandas.DataFrame

Examples

>>> diff = get_diff_between_model_parts('uuid1', 'uuid2')

triplets.cgmes_tools.get_filename_from_metadata(meta_data, file_type='xml', filename_mask='{scenarioTime:%Y%m%dT%H%MZ}_{processType}_{modelingEntity}_{messageType}_{version:03d}')

Generate a CGMES filename from metadata using a specified filename mask.

Parameters:

• meta_data (dict) – Dictionary containing metadata keys (e.g., ‘scenarioTime’, ‘processType’) and values.

• file_type (str, optional) – File extension for the generated filename (default is ‘xml’).

• filename_mask (str, optional) – Format string defining the filename structure (default follows CGMES convention).

Returns:

Generated filename adhering to the CGMES naming convention.

Return type:

str

Notes

• Removes ‘Model.’ prefix from metadata keys for compatibility with string formatting.

• Converts ‘scenarioTime’ to datetime and ‘version’ to integer before formatting.

• Uses the provided filename_mask to construct the filename.

Examples

>>> meta = {'Model.scenarioTime': '20230101T0000Z', 'Model.processType': 'A01', ...}
>>> get_filename_from_metadata(meta)
'20230101T0000Z_A01_ENTITY_EQ_001.xml'

triplets.cgmes_tools.get_limits(data)

Retrieve operational limits from a CGMES dataset, including equipment types.

Parameters:

data (pandas.DataFrame) – Triplet dataset containing CGMES data.

Returns:

DataFrame containing operational limits with associated equipment types.

Return type:

pandas.DataFrame

Notes

• Combines OperationalLimitSet, OperationalLimit, OperationalLimitType, and Terminal data.

• Links equipment via Terminal.ConductingEquipment or OperationalLimitSet.Equipment.

Examples

>>> limits = get_limits(data)

triplets.cgmes_tools.get_loaded_model_parts(data)

Retrieve a DataFrame of loaded CGMES model parts with their FullModel metadata.

Parameters:

data (pandas.DataFrame) – Triplet dataset containing CGMES data.

Returns:

DataFrame containing FullModel data for loaded model parts.

Return type:

pandas.DataFrame

Notes

• Does not correctly resolve ‘Model.DependentOn’ relationships.

Examples

>>> model_parts = get_loaded_model_parts(data)

triplets.cgmes_tools.get_loaded_models(data)

Retrieve a dictionary of loaded CGMES model parts and their UUIDs.

Parameters:

data (pandas.DataFrame) – Triplet dataset containing CGMES data with ‘Model.profile’ and ‘Model.DependentOn’ keys.

Returns:

Dictionary where keys are StateVariables (SV) UUIDs and values are DataFrames containing model parts (ID, PROFILE, INSTANCE_ID) and their dependencies.

Return type:

dict

Examples

>>> models = get_loaded_models(data)
>>> print(models)
{'SV_UUID': DataFrame(...), ...}

triplets.cgmes_tools.get_metadata_from_FullModel(data)

Extract metadata from the FullModel entries in a CGMES triplet dataset.

Parameters:

data (pandas.DataFrame) – Triplet dataset containing CGMES data with ‘KEY’, ‘VALUE’, and ‘ID’ columns.

Returns:

Dictionary of metadata key-value pairs for the FullModel instance.

Return type:

dict

Notes

• Assumes the dataset contains a ‘Type’ key with value ‘FullModel’.

• Removes the ‘Type’ key from the resulting metadata dictionary.

Examples

>>> meta = get_metadata_from_FullModel(data)
>>> print(meta)
{'Model.scenarioTime': '20230101T0000Z', 'Model.processType': 'A01', ...}

triplets.cgmes_tools.get_metadata_from_filename(file_name)

Extract metadata from a CGMES filename following the CGMES naming convention.

Parameters:

file_name (str) – Name of the CGMES file (e.g., ‘20230101T0000Z_A01_ENTITY_EQ_001.xml’).

Returns:

Dictionary containing metadata keys (e.g., ‘Model.scenarioTime’, ‘Model.processType’) and their corresponding values extracted from the filename.

Return type:

dict

Notes

• Expects filenames to follow CGMES conventions with underscores separating metadata fields.

• Handles cases with 4 or 5 metadata elements, setting ‘Model.processType’ to empty string for older formats (pre-QoDC 2.1).

• Splits ‘Model.modelingEntity’ into ‘Model.mergingEntity’, ‘Model.domain’, and ‘Model.forEntity’ if applicable.

Examples

>>> get_metadata_from_filename('20230101T0000Z_A01_ENTITY_EQ_001.xml')
{'Model.scenarioTime': '20230101T0000Z', 'Model.processType': 'A01', ...}

triplets.cgmes_tools.get_metadata_from_xml(filepath_or_fileobject)

Extract metadata from the FullModel element of a CGMES XML file.

Parameters:

filepath_or_fileobject (str or file-like object) – Path to the XML file or a file-like object containing CGMES XML data.

Returns:

DataFrame with columns [‘tag’, ‘text’, ‘attrib’] containing metadata from the FullModel element.

Return type:

pandas.DataFrame

Examples

>>> df = get_metadata_from_xml('path/to/file.xml')
>>> print(df)
   tag                text  attrib
0  Model.scenarioTime  20230101T0000Z  {}
...

triplets.cgmes_tools.get_model_data(data, model_instances_dataframe)

Extract data for specific CGMES model instances.

Parameters:

• data (pandas.DataFrame) – Triplet dataset containing CGMES data.

• model_instances_dataframe (pandas.DataFrame) – DataFrame containing ‘INSTANCE_ID’ column with model instance identifiers.

Returns:

Filtered dataset containing only data for the specified model instances.

Return type:

pandas.DataFrame

Examples

>>> model_data = get_model_data(data, models['SV_UUID'])

triplets.cgmes_tools.scale_load(data, load_setpoint, cos_f=None)

Scale active and reactive power loads in a CGMES SSH instance.

Parameters:

• data (pandas.DataFrame) – Triplet dataset containing SSH load information.

• load_setpoint (float) – Target total active power (P) setpoint for scaling.

• cos_f (float, optional) – Cosine of the power factor angle (cos(φ)). If None, calculated from the ratio of total Q to P.

Returns:

Updated dataset with scaled P and Q values for ConformLoad instances.

Return type:

pandas.DataFrame

Notes

• Scales only ConformLoad instances, preserving NonConformLoad values.

• Maintains or computes the power factor using cos_f.

Examples

>>> updated_data = scale_load(data, load_setpoint=1000.0, cos_f=0.9)

triplets.cgmes_tools.statistics_GeneratingUnit_types(data)

Calculate statistics for GeneratingUnit types in a CGMES dataset.

Parameters:

data (pandas.DataFrame) – Triplet dataset containing CGMES data.

Returns:

DataFrame with counts, total, and percentage of each GeneratingUnit type.

Return type:

pandas.DataFrame

Examples

>>> stats = statistics_GeneratingUnit_types(data)
>>> print(stats)
   Type  count  TOTAL    %
0  Hydro   10     20  50.0
...

triplets.cgmes_tools.switch_equipment_terminals(data, equipment_id, connected: str = 'false')

Update connection statuses of terminals for specified equipment in a CGMES dataset.

Parameters:

• data (pandas.DataFrame) – Triplet dataset containing EQ and SSH information.

• equipment_id (str or list) – Identifier(s) (mRID) of the equipment whose terminals’ statuses are to be updated.

• connected (str, optional) – New connection status (‘true’ or ‘false’, default is ‘false’).

Returns:

Updated dataset with modified terminal connection statuses.

Return type:

pandas.DataFrame

Raises:

ValueError – If connected is not ‘true’ or ‘false’.

Examples

>>> updated_data = switch_equipment_terminals(data, ['uuid1', 'uuid2'], connected='true')

triplets.cgmes_tools.tableview_by_IDs(data, IDs_dataframe, IDs_column_name)

Create a tabular view of a CGMES triplet dataset filtered by IDs.

Parameters:

• data (pandas.DataFrame) – Triplet dataset containing CGMES data.

• IDs_dataframe (pandas.DataFrame) – DataFrame containing IDs to filter by.

• IDs_column_name (str) – Column name in IDs_dataframe containing IDs (e.g., ‘PowerTransformer.ID’).

Returns:

Pivoted DataFrame with IDs as index and KEYs as columns.

Return type:

pandas.DataFrame

Examples

>>> table = tableview_by_IDs(data, ids_df, 'PowerTransformer.ID')

triplets.cgmes_tools.update_FullModel_from_dict(data, metadata, update=True, add=False)

Update or add metadata to FullModel entries in a CGMES triplet dataset.

Parameters:

• data (pandas.DataFrame) – Triplet dataset containing CGMES data.

• metadata (dict) – Dictionary of metadata key-value pairs to update or add.

• update (bool, optional) – If True, update existing metadata keys (default is True).

• add (bool, optional) – If True, add new metadata keys (default is False).

Returns:

Updated triplet dataset with modified FullModel metadata.

Return type:

pandas.DataFrame

Examples

>>> meta = {'Model.scenarioTime': '20230102T0000Z'}
>>> updated_data = update_FullModel_from_dict(data, meta)

triplets.cgmes_tools.update_FullModel_from_filename(data, parser=<function get_metadata_from_filename>, update=False, add=True)

Update FullModel metadata in a triplet dataset using metadata parsed from filenames.

Parameters:

• data (pandas.DataFrame) – Triplet dataset containing CGMES data with ‘label’ keys for filenames.

• parser (callable, optional) – Function to parse metadata from filenames, returning a dictionary (default is get_metadata_from_filename).

• update (bool, optional) – If True, update existing metadata keys (default is False).

• add (bool, optional) – If True, add new metadata keys (default is True).

Returns:

Updated triplet dataset with FullModel metadata derived from filenames.

Return type:

pandas.DataFrame

Examples

>>> updated_data = update_FullModel_from_filename(data)

triplets.cgmes_tools.update_filename_from_FullModel(data, filename_mask='{scenarioTime:%Y%m%dT%H%MZ}_{processType}_{modelingEntity}_{messageType}_{version:03d}', filename_key='label')

Update filenames in a CGMES triplet dataset based on FullModel metadata.

Parameters:

• data (pandas.DataFrame) – Triplet dataset containing CGMES data with FullModel metadata.

• filename_mask (str, optional) – Format string defining the filename structure (default follows CGMES convention).

• filename_key (str, optional) – Key in the dataset where filenames are stored (default is ‘label’).

Returns:

Updated triplet dataset with filenames modified based on FullModel metadata.

Return type:

pandas.DataFrame

Examples

>>> updated_data = update_filename_from_FullModel(data)