logr.Rmd

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

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

The **logr** package helps create log files for R scripts.  The package 
provides easy logging, without the complexity of other logging systems.  It is 
designed for analysts who simply want a written log of their program 
execution.  The package is implemented as a wrapper to 
the base R `sink()` function.

## How to use
There are really only three **logr** functions:  

* `log_open()`
* `log_print()`
* `log_close()`  

The `log_open()` function initiates the log.  The 
`log_print()` function prints an object to the log.  The `log_close()` function
closes the log.  In normal situations, a user would place the call to 
`log_open()` at the top of the program, call `log_print()` as needed in the 
program body, and call `log_close()` once at the end of the program.

A sample program is as follows:
```{r eval=FALSE, echo=TRUE}
library(logr)

# Create temp file location
tmp <- file.path(tempdir(), "test.log")

# Open log
lf <- log_open(tmp)

# Send message to log
log_print("High Mileage Cars Subset")

# Perform operations
hmc <- subset(mtcars, mtcars$mpg > 20)

# Print data to log
log_print(hmc)

# Close log
log_close()

# View results
writeLines(readLines(lf))

```

### What to print to the log
You can print to the log anything that you can print to the console: vectors,
lists, and data frames are all valid objects for logging.  Under the hood, 
**logr** calls the `print()` function on that object, and writes the results 
to the log. The `log_print()` function, by default, will also print the 
object to the console. That means you can replace calls to `print()` with 
`log_print()`, and there will be no loss of convenience during development.

### What the log looks like
The log created by **logr** is simpler than most logging packages.  This 
log is designed to be human-readable, and increases the traceability of your
activities.  There are three main enhancements to a **logr** log:

  * A log header
  * Notes
  * A log footer

Here is an example log, created by the sample program above:
```
========================================================================= 
Log Path: C:/Users/dbosa/AppData/Local/Temp/RtmpQtOzhy/log/test.log 
Working Directory: C:/packages/logr 
User Name: dbosak 
R Version: R Under development (unstable) (2020-06-29 r78751) 
Machine: BOSAK-MAIN x86-64 
Operating System: Windows 10 x64 build 18362 
Base Packages: stats graphics grDevices utils datasets methods base
Other Packages: logr_1.2.7 dplyr_1.0.7 testthat_3.1.0 
Log Start Time: 2020-06-30 07:15:52 
========================================================================= 

High Mileage Cars Subset 

NOTE: Log Print Time:  2020-06-30 07:15:52 
NOTE: Elapsed Time in seconds: 0.0219531059265137 

                mpg cyl  disp  hp drat    wt  qsec vs am gear carb
Mazda RX4      21.0   6 160.0 110 3.90 2.620 16.46  0  1    4    4
Mazda RX4 Wag  21.0   6 160.0 110 3.90 2.875 17.02  0  1    4    4
Datsun 710     22.8   4 108.0  93 3.85 2.320 18.61  1  1    4    1
Hornet 4 Drive 21.4   6 258.0 110 3.08 3.215 19.44  1  0    3    1
Merc 240D      24.4   4 146.7  62 3.69 3.190 20.00  1  0    4    2
Merc 230       22.8   4 140.8  95 3.92 3.150 22.90  1  0    4    2
Fiat 128       32.4   4  78.7  66 4.08 2.200 19.47  1  1    4    1
Honda Civic    30.4   4  75.7  52 4.93 1.615 18.52  1  1    4    2
Toyota Corolla 33.9   4  71.1  65 4.22 1.835 19.90  1  1    4    1
Toyota Corona  21.5   4 120.1  97 3.70 2.465 20.01  1  0    3    1
Fiat X1-9      27.3   4  79.0  66 4.08 1.935 18.90  1  1    4    1
Porsche 914-2  26.0   4 120.3  91 4.43 2.140 16.70  0  1    5    2
Lotus Europa   30.4   4  95.1 113 3.77 1.513 16.90  1  1    5    2
Volvo 142E     21.4   4 121.0 109 4.11 2.780 18.60  1  1    4    2

NOTE: Data frame has 14 rows and 11 columns. 

NOTE: Log Print Time:  2020-06-30 07:15:52 
NOTE: Elapsed Time in seconds: 0.0508558750152588 

========================================================================= 
Log End Time: 2020-06-30 07:15:53 
Log Elapsed Time: 0 00:00:00 
========================================================================= 
```

### Next Steps

For addition exploration of the **logr** package, please read the 
following articles:

* [Log Parts](logr-parts.html)
* [Additional Features](logr-features.html)
* [Global Options](logr-globals.html)
* [Aliases for log_print()](logr-put.html)
* [tidylog Integration](logr-tidylog.html)
* [Complete Example](logr-example1.html)