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

Non-documented objects

Description

This page contains aliases for all "non-documented" objects that R 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
~~|
~~+--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

Fields and Methods

Methods:

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)
 

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

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

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

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

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

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

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

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 table of contents field

Description

Insert table of contents field.

Usage

## S3 method for class 'RTF'
addTOC(this, ...)

Arguments

Author(s)

Michael E. Schaffer

See Also

For more information see 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

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

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

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

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

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

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

Author(s)

Michael E. Schaffer

See Also

For more information see 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

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

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

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

Value

Output the content of the object as RTF code.

Author(s)

Michael E. Schaffer

See Also

For more information see RTF.