Skip to content

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