Package 'rtf'

Package rtf

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.

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

---

Insert a header into the RTF document

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.

---

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.

---

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.

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.

---

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.

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.

---

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

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.

---

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.

---

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.

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.

---

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.

---

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.

---

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.

---

The RTF class

Description

This is the class representing an RTF file output.

Package: rtf
Class RTF

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.
...	Not used.

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.

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)

---

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.

---

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.

---

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.

---