Trace Migration¶
The migrate-trace command converts legacy Trace pickle files into portable
GraphML format with accompanying metadata. This enables integration with
modern causaliq workflows and third-party graph tools.
Parameters¶
| Parameter | CLI Flag | Required | Description |
|---|---|---|---|
network |
-n/--network |
Yes* | Network name to process |
series |
-s/--series |
Yes* | Series path (e.g., TABU/SAMPLE/BASE) |
root_dir |
-r/--root-dir |
Yes | Root directory |
sample_size |
-N/--sample-size |
Yes | Filter by sample size (e.g., 10k) |
seed |
-S/--seed |
No | Filter by seed (single value or range) |
output |
-o/--output |
CLI only | Output directory for _meta.json and .graphml files |
Notes:
- Sample size accepts integers or shorthand:
1K= 1000,10k= 10000,1m= 1000000 - Seed accepts: single value (
5), range (0-24), or, in actions only, a YAML list ([0, 1, 2]) - If
seedis omitted, all seeds are included - CLI output defaults to
migrated/<series>/<network>/
How It Works¶
Step 1: Load Trace Files¶
Trace files are loaded from the experiments directory based on the series and network pattern. Each Trace contains:
- The learnt DAG from structure learning
- Algorithm parameters and configuration
- Sample size and random seed used
- Score metrics and iteration history
Step 2: Extract Graph and Metadata¶
For each Trace, the migration extracts:
| Component | Description |
|---|---|
| Result DAG | Final learnt graph structure |
| Metadata | Algorithm, parameters, N, score, software version |
Traces without a valid result graph are skipped with a warning.
Step 3: Convert to GraphML¶
The DAG is serialised to GraphML format, which:
- Preserves all nodes and directed edges
- Is readable by NetworkX, Gephi, Cytoscape, and other tools
- Includes graph-level metadata as GraphML data elements
CLI Usage¶
Example Commands¶
# Migrate all traces for asia network from TABU/STD series
causaliq-analysis migrate-trace `
--network=asia `
--series=TABU/STD `
--root-dir=experiments
# Migrate specific sample size and seeds
causaliq-analysis migrate-trace `
--network=asia `
--series=TABU/STD `
--N=10k `
--seed=0-2 `
--output=migrated/asia_10k
# Migrate from non-default root directory
causaliq-analysis migrate-trace `
--network=alarm `
--series=HC/SAMPLE/BASE `
--root-dir=/data/experiments `
--output=output/alarm_graphs
Output Structure¶
migrated/TABU/STD/asia/
├── N1000.graphml # Graph for N=1000, seed=0
├── N1000.json # Metadata for N=1000
├── N1000_1.graphml # Graph for N=1000, seed=1
├── N1000_1.json # Metadata for N=1000, seed=1
└── ...
Workflow Action¶
The migrate_trace action can be used in causaliq-workflow definitions
for batch migration across multiple networks.
Example Workflow¶
# migrate_experiments.yaml
description: "Migrate legacy traces to GraphML format"
matrix:
network: [asia, alarm, insurance]
series: [TABU/STD, HC/STD]
sample_size: [1K, 10K]
seed: [0]
actions:
migrate_trace:
action: migrate_trace
series: "{{series}}"
network: "{{network}}"
sample_size: "{{sample_size}}"
seed: "{{seed}}"
root_dir: experiments
This workflow migrates traces for all matrix combinations, storing one GraphML object in the workflow cache for each entry.
One Object per Cache Key¶
Each job must match exactly one trace file, because every cache entry holds one object of the cache's type. If a job matches several traces, the matrix is missing a distinguishing dimension, and the action reports an error naming the problem:
migrate_trace matched 4 graphs for one cache key. Add a matrix key
(for example 'sample_size' or 'seed') to distinguish them.
Add the missing key (for example sample_size or seed) to the matrix so that
each combination selects a single trace.
Action Outputs¶
| Output | Description |
|---|---|
num_graphs |
Number of graphs converted (always 1 for a successful entry) |
skipped |
Number of traces skipped (no result graph) |
status |
Execution status (success, skipped, error) |
The action also returns GraphML content as objects that can be:
- Stored in the workflow cache
- Passed to downstream actions (e.g.,
merge_graphs) - Written to files via output configuration
Output Formats¶
GraphML¶
Standard XML-based graph format with directed edges:
<?xml version="1.0" encoding="UTF-8"?>
<graphml xmlns="http://graphml.graphdrawing.org/xmlns">
<graph id="G" edgedefault="directed">
<node id="A"/>
<node id="B"/>
<node id="C"/>
<edge source="A" target="B"/>
<edge source="B" target="C"/>
</graph>
</graphml>
Metadata JSON¶
Accompanying metadata for each graph:
{
"id": "asia_N1000_0",
"algorithm": "TABU",
"params": {"max_parents": 4, "tabu_size": 10},
"N": 1000,
"score": -24531.42,
"software_version": "1.3.0"
}
See Also¶
- Graph Merging — Combine migrated graphs into PDGs
- Trace API Reference — Trace class documentation