report_RLum: Create a HTML report for (RLum) objects

Description

This function creates a HTML report for a given object, listing its complete structure and content. The object itself is saved as a serialised .Rds file. The report file serves both as a convenient way of browsing through objects with complex data structures as well as a mean of properly documenting and saving objects.

Usage

report_RLum(object, file = tempfile(), title = "RLum.Report",
  compact = TRUE, timestamp = TRUE, show_report = TRUE,
  launch.browser = FALSE, css.file = NULL, quiet = TRUE,
  clean = TRUE, ...)

Arguments

object

(required): The object to be reported on, preferably of any RLum-class.

file

character (with default): A character string naming the output file. If no filename is provided a temporary file is created.

title

character (with default): A character string specifying the title of the document.

compact

logical (with default): When TRUE the following report components are hidden: @.pid, @.uid, 'Object structure', 'Session Info' and only the first and last 5 rows of long matrices and data frames are shown. See details.

timestamp

logical (with default): TRUE to add a timestamp to the filename (suffix).

show_report

logical (with default): If set to TRUE the function tries to display the report output in the local viewer, e.g., within RStudio after rendering.

launch.browser

logical (with default): TRUE to open the HTML file in the system's default web browser after it has been rendered.

css.file

character (optional): Path to a CSS file to change the default styling of the HTML document.

quiet

logical (with default): TRUE to supress printing of the pandoc command line.

clean

logical (with default): TRUE to clean intermediate files created during rendering.

...

further arguments passed to or from other methods and to control the document's structure (see details).

Value

Writes a HTML and .Rds file.

Function version

0.1.1 (2018-06-10 16:57:37)

How to cite

Burow, C., Kreutzer, S. (2018). report_RLum(): Create a HTML report for (RLum) objects. Function version 0.1.1. In: Kreutzer, S., Burow, C., Dietze, M., Fuchs, M.C., Schmidt, C., Fischer, M., Friedrich, J. (2018). Luminescence: Comprehensive Luminescence Dating Data Analysis. R package version 0.8.6. https://CRAN.R-project.org/package=Luminescence

Details

The HTML report is created with rmarkdown::render and has the following structure:

Section	Description
`Header`	A summary of general characteristics of the object
`Object content`	A comprehensive list of the complete structure and content of the provided object.
`Object structure`	Summary of the objects structure given as a table
`File`	Information on the saved RDS file
`Session Info`	Captured output from `sessionInfo()`
`Plots`	(optional) For `RLum-class` objects a variable number of plots

The structure of the report can be controlled individually by providing one or more of the following arguments (all logical):

Argument	Description
`header`	Hide or show general information on the object
`main`	Hide or show the object's content
`structure`	Hide or show object's structure
`rds`	Hide or show information on the saved RDS file
`session`	Hide or show the session info
`plot`	Hide or show the plots (depending on object)

Note that these arguments have higher precedence than compact.

Further options that can be provided via the ... argument:

Argument	Description
`short_table`	If `TRUE` only show the first and last 5 rows of lang tables.
`theme`	Specifies the Bootstrap theme to use for the report. Valid themes include "default", "cerulean", "journal", "flatly", "readable", "spacelab", "united", "cosmo", "lumen", "paper", "sandstone", "simplex", and "yeti".
`highlight`	Specifies the syntax highlighting style. Supported styles include "default", "tango", "pygments", "kate", "monochrome", "espresso", "zenburn", "haddock", and "textmate".
`css`	`TRUE` or `FALSE` to enable/disable custom CSS styling

The following arguments can be used to customise the report via CSS (Cascading Style Sheets):

Argument	Description
`font_family`	Define the font family of the HTML document (default: arial)
`headings_size`	Size of the <h1> to <h6> tags used to define HTML headings (default: 166%).
`content_color`	Color of the object's content (default: #a72925).

Note that these arguments must all be of class character and follow standard CSS syntax. For exhaustive CSS styling you can provide a custom CSS file for argument css.file. CSS styling can be turned of using css = FALSE.

Examples

Run this code

# NOT RUN {
# }
# NOT RUN {
## Example: RLum.Results ----

# load example data
data("ExampleData.DeValues")

# apply the MAM-3 age model and save results
mam <- calc_MinDose(ExampleData.DeValues$CA1, sigmab = 0.2)

# create the HTML report
report_RLum(object = mam, file = "~/CA1_MAM.Rmd",
            timestamp = FALSE,
            title = "MAM-3 for sample CA1")

# when creating a report the input file is automatically saved to a
# .Rds file (see saveRDS()).
mam_report <- readRDS("~/CA1_MAM.Rds")
all.equal(mam, mam_report)


## Example: Temporary file & Viewer/Browser ----

# (a)
# Specifying a filename is not necessarily required. If no filename is provided,
# the report is rendered in a temporary file. If you use the RStudio IDE, the
# temporary report is shown in the interactive Viewer pane.
report_RLum(object = mam)

# (b)
# Additionally, you can view the HTML report in your system's default web browser.
report_RLum(object = mam, launch.browser = TRUE)


## Example: RLum.Analysis ----

data("ExampleData.RLum.Analysis")

# create the HTML report (note that specifying a file
# extension is not necessary)
report_RLum(object = IRSAR.RF.Data, file = "~/IRSAR_RF")


## Example: RLum.Data.Curve ----

data.curve <- get_RLum(IRSAR.RF.Data)[[1]]

# create the HTML report
report_RLum(object = data.curve, file = "~/Data_Curve")

## Example: Any other object ----
x <- list(x = 1:10,
          y = runif(10, -5, 5),
          z = data.frame(a = LETTERS[1:20], b = dnorm(0:9)),
          NA)

report_RLum(object = x, file = "~/arbitray_list")
# }
# NOT RUN {
# }

Run the code above in your browser using DataLab

Last chance! 50% off unlimited learning