triplets.export

Triplet DataFrame export functions.

Formats: Excel, CSV, CIM XML, N-Quads, NetworkX. Each format has its own {format}_{engine}.py file.

CIM XML engines (mirrors triplets.parser engine setup): - python_lxml (pure Python + lxml, always available) - cython_pugixml (compiled Arrow → pugixml extension, fastest) Fallback: cython_pugixml → python_lxml

Engine auto-selection differs by format (by design): - CSV: by input type — a polars DataFrame uses the polars engine, else pandas. - N-Quads: polars when installed (pandas input is converted), else pandas. - CIM XML: the fastest available compiled engine (cython_pugixml → python_lxml). - Excel / NetworkX: pandas only — polars input is converted to pandas first.

triplets.export.export_to_excel(data, *args, **kwargs)[source]

Export triplet data to Excel file(s), with each type on a separate sheet.

Parameters:

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

  • path (str, optional) – Directory path to save Excel file(s), or file path when single_file=True.

  • multivalue (bool, default True) – If True, aggregate duplicate (ID, KEY) pairs into lists.

  • export_to_memory (bool, default False) – If True, return BytesIO objects; if False, save to disk.

  • single_file (bool, default False) – If True, export all data to a single file instead of one file per INSTANCE_ID.

  • filename (str, optional) – Filename to use when single_file=True. If None, uses ‘export.xlsx’.

  • apply_formatting (bool, default True) – If True, apply column width and freeze panes formatting.

Returns:

Depends on single_file and export_to_memory flags.

Return type:

BytesIO, str, or list

triplets.export.export_to_csv(data, path=None, multivalue=True, export_to_memory=False, single_file=False, base_filename=None)[source]

Export triplet DataFrame to CSV files.

Auto-detects engine: polars if input is polars DataFrame, else pandas.

triplets.export.export_to_cimxml(data, rdf_map=None, namespace_map=None, class_KEY='Type', export_undefined=False, export_type=ExportType.XML_PER_INSTANCE_ZIP_PER_XML, global_zip_filename='Export.zip', debug=False, export_to_memory=False, export_base_path='', comment=None, max_workers=None, engine='auto', datatypes=False)[source]

Export a full triplet dataset to CIM RDF XML files or ZIP archives.

Processes all instances (grouped by INSTANCE_ID) and exports them according to the specified export_type. Supports parallel processing and in-memory or disk output.

