Generating a Log

logrx has been built with both the flexibility of code execution and a number of different use cases in mind. While the basic case has been outlined in our Get Started vignette, here we will be discussing different methods of execution and creation of log files. These examples are meant to guide users who wish to explore different methods of execution or for those using logrx to create scripting.

Methods of Execution

Below you will find a number of examples for different methods of execution, these go in an increasing level of complexity and increasing level of technical knowledge. The below examples are meant to be starting points for those interested in using logrx in more complex settings.

axecute()

The easiest of the execution methods to use is axecute(). This function can be used to execute code from an R terminal or using command line scripts. A log is set-up around the program, and its code is run safely and loudly (using safely() from purrr).

axecute("my_script.R")

log_*() functions

The log_*() family of functions are the core of logrx and are used internally to configure, write, and remove the log and other objects. While these are exported functions of the package, they are intended to be used in special cases where axecute() will not work.

Use the log_*() functions to do the following:

• log_init() to create the environment log.rx

• log_config() to add the core elements of the log to the environment, and basic elements that are available at the time of configuration

• run_safely_loudly() to execute the program code, and capture errors, warnings, messages, output, and result. This must be passed an executable R file to run and create the log elements from

• log_write() to generate and format the log

• log_remove() to remove the log.rx environment created by code execution

log_config("my_script.R")
run_safely_loudly("my_script.R")
log_write()
log_remove()

Command Line Execution

While executing from an R terminal is nice if you have access to one, you can also execute your code using system command line. This is done using the Rscript -e command which executes a file using the registered Rscript executable. Below are a few examples of how to use the command line to execute a file and create a log as well as how to manipulate the outputs of the execution. These are likely to be advanced examples for most users.

The below chunk will run the file my_script.R and output any standard output that is created by the execution of the file to the default location.

Rscript -e "logrx::axecute('my_script.R', log_name = 'my_script.log', log_path = '.')"

The below chunk will run the file my_script.R and output any standard output that is created by the execution of the file to a file called temp.log. This output can then later be accessed should the user want to check the output of the file execution.

Rscript -e "logrx::axecute('my_script.R', log_name = 'my_script.log', log_path = '.')" > temp.log 2>&1

The below chunk will run the file my_script.R and output any standard output that is created by the execution of the file to a file called temp.log. It will then take the contents of the temp.log file and add those to the end of the log file generated by the file execution and remove the temporary output log.

Rscript -e "logrx::axecute('my_script.R', log_name = 'my_script.log', log_path = '.')" > temp.log 2>&1; cat my_script.log >> my_script.log; rm my_script.log

Scripting with logrx

While logrx is built around creating a log for a program it can just as easily be used when running an entire set of programs. The axecute() function has been built with both single file execution and scripted file execution in mind. With the use of simple functions such as lapply() scripting is easy. Below is some sample code of how lapply() can be used with axecute().

lapply(c("file.R", "otherfile.R"), axecute)

If your scripting needs to work on the contents of a directory instead of a pre-defined list, functions such as list.files can be used to obtain a list of files to use. Below is an example of how this can be applied in practice by getting all files ending in .R in the current working directory using a regular expression, and then using lapply() to run the files using axecute().

r_script_list <- list.files(path = ".", pattern = "\\.R$")
lapply(r_script_list, axecute)

Additionally, if you need your code to run using a shell scripting language such as bash these files can be created to run using the previously outlined Command Line Execution examples. The above scripting examples can be translated into a variety of different scripting languages. Below is an example where the bash script is executed in a directory of R files, this should execute all R files in the directory using axecute() and create a corresponding set of log files.

for file in *.R; do
    [ -f "$file" ] || continue
    Rscript -e "logrx::axecute('$file')"
done