Command-line bioinformatics and reproducible execution

Practical 3: Genomics, systems biology and multi-omics

Learning objectives

Pass an explicit input path to a script; inspect exit status; distinguish stdout and generated files; quote paths containing spaces.

Biological question and data

Can the same file-processing task run independently of an interactive R session?

This portable exercise launches the Rscript executable belonging to the current R installation. It requires no Unix shell or external bioinformatics program. It illustrates the command-line interface pattern used by larger tools.

No biological download is required. Numerical inputs are hypothetical, not observed animal data. The runnable examples use base R. Count and abundance units are specified where used.

1. Create a small input and worker script

Both files live in a fresh temporary directory. The script takes exactly one input argument and validates it.

Show R code 
work <- tempfile("cli-example-"); dir.create(work)
input <- file.path(work,"sample counts.csv")
write.csv(data.frame(sample=c("s1","s2","s3"),count=c(10,20,30)),input,row.names=FALSE)
worker <- file.path(work,"summarise.R")
writeLines(c('args <- commandArgs(trailingOnly=TRUE)',
 'stopifnot(length(args)==1L, file.exists(args[1]))',
 'd <- read.csv(args[1])',
 'stopifnot(all(c("sample","count") %in% names(d)))',
 'cat(sum(d$count), "\n")'),worker)
readLines(worker)
[1] "args <- commandArgs(trailingOnly=TRUE)"               
[2] "stopifnot(length(args)==1L, file.exists(args[1]))"    
[3] "d <- read.csv(args[1])"                               
[4] "stopifnot(all(c(\"sample\",\"count\") %in% names(d)))"
[5] "cat(sum(d$count), \""                                 
[6] "\")"

Explicit arguments make the worker independent of objects in the current global environment.

2. Run and capture the process

Quote each path as a separate argument, including the intentionally spaced input filename.

Show R code 
executable <- file.path(R.home("bin"),if(.Platform$OS.type=="windows") "Rscript.exe" else "Rscript")
output <- system2(executable,args=c("--vanilla",shQuote(worker),shQuote(input)),
 stdout=TRUE,stderr=TRUE)
status <- attr(output,"status"); if(is.null(status)) status <- 0L
c(status=status,total=as.numeric(tail(output,1)))
status  total 
     0     60
Show R code 
stopifnot(status==0L,as.numeric(tail(output,1))==60)

The worker reports 60 and exits successfully. Locale-startup messages may appear before the final number on some systems.

3. Describe the workflow boundary

Record executable, arguments, input and expected output before applying this pattern to another tool.

Show R code 
record <- data.frame(step="sum counts",executable=basename(executable),
 input=basename(input),output="stdout total",expected_total=60)
record
        step  executable             input       output expected_total
1 sum counts Rscript.exe sample counts.csv stdout total             60

For a real aligner, include reference, version, options, resource requirements and the meaning of each output. A zero exit code does not certify biological correctness.

4. Validate a worker boundary

Command-line arguments are text. A worker should check required arguments, input existence and expected columns before producing a result. An output left from a previous run can remain present after a new run fails; checking only its presence is insufficient.

Show R code 
validate_table <- function(tab) {
 stopifnot(all(c('animal','value') %in% names(tab)),
 !anyDuplicated(tab$animal),is.numeric(tab$value),all(is.finite(tab$value)))
 TRUE
}
validate_table(data.frame(animal=c('a1','a2'),value=c(2,4)))
[1] TRUE
Show R code 
tryCatch(validate_table(data.frame(animal=c('a1','a1'),value=c(2,4))),
 error=function(e) 'duplicate key rejected')
[1] "duplicate key rejected"

5. Explain the reproducibility boundary

Record the exact command, worker version, input checksum and exit status. Capture errors separately from scientific output. A return status of zero indicates successful process completion under the program’s rules; it does not certify a valid biological analysis. Run an independent small calculation to verify the worker’s result, then investigate discrepancies before extending it to more files.

On real projects, use project-relative paths and preserve source inputs. Arguments containing spaces need shell-appropriate quoting; operating-system conventions should be documented for students.

Interpretation challenge

The output CSV exists, but the latest worker returned a nonzero status. Can it be used as the new result?

No. It could be stale or incomplete. Inspect the error, correct the failed run and verify that the expected output belongs to the successful invocation.

Interpretation and limits

Use tool-specific documentation for real aligners or quantifiers; this example runs no alignment. Keep restricted data out of command logs and public repositories. Temporary files are left in R’s temporary directory for inspection.

Exercises

  1. What changes if the worker relies on an interactive variable?
  2. Why quote the filename?
  3. Which check remains necessary after a successful exit?
  1. A clean Rscript process does not contain that variable.
  2. Spaces must stay within one argument.
  3. Check output structure, sample/reference identity and scientific plausibility, not just process completion.

Continue learning

B04 Programming and B17 Integrity.

Continue with data handling. Return to the practical index or the unified map.