Luminescence (version 0.9.25)

report_RLum: 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,
  ...
)

Value

Writes a HTML and .Rds file.

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).

Function version

0.1.5

Author

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

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., Colombo, M., 2024. Luminescence: Comprehensive Luminescence Dating Data Analysis. R package version 0.9.25. https://r-lum.github.io/Luminescence/

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.

See Also

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

Examples

if (FALSE) {
## 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")
}