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 Properties

Add workflow-level properties for identification and path management:

# with_properties.yml
id: "experiment-001"
description: "Evaluate learned graphs"
root_dir: "/experiments/project"

steps:
  - name: "Evaluate Graphs"
    uses: "causaliq-analysis"
    with:
      action: "evaluate_graph"
      input: "results/graphs.db"
      reference: "networks/asia/true.graphml"

Matrix Expansion

Run steps across multiple parameter combinations:

# matrix_example.yml
id: "comparison"

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"

Update Pattern

Add analysis to existing entries (requires input, no matrix or output):

# update_pattern.yml
steps:
  - name: "Evaluate Graphs"
    uses: "causaliq-analysis"
    with:
      action: "evaluate_graph"
      input: "results/graphs.db"
      reference: "networks/{{network}}/true.graphml"

The {{network}} variable resolves from each entry's metadata at runtime.

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
id: "full-pipeline"

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
steps:
  - name: "Evaluate High-Quality"
    uses: "causaliq-analysis"
    with:
      action: "evaluate_graph"
      input: "results/graphs.db"
      filter: "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).

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-level=all

Further Reading