Skip to content

GraphML Format I/O

GraphML I/O functions for reading and writing graphs in GraphML format. Supports both standard graphs (SDG, PDAG, DAG) and probabilistic dependency graphs (PDG).

Overview

GraphML is an XML-based format for graphs. This module supports:

  • Reading and writing SDG, PDAG, and DAG graphs
  • Reading and writing PDG (probabilistic) graphs
  • Both filesystem paths and file-like objects (e.g., StringIO)
  • Interoperability with workflow caches

Reference: GraphML Specification

Functions

Standard Graph I/O

read()

Read a graph from a GraphML file or file-like object.

from causaliq_core.graph.io import graphml

# From file path
graph = graphml.read("graph.graphml")

# From file-like object
from io import StringIO
xml_content = '<graphml>...</graphml>'
graph = graphml.read(StringIO(xml_content))

Returns SDG, PDAG, or DAG depending on edge types in the graph.

write()

Write a graph to a GraphML file or file-like object.

from causaliq_core.graph import DAG
from causaliq_core.graph.io import graphml

dag = DAG(["A", "B"], [("A", "->", "B")])

# To file path
graphml.write(dag, "output.graphml")

# To file-like object
from io import StringIO
buffer = StringIO()
graphml.write(dag, buffer)
xml_content = buffer.getvalue()

PDG I/O

read_pdg()

Read a Probabilistic Dependency Graph from GraphML.

from causaliq_core.graph.io import graphml

pdg = graphml.read_pdg("probabilistic_graph.graphml")

write_pdg()

Write a Probabilistic Dependency Graph to GraphML.

from causaliq_core.graph import PDG
from causaliq_core.graph.io import graphml

pdg = PDG(nodes, edges)
graphml.write_pdg(pdg, "output.graphml")

Type Alias

FileLike

Type alias for file path or file-like object:

FileLike = Union[str, Path, TextIO]

Reference

read 

read(file: FileLike) -> Union[SDG, PDAG, DAG]

Read a graph from a GraphML file or file-like object.

Supports standard GraphML files with optional edge endpoint attributes to represent different edge types (directed, undirected, bidirected, etc.). Without endpoint attributes, edges default to directed.

Parameters:

  • file

    (FileLike) –

    File path (str or Path) or file-like object (e.g., StringIO). For file paths, suffix must be '.graphml'.

Returns:

  • Union[SDG, PDAG, DAG] –

    SDG, PDAG or DAG depending on edge types in the graph.

Raises:

  • TypeError –

    If argument types incorrect.

  • ValueError –

    If file path suffix not '.graphml'.

  • FileNotFoundError –

    If specified file does not exist.

  • FileFormatError –

    If file contents are not valid GraphML.

Example

from io import StringIO xml = '' graph = read(StringIO(xml))

write 

write(graph: Union[SDG, PDAG, DAG], file: FileLike, graph_id: str = 'G') -> None

Write a graph to a GraphML file or file-like object.

Exports the graph with node ordering preserved and edge types encoded using sourceEndpoint/targetEndpoint data attributes.

Parameters:

  • graph

    (Union[SDG, PDAG, DAG]) –

    SDG, PDAG or DAG to write.

  • file

    (FileLike) –

    File path (str or Path) or file-like object (e.g., StringIO). For file paths, suffix must be '.graphml'.

  • graph_id

    (str, default: 'G' ) –

    ID attribute for the graph element. Defaults to "G".

Raises:

  • TypeError –

    If argument types incorrect.

  • ValueError –

    If file path suffix not '.graphml'.

Example

from io import StringIO buffer = StringIO() write(graph, buffer) xml_content = buffer.getvalue()

read_pdg 

read_pdg(file: FileLike) -> 'PDG'

Read a PDG from a GraphML file or file-like object.

Reads a Probabilistic Dependency Graph with edge probability attributes. The file should have undirected edges with p_forward, p_backward, p_undirected, and p_none data attributes.

Parameters:

  • file

    (FileLike) –

    File path (str or Path) or file-like object (e.g., StringIO). For file paths, suffix must be '.graphml'.

Returns:

  • 'PDG' –

    PDG instance with edge probabilities.

Raises:

  • TypeError –

    If argument types incorrect.

  • ValueError –

    If file path suffix not '.graphml'.

  • FileNotFoundError –

    If specified file does not exist.

  • FileFormatError –

    If file contents are not valid GraphML or missing required probability attributes.

Example

from io import StringIO xml = ''' ... ... ... ... ... ... 0.8 ... 0.1 ... 0.05 ... 0.05 ... ... ... ''' pdg = read_pdg(StringIO(xml))

write_pdg 

write_pdg(pdg: 'PDG', file: FileLike) -> None

Write a PDG to a GraphML file or file-like object.

Exports the PDG with undirected edges and probability data attributes (p_forward, p_backward, p_undirected, p_none).

Only edges with p_exist > 0 (i.e., p_none < 1.0) are written.

Parameters:

  • pdg

    ('PDG') –

    PDG to write.

  • file

    (FileLike) –

    File path (str or Path) or file-like object (e.g., StringIO). For file paths, suffix must be '.graphml'.

Raises:

  • TypeError –

    If argument types incorrect.

  • ValueError –

    If file path suffix not '.graphml'.

Example

from io import StringIO from causaliq_core.graph.pdg import PDG, EdgeProbabilities pdg = PDG(["A", "B"], { ... ("A", "B"): EdgeProbabilities(forward=0.8, none=0.2) ... }) buffer = StringIO() write_pdg(pdg, buffer) print(buffer.getvalue())