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, optional) – Output file path (.nq). 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¶

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¶

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()