Parameters:

  • data (pandas.DataFrame) – Full triplet dataset with columns [‘INSTANCE_ID’, ‘ID’, ‘KEY’, ‘VALUE’].

  • rdf_map (dict or str, optional) – RDF mapping configuration (see generate_xml()).

  • namespace_map (dict, optional) – Namespace prefix-to-URI mapping (see generate_xml()).

  • class_KEY (str, default "Type") – Key identifying object types in triplet data.

  • export_undefined (bool, default False) – If True, also export classes/attributes without a schema definition (internal structures like Distribution/NamespaceMap) under the http://triplets# namespace. Normal exports carry only schema-defined content. (The cython engine emits undefined elements un-namespaced.)

  • export_type (ExportType or str, default ExportType.XML_PER_INSTANCE_ZIP_PER_XML) – Export format: - XML_PER_INSTANCE: One XML file per instance. - XML_PER_INSTANCE_ZIP_PER_ALL: All XMLs in a single ZIP. - XML_PER_INSTANCE_ZIP_PER_XML: Each XML in its own ZIP.

  • global_zip_filename (str, default "Export.zip") – Filename for the global ZIP archive (used with ZIP_PER_ALL).

  • debug (bool, default False) – Enable detailed timing and debug logging.

  • export_to_memory (bool, default False) – If True, return file-like objects (BytesIO); if False, save to disk.

  • export_base_path (str, default "") – Directory to save files when export_to_memory=False. Uses current directory if empty.

  • comment (str, optional) – Optional XML comment added to each generated file.

  • max_workers (int, optional) – Number of parallel workers for XML generation. If None, runs sequentially.

  • engine (str, default "auto") – XML generation engine. “auto” picks best available. Options: “python_lxml” (lxml, always available), “cython_pugixml” (compiled, fastest). Aliases: “performance”/”pugixml” → cython_pugixml, “lxml”/”pandas” → python_lxml.

  • datatypes (bool, default False) – If True, annotate literal elements with rdf:datatype from the schema’s xsd:type, like the N-Quads export (“44.84” → rdf:datatype xsd#float; xsd:string stays plain). Currently python_lxml only — “auto” picks it.

Returns:

  • If export_to_memory=True: List of BytesIO objects with .name attribute.

  • If export_to_memory=False: List of saved filenames (relative to export_base_path).

Return type:

list

Examples

>>> files = export_to_cimxml(
...     data,
...     rdf_map="config/cim_map.json",
...     export_type=ExportType.XML_PER_INSTANCE_ZIP_PER_XML,
...     export_to_memory=True,
...     max_workers=4
... )
>>> for f in files:
...     print(f"name:", f.name)

Notes

  • Uses concurrent.futures.ProcessPoolExecutor for parallel XML generation.

  • All XML files are UTF-8 encoded with XML declaration.

  • ZIP files use DEFLATED compression.

  • Filenames are derived from instance label or UUID.

triplets.export.export_to_nquads(data, path=None, rdf_map=None, engine='auto', export_to_memory=False)[source]

Export triplet DataFrame to N-Quads file.

Parameters:

  • path (str or Path, optional) – Output file path (.nq); defaults to “export.nq” in the current directory. Ignored when export_to_memory=True.

  • rdf_map (dict or str, optional) – Export schema for proper enum detection and literal datatype annotations. If None, enums exported as literals.

  • engine (str, default "auto") – “polars” (lazy expression plan, ~4x faster) or “pandas”. “auto” picks polars when installed, converting pandas input (~17 ms per million rows); falls back to pandas otherwise.

  • export_to_memory (bool, default False) – If True, return an in-memory BytesIO (with .name) instead of writing to disk — same convention as export_to_csv / export_to_cimxml.

triplets.export.export_to_networkx(data, *args, **kwargs)[source]

Convert a triplet dataset to a NetworkX graph.

Parameters:

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

Returns:

A NetworkX graph with nodes (IDs with Type attributes) and edges (references).

Return type:

networkx.Graph

Notes

  • TODO: Add all node data and support additional graph export formats.

Examples

>>> graph = data.to_networkx()
triplets.export.generate_xml(instance_data, rdf_map=None, namespace_map=None, class_KEY='Type', export_undefined=False, comment=None, debug=False, datatypes=False)[source]

Generate an RDF XML file from a triplet dataset instance.

This function processes a single instance (grouped by INSTANCE_ID) from a triplet dataset and exports it as an RDF/XML document using provided or inferred mapping rules.

Parameters:

  • instance_data (pandas.DataFrame) – Triplet dataset for a single instance, with columns [‘’ID’, ‘KEY’, ‘VALUE’, INSTANCE_ID’]. Must contain at least one row with KEY == class_KEY to define object types.

  • rdf_map (dict or str, optional) – Dictionary mapping CIM classes and attributes to RDF namespaces and export rules. If a string is provided, it is treated as a file path to a JSON configuration. If None, attempts to infer from instance data (e.g., profile-based mapping).

  • namespace_map (dict, optional) – Mapping of namespace prefixes to URIs (e.g., {"cim": "http://iec.ch/TC57/2013/CIM-schema-cim16#"}). Must include "rdf" namespace. If None, inferred from rdf_map or instance.

  • class_KEY (str, default "Type") – Column key used to identify object class/type in the triplet data.

  • export_undefined (bool, default False) – If True, also export classes and attributes without a schema definition (internal structures like Distribution/NamespaceMap) under the http://triplets# namespace. Off by default — normal exports carry only schema-defined content.

  • comment (str, optional) – Optional comment to insert at the top of the XML output (as XML comment).

  • datatypes (bool, default False) – If True, annotate literal elements with rdf:datatype from the schema’s xsd:type (like the N-Quads export); xsd:string stays unannotated.

  • debug (bool, default False) – If True, log detailed timing and debug information during processing.

Returns:

Dictionary containing: - 'filename' (str): Generated filename (from label or UUID). - 'file' (bytes): UTF-8 encoded XML content.

Return type:

dict

Raises:

  • KeyError – If required columns are missing in instance_data.

  • ValueError – If invalid export configuration or mapping is detected.

Examples

>>> instance = data[data["INSTANCE_ID"] == 1]
>>> result = generate_xml(
...     instance,
...     rdf_map="config/eq_profile.json",
...     comment="Exported on 2025-11-11",
...     debug=True
... )
>>> with open(result["filename"], "wb") as f:
...     f.write(result["file"])

Notes

  • Supports profile-based mapping (e.g., “EQ”, “SSH”) via Model.profile or Model.messageType.

  • Uses lxml.etree with ElementMaker for XML construction.

  • Undefined classes are exported with rdf:about="urn:uuid:<ID>" when export_undefined=True.

triplets.export.get_cimxml_engine(name='auto')[source]

Resolve CIM XML engine name (with aliases) and return (name, module).

class triplets.export.ExportType(*values)[source]

Bases: StrEnum

XML_PER_INSTANCE = 'xml_per_instance'
XML_PER_INSTANCE_ZIP_PER_ALL = 'xml_per_instance_zip_per_all'
XML_PER_INSTANCE_ZIP_PER_XML = 'xml_per_instance_zip_per_xml'

triplets.export.cimxml_pandas

triplets.export.cimxml_pandas.generate_xml(instance_data, rdf_map=None, namespace_map=None, class_KEY='Type', export_undefined=False, comment=None, debug=False, datatypes=False)[source]

Generate an RDF XML file from a triplet dataset instance.

This function processes a single instance (grouped by INSTANCE_ID) from a triplet dataset and exports it as an RDF/XML document using provided or inferred mapping rules.

Parameters:

  • instance_data (pandas.DataFrame) – Triplet dataset for a single instance, with columns [‘’ID’, ‘KEY’, ‘VALUE’, INSTANCE_ID’]. Must contain at least one row with KEY == class_KEY to define object types.

  • rdf_map (dict or str, optional) – Dictionary mapping CIM classes and attributes to RDF namespaces and export rules. If a string is provided, it is treated as a file path to a JSON configuration. If None, attempts to infer from instance data (e.g., profile-based mapping).

  • namespace_map (dict, optional) – Mapping of namespace prefixes to URIs (e.g., {"cim": "http://iec.ch/TC57/2013/CIM-schema-cim16#"}). Must include "rdf" namespace. If None, inferred from rdf_map or instance.

  • class_KEY (str, default "Type") – Column key used to identify object class/type in the triplet data.

  • export_undefined (bool, default False) – If True, also export classes and attributes without a schema definition (internal structures like Distribution/NamespaceMap) under the http://triplets# namespace. Off by default — normal exports carry only schema-defined content.

  • comment (str, optional) – Optional comment to insert at the top of the XML output (as XML comment).

  • datatypes (bool, default False) – If True, annotate literal elements with rdf:datatype from the schema’s xsd:type (like the N-Quads export); xsd:string stays unannotated.

  • debug (bool, default False) – If True, log detailed timing and debug information during processing.

Returns:

Dictionary containing: - 'filename' (str): Generated filename (from label or UUID). - 'file' (bytes): UTF-8 encoded XML content.

Return type:

dict

Raises:

  • KeyError – If required columns are missing in instance_data.

  • ValueError – If invalid export configuration or mapping is detected.

Examples

>>> instance = data[data["INSTANCE_ID"] == 1]
>>> result = generate_xml(
...     instance,
...     rdf_map="config/eq_profile.json",
...     comment="Exported on 2025-11-11",
...     debug=True
... )
>>> with open(result["filename"], "wb") as f:
...     f.write(result["file"])

Notes

  • Supports profile-based mapping (e.g., “EQ”, “SSH”) via Model.profile or Model.messageType.

  • Uses lxml.etree with ElementMaker for XML construction.

  • Undefined classes are exported with rdf:about="urn:uuid:<ID>" when export_undefined=True.

triplets.export.excel_pandas

triplets.export.excel_pandas.export_to_excel(data, path=None, multivalue=True, export_to_memory=False, single_file=False, filename=None, apply_formatting=True)[source]

Export triplet data to Excel file(s), with each type on a separate sheet.

Parameters:

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

  • path (str, optional) – Directory path to save Excel file(s), or file path when single_file=True.

  • multivalue (bool, default True) – If True, aggregate duplicate (ID, KEY) pairs into lists.

  • export_to_memory (bool, default False) – If True, return BytesIO objects; if False, save to disk.

  • single_file (bool, default False) – If True, export all data to a single file instead of one file per INSTANCE_ID.

  • filename (str, optional) – Filename to use when single_file=True. If None, uses ‘export.xlsx’.

  • apply_formatting (bool, default True) – If True, apply column width and freeze panes formatting.

Returns:

Depends on single_file and export_to_memory flags.

Return type:

BytesIO, str, or list

triplets.export.csv_pandas

triplets.export.csv_pandas.export_to_csv(data, path=None, multivalue=True, export_to_memory=False, single_file=False, base_filename=None)[source]

Export triplet data to CSV files, with each type as a separate file.

Parameters:

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

  • path (str, optional) – Directory path to save CSV file(s).

  • multivalue (bool, default True) – If True, aggregate duplicate (ID, KEY) pairs into lists.

  • export_to_memory (bool, default False) – If True, return BytesIO objects; if False, save to disk.

  • single_file (bool, default False) – If True, export all data using a single base filename.

  • base_filename (str, optional) – Base filename when single_file=True. If None, uses ‘export’.

triplets.export.csv_polars

CSV export using polars native write_csv.

Exports triplet data to CSV files, one per type. Uses polars for fast I/O.

triplets.export.csv_polars.export_to_csv(data, path=None, multivalue=True, export_to_memory=False, single_file=False, base_filename=None)[source]

Export triplet data to CSV files using polars.

Parameters:

  • data (polars.DataFrame) – Triplet dataset with columns [ID, KEY, VALUE, INSTANCE_ID].

  • path (str, optional) – Directory path to save CSV files.

  • multivalue (bool, default True) – If True, aggregate duplicate (ID, KEY) pairs into lists.

  • export_to_memory (bool, default False) – If True, return BytesIO objects; if False, save to disk.

  • single_file (bool, default False) – If True, export all data using a single base filename.

  • base_filename (str, optional) – Base filename when single_file=True. If None, uses ‘export’.

triplets.export.nquads_pandas

N-Quads export using pandas — schema-aware value classification.

triplets.export.nquads_pandas.export_to_nquads(data, path=None, rdf_map=None, export_to_memory=False)[source]

Export triplet DataFrame to N-Quads file.

Parameters:

  • data (pandas.DataFrame) – Triplet dataset with columns [ID, KEY, VALUE, INSTANCE_ID].

  • path (str, optional) – Output file path (.nq). Ignored when export_to_memory=True.

  • rdf_map (dict or str, optional) – Export schema for proper enum/association detection and literal datatype annotations (“400”^^<…XMLSchema#float>). If None, enumerations won’t get namespace and literals stay untyped.

  • export_to_memory (bool, default False) – If True, return an in-memory BytesIO (with .name) instead of writing to disk.

triplets.export.nquads_polars

N-Quads export using polars — lazy expression plan, fully vectorized.

triplets.export.nquads_polars.export_to_nquads(data, path=None, rdf_map=None, export_to_memory=False)[source]

Export triplet DataFrame to N-Quads file.

Parameters:

  • data (polars.DataFrame) – Triplet dataset with columns [ID, KEY, VALUE, INSTANCE_ID].

  • path (str, optional) – Output file path (.nq). Ignored when export_to_memory=True.

  • rdf_map (dict or str, optional) – Export schema for proper enum/association detection and literal datatype annotations (“400”^^<…XMLSchema#float>).

  • export_to_memory (bool, default False) – If True, return an in-memory BytesIO (with .name) instead of writing to disk.

triplets.export.nquads_polars.write_nquads_batches(reader, handle, rdf_map=None)[source]

Stream a pyarrow.RecordBatchReader into an open binary handle.

One batch is formatted and written at a time, so memory stays bounded by a single batch regardless of the total size — the out-of-core export counterpart of parse_batches. The schema metadata is resolved once.

triplets.export.networkx_pandas

triplets.export.networkx_pandas.export_to_networkx(data)[source]

Convert a triplet dataset to a NetworkX graph.

Parameters:

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

Returns:

A NetworkX graph with nodes (IDs with Type attributes) and edges (references).

Return type:

networkx.Graph

Notes

  • TODO: Add all node data and support additional graph export formats.

Examples

>>> graph = data.to_networkx()

triplets.export.cimxml_pugixml

Performance CIM XML export engine.

Same generate_xml() contract as cimxml_pandas, but the XML is built by the compiled extension (Arrow string arrays → pugixml DOM → bytes) instead of lxml. ~Identical output, much faster on large instances.

triplets.export.cimxml_pugixml.generate_xml(instance_data, rdf_map=None, namespace_map=None, class_KEY='Type', export_undefined=False, comment=None, debug=False, datatypes=False)[source]

Generate an RDF XML file from a triplet dataset instance.

Same parameters and return value as cimxml_pandas.generate_xml(); see there for full documentation.

Returns:

{‘filename’: str, ‘file’: bytes (UTF-8 XML)}

Return type:

dict

triplets.export.cimxml_utils

triplets.export.cimxml_utils.resolve_instance_config(instance_data, rdf_map, namespace_map=None)[source]

Resolve per-instance export config shared by all cimxml engines.

Returns:

file_name : from the instance ‘label’ (source filename) or a new UUID namespace_map : given > instance NamespaceMap > schema ProfileNamespaceMap instance_rdf_map : profile section matched by the schema’s own identity

metadata (section key / keyword / versionIRI / conformsTo) against the instance header (Model.messageType, keyword, Model.profile, conformsTo); legacy URL-substring fallback for 2.4.15-era URLs; schema root when nothing matches

Return type:

tuple (file_name, namespace_map, instance_rdf_map)

triplets.export.nquads_utils

Shared N-Quads logic — schema parsing and value classification.

Used by nquads_pandas.py and nquads_polars.py.

triplets.export.nquads_utils.build_key_metadata(rdf_map)[source]

Extract enum keys, key→namespace, and key→datatype mappings from export schema.

Parameters:

rdf_map (dict or str) – Export schema (loaded JSON dict or path to JSON file).

Returns:

  • enum_keys (set) – KEY names whose values are enumerations (need namespace on VALUE).

  • key_namespaces (dict) – KEY name → namespace URI for predicate construction.

  • key_datatypes (dict) – KEY name → full xsd datatype URI (from the schema’s “xsd:type”, e.g. “xsd:float” → “http://www.w3.org/2001/XMLSchema#float”). A key present here is a literal attribute by schema. xsd:string keys map to None: literal, but no annotation (RDF 1.1 default).

triplets.export.nquads_utils.flatten_schema(rdf_map)[source]

Flatten the export schema across profiles for human-context lookups.

The same class/property key repeats per profile with essentially the same definition — the first occurrence wins. Complements build_key_metadata (which extracts the machine fields); this pulls the human ones.

Returns:

  • key_info (dict) – “Class.attr” → {“description”, “multiplicity”} for property entries (Attribute / Association / Enumeration).

  • class_info (dict) – “Class” → description for class entries.

triplets.export.nquads_utils.make_subject(id_val)[source]

Convert ID to subject URI.

triplets.export.nquads_utils.make_predicate(key, key_namespaces=None)[source]

Convert KEY to predicate URI.

triplets.export.nquads_utils.make_object(key, value, enum_keys=None, key_datatypes=None)[source]

Convert VALUE to object (URI or literal).

Rules: - Type row → <namespace#ClassName> - Already starts with http/https/urn → <value> (pass through) - Enum KEY → <namespace#EnumValue> - KEY with schema datatype → “literal”^^<xsd type> (plain for xsd:string);

takes precedence over the UUID heuristic (e.g. IdentifiedObject.mRID is a string attribute, not a reference)

  • UUID pattern → <urn:uuid:value>

  • Everything else → “literal” (with escaping)

triplets.export.nquads_utils.make_graph(instance_id)[source]

Convert INSTANCE_ID to graph URI.