oxo-flow import#
Migrating a whole pipeline? Start here: Migrating from Nextflow or Snakemake walks the decision tree, the gate sequence, and the fidelity checklist. This page is the command reference.
Transpile a supported deterministic subset of Nextflow DSL2 or Snakemake
into a native .oxoflow workflow.
Usage#
Description#
oxo-flow import extracts process/rule definitions, resource directives,
environments, literal I/O patterns, and shell bodies into .oxoflow. It is a
deterministic translator, not an interpreter: there is no semantic parity
with the source engine, and every construct outside the documented subset is a
hard error that names the construct (parse-level errors carry a source line). The importer never invents a path, drops
a semantic directive, or writes a workflow it could not translate.
Before returning, the generated TOML is parsed and statically validated by the
engine (WorkflowConfig::parse + validate_format). If the emitter ever
produces an unrunnable workflow, the import fails and no output file is written.
What is translated#
Nextflow DSL2#
| Construct | Behavior |
|---|---|
process NAME { … } |
One rule per process (name lowercased) |
cpus / memory / time |
resources.threads / resources.memory / resources.time_limit; unparseable or dynamic values are errors |
disk / queue |
resources.disk / resources.partition |
scratch true |
scratch = true |
maxRetries N |
retries = N |
errorStrategy 'terminate' / 'retry' |
Accepted; ignore / finish are errors |
conda / container |
environment (literal specs only; dynamic values are errors) |
module |
environment.modules (HPC modules) |
env NAME, "value" / env 'NAME=value' |
envvars |
tag |
Ignored (cosmetic) |
label / publishDir |
Warning: resource settings from nextflow.config and output publishing are not imported |
when: task.ext.when == null \|\| task.ext.when |
Accepted with a warning (the rule runs unconditionally); any other when is an error |
stub: |
Ignored with a warning (test-only body) |
input: path/file channels |
Literal patterns or workflow-supplied variables; val/tuple val metadata is ignored |
output: path/file |
Every path expression on the declaration, including tuple members; emit: labels are kept |
script: / shell: |
Double-quoted, triple-quoted, and single-quoted bodies |
$task.cpus |
{threads} |
$task.ext.args / def args = task.ext.args ?: '' |
{config.ext_args}, with [config] ext_args = "" emitted |
$task.ext.prefix / def prefix = task.ext.prefix ?: "${meta.id}" / ${meta.id} |
{sample} |
Declared input variables ($reads, ${reads}) |
{input} / {input[N]} by declaration position |
versions.yml output |
Skipped (the engine records versions separately) |
| Workflow wiring | Call, pipe, channel-variable, upstream-output, and upstream-emit forms (table below) |
Hard errors (no output written):
include/includeConfig(the include graph is not followed; concatenate the files or import each module).- Dynamic
cpus/memory/time/container/conda,errorStrategy 'ignore'|'finish',maxForks,cache,storeDir,beforeScript,afterScript,resourceLimits,machineType,accelerator,clusterOptions,penv,exec:, and unknown process directives. stdinandenv(...)inputs.- A bare output glob (
path("*.bam")): the produced filename is unknown, and guessing would mistranslate the pipeline. Use an input-anchored expression (${reads}.bam,${meta.id}.bam) or a concrete filename. - Indexed input references (
${reads[0]},$reads[0]): oxo-flow exposes whole inputs, not per-file tuple indexing. Split the channel or hand-port. - Unresolved interpolations (
${params.x}, unknownmeta.*,task.ext.*other than args/prefix,Channel.*in a script, project/runtime paths). - A single-quoted script that references a declared input variable: Nextflow does not interpolate single-quoted strings, so mapping the variable would change the command.
- Fan-in and mixed outputs: a wildcard input that appears in no output of
the rule (e.g.
expand("quant/{sample}.sf", …)feeding a constantresults/report.txt, orrules.<name>.outputinto a constant output), or a wildcard fan-out whose output set mixes wildcard and constant paths (e.g.out/{sample}.bamplusreports/summary.txt). Every instance would write the constant output, and a wildcard input with no matching output has no fan-out source. Use the engine'sexpand_inputsfan-in construct (workflow-format reference) or hand-port the rule. - A process declared with
pathinputs but never invoked in aworkflow {}block (the input source is unknown). - A process invoked more than once in the workflow block.
- Input globs with more than one
*or character classes, and multi-outputPROC.outselections without.out.<emit>.
Snakemake#
| Construct | Behavior |
|---|---|
rule NAME: |
One rule per rule block; duplicate names are errors |
input: / output: |
Quoted literal patterns; fan-OUT expand("pattern/{wildcard}", …) where the rule's output carries the same wildcard; rules.<name>.output (single-output rules only) |
temp(…) / protected(…) / ancient(…) |
temporary + temp_output, protected_output, ancient |
touch(…) |
Treated as a plain output with a warning (the engine verifies declared outputs exist) |
threads: / priority: / retries: |
Rule fields |
resources: mem_mb, mem_gb, time/runtime, gpu, disk_mb |
resources (exact MB; other resource keys are errors) |
conda: / container: / singularity: / envmodules: |
environment; container wins over conda (warning); combining envmodules with conda/container is an error |
log: / benchmark: |
Rule log / benchmark fields; {log} / {benchmark} placeholders are translated |
envvars: |
envvars |
localrules: / global wildcard_constraints: |
Rule flags / [wildcard_constraints] |
shell: |
Single-line and triple-quoted bodies |
{input} / {input.name} / {output.name} / {wildcards.X} / {threads} |
Engine placeholders ({input[N]} by declared position) |
rule all (target-only sink) |
Dropped with a warning; an oxo-flow rule with no command would be rejected by validate |
Hard errors (no output written): params:, run:, script:, notebook:,
per-rule wildcard_constraints:, shadow:, group:, default_target:,
handlers:, include:, subworkflow, module, use rule, configfile:,
ruleorder:, onsuccess:, onerror:, directory(...), lambda/config/params/
checkpoints-based dynamic input/output, unknown directives, unknown resource
keys, duplicate rule names, fan-in/mixed outputs (a wildcard input with no
matching output wildcard, or wildcard inputs alongside a constant output that
every instance would overwrite — use expand_inputs or hand-port), and
{params.*} / {resources.*} / {rule} / {checkpoints.*} placeholders in
shell:.
For a fan-out expand(pattern, key=[...]), the explicit value list is not
materialized: the pattern is imported, but the wildcard domain must be
declared with sample_pattern, [[sample_groups]], [[pairs]], or
[[values]] before running.
Brace text the importer does not recognize (bash ${VAR}, brace expansion,
awk {print $1}) passes through unchanged.
Nextflow wiring forms#
The importer resolves a process's input channels, in the order the process declares them, from exactly these forms:
| Form | Example | Result |
|---|---|---|
| Call, direct source | COUNT(Channel.fromPath("data/*.txt")) |
input data/{sample}.txt + sample_pattern |
| Call, channel variable | reads = Channel.fromPath("data/*.txt") then COUNT(reads) |
same as above |
| Pipe, direct source | Channel.fromPath("data/*.txt") \| COUNT |
same as above |
| Pipe, channel variable | reads \| COUNT |
same as above |
| Upstream output | ALIGN(TRIM.out) |
input = TRIM's single output pattern; adds depends_on = ["trim"] |
| Upstream emit | ALIGN(TRIM.out.bam) |
input = TRIM's emit: bam output pattern; adds the edge |
| Upstream-output pipe | TRIM.out.bam \| ALIGN |
same as TRIM.out.bam above |
Wiring is positional: argument i feeds the process's i-th declared path
input, and the argument count must match the declaration count. Any other
wiring expression aborts the import with the construct named.
After importing#
The import warnings are the migration checklist. Always run the static gates in order:
validate checks the workflow contract and BioTypes, lint reports best
practices, and dry-run previews the resolved commands and missing inputs.
None of them executes a tool or proves scientific equivalence — see
Migrating from Nextflow or Snakemake
for the full checklist.
When --from is omitted, oxo-flow import auto-detects the source format from
the file extension (.nf for Nextflow, Snakefile or .smk for Snakemake) or
through content inspection.
Options#
| Option | Description |
|---|---|
<SOURCE> |
Path to the Nextflow (.nf) or Snakemake (Snakefile, .smk) source file |
--from <FORMAT> |
Explicit source format: nextflow or snakemake (auto-detected if omitted) |
-o, --output <OUTPUT> |
Output .oxoflow file (prints to stdout if omitted). Existing files are never overwritten |
Examples#
Transpile a Nextflow pipeline and print to stdout:
Transpile a Snakemake pipeline to a file:
Transpile with an explicit format: