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

msWord {microplot}

R Documentation

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 class '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 class '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 class '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 class '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 class '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
           )

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.

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

Note

The msWord function uses facilities provided by the flextable and officer packages.

Author(s)

Richard M. Heiberger <rmh@temple.edu>

Examples

## See demos.

[Package microplot version 1.0-45 Index]