Skip to content

Common Parameters

These parameters are shared across many CausalIQ workflow actions. Individual action documentation specifies which parameters apply and any action-specific behaviour.

Defaults and Omission

Omitting a parameter applies the action's declared default, and it is also how a parameter that does not apply is expressed. There is no "none" or "null" value to learn: write neither, and the action evaluates only what applies.

Where a default has a natural explicit spelling, the action exposes it as a value so the default can be pinned, compared in a filter, or passed to a called workflow:

Parameter Default value Meaning
randomise no-randomise apply no randomisation
sample_size all use every row
variable_types impute infer types from the data
timeout 60 sixty minutes

A literal null in a with block is rejected; use omission instead. See Core Concepts for the full rule and the matrix wildcard exception.

input Parameter

Specifies the source of data for the action.

Usage Description
Workflow cache Path to .db file containing entries to process
Data files Path to input files (CSV, GraphML, etc.)
with:
  input: "results/graphs.db"       # Process entries from cache

For aggregate steps, input points to a workflow cache. For create steps, it may point to data files.

Multiple Inputs

Some actions accept multiple input sources:

with:
  input:
    - "results/llm_graphs.db"
    - "results/discovery_graphs.db"

output Parameter

Specifies where results should be stored.

Usage Description
Workflow cache Path to .db file for storing results
Directory Path to directory for file output
with:
  output: "results/merged.db"      # Store results in cache

Note: Steps that write a plain file (for example plot) also take output; it names the file rather than a workflow cache.

Output Behaviour by Pattern

Pattern Output Behaviour
Create Required New entries added to output cache
Aggregate Required Aggregated entries added to output cache
Run once Required file One file written, outside matrix expansion

filter Parameter

Restricts which entries are processed by the action.

with:
  input: "results/graphs.db"
  filter: sample_size >= 100 and network in ['asia', 'cancer']

Filter Syntax

Filter expressions use Python syntax with supported operators:

Category Operators
Comparison ==, !=, >, <, >=, <=
Boolean and, or, not
Membership in
Grouping ()

Bare Values in Filters

A bare word on the right of a comparison is a literal value unless it is a declared parameter or a matrix variable used as a reference:

filter: network == asia and f1 > 0.8

The expression above is equivalent to network == 'asia' and f1 > 0.8, and both forms are accepted. Quote a value only when its text collides with a workflow parameter or with a field name used on the left of a comparison:

filter: description == 'description'   # literal text
filter: description == description     # declared parameter or left-hand field

The left side of a comparison is always a field reference. See Values and Quoting for the full rules.

Supported Functions

Function Description
len() Length of string or list
str() Convert to string
int() Convert to integer
float() Convert to float
bool() Convert to boolean
abs() Absolute value
min() Minimum of values
max() Maximum of values

Random Sampling in Filters

The random(count, seed) function selects a reproducible random subset of values for a variable. Use it with the in operator:

filter: pdg_seed in random(5, 42)

This collects all distinct values of pdg_seed across the entries, then deterministically selects 5 of them using the given seed. Only entries whose pdg_seed is in the selected set pass the filter.

The selection is deterministic — the same seed always produces the same subset, ensuring reproducibility across runs.

# Select 3 random seeds and 2 random sample sizes
filter: pdg_seed in random(3, 0) and sample_size in random(2, 1)

!!! note The total number of distinct values for the variable must be at least as large as the requested count. If fewer distinct values exist, an error is raised.

Filter Variables

Filter expressions can reference matrix values, result-object fields and producer metadata:

# Matrix and result-object fields use bare names
filter: network in ['asia', 'cancer', 'alarm'] and f1 > 0.8

# Metadata uses the action qualifier
filter: learn_graph.algorithm == 'pc' and learn_graph.status == 'ok'

# Nested metadata uses the full path
filter: learn_graph.hyperparameters.iss > 10 and sample_size < 10000

Bare metadata names such as status or algorithm are rejected: the reference must name the producer (learn_graph.status, evaluate_graph.status). Use the explicit learn_graph.parameters.algorithm and learn_graph.result.status forms when a name exists in both blocks, and the provider-qualified causaliq_discovery.learn_graph.status form when action names collide.

Template Variables in Filters

Filter expressions support {{variable}} template substitution, resolved from workflow parameters, supplied parameters and matrix values before evaluation. This enables parameterised filters that change per matrix combination:

matrix:
  network: [asia, cancer]
  llm_model: [anthropic_claude, gemini_flash]

steps:
  - name: "Merge by Model"
    uses: "causaliq-analysis"
    with:
      action: "merge_graphs"
      input: "results/pdgs.db"
      filter: llm_model == '{{llm_model}}' or sample_size == '1K'
      output: "results/merged.db"

For the {network: asia, llm_model: anthropic_claude} combination, the filter resolves to llm_model == 'anthropic_claude' or sample_size == '1K'.

Filter vs Conservative Execution

Mechanism Purpose Result
filter Exclude entries from processing Entry status: IGNORED
Conservative execution Skip already-processed entries Entry status: SKIPPED

Filtered entries are never processed, even with --mode=force.

reference Parameter

For evaluation actions, specifies the ground truth for comparison.

with:
  action: "evaluate_graph"
  input: "results/graphs.db"
  reference: "networks/{{network}}/true.graphml"

The reference path often uses template variables to match entries with their corresponding ground truth files.

metric Parameter

Specifies which metrics to compute for evaluation actions.

with:
  action: "evaluate_graph"
  input: "results/graphs.db"
  reference: "networks/asia/true.graphml"
  metric:
    - f1
    - precision
    - recall
    - shd

Available metrics depend on the specific action. See action documentation for supported metrics.

Template Variables in Parameters

Most parameters support template variable substitution:

id: "exp-001"

matrix:
  network: [asia, cancer]

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

See Core Concepts for variable resolution order.