Common I/O Functions

The causaliq_core.graph.io.common module provides a unified interface for reading and writing graphs from different file formats. It automatically detects the file format based on the file suffix and delegates to the appropriate format-specific module.

Supported Formats

Extension	Format	Module	Description
.csv	Bayesys	bayesys	CSV-based format used by Bayesys software
.tetrad	Tetrad	tetrad	Native format used by Tetrad software

Functions

read(path: str) -> Union[PDAG]

Read a graph from a file, automatically detecting the format from the file suffix.

Parameters: - path (str): Full path name of file to read

Returns: - PDAG or DAG: Graph read from file

Raises: - TypeError: If path is not a string - ValueError: If file suffix is not supported - FileNotFoundError: If file is not found - FileFormatError: If file format is invalid

Example:

# Import from common module directly
from causaliq_core.graph.io.common import read

# Or import from top-level graph module (recommended)
from causaliq_core.graph import read

# Read Bayesys CSV file
csv_graph = read("data/graph.csv")

# Read Tetrad format file  
tetrad_graph = read("data/graph.tetrad")

write(graph: PDAG, path: str) -> None

Write a graph to a file, automatically detecting the format from the file suffix.

Parameters: - graph (PDAG): Graph to write to file - path (str): Full path name of file to write

Raises: - TypeError: If bad argument types - ValueError: If file suffix is not supported - FileNotFoundError: If path to file does not exist

Example:

# Import from common module directly
from causaliq_core.graph.io.common import write

# Or import from top-level graph module (recommended)
from causaliq_core.graph import write, DAG

# Create a graph
dag = DAG(["A", "B", "C"], [("A", "->", "B"), ("B", "->", "C")])

# Write to Bayesys CSV format
write(dag, "output/result.csv")

# Write to Tetrad format
write(dag, "output/result.tetrad")

Usage Patterns

Format Detection

The module uses the file extension to determine the appropriate format:

# Import from top-level graph module (recommended)
from causaliq_core.graph import read

# These will use different I/O modules automatically
bayesys_graph = read("data.csv")      # Uses bayesys.read()
tetrad_graph = read("data.tetrad")    # Uses tetrad.read()

Error Handling

from causaliq_core.graph import read

try:
    graph = read("data.txt")  # Unsupported format
except ValueError as e:
    print(f"Unsupported format: {e}")
    # Output: "common.read() unsupported file suffix: .txt"

Round-trip Operations

from causaliq_core.graph import read, write

# Read graph in one format
graph = read("input.csv")

# Write in different format  
write(graph, "output.tetrad")

# Verify round-trip
graph2 = read("output.tetrad")
assert set(graph.nodes) == set(graph2.nodes)

Reference

Functions:

• read_graph –

  Read a graph from a file, automatically detecting format from suffix.

• write_graph –

  Write a graph to a file, automatically detecting format from suffix.

read_graph

read_graph(path: str) -> Union[PDAG]

Read a graph from a file, automatically detecting format from suffix.

Supports: - .csv files (Bayesys format) - .tetrad files (Tetrad format)

Parameters:

• path

  (str) –

  Full path name of file to read.

Returns:

• Union[PDAG] –

  Graph read from file (PDAG or DAG).

Raises:

• TypeError –

  If path is not a string.

• ValueError –

  If file suffix is not supported.

• FileNotFoundError –

  If file is not found.

• FileFormatError –

  If file format is invalid.

write_graph

write_graph(graph: PDAG, path: str) -> None

Write a graph to a file, automatically detecting format from suffix.

Supports: - .csv files (Bayesys format) - .tetrad files (Tetrad format)

Parameters:

• graph

  (PDAG) –

  Graph to write to file.

• path

  (str) –

  Full path name of file to write.

Raises:

• TypeError –

  If bad arg types.

• ValueError –

  If file suffix is not supported.

• FileNotFoundError –

  If path to file does not exist.