Skip to contents

Describe one command of a pipeline

Source: R/run_step.R
run_step.Rd

Builds one step for run_pipeline(). run_step() takes the same command, arguments and env_name as run(), but it does not run anything. It only records the command, so run_pipeline() can start every step together and connect them with pipes.

Usage

run_step(cmd, ..., env_name = NULL, method = NULL, stderr)

Arguments

cmd

Character string, the command to run: a single, non-empty string. Its arguments go in ....

...

Arguments of the command, unnamed, as in run(). Each element of a character, numeric or logical vector is one argument. run_step() drops NULL values and writes numbers in full, never in scientific notation: it stores 100000 as "100000". NA, named arguments, and values that are not atomic vectors (for example lists) abort with class condathis_run_step_invalid_args.

env_name

Character string with the environment the command runs in, or an environment given by env_path(). Defaults to NULL: the env_name of run_pipeline(). A name must follow the rules of the env_name argument of run(). Invalid values abort with class condathis_invalid_env_name.

method

Character string naming the backend for this step, as the method of run_pipeline(). Defaults to NULL: the method of run_pipeline(). Steps that share an environment must agree on it. run_pipeline() checks whether the backend is registered when it runs, before it starts anything.

stderr

Standard error target for this step, replacing the stderr of run_pipeline(): "|" to capture it, NULL to discard it, or a file path. When not given, the step uses the stderr of run_pipeline().

Value

An object of class condathis_run_step, for run_pipeline(), which prints as the command line and its environment. c() combines steps into a list of steps of class condathis_run_steps, which c() extends again. c(step_1, step_2), c(c(step_1, step_2), step_3) and Reduce(c, steps) all give a list for run_pipeline(!!!steps). c() with a value that is not a step gives a plain list, as the default c() does.

Details

run_step() checks arguments when it builds the step, so it reports a mistake on the line that made it. Each invalid argument aborts with class condathis_run_step_invalid_<argument>, for example condathis_run_step_invalid_cmd, and with the shared classes condathis_invalid_<argument> and condathis_invalid_arg.

See also

Other commands: parse_output(), run(), run_bin(), run_pipeline()

Examples

condathis::run_step(
  "pigz", "--decompress", "--stdout", "reads.fastq.gz",
  env_name = "pigz-env"
)
#> <run_step> pigz --decompress --stdout reads.fastq.gz [env: pigz-env]
condathis::run_step(
  "rg", "--count", "^@read",
  env_name = condathis::env_path("/opt/envs/ripgrep")
)
#> <run_step> rg --count ^@read [env: /opt/envs/ripgrep]

# Combine steps with `c()`, then pass them to `run_pipeline()` with `!!!`
steps <- c(
  condathis::run_step("seq", "1", "10"),
  condathis::run_step("head", "-n", "3")
)
steps
#> <run_steps> 2 steps
#> [1] <run_step> seq 1 10 [env: pipeline default]
#> [2] <run_step> head -n 3 [env: pipeline default]