---
title: "logrxpackage"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{logrxpackage}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

```{r setup, echo = FALSE}
library(logrx)
```

# Generating a log

The purpose of the `logrx` package is to generate a log upon execution of an R script which enables traceability and reproducibility of the executed code. Generating a log with `{logrx}` can be as simple as running one line of code as seen in the below example of how to use the `axecute()` function..  However, `{logrx}` has much more advanced capabilities to meet the demands of Clinical Reporting. To learn additional techniques about executing code with ```{logrx}``` please visit our [Execution Vignette](https://pharmaverse.github.io/logrx/articles/execution.html).

## `axecute()`

`axecute()` enables the command line submission of a program. A log is set-up around the program, and its code is run safely and loudly (using  `safely()` from the `purrr` package).  The log will be generated in the same folder as the script unless you specify differently.

```{r axecute, eval = FALSE}
axecute("my_script.R")
```

## `logrx` addin:

A log can be generated using the ```{logrx}``` addin, which is a simple point and click interface that allows you to run a single program.  The Addin ships with the package and is available once you use install the package.  The gif on the [Get Started](https://pharmaverse.github.io/logrx/index.html) page gives a quick snapshot of its intended use.  

# Log attributes

We have compiled a brief overview of the information that we capture in the log file generated by `{logrx}`.  We allow users to customize sections of the log based on their needs for a log, e.g. you can toggle on/off the messages, outputs, errors and messages.  You can also build into your log approved and unapproved packages used in your R script - see [Logging Unapproved Package and Function Use](https://pharmaverse.github.io/logrx/articles/approved.html) for additional guidance.  To see an example of what is included in a log file for an `adsl.R` script see [Logging for an ADSL dataset](https://pharmaverse.github.io/logrx/articles/adsl_demo.html).

The following attributes are recorded in the log:

* **Metadata**: `{logrx}` package information
   + Version of the package
   + Type of build
   + Link to the GitHub repository
* **User and File Information**
   + User that generated the log
   + Name and path of the script for which the log was generated
   + `hash_sum`: A unique hashsum is created for the log file
* **Session Information**: The R session information
   + R version
   + OS and system
   + GUI
   + Language and timezone
   + Packages - List of all available packages in the environment
   + External Software - List of all external software
* **Repo URLs (optional)** - URLs of the repositories for use by `install.packages()` and `updated.packages()`
* **Masked Functions** - List of all functions masked by packages
* **Program Run Time Information** - Start, end, and run times
* **Used Package and Functions (optional)** - List of all packages and functions used in the 
script for which the log was generated
* **Unapproved Package and Functions (optional)** - List of all packages and functions used in 
the script for which the log was generated that are not part of the approved 
list of packages and functions.
* **Errors and Warnings** - List of Errors and Warnings created during execution of the script. Since R does not return line numbers along with error or warning messages we do not include them in the log. The R programming language uses a call stack during execution making finding the exact location of an error without human interaction complicated.  
* **Messages, Output and Results (optional)** - List of Messages, Outputs and Results created during execution of the script.  In certain situations the log will not capture these if they are redirected to a different location.
* **Extra Info (optional)** - Extra info that use can manually add via a list object
* **Log Output File** - Name and path of the log