report_RLum: Create a HTML-report for (RLum) objects

In Luminescence: Comprehensive Luminescence Dating Data Analysis

Create a HTML-report for (RLum) objects

Description

Create a HTML-report for (RLum) 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 suppress 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).

Details

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.

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 long 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	Colour 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.

Value

Writes a HTML and .Rds file.

Function version

0.1.5

How to cite

Burow, C., Kreutzer, S., 2024. report_RLum(): Create a HTML-report for (RLum) objects. Function version 0.1.5. In: Kreutzer, S., Burow, C., Dietze, M., Fuchs, M.C., Schmidt, C., Fischer, M., Friedrich, J., Mercier, N., Philippe, A., Riedesel, S., Autzen, M., Mittelstrass, D., Gray, H.J., Galharret, J., 2024. Luminescence: Comprehensive Luminescence Dating Data Analysis. R package version 0.9.24. https://CRAN.R-project.org/package=Luminescence

Note

This function requires the R packages 'rmarkdown', 'pander' and 'rstudioapi'.

Author(s)

Christoph Burow, University of Cologne (Germany), Sebastian Kreutzer, Institute of Geography, Heidelberg University (Germany)
, RLum Developer Team

See Also

rmarkdown::render, pander::pander_return, pander::openFileInOS, rstudioapi::viewer, browseURL

Examples

## 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")

## End(Not run)

Luminescence documentation built on June 22, 2024, 9:54 a.m.