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

View source: R/report_RLum.R

report_RLumR Documentation

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.