Report functions for HTML and PDF files

Description

The R3port package is written to easily create pdf and html documents including tables, listings and plots.

Details

The package makes use of the option system within R. The way it was implemented is to always use an option in case it was set in options(). If an option is NULL, the function will evaluate the argument. The following options can be set within the package:

• show (see ltx_doc(), html_doc())

• template (see ltx_doc(), html_doc())

• css (see html_doc())

• compile (see ltx_doc())

• orientation (see ltx_doc())

• pwidth (see ltx_plot(), html_plot())

• pheight (see ltx_plot(), html_plot())

Author(s)

Maintainer: Richard Hooijmaijers richardhooijmaijers@gmail.com

Other contributors:

• Richard Hooijmaijers [copyright holder]

See Also

Useful links:

• https://github.com/RichardHooijmaijers/R3port

Calculate frequency statistics on data frame

Description

This function calculates frequency statistics on a data frame. It is intended to use to calculate the frequency and percentages based on a predefined denominator.

Usage

freq(
  dfrm,
  vars,
  id,
  denom = nrow(dfrm),
  dig = 2,
  total = NULL,
  totaldenom = nrow(dfrm),
  spacechar = NULL
)

Arguments

Details

The function calculates frequency statistics of variable(s) within a data frame. Furthermore, the frequencies for a total can also be generated. To calculate the percentages, the denominator should be supplied (and in case totals has a value also totaldenom). The denom and totaldenom can be a constant numerical value, a variable within the data frame or a separate data frame. In case the argument is a data frame, the function will attempt to merge this data frame based on equal variables within dfrm/denom and dfrm/totaldenom. The possibility for a separate denominator is implemented as in many cases the denominator is not the total number of observations but is defined elsewhere (e.g. for number of adverse events, the total number of subjects is used as denominator).

Value

The function returns a dataframe with frequencies and percentages

Examples

data(Indometh)
freq(Indometh,vars="time",id="Subject",
        denom=nrow(Indometh),total="",totaldenom=nrow(Indometh))

Combines multiple HTML files to a single tex and compiles document

Description

This function combines multiple HTML files. This is done based on the name of the files and should end with raw.tex to make the function pick-up these files.

Usage

html_combine(
  combine = ".",
  out = NULL,
  toctheme = TRUE,
  css = paste0(system.file(package = "R3port"), "/style.css"),
  clean = 0,
  ...
)

Arguments

Details

Currently the generated output is saved in the same place where the separate tables and plots are located defined in the 'combine' argument. This is done even when a different file path is specified in 'out' (using the basename function). The reason is to not copy files linked within the document and preventing broken links. This behaviour might change in future releases

Value

The function returns a HTML file (or writes output to console)

Examples

# Take into account the usage of tempfile() with multiple function calls
data(Theoph)
html_list(Theoph[1:11,],out=tempfile(fileext=".html"),show=FALSE)
html_plot(plot(conc~Time,data=Theoph),out=tempfile(fileext=".html"),show=FALSE)
## Not run: 
  html_combine(combine=tempdir(),out="rep1.html")

  # toctheme can be used to have a clickable toc,
  # a bootstrap template for this is provided in the package
  html_combine(combine=tempdir(),out="rep1.html",
              template=paste0(system.file(package="R3port"),"/bootstrap.html"),
              toctheme=TRUE)
 
## End(Not run)

Prints a HTML table, listing or plot to a a file or console

Description

This function makes a HTML document using output generated with functions in the R3port package or any other HTML code available as vector. Basically it adds tags to a html template file and let's the user select various options to customize the output.

Usage

html_doc(
  text,
  out = NULL,
  show = TRUE,
  rtitle = "report",
  template = paste0(system.file(package = "R3port"), "/simple.html"),
  rendlist,
  css = paste0(system.file(package = "R3port"), "/style.css")
)

Arguments

Details

This function is used as wrapper within multiple functions in the R3port package but is also convenient in case custom information should be placed within an output document

Value

The function returns a HTML file (or writes output to console)

See Also

ltx_doc()

Examples

txt <- "<h1>Example</h1>"
tbl <- "<table><tr><td id='fcol'>table data</td><td>for custom table</td></tr></table>"
add <- "<p>Including some additional text</p>"
## Not run: 
  html_doc(c(txt,tbl,add),out=tempfile(fileext=".html"))

## End(Not run)

Creates a HTML listing

Description

This function creates a HTML listing which can be written to a file or console

Usage

html_list(
  dfrm,
  vars = names(dfrm),
  fill = "",
  vargroup = NULL,
  porder = TRUE,
  uselabel = TRUE,
  footnote = NULL,
  title = "listing",
  titlepr = NULL,
  group = NULL,
  xrepeat = FALSE,
  tclass = "sample",
  out = NULL,
  rawout = paste0(out, ".rawhtml"),
  ...
)

