Skip to contents

Create Bash-Executable R Job Project

Source: R/interface.R
run_bash_job.Rd

Creates a standalone R project that can be executed in bash/terminal using tools like screen or tmux for persistent execution. This function generates all necessary files for running R jobs in server environments or for long-running processes that need to persist beyond the current R session.

Usage

run_bash_job(
  .file,
  .target_dictionary = NULL,
  .external_val = NULL,
  .job_name = NULL,
  .save_when_error = T,
  .save_method = c("qs2", "rds"),
  .check_memory_useage = F,
  .max_memory_useage = NULL,
  .gc_span = 0
)

Arguments

.file

Character. Path to the R script file to execute.

.target_dictionary

Character. Target directory where the project will be created. Must be provided and accessible. The directory will be created if it doesn't exist.

.external_val

List. Named list of external variables to make available in the execution environment. These will be saved to a file and loaded during execution. Default is NULL.

.job_name

Character. Optional name for the job used in logging and identification. If NULL, a timestamp-based name will be generated.

.save_when_error

Logical. Whether to save the environment state when a fatal error occurs. Default is TRUE.

.save_method

Character. Save method for error state and external variables. Either "qs2" for faster compression or "rds" for standard R serialization. Default is "qs2".

.check_memory_useage

Logical. Whether to monitor and report memory usage in log files. Default is FALSE.

.max_memory_useage

Numeric. Maximum memory usage in bytes. Job will be stopped if this limit is exceeded. Default is NULL (no limit).

.gc_span

Numeric. Interval for garbage collection. If > 0, performs gc() every N lines of code. Default is 0 (no automatic GC).

Value

Invisible NULL. The function creates files in the target directory and prints instructions for execution.

Details

This function creates a complete R project structure in the specified directory:

  • run.R: Main execution script

  • bg_job_external.files.*: Serialized external variables (if provided)

The generated project can be executed independently using: Rscript run.R

For persistent execution on servers, use:

  • screen -S job_name Rscript run.R

  • tmux new-session -d -s job_name 'Rscript run.R'

  • nohup Rscript run.R > output.log 2>&1 &

Note

If run.R already exists in the target directory, a new file with a random suffix will be created to avoid conflicts.

Author

Zhiming Ye

Examples

if (FALSE) { # \dontrun{
# Create a simple bash job project
run_bash_job(
  .file = "long_running_analysis.R",
  .target_dictionary = "~/projects/analysis_job",
  .job_name = "genomics_analysis"
)

# Create project with external data and memory monitoring
large_dataset <- read.csv("big_data.csv")
config <- list(threads = 8, output_format = "csv")

run_bash_job(
  .file = "data_processing.R",
  .target_dictionary = "/scratch/user/processing_job",
  .external_val = list(
    data = large_dataset,
    config = config,
    timestamp = Sys.time()
  ),
  .job_name = "big_data_processing",
  .check_memory_useage = TRUE,
  .max_memory_useage = 32e9,  # 32GB limit
  .save_method = "qs2"
)

# Execute the created project (run these commands in terminal):
# cd ~/projects/analysis_job
# screen -S analysis Rscript run.R
# # Detach with Ctrl+A, D
# # Reattach with: screen -r analysis

# Alternative execution methods:
# tmux new-session -d -s analysis 'Rscript run.R'
# nohup Rscript run.R > analysis.log 2>&1 &
} # }