Skip to content

Action Patterns

CausalIQ workflow actions follow one of two patterns, determined by whether they read a workflow cache: Create writes entries without reading a cache, and Aggregate reads entries from a cache and writes new ones. Actions that write a plain file instead of a cache run once, outside matrix expansion.

Pattern Summary

Pattern Input Output Matrix Purpose
Create action-specific required required Generate new cache entries
Aggregate required required required Combine entries into summaries

Pattern 1: Create

Create actions generate new entries in an output cache.

Parameter Requirement
input Not used (or refers to data files, not caches)
output Required (workflow cache path)
matrix Required

The matrix defines the combinations for which entries are created. Each matrix combination produces one entry in the output cache.

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"

This creates 4 entries (2 networks × 2 sample sizes) in graphs.db.

Conservative Execution

An entry is created only if it does not already exist. If an entry with matching matrix values exists, the action is skipped for that combination.

Run-once Steps

Steps that write a plain file instead of a workflow cache run once.

Parameter Requirement
input Any (data files or a workflow cache)
output Required, but not a .db cache
matrix Not required

A file output has no cache dimensionality, so the step runs a single time however many matrix combinations the workflow declares, and it is skipped on later jobs. Such a step may still read a cache: plot reads a metrics cache and writes one image. A file-output step that also declares a matrix keeps per-combination granularity; summarise relies on this to write one row per combination.

A step that calls another workflow follows its own rule: it runs once unless its with values vary across the matrix. See Reusable Workflows.

matrix:
  network: [asia, cancer]
  sample_size: [100, 1000]

steps:
  - name: "Plot F1"
    uses: "causaliq-analysis"
    with:
      action: "plot"
      input: "results/metrics.db"
      output: "results/f1.png"

Pattern 2: Aggregate

Aggregate actions combine multiple entries into summary entries.

Parameter Requirement
input Required (workflow cache path)
output Required (workflow cache path)
matrix Required

The matrix controls the output dimensionality — input entries are grouped by matrix values and aggregated into new entries in the output cache.

matrix:
  network: [asia, cancer]

steps:
  - name: "Merge by Network"
    uses: "causaliq-analysis"
    with:
      action: "merge_graphs"
      input: "results/graphs.db"
      output: "results/merged.db"

If graphs.db contains entries for multiple sample sizes per network, this produces 2 entries in merged.db — one merged result per network.

Entry Grouping

Entries from the input cache are automatically grouped by current matrix values. For each matrix combination, all matching entries are passed to the action for aggregation.

A null value on either side (target or entry) is treated as a wildcard and always matches. A missing key on the entry side (dimension absent from the input cache) is also treated as a wildcard. See Null Values and Dimension Matching for the full matching rules.

Filtering Entries

Use the filter parameter to restrict which entries are aggregated:

steps:
  - name: "Merge Filtered"
    uses: "causaliq-analysis"
    with:
      action: "merge_graphs"
      input: "results/graphs.db"
      filter: learn_graph.edge_count > 5 and sample_size >= 100
      output: "results/merged.db"

Matrix and result-object fields use bare names; metadata uses the producer qualifier (learn_graph.edge_count).

Filter expressions support template variables, so you can parameterise the filter per matrix combination:

matrix:
  network: [asia, cancer]
  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"

Here, for each matrix combination the filter resolves to concrete values, selecting the matching LLM entry from one cache and the matching BNSL entry from the other for fusion. Entries from each cache only contain dimensions relevant to their source, and missing dimensions are treated as wildcards during matching.

See Common Parameters for filter expression syntax.

Conservative Execution

An output entry is created only if it does not already exist in the output cache.

Choosing the Right Pattern

You want to... Use pattern
Generate graphs from data Create
Evaluate graphs and store metrics Aggregate
Merge multiple graphs into one Aggregate
Compute statistics across experiments Aggregate
Convert file formats Create
Plot results to an image Run once (file output)

Force Mode

To bypass conservative execution and re-run actions regardless of existing results, use --mode=force:

cqflow run workflow.yml --mode=force

This re-processes all applicable entries but does not override filter expressions (filtered entries remain excluded).