Arguments

Details

The vargroup argument should be provided in the following form:
c(rep("",4),rep("group1",3),rep("group2",4)). The function will place the text within the vector with the given length as first line in the table with a midrule below it. an exception is made for empty strings. The format of the current listing/css was designed to look good in the browser and in a WORD document (when html is opened in WORD). Additional colspans are added in the table header which might lead to additional space in case a user defined css file is used.

Value

The function returns a HTML file (or writes output to console)

Examples

# an example how vargroup can be used
grp <- c(rep("",3),rep("grouped variables",2))
## Not run: 
  data(Theoph)
  html_list(Theoph,out=tempfile(fileext=".html"))
  html_list(Theoph,out=tempfile(fileext=".html"),vargroup=grp)

## End(Not run)

Prints a R plot to a HTML file or console

Description

This function makes a HTML document including the defined plots

Usage

html_plot(
  plot,
  out,
  title = "plot",
  titlepr = NULL,
  footnote = "",
  pwidth = 1000,
  pheight = 600,
  res = NULL,
  fontsize = 12,
  units = "px",
  rawout = paste0(out, ".rawhtml"),
  cleancur = FALSE,
  ...
)

Arguments

Value

The function returns a HTML file (or writes output to console)

Examples

# It is convenient to have an object for the plot argument
## Not run: 

  data(Theoph)
  library(ggplo2)
  pl <- qplot(Time, conc, data=Theoph, facets=~Subject,geom="line")
  html_plot(pl,out=paste0(tempfile(),".html"))

  # Base plots work a bit different and can be placed
  # in the function directly or wrapped in a function
  html_plot(plot(conc~Time,data=Theoph),out=tempfile(fileext=".html"))
  pl <- function() {
    plot(conc~Time,data=Theoph)
    title(main="a plot")
  }
  html_plot(pl(),out=tempfile(fileext=".html"))

## End(Not run)

Creates a HTML table

Description

This function creates a HTML table. The function calls a combination of functions within the R3port package to create an overall table and writes it to a file or console

Usage

html_table(
  dfrm,
  x,
  y,
  var,
  fill = "",
  uselabel = TRUE,
  yhead = FALSE,
  footnote = NULL,
  title = "table",
  titlepr = NULL,
  xabove = FALSE,
  group = NULL,
  xrepeat = FALSE,
  tclass = "sample",
  out = NULL,
  rawout = paste0(out, ".rawhtml"),
  ...
)

Arguments

Details

The format of the current table/css was designed to look good in the browser and in a WORD document (when html is opened in WORD). Additional colspans are added in the table header which might lead to additional space in case a user defined css file is used.

Value

The function returns a HTML file (or writes output to console)

Examples

## Not run: 
  data(Indometh)
  Indometh$id  <- as.numeric(as.character(Indometh$Subject))
  Indometh$trt <- ifelse(Indometh$id<4,"trt 1","trt 2")

  html_table(Indometh,x=c("trt","time"),y="id",var="conc",
            out=tempfile(fileext=".html"),xabove=TRUE)

  # Usage of multiple y values
  html_table(Indometh,x="time",y=c("trt","id"),var="conc",
            out=tempfile(fileext=".html"))

  # Some examples for different options
  html_table(Indometh,x=c("time","trt"),y="id",var="conc",
            out=tempfile(fileext=".html"),yhead=TRUE,
            group=1,titlepr="TBL01",title="Dummy table",
            footnote="this table is not very informative")

## End(Not run)

Designs a table based on a object returned by the table_prep function

Description

This function designs the a HTML table based on the data frame list returned by the table_prep function.

Usage

html_table_design(
  dfl,
  uselabel = TRUE,
  yhead = FALSE,
  footnote = NULL,
  title = "table",
  titlepr = NULL,
  xabove = TRUE,
  group = NULL,
  xrepeat = FALSE,
  tclass = "sample"
)

Arguments

Details

This function designs a HTML pivot table based on the results of the table_prep output. This means that the function Should always be used in conjunction with this function.

Value

The function returns a vector that defines the entire HTML table. This vector can be adapted manually however it is intended to be used in a print function to add to a HTML document.

Examples

## Not run: html_table_design(lstobject)

Combines multiple latex files to a single tex and compiles document

Description

This function combines multiple latex files. This is done based on the name of the files and should end with raw.tex to make the function pick-up these files.

Usage

ltx_combine(combine = ".", out = NULL, presentation = FALSE, clean = 0, ...)

Arguments

Details

Currently the generated output is saved in the same place where the separate tables and plots are located defined in the 'combine' argument. This is done even when a different file path is specified in 'out' (using the basename function). The reason is to not copy files linked within the document and preventing broken links. This behaviour might change in future releases

Value

The function returns a latex file (or writes output to console)

Examples

# Take into account the usage of tempfile() with multiple function calls
## Not run: 
  data(Theoph)
  ltx_list(Theoph[1:11,],out=tempfile(fileext=".tex"),show=FALSE)
  ltx_plot(plot(conc~Time,data=Theoph),out=tempfile(fileext=".tex"),show=FALSE)
  ltx_combine(combine=tempdir(),out="rep1.tex")

  # possibility for presentation layout (beamer template provided in package)
  ltx_combine(combine=tempdir(),out="rep1.tex",
              template=paste0(system.file(package="R3port"),"/beamer.tex"),
              presentation=TRUE)

  # Or other template with different orientation
  ltx_combine(combine=tempdir(),out="rep1.tex",
              template=paste0(system.file(package="R3port"),"/listing.tex"),
              orientation="portrait")

## End(Not run)

Prints latex code for a table, listing, plot, or text to a a file or console

Description

This function makes a latex document using output generated with functions in the R3port package or any other latex code available as vector. Basically it adds a preamble to a tex file and let's the user select various options to customize the output.

Usage

ltx_doc(
  text,
  out = NULL,
  template = paste0(system.file(package = "R3port"), "/simple.tex"),
  rendlist,
  orientation = "landscape",
  rtitle = "report",
  compile = TRUE,
  show = TRUE
)

Arguments

Value

The function returns a latex file (or writes output to console)

See Also

html_doc()

Examples

## Not run: 
  txt <- "\\section{example}"
  tbl <- "\\begin{tabular}{|l|c|r|} 1 & 2 & 3 \\\\ 4 & 5 & 6 \\\\ \\end{tabular}"
  add <- "\\\\ Including some additional text"
  ltx_doc(c(txt,tbl,add),out=paste0(tempfile(),".tex"),show=FALSE)

  # You can use xtable (and any other packages that output tex)
  library(xtable)
  data(Theoph)
  xtbl <- print(xtable(Theoph),tabular.environment="longtable",floating=FALSE,print.results=FALSE)
  ltx_doc(xtbl,out=tempfile(fileext = ".tex"))


## End(Not run)

Creates a latex listing

Description

This function creates a latex listing which can be written to a file or console

Usage

ltx_list(
  dfrm,
  vars = names(dfrm),
  fill = "",
  vargroup = NULL,
  porder = TRUE,
  uselabel = TRUE,
  footnote = "",
  tablenote = "",
  mancol = NULL,
  size = "\\footnotesize",
  title = "listing",
  titlepr = NULL,
  group = NULL,
  xrepeat = FALSE,
  hyper = TRUE,
  out = NULL,
  rawout = paste0(out, ".rawtex"),
  convchar = TRUE,
  tabenv = "longtable",
  label = NULL,
  flt = "h",
  ...
)

Arguments

Details

The vargroup argument should be provided in the following form:
c(rep("",4),rep("group1",3),rep("group2",4)). The function will place the text within the vector with the given length as first line in the table with a midrule below it. an exception is made for empty strings.

Value

The function returns a latex file (or writes output to console)

Examples

## Not run: 
  data(Theoph)
  grp <- c(rep("",3),rep("grouped variables",2))
  ltx_list(Theoph,out=tempfile(fileext=".tex"),vargroup=grp,
           template=paste0(system.file(package="R3port"),"/listing.tex"))

## End(Not run)

Prints a R plot to a latex file or console

Description

This function makes a latex document including the plots defined

Usage

ltx_plot(
  plot,
  out,
  title = "plot",
  titlepr = NULL,
  footnote = "",
  plotnote = "",
  lwidth = NULL,
  pwidth = 10,
  pheight = 5.5,
  res = NULL,
  hyper = TRUE,
  outfmt = "pdf",
  fontsize = 12,
  units = "px",
  rawout = paste0(out, ".rawtex"),
  linebreak = TRUE,
  label = NULL,
  captpl = "top",
  rotate = FALSE,
  cleancur = FALSE,
  titlesub = NULL,
  shorttitle = NULL,
  ...
)

Arguments

Value

The function returns a latex file (or writes output to console)

Examples

# It is convenient to have an object for the plot argument
## Not run: 
  data(Theoph)
  library(ggplot2)
  pl <- ggplot(Theoph,aes(Time,conc)) + geom_line() + facet_wrap(~Subject)
  ltx_plot(pl,out=tempfile(fileext=".tex"))

  # Base plots work a bit different and can be placed
  # in the function directly or wrapped in a function
  pl <- function() {
    plot(conc~Time,data=Theoph)
    title(main="a plot")
  }
  ltx_plot(pl(),out=tempfile(fileext=".tex"))
  # In case of big data it can be more convenient to have a png included
  ltx_plot(plot(rnorm(1e6)),out=tempfile(fileext=".tex"),
           outfmt="png",pwidth=2000,pheight=1200)

## End(Not run)

Creates a latex table

Description

This function creates a latex table. The function calls a combination of functions within the R3port package to create an overall table and writes it to a file or console

Usage

ltx_table(
  dfrm,
  x,
  y,
  var,
  fill = "",
  uselabel = TRUE,
  yhead = FALSE,
  footnote = "",
  tablenote = "",
  mancol = NULL,
  size = "\\footnotesize",
  title = "table",
  titlepr = NULL,
  xabove = FALSE,
  group = NULL,
  xrepeat = FALSE,
  hyper = TRUE,
  out = NULL,
  rawout = paste0(out, ".rawtex"),
  convchar = TRUE,
  tabenv = "longtable",
  label = NULL,
  flt = "h",
  ...
)

Arguments

Value

The function returns a latex file (or writes output to console)

Examples

## Not run: 
  data(Indometh)
  Indometh$id  <- as.numeric(as.character(Indometh$Subject))
  Indometh$trt <- ifelse(Indometh$id<4,"trt 1","trt 2")

  ltx_table(Indometh,x=c("trt","time"),y="id",var="conc",
            out=tempfile(fileext=".tex"),xabove=TRUE)

  # Usage of multiple y values
  ltx_table(Indometh,x="time",y=c("trt","id"),var="conc",
            out=tempfile(fileext=".tex"))

  # Some examples for different options
  ltx_table(Indometh,x=c("time","trt"),y="id",var="conc",
            out=tempfile(fileext=".tex"),yhead=TRUE,
            group=1,titlepr="TBL01",title="Dummy table",
            footnote="this table is not very informative")

## End(Not run)

Designs a table based on a object returned by the table_prep function

Description

This function designs the a latex table based on the data frame list returned by the table_prep function.

Usage

ltx_table_design(
  dfl,
  uselabel = TRUE,
  yhead = FALSE,
  footnote = "",
  tablenote = "",
  mancol = NULL,
  size = "\\normalsize",
  title = "table",
  titlepr = NULL,
  xabove = TRUE,
  group = NULL,
  xrepeat = FALSE,
  hyper = TRUE,
  tabenv = "longtable",
  label = NULL,
  flt = "h"
)

Arguments

Details

This function designs a latex pivot table based on the results of the table_prep output. This means that the function Should always be used in conjunction with this function.

Value

The function returns a vector that defines the entire latex table. This vector can be adapted manually however it is intended to be used in a print function to add to a latex document.

Examples

## Not run: ltx_table_design(lstobject)

Calculate summary statistics on a data frame

Description

This function calculates summary statistics on a data frame. It is intended to use to calculate a standard number of descriptive statistics which are defined in the packs argument

Usage

means(dfrm, variable, by, total = NULL, pack = 1, dig = 2, alpha = 0.1)

Arguments

Details

The function calculates multiple statistics of a data frame that can be stratified. Furthermore, the statistics for a total can also be generated. Currently the function has the possibility to calculate 3 different sets of statistics which are commonly used within the field of clinical data analysis:

1. N, Mean, Median, SD, Min, Max

2. Ntot, N, Nmiss, Mean, Median, SD, Min, Max, CLM (different N values are given to identify the number of missing values)

3. N, Mean (SD), Median, Range (Both Mean (SD) and Range are concatenated to generate a dense overview of statistics)

All statistics are calculated on using na.rm set to TRUE, meaning that NA values are removed before calculating the statistics. A predefined set of statistics is chosen and not the possibility to implement user defined descriptive statistics. The reason for this is that there are many other (more simple) options to do this within R.

Value

The function returns a dataframe with calculated descriptive statistics

Examples

data(Indometh)
means(Indometh,"conc","time",total="time",pack=3)

Prepares the data for pivotal tabulation

Description

This function prepares the data pivotal for tabulation. It is intended to use as a first step in the creation of a report pivotal table. It is not likely that this function will be used as stand-alone

Usage

table_prep(dfrm, x, y, var, fill = "", type = "latex", convchar = TRUE)

Arguments

Details

This function only prepares the data for pivotal tabulation. The base of the function is the dcast function from plyr to reshape the data and the generation of a table header object to indicate how headers should be placed within the table. The function also specifies a type argument which includes "latex" or "html", this is necessary to identify specific character handling (convchar) that differs between HTML and LaTeX.

Value

The function returns a list with the original dataframe, the table header, table data and other table specifications

Examples

data(Indometh)
table_prep(Indometh,"time","Subject","conc")