msWord: Display a table in 'MS Word' containing panels from R graphs in its cells.

Description

Display a table in 'MS Word' containing panels from R graphs in its cells. msWord methods for "trellis", "ggplot", "graphicsList", "microplotMatrix", and "includegraphicsMatrix" objects. The output file can be a .docx or .html file.

Usage

msWord(object, ...)
# S3 method for microplotMatrix
msWord( ## calls msWord.graphicsClass
       object, ## microplotMatrix
       ## (matrix of filenames containing individual panels)
       ## (0 columns permitted)
       filetype=c("docx","html"),
       dataobject=matrix(, nrow(object), 0), ## numeric or character matrix
       data.first=TRUE,
       title=first.word(deparse(substitute(object))),
       rowlabel=title,
       rowname=rownames(object),
       data.header="data",
       graph.header="graph",
       graph.file.directory="./",
       axis.files=attr(object,"axis.names"),
       lab.files=attr(object,"lab.names"),
       key.file=attr(object,"key.name"),
       x.axis=(!is.null(axis.files) && !is.null(axis.files["x"])),
       y.axis=(!is.null(axis.files) && !is.null(axis.files["y"])),
       xlab=FALSE,
       ylab=FALSE,
       label.x.axis="",  ## empty, nchar=0
       label.y.axis=" ", ## one space, nchar=1
       height.panel=1, ## inches
       width.panel=1, ## inches
       height.x.axis=height.panel[1], ## inches ## [1] is defensive for lazy evaluation
       width.y.axis=width.panel[1], ## inches
       height.xlab=height.panel[1], ## inches
       width.ylab=width.panel[1], ## inches
       height.key=height.panel[1], ## inches
       width.key=width.panel[1], ## inches
       FlexTableWidths=NULL, ## inches ## value used will be an attribute of result
       rmh.borders=TRUE,
       caption=NULL,
       file=paste0(title, ".", filetype),
       doc.title="Microplot",
       width.rowname=.4,
       width.dataobject=1,
       width.between=.1,
       landscape=FALSE,
       rgroup=NULL,
       n.rgroup=NULL,
       rgroup.exclude.borders=NULL,
       key.align="center",  ## flextable::align
       ...)
# S3 method for graphicsClass
msWord( ## calls msWord.graphicsClass
           object, ## called by trellis, ggplot, graphicsList methods
           ## microplot arguments
           figPrefix=first.word(deparse(substitute(object))),
           device="png",
           key=FALSE,
           title=figPrefix, ## subject to lazy evaluation
           ... ## can include arguments to
           ## microplot,
           ## msWord.microplotMatrix
           )
# S3 method for trellis
msWord( ## calls msWord.graphicsClass
           object=stop("trellis object is required", call. = FALSE),
           figPrefix=first.word(deparse(substitute(object))),
           title=figPrefix,
           ... ## can include arguments to
           ## msWord.graphicsClass,
           ## microplot,
           ## msWord.microplotMatrix
           )
# S3 method for ggplot
msWord(object=stop("ggplot object is required", call. = FALSE),
           figPrefix=first.word(deparse(substitute(object))),
           title=figPrefix,
           ... ## can include arguments to
           ## msWord.graphicsClass,
           ## microplot,
           ## msWord.microplotMatrix
           )
# S3 method for graphicsList
msWord(object=stop("graphicsList object is required", call. = FALSE),
           ## matrix or vector of trellis objects or ggplot objects,
           ## with dim and dimnames,
           ## normally each containing one panel.
           ## The axes and key will be taken from object[[1]].
           figPrefix=first.word(deparse(substitute(object))),
           title=figPrefix,
           ... ## can include arguments to
           ## msWord.graphicsClass,
           ## microplot,
           ## msWord.microplotMatrix
           )

Value

The returned value depends on the filetype argument.

For filetype="docx", the value is the name of a generated file

docx file with class "msWordFilename". Printing the returned value will display the generated file on screen. The result has an attribute "microplotMatrix" containing its argument

object, which contains the names of the generated microplots. The result has an attribute showing the actual FlexTableWidths

used. The user may wish to use the FlexTableWidths argument on a following run to modify these values.

For filetype="html", the value is a flextable object. Printing the returned value will display the generated table in a browser window. If you wish to keep the html object, you MUST save it manually! The original file is in a temporary directory and will vanish when R is closed. Switch to the browser window and save the displayed table as a 'Web Archive' in a directory of your choice. Choose an appropriate basename for the saved file, as the default basename of the file is the noninformative "index".

Arguments

object: "microplotMatrix" (Matrix of filenames containing individual panels) (0 columns permitted).
filetype: File extension of generated file. Character, either "docx" or "html". For filetype="docx" the result is a variable containing the filename of a generated MS Word file. See the discussion of value below for additional information on the value. For filetype="html" the result is a variable containing a flextable object. See the discussion of value below to learn how to save the html file.
dataobject: Numeric or character matrix (or data.frame).
data.first: Logical. If TRUE, then output file will have dataobject columns first, then graphics object columns. If FALSE, then output file will have graphics object columns first, then dataobject columns.
title: Basename of generated file. We replace all "." in the title by "-".
figPrefix: See microplot.trellis. The 'latex' macro \includegraphics requires that there be no "." in the filename basename. We also enforce this requirement for msWord. We replace all "." in the figPrefix by "-".
rowlabel: Header name for column of rownames in the generated file.
rowname: Rownames of constructed table. Default is rownames of object. Specify rowname=NULL to suppress the use of row names.
data.header, graph.header: Header names for groupings of data columns and graph columns. Used when both dataobject and object are present, one of them is not missing.
graph.file.directory: Directory containing files named in object.
axis.files, lab.files, key.file: Filenames for graphics files containing axes, axis labels, and key (legend).
x.axis, xlab: Logical. If x.axis==TRUE each column of graphs will have the x.axis file placed as the last item in that column. If both are TRUE then the xlab file will be placed in the row following the x.axis file.
y.axis, ylab: Logical. If y.axis==TRUE each row of graphs will have the y.axis file placed as the first item in that row. If both are TRUE, then the ylab file will be placed on each row immediately before the y.axis file.
label.x.axis, label.y.axis: Labels that will used in the column name of the y.axis and the y.axis position for the x.axis in the 'latex' display of the graphic.
height.panel, width.panel, height.x.axis, width.y.axis, height.xlab, width.ylab: See microplot.
height.key, width.key, device, key: See microplot.
FlexTableWidths: Widths of all columns, including header and between columns, in inches. The default is to base the widths on the widths of individual columns above. The actual widths used are returned as an attribute of the returned filename. You may wish to examine these values from the first run, and then modify them on second and later runs.
rmh.borders: My preferences for borders on cells based on the American Statistical Association (https://academic.oup.com/DocumentLibrary/JSSMET/ASASTYLE_GUIDE.pdf) style sheet. The flextable default, with full borders between rows, does not conform.
caption: The table will be rendered with a numbered caption containing this string as the caption value.
file: Name of generated file.
doc.title: Title that appears in the MS Word Properties list.
width.rowname: Number of inches for the rowname column.
width.dataobject: Number of inches for each column In the data.object.
width.between: Number of inches for the column between the object (graphs) and the dataobject (numbers or text).
landscape: Logical. If TRUE then the table is produced in a landscape orientation. If FALSE, then in a portrait orientation.
rgroup, n.rgroup, rgroup.exclude.borders: Argument names borrowed from latex. rgroup gives the names of groupings of rows in the table. n.rgroup gives the number of rows within each group. rgroup.exclude.borders is not borrowed. It gives the row numbers of rows which are not to have a border between the rowname and the body of the table.
key.align: flextable::align one of left, right, center.

...: Additional arguments are currently ignored by msWord.microplotMatrix. They are forwarded to other methods by the other functions documented here.

Author

Richard M. Heiberger <rmh@temple.edu>

Examples

Run this code

## See demos.

Run the code above in your browser using DataLab