Skip to content

Architecture Overview

CausalIQ Ecosystem

causaliq-analysis is a component of the overall CausalIQ ecosystem architecture.

Package Purpose

causaliq-analysis provides tools for analysing and summarising results from causal discovery experiments:

  • Graph merging — Combine multiple learned graphs into probabilistic dependency graphs (PDGs)
  • Structural evaluation — Compute accuracy metrics against ground truth for deterministic graphs (DAG/PDAG/CPDAG) and probabilistic dependency graphs (PDGs)
  • Metric summarisation — Aggregate metric values from several workflow caches into a single table of summary statistics (mean, SD, count) written as CSV, LaTeX or Markdown
  • Plot generation — Chart metric summaries produced by the summarise step
  • Trace migration — Convert legacy experiment traces to modern formats

Key Architectural Concepts

Summarisation Paradigm

The summarisation paradigm provides a consistent pattern for aggregating experimental results across different dimensions. This enables workflows that:

  • Group results by network, sample size, algorithm, etc.
  • Filter inputs by metadata criteria
  • Apply metadata-driven weighting
  • Produce outputs with full provenance tracking

Summarise Tables

The summarise columns note defines the table model built on the paradigm: grouping dimensions followed by base columns drawn from named input caches and derived columns computed over them, rendered as CSV, LaTeX or Markdown.

Typed Workflow Caches

Workflow caches follow a single typed-object model: one cache holds one object type, and a successful entry holds provenance metadata plus exactly one typed object, whilst a failed entry holds provenance only. A failed evaluation is recorded in the metrics cache as a provenance-only entry with status input_failed, so failures appear alongside results without any metric values. merge_graphs, evaluate_graph, best_graph, summarise and plot therefore read and write caches whose type is implied by the workflow's input/output parameters, and no action takes an object-type filter. See the causaliq-workflow Cache Type Model for the full design.

Graph Types

The package works with graph types from causaliq-core:

Type Description
DAG Directed acyclic graph with fully oriented edges
CPDAG Completed partially directed acyclic graph (Markov equivalence class)
PDG Probabilistic dependency graph with edge probabilities

evaluate_graph compares deterministic graphs (DAG/PDAG/CPDAG) directly and PDGs probabilistically: each node pair contributes the sixteen products of the reference and graph edge-state probabilities (forward, backward, undirected, none), so low-level edge counts are fractional. Since a PDG can represent a DAG, PDAG or CPDAG, this single comparison path supports all graph types produced by the CausalIQ ecosystem.

Action Classes and Registry

Each workflow action is implemented as a small class in workflow_action/actions/, subclassing the AnalysisAction contract with its own validate and run methods. workflow_action/actions/__init__.py maps action names to classes in ACTION_CLASSES. The provider in workflow_action/__init__.py stays thin: it checks that the action is supported and that the parameters are known, then delegates validation and execution to the registered class. Adding an action therefore means adding one module plus one registry entry, and nothing else in the provider.

CLI Commands and Registry

Each CLI command is implemented in its own module in cli/commands/ as a click command with its own options. cli/commands/__init__.py lists the command objects in COMMANDS and registers them on the group through register_commands. The package __init__.py stays thin: it defines the click group cli and the main entry point, then registers the commands. Shared, cross-command helpers live in cli/common.py. Adding a command therefore means adding one module plus one registry entry.

Trace Package

The legacy trace support is split into a trace/ package whose __init__.py re-exports the public names (Trace, DiffType, CompatibilityUnpickler, load_with_compatibility, CONTEXT_FIELDS) so existing imports from causaliq_analysis.trace keep working. The Trace class stays thin, delegating comparison to trace.diffs and score recalculation to trace.scores; legacy pickle remapping lives in trace.compatibility.

Plot Package

The legacy plotting code is split into a plot/ package whose __init__.py re-exports the public names (run_plot, parse_properties, relplot, plot_scatter, plot_degree_distribution, SUPPORTED_KINDS) so existing imports from causaliq_analysis.plot keep working. The chart property parser lives in plot.properties, the axis-styling and annotation helpers in plot.axes, the seaborn builders in plot.charts and the run_plot entry point in plot.run. The chart builders stay thin by delegating the shared figure style, per-kind figure construction and the figure/axes/legend post-processing to module-level helpers, and plot_scatter shares those helpers with relplot.

Merge, Metrics, Migration and Validation Modules

merge.py, metrics.py, migrate.py and validation.py remain single modules, but each public entry point stays small by delegating to private helpers. Graph validation, weight normalisation and the average and per-source merge strategies are separated in merge.py; the PDG comparison, summary metrics and Bayesys scores are computed by dedicated helpers in metrics.py; trace filtering, graph generation, logging and file writing are split in migrate.py; and the CLI and workflow seed parsing share range helpers in validation.py. Graph file auto-detection in graph_io.py reads file text through a helper so its nesting stays shallow. Public names are unchanged, so existing imports from these modules keep working.

Integration Points

Component Integration
causaliq-core Graph types, filter evaluation, weight computation
causaliq-workflow Workflow actions, cache storage, matrix execution
causaliq-data Dataset loading for evaluation

Module Structure

src/causaliq_analysis/
├── __init__.py         # Package exports and version metadata
├── cli/                # Command-line interface
│   ├── __init__.py     # click group `cli`, `main` and public re-exports
│   ├── common.py       # Shared metadata and summary helpers
│   └── commands/       # Individual CLI commands
│       ├── __init__.py # Command registry (COMMANDS)
│       ├── best_graph.py # best-graph command
│       ├── evaluate_graph.py # evaluate-graph command
│       ├── merge_graphs.py # merge-graphs command
│       ├── migrate_trace.py # migrate-trace command
│       ├── plot.py     # plot command
│       └── summarise.py # summarise command
├── graph.py            # Graph action enumerations
├── graph_io.py         # Graph file reading (including PDGs)
├── merge.py            # Graph merging to PDG
├── metrics.py          # Structural comparison metrics
├── migrate.py          # Trace migration utilities
├── plot/               # Chart generation from summarise output
│   ├── __init__.py     # Public re-exports (run_plot, parse_properties, ...)
│   ├── axes.py         # Axis styling and box/violin annotations
│   ├── charts.py       # Seaborn chart builders
│   ├── properties.py   # Chart property parsing
│   └── run.py          # run_plot entry point and CSV helpers
├── trace/              # Legacy Trace format support
│   ├── __init__.py     # Public re-exports (Trace, DiffType, ...)
│   ├── compatibility.py # Legacy pickle compatibility
│   ├── diffs.py        # Trace comparison (DiffType)
│   ├── scores.py       # Score recalculation for a trace series
│   └── trace.py        # Trace class and context constants
├── validation.py       # Input validation
└── workflow_action/    # Workflow action interface
    ├── __init__.py     # Provider class and public API
    ├── types.py        # Shared type imports and fallback stubs
    ├── helpers.py      # Cache parsing and graph extraction helpers
    └── actions/        # Individual workflow action classes
        ├── __init__.py # Action registry
        ├── base.py     # Abstract action contract
        ├── best_graph.py # BestGraphAction (optimal DAG extraction)
        ├── evaluate_graph.py # EvaluateGraphAction (structural metrics)
        ├── merge_graphs.py # MergeGraphsAction (graph merging to PDG)
        ├── migrate_trace.py # MigrateTraceAction (legacy traces to GraphML)
        ├── plot.py     # PlotAction (chart generation)
        └── summarise.py # SummariseAction (metric aggregation to CSV)