Help for package rtf (original) (raw)
| Version: | 0.4-14.1 |
|---|---|
| Depends: | R (≥ 2.10.1) |
| Imports: | R.oo, R.methodsS3 |
| Suggests: | ggplot2, lattice, grid, xtable, gsubfn |
| Date: | 2019-05-26 |
| Title: | Rich Text Format (RTF) Output |
| Description: | A set of R functions to output Rich Text Format (RTF) files with high resolution tables and graphics that may be edited with a standard word processor such as Microsoft Word. |
| License: | GPL-2 | GPL-3 [expanded from: GPL (≥ 2)] |
| LazyLoad: | TRUE |
| Packaged: | 2020-03-22 09:06:07 UTC; hornik |
| NeedsCompilation: | no |
| Repository: | CRAN |
| URL: | https://github.com/schaffman5/rtf |
| BugReports: | https://github.com/schaffman5/rtf/issues |
| Author: | Michael E. Schaffer [aut, cre, cph] |
| Maintainer: | Michael E. Schaffer mschaff@gmail.com |
| Date/Publication: | 2020-03-22 09:32:44 UTC |
Description
A set of R functions to output Rich Text Format (RTF) files with high resolution tables and graphics that may be edited with a standard word processor such as Microsoft Word. This is useful for compiling R results into a document for further editing or to be merged with another document.
While Sweave and odfWeave provide nicely formatted outputs, the syntax can be difficult for beginners to master. Moreover, Sweave compilation to a PDF is not editable. Other packages such as SWord and R2wd provide similar functionality but require the user to be running a Microsoft Windows OS.
This package is written in pure R and does not require leaving the R environment to write files. R data frames and table objects are converted to nicely formatted RTF tables. One important limitation of the RTF specification is that vector graphics output is limited to Windows Meta File (WMF) and Enhanced Meta File (EMF) formats. Because these formats are not supported across platforms, this package currently only supports RTF embedding of PNG plots and images. To ensure high quality reports, the resolution may be specified when writing the RTF output.
Requirements
This package depends on the R.oo package.
Usage
For usage details [RTF](#topic+RTF).
Author(s)
Michael E. Schaffer
References
[1] http://en.wikipedia.org/wiki/Rich_Text_Format
[2] http://latex2rtf.sourceforge.net/rtfspec_7.html#rtfspec_paraforprop
Non-documented objects
Description
This page contains aliases for all "non-documented" objects thatR CMD check detects in this package.
Almost all of them are generic functions that have a specific document for the corresponding method coupled to a specific class. Other functions are re-defined by setMethodS3() to_default_ methods. Neither of these two classes are non-documented in reality.
Author(s)
Michael E. Schaffer
The RTF class
Description
This is the class representing an RTF file output.
Package: rtf
Class RTF
[Object](../../R.oo/refman/R.oo.html#topic+Object)~~|~~+-- RTF
Directly known subclasses:
public static class RTF
extends Object
Usage
RTF(file="", width=8.5, height=11, omi=c(1, 1, 1, 1), font.size=10)
Arguments
| file | The path of the output file. |
|---|---|
| width | The width of the output page. |
| height | The width of the output page. |
| omi | A vector representing the outer margins in inches (bottom, left, top, right). |
| font.size | Default font size for the document in points. |
Fields and Methods
Methods:
| | addHeader | Insert a header into the RTF document. | | ------------------------------------------------- | ---------------------------------------------------------------------------------- | | | addNewLine | Insert a new line into the RTF document. | | | addPageBreak | Insert a page break into the RTF document optionally specifying new page settings. | | | addParagraph | Insert a paragraph into the RTF document. | | | addPlot | Insert a plot into the RTF document. | | | addPng | Insert an existing PNG image into the RTF document. | | | addSessionInfo | Insert session information into the RTF document. | | | addTOC | Insert table of contents field. | | | addTable | Insert a table into the RTF document. | | | addText | Insert text into the RTF document. | | | addTrellisObject | Insert a trellis plot object into the RTF document. | | | decreaseIndent | Decrease RTF document indent. | | | done | Write and close the RTF output. | | | endParagraph | End a paragraph in the RTF document. | | | increaseIndent | Increase RTF document indent. | | | setFontSize | Set RTF document font size. | | | startParagraph | Start a new paragraph in the RTF document. | | | view | View encoded RTF. | | | |
Methods inherited from Object: ,, ,<-, [[, [[<-, as.character, attach, attachLocally, clearCache, clearLookupCache, clone, detach, equals, extend, finalize, getEnvironment, getFieldModifier, getFieldModifiers, getFields, getInstantiationTime, getStaticInstance, hasField, hashCode, ll, load, names, objectSize, print, save
Author(s)
Michael E. Schaffer
See Also
For more information see [RTF](#topic+RTF).
Examples
## Not run:
output<-"test_RTF-class.doc"
png.res<-300
rtf<-RTF(output,width=8.5,height=11,font.size=10,omi=c(1,1,1,1))
addHeader(rtf,title="Test",subtitle="2011-08-15\n")
addPlot(rtf,plot.fun=plot,width=6,height=6,res=300, iris[,1],iris[,2])
# Try trellis plots
if(require(lattice) & require(grid)) {
# single page trellis objects
addPageBreak(rtf, width=11,height=8.5,omi=c(0.5,0.5,0.5,0.5))
p <- histogram( ~ height | voice.part, data = singer, xlab="Height")
addTrellisObject(rtf,trellis.object=p,width=10,height=7.5,res=png.res)
p <- densityplot( ~ height | voice.part, data = singer, xlab = "Height")
addTrellisObject(rtf,trellis.object=p,width=10,height=7.5,res=png.res)
# multipage trellis object
p2<-xyplot(uptake ~ conc | Plant, CO2, layout = c(2,2))
addTrellisObject(rtf,trellis.object=p2,width=6,height=6,res=png.res)
}
addPageBreak(rtf, width=6,height=10,omi=c(0.5,0.5,0.5,0.5))
addTable(rtf,as.data.frame(head(iris)),font.size=10,row.names=FALSE,NA.string="-")
addSessionInfo(rtf)
done(rtf)
## End(Not run)
Description
Insert a header into the RTF document.
Usage
## S3 method for class 'RTF'
addHeader(this, title, subtitle=NULL, font.size=NULL, TOC.level=NULL, ...)
Arguments
| this | An RTF object. |
|---|---|
| title | Header title text. |
| subtitle | Header subtitle text. optional. |
| font.size | Font size in points. optional. |
| TOC.level | Indent level for table of contents. optional. |
| ... | Not used. |
Author(s)
Michael E. Schaffer
See Also
For more information see [RTF](#topic+RTF).
Insert a new line into the RTF document
Description
Insert a new line into the RTF document.
Usage
## S3 method for class 'RTF'
addNewLine(this, n=1, ...)
Arguments
| this | An RTF object. |
|---|---|
| n | Number of lines to add. Default is 1. optional |
| ... | Not used. |
Author(s)
Michael E. Schaffer
See Also
For more information see [RTF](#topic+RTF).
Insert a page break into the RTF document optionally specifying new page settings
Description
Insert a page break into the RTF document optionally specifying new page settings.
Usage
## S3 method for class 'RTF'
addPageBreak(this, width=8.5, height=11, omi=c(1, 1, 1, 1), ...)
Arguments
| this | An RTF object. |
|---|---|
| width | New page width in inches. optional. |
| height | New page height in inches. optional. |
| omi | A vector of page margins (botton, left, top, right) optional. |
| ... | Not used. |
Author(s)
Michael E. Schaffer
See Also
For more information see [RTF](#topic+RTF).
Examples
rtf<-RTF("test_addPageBreak.doc",width=8.5,height=11,font.size=10,omi=c(1,1,1,1))
addPageBreak(rtf,width=11,height=8.5,omi=c(0.5,0.5,0.5,0.5))
done(rtf)
Insert a paragraph into the RTF document
Description
Insert a paragraph into the RTF document.
Usage
## S3 method for class 'RTF'
addParagraph(this, ...)
Arguments
| this | An RTF object. |
|---|---|
| ... | A character vector of text to add. |
Author(s)
Michael E. Schaffer
See Also
For more information see [RTF](#topic+RTF).
Insert a plot into the RTF document
Description
Insert a plot into the RTF document.
Usage
## S3 method for class 'RTF'
addPlot(this, plot.fun=plot.fun, width=3, height=0.3, res=300, ...)
Arguments
| this | An RTF object. |
|---|---|
| plot.fun | Plot function. |
| width | Plot output width in inches. |
| height | Plot output height in inches. |
| res | Output resolution in dots per inch. |
| ... | Arguments for plot.fun. |
Details
Plots are added to the document as PNG objects. This function will work with all base graphics methods for plotting. For more sophisticated plots, you may need to wrap your plot code into a function, and then pass a reference to that function to this method. The parameters for the plot method would then get passed in as '...' above.
To output a ggplot2 plot, simply assign the plot to a variable. Then use 'print' as the plot function and pass in the plot variable assigned above.
Author(s)
Michael E. Schaffer
See Also
For more information see [RTF](#topic+RTF).
Examples
rtf<-RTF("test_addPlot.doc",width=8.5,height=11,font.size=10,omi=c(1,1,1,1))
addPlot(rtf,plot.fun=plot,width=6,height=6,res=300, iris[,1],iris[,2])
done(rtf)
Insert an existing PNG image into the RTF document
Description
Insert an existing PNG image into the RTF document.
Usage
## S3 method for class 'RTF'
addPng(this, file, width=3, height=0.3, ...)
Arguments
| this | An RTF object. |
|---|---|
| file | Image file path. |
| width | Plot output width in inches. |
| height | Plot output height in inches. |
| ... | Not used. |
Details
Add existing PNG file to RTF document.
Author(s)
Michael E. Schaffer
See Also
For more information see [RTF](#topic+RTF).
Insert session information into the RTF document
Description
Insert session information into the RTF document.
Usage
## S3 method for class 'RTF'
addSessionInfo(this, locale=TRUE, ...)
Arguments
| this | An RTF object. |
|---|---|
| locale | Output the locale. |
| ... | Not used. |
Details
Exports session information to the RTF document in a similar
Author(s)
Michael E. Schaffer
See Also
For more information see [RTF](#topic+RTF)., [sessionInfo](../../../../doc/manuals/r-patched/packages/utils/refman/utils.html#topic+sessionInfo).
Examples
rtf<-RTF("test_addSessionInfo.doc",width=8.5,height=11,font.size=10,omi=c(1,1,1,1))
addSessionInfo(rtf)
done(rtf)
Insert table of contents field
Description
Insert table of contents field.
Usage
## S3 method for class 'RTF'
addTOC(this, ...)
Arguments
| this | An RTF object. |
|---|---|
| ... | Not used. |
Author(s)
Michael E. Schaffer
See Also
For more information see [RTF](#topic+RTF).
Insert a table into the RTF document
Description
Insert a table into the RTF document.
Usage
## S3 method for class 'RTF'
addTable(this, dat, col.widths=NULL, col.justify=NULL, header.col.justify=NULL,
font.size=NULL, row.names=FALSE, NA.string="-", space.before=NULL, space.after=NULL,
...)
Arguments
| this | An RTF object. |
|---|---|
| dat | A matrix, data frame, or table. |
| col.widths | A vector of column widths in inches. optional. |
| col.justify | A single value or vector of column justifications ('L', 'R', 'C', or 'J' for Left, Right, Center, and Justify, respectively). optional. |
| header.col.justify | A single value or vector of table header column justifications ('L', 'R', 'C', or 'J' for Left, Right, Center, and Justify, respectively). optional. |
| font.size | Font size in points. optional. |
| row.names | Boolean argument to include row names in tables. optional. |
| NA.string | A character string to replace NA values in the table. |
| space.before | Space before each row (in inches). optional. |
| space.after | Space after each row (in inches). optional. |
| ... | Not used. |
Author(s)
Michael E. Schaffer
See Also
For more information see [RTF](#topic+RTF).
Examples
rtf<-RTF("test_addTable.doc",width=8.5,height=11,font.size=10,omi=c(1,1,1,1))
addTable(rtf,as.data.frame(head(iris)),font.size=10,row.names=FALSE,NA.string="-",
col.widths=rep(1,5))
tab<-table(iris$Species,floor(iris$Sepal.Length))
names(dimnames(tab))<-c("Species","Sepal Length")
addTable(rtf,tab,font.size=10,row.names=TRUE,NA.string="-",col.widths=c(1,rep(0.5,4)) )
done(rtf)
Insert text into the RTF document
Description
Insert text into the RTF document.
Usage
## S3 method for class 'RTF'
addText(this, ..., bold=FALSE, italic=FALSE)
Arguments
| this | An RTF object. |
|---|---|
| bold | Bold text. optional. |
| italic | Italic text. optional. |
| ... | Any number of character strings to concatenate. |
Author(s)
Michael E. Schaffer
See Also
For more information see [RTF](#topic+RTF).
Insert a trellis plot object into the RTF document
Description
Insert a trellis plot object into the RTF document.
Usage
## S3 method for class 'RTF'
addTrellisObject(this, trellis.object, width=3, height=0.3, res=300, rotate=NULL, ...)
Arguments
| this | An RTF object. |
|---|---|
| trellis.object | The trellis plot object. |
| width | Plot output width in inches. |
| height | Plot output height in inches. |
| res | Output resolution in dots per inch. |
| rotate | Object rotation in degrees. optional. |
| ... | Not used. |
Details
Plots are added to the document as PNG objects. Multi-page trellis objects are automatically split across multiple pages in the RTF output file. To rotate the object to landscape orientation within the RTF output, use rotate=90. When using rotation, width and height still refer to the unrotated plot dimensions and not the rotated output dimensions on the RTF page. An alternative to rotating the plot is to rotate the entire page using a call to addPageBreak with suitable page width and height dimensions.
Author(s)
Michael E. Schaffer
See Also
For more information see [RTF](#topic+RTF).
Examples
## Not run:
rtf<-RTF("test_addTrellisObject.doc",width=8.5,height=11,font.size=10,omi=c(1,1,1,1))
if(require(lattice) & require(grid)) {
# multipage trellis object
p2<-xyplot(uptake ~ conc | Plant, CO2, layout = c(2,2))
addTrellisObject(rtf,trellis.object=p2,width=8,height=4,res=300, rotate=90)
}
done(rtf)
## End(Not run)
Decrease RTF document indent
Description
Decrease RTF document indent.
Usage
## S3 method for class 'RTF'
decreaseIndent(this, ...)
Arguments
| this | An RTF object. |
|---|---|
| ... | Not used. |
Author(s)
Michael E. Schaffer
See Also
For more information see [RTF](#topic+RTF).
Write and close the RTF output
Description
Write and close the RTF output.
Usage
## S3 method for class 'RTF'
done(this, ...)
Arguments
| this | An RTF object. |
|---|---|
| ... | Not used. |
Author(s)
Michael E. Schaffer
See Also
For more information see [RTF](#topic+RTF).
End a paragraph in the RTF document
Description
End a paragraph in the RTF document.
Usage
## S3 method for class 'RTF'
endParagraph(this, ...)
Arguments
| this | An RTF object. |
|---|---|
| ... | Not used. |
Author(s)
Michael E. Schaffer
See Also
For more information see [RTF](#topic+RTF).
Increase RTF document indent
Description
Increase RTF document indent.
Usage
## S3 method for class 'RTF'
increaseIndent(this, ...)
Arguments
| this | An RTF object. |
|---|---|
| ... | Not used. |
Author(s)
Michael E. Schaffer
See Also
For more information see [RTF](#topic+RTF).
Get an RTF encoded forest plot
Description
Get an RTF encoded forest plot.
Usage
rtf.forest.plot(x=1.25, min=0.5, max=2, xlim=c(0.1, 12), width=3, height=0.3, cex=1,
lwd=0.75, res=300)
Arguments
| x | x (e.g. hazard ratio). |
|---|---|
| min | Minimum whisker (e.g. lower bound of 95% hazard ratio CI). |
| max | Maximum whisker (e.g. upper bound of 95% hazard ratio CI). |
| xlim | A vector specifying the x limits. |
| width | Plot width in inches. |
| height | Plot height in inches. |
| cex | A numerical value giving the amount by which plotting text and symbols should be magnified relative to the default. |
| lwd | Line width. |
| res | Output resolution in dots per inch. |
Details
Create a forest plot and convert PNG to RTF code. This is useful for embedding into a data frame of hazard ratios and then writing an RTF output file. See the example below for usage.
Examples
## Not run:
tab<-data.frame(
Label=c("Test1","Test2","Test3"),
HR=c(1,2,0.45),
Lower.CI=c(0.5,1.1,0.25),
Upper.CI=c(2,3.5,0.9),
stringsAsFactors=FALSE,
check.names=FALSE)
# create forest plots by row
forest.plot.args<-list(xlim=c(0.1,5),width=3.0,height=0.3,cex=1,lwd=0.75,res=300)
tab$"HR Plot (log scale)"<-mapply(rtf.forest.plot,tab$HR,tab$Lower.CI,tab$Upper.CI,
MoreArgs=forest.plot.args)
# rbind the x-scale to the table in the plot column
xscale<-rtf.forest.plot.xscale(xlim=c(0.1,5),width=3.0,height=0.3,cex=1,
lwd=0.75,res=300)
tab<-data.frame(lapply(tab, as.character),
stringsAsFactors=FALSE,
check.names=FALSE)
tab<-rbind(tab,list("","","","",xscale))
# write the RTF output
rtf<-RTF("test_rtf.forest.plot.doc",width=8.5,height=11,font.size=10,omi=c(1,1,1,1))
addTable(rtf,tab,col.widths=c(0.75,0.75,0.75,0.75,3))
done(rtf)
## End(Not run)
Set RTF document font size
Description
Set RTF document font size.
Usage
## S3 method for class 'RTF'
setFontSize(this, font.size, ...)
Arguments
| this | An RTF object. |
|---|---|
| font.size | New default font size in points. |
| ... | Not used. |
Author(s)
Michael E. Schaffer
See Also
For more information see [RTF](#topic+RTF).
Start a new paragraph in the RTF document
Description
Start a new paragraph in the RTF document.
Usage
## S3 method for class 'RTF'
startParagraph(this, ...)
Arguments
| this | An RTF object. |
|---|---|
| ... | Not used. |
Author(s)
Michael E. Schaffer
See Also
For more information see [RTF](#topic+RTF).
View encoded RTF
Description
View encoded RTF.
Usage
## S3 method for class 'RTF'
view(this, ...)
Arguments
| this | An RTF object. |
|---|---|
| ... | Not used. |
Value
Output the content of the object as RTF code.
Author(s)
Michael E. Schaffer
See Also
For more information see [RTF](#topic+RTF).