Workflow Examples
This page provides concise examples illustrating the workflow concepts documented in the User Guide.
Minimal Workflow
A single-step workflow with no matrix:
# simple.yml
steps:
- name: "Evaluate Graphs"
uses: "causaliq-analysis"
with:
action: "evaluate_graph"
input: "results/graphs.db"
reference: "networks/asia/true.graphml"
Workflow with Parameters
Declare workflow parameters for identification and path management, with optional defaults:
# with_parameters.yml
id: "experiment-001"
reference: "networks/asia/true.graphml"
steps:
- name: "Evaluate Graphs"
uses: "causaliq-analysis"
with:
action: "evaluate_graph"
input: "results/{{id}}/graphs.db"
reference: {{reference}}
# Override a declared default
cqflow run with_parameters.yml --param id=experiment-002
Matrix Expansion
Run steps across multiple parameter combinations:
# matrix_example.yml
matrix:
network: [asia, cancer, alarm]
sample_size: [100, 1000]
steps:
- name: "Learn Structure"
uses: "causaliq-discovery"
with:
action: "learn_structure"
network: {{network}}
sample_size: {{sample_size}}
output: "results/graphs.db"
This creates 6 cache entries (3 networks × 2 sample sizes).
Template Variables
Reference workflow and matrix values in parameters:
# templates.yml
id: "exp-001"
matrix:
network: [asia, cancer]
steps:
- name: "Learn"
uses: "causaliq-discovery"
with:
action: "learn_structure"
network: {{network}}
dataset: "data/{{network}}_10k.csv"
output: "results/{{id}}/graphs.db"
Create Pattern
Generate new cache entries (requires matrix and output):
# create_pattern.yml
matrix:
network: [asia, cancer]
sample_size: [100, 1000]
steps:
- name: "Learn Graphs"
uses: "causaliq-discovery"
with:
action: "learn_structure"
network: {{network}}
sample_size: {{sample_size}}
output: "results/graphs.db"
Run-once Steps
Steps that write a plain file run once, even when the workflow declares a matrix:
# plot_pattern.yml
matrix:
network: [asia, cancer]
steps:
- name: "Plot Metrics"
uses: "causaliq-analysis"
with:
action: "plot"
input: "results/metrics.db"
output: "results/f1.png"
Aggregate Pattern
Combine entries into summaries (requires input, output, and matrix):
# aggregate_pattern.yml
matrix:
network: [asia, cancer]
steps:
- name: "Merge by Network"
uses: "causaliq-analysis"
with:
action: "merge_graphs"
input: "results/graphs.db"
output: "results/merged.db"
Entries are grouped by matrix values; one output entry per network.
Multi-Step Workflow
Chain multiple steps sequentially:
# multi_step.yml
matrix:
network: [asia, cancer]
sample_size: [100, 1000]
steps:
- name: "Learn Structure"
uses: "causaliq-discovery"
with:
action: "learn_structure"
network: {{network}}
sample_size: {{sample_size}}
output: "results/graphs.db"
- name: "Evaluate Graphs"
uses: "causaliq-analysis"
with:
action: "evaluate_graph"
input: "results/graphs.db"
reference: "networks/{{network}}/true.graphml"
Filtering Entries
Restrict which entries are processed:
# with_filter.yml
matrix:
network: [asia]
steps:
- name: "Evaluate High-Quality"
uses: "causaliq-analysis"
with:
action: "evaluate_graph"
input: "results/graphs.db"
filter: learn_graph.edge_count > 5 and sample_size >= 100
reference: "networks/{{network}}/true.graphml"
Aggregation with Parameterised Filters
Use template variables in filters to select different subsets per matrix
combination. Store entries from different sources in separate caches
and use the list syntax for input: to read from both:
# fuse.yml
matrix:
network: [asia, sports]
llm_model: [anthropic_claude, gemini_flash]
sample_size: [1K, 10K]
steps:
- name: "Fuse LLM and BNSL PDGs"
uses: "causaliq-analysis"
with:
action: "merge_graphs"
input:
- "results/bnsl-pdgs.db"
- "results/llm-pdgs.db"
filter: llm_model == '{{llm_model}}' or sample_size == '{{sample_size}}'
output: "results/fused.db"
For {network: asia, llm_model: anthropic_claude, sample_size: 1K}, the
filter resolves to llm_model == 'anthropic_claude' or sample_size == '1K',
selecting the matching LLM entry from one cache and the matching BNSL entry
from the other. Each cache only contains dimensions relevant to its source;
missing dimensions are treated as wildcards during matching (see
Null Values and Dimension Matching).
Reusable Workflow
Call another workflow file in place of an action step:
# parent.yml
steps:
- name: Asia benchmark
uses: ./modules/benchmark.yml
with:
sample_size: 1000
- name: Summarise
uses: causaliq-analysis
with:
action: summarise
input: results/graphs.db
output: results/summary.csv
# modules/benchmark.yml
sample_size: 1000
matrix:
network: [asia, cancer]
steps:
- name: Learn graphs
uses: causaliq-discovery
with:
action: learn_structure
network: {{network}}
sample_size: {{sample_size}}
output: results/graphs.db
The call resolves ./modules/benchmark.yml relative to parent.yml and
runs the whole called workflow once. See
Reusable Workflows.
Running Workflows
# Validate and preview (default)
cqflow run workflow.yml
# Execute with conservative execution
cqflow run workflow.yml --mode=run
# Force re-execution of all steps
cqflow run workflow.yml --mode=force
# Detailed per-entry logging
cqflow run workflow.yml --mode=run --log-depth=2
Further Reading
- Core Concepts — Workflows, steps, matrix
- Action Patterns — Create, aggregate and run-once steps
- Workflow Caching — Result storage
- Common Parameters — Shared parameters
- CLI Usage — Command-line interface