From 244856c14284dee20759e19f13f51ef665b5c023 Mon Sep 17 00:00:00 2001 From: dscott Date: Thu, 28 Jan 2016 04:22:53 +0000 Subject: [PATCH] Finished documentation changes to xtableFtable and xtableList. Package should be ready for submission. git-svn-id: svn://scm.r-forge.r-project.org/svnroot/xtable@103 edb9625f-4e0d-4859-8d74-9fd3b1da38cb --- pkg/NAMESPACE | 2 +- pkg/NEWS | 14 ++++++-- pkg/R/sanitize.R | 8 +++++ pkg/R/xtableFtable.R | 5 ++- pkg/man/sanitize.Rd | 15 ++++++++- pkg/man/xtableFtable.Rd | 16 ++++----- pkg/man/xtableList.Rd | 73 ++++++++++++++++++++++++++++++++++++----- 7 files changed, 106 insertions(+), 27 deletions(-) diff --git a/pkg/NAMESPACE b/pkg/NAMESPACE index 77c56f0..f5c4c69 100644 --- a/pkg/NAMESPACE +++ b/pkg/NAMESPACE @@ -10,7 +10,7 @@ export("caption<-", "caption", "label", "label<-", "xtableFtable", "print.xtableFtable", "toLatex.xtable", "autoformat", "xalign", "xdigits", "xdisplay", - "sanitize", "sanitize.numbers", "sanitize.final") + "sanitize", "sanitize.numbers", "sanitize.final", "as.is", "as.math") S3method("print", "xtable") S3method("print", "xtableMatharray") diff --git a/pkg/NEWS b/pkg/NEWS index 9687f7d..057abe0 100644 --- a/pkg/NEWS +++ b/pkg/NEWS @@ -7,9 +7,11 @@ tables from the spatial econometrics packages, spdep, splm, and sphet. * Extracted sanitize functions from print.xtable as stand-alone - functions, and exported them. + functions, and exported them. Added helper functions as.is and + as.math for assistance with sanitization (supplied by Stefan + Edwards in Feature Request #5303). * Added option to produce math style exponents when sanitizing - numbers, as suggested by Don Armstrong (don@donarmstrong.com), who + numbers, as suggested by Don Armstrong , who also provided code * Fixed bug #6907. Warning was created when the data frame as no rows for type is 'html'. Added a test to create the matrix @@ -22,7 +24,13 @@ Loehnert, which was to replace { and } by \begingroup and \endgroup respectively as the delimiters when size was to changed in a table. - + * Added functions xtableList and print.xtableList to produce + composite tables consisting of a number of subtables. + * Added xtableFtable and print.xtableFtable to format flat tables + produced by ftable. Included examples in the xtable gallery. + * Produced new vignettes: 'The xtableList Gallery' to illustrate + xtableList and print.xtableList; and 'The Other Packages Gallery' + to illustrate methods for classes of objects from other packages. 1.8-0 * autoformat, xalign, xdigits, xdisplay from Arni Magnusson, added diff --git a/pkg/R/sanitize.R b/pkg/R/sanitize.R index c31a660..b5b83cf 100644 --- a/pkg/R/sanitize.R +++ b/pkg/R/sanitize.R @@ -87,3 +87,11 @@ sanitize.final <- function(str, type){ return(str) } } + +### Some trivial helper functions +### Suggested by Stefan Edwards, sme@iysik.com +### Helper function for disabling sanitizing +as.is <- function(str) {str} + +### Helper function for embedding names in a math environment +as.math <- function(str, ...) { paste0('$',str,'$', ...) } diff --git a/pkg/R/xtableFtable.R b/pkg/R/xtableFtable.R index c4e0369..34b544d 100644 --- a/pkg/R/xtableFtable.R +++ b/pkg/R/xtableFtable.R @@ -78,8 +78,7 @@ print.xtableFtable <- function(x, NA.string = getOption("xtable.NA.string", ""), only.contents = getOption("xtable.only.contents", FALSE), add.to.row = getOption("xtable.add.to.row", NULL), - sanitize.text.function = getOption("xtable.sanitize.text.function", - function(x){x}), + sanitize.text.function = getOption("xtable.sanitize.text.function", as.is), sanitize.rownames.function = getOption("xtable.sanitize.rownames.function", sanitize.text.function), sanitize.colnames.function = getOption("xtable.sanitize.colnames.function", @@ -182,7 +181,7 @@ print.xtableFtable <- function(x, print.xtable(fmtFtbl, hline.after = hline.after, include.rownames = FALSE, include.colnames = FALSE, booktabs = booktabs, - sanitize.text.function = function(x){x}) + sanitize.text.function = as.is) } else { stop("print.xtableFtable not yet implemented for this type") } diff --git a/pkg/man/sanitize.Rd b/pkg/man/sanitize.Rd index 3bba107..5b65808 100644 --- a/pkg/man/sanitize.Rd +++ b/pkg/man/sanitize.Rd @@ -2,6 +2,8 @@ \alias{sanitize} \alias{sanitize.numbers} \alias{sanitize.final} +\alias{as.is} +\alias{as.math} \title{ Sanitization Functions @@ -16,6 +18,8 @@ sanitize(str, type) sanitize.numbers(str, type, math.style.negative = FALSE, math.style.exponents = FALSE) sanitize.final(str, type) +as.is(str) +as.math(str, ...) } \arguments{ @@ -32,6 +36,8 @@ sanitize.final(str, type) for 5e5. If \code{"UTF-8"} or \code{"UTF-8"}, then use UTF-8 to approximate the LaTeX typsetting for 5e5. Default value is \code{FALSE}.} + \item{\dots}{Additional arguments. Character strings or character + vectors.} } \details{ @@ -59,6 +65,10 @@ sanitize.final(str, type) effect. When \code{type} is \code{"html"}, multiple spaces are replaced by a single space and occurrences of \code{' align="left"'} are eliminated. + + \code{as.is} and \code{as.math} are trivial helper functions to + disable sanitizing and to insert a some mathematics in a string + respectively. } \value{ Returns the sanitized character object. @@ -70,10 +80,11 @@ sanitize.final(str, type) Swinton , Uwe Ligges , and probably David B. Dahl . + \code{as.is} and \code{as.math} suggested and provided by Stefan + Edwards . } \examples{ - insane <- c("&",">", ">","_","\%","$","\\\\","#","^","~","{","}") names(insane) <- c("Ampersand","Greater than","Less than", "Underscore","Percent","Dollar", @@ -87,6 +98,8 @@ x <- rnorm(10) sanitize.numbers(x, "latex", TRUE) sanitize.numbers(x*10^(10), "latex", TRUE, TRUE) sanitize.numbers(x, "html", TRUE, TRUE) +as.is(insane) +as.math("x10^10", ": mathematical expression") } \keyword{print } diff --git a/pkg/man/xtableFtable.Rd b/pkg/man/xtableFtable.Rd index 6e783a7..5d6b2dc 100644 --- a/pkg/man/xtableFtable.Rd +++ b/pkg/man/xtableFtable.Rd @@ -35,8 +35,7 @@ xtableFtable(x, caption = NULL, label = NULL, NA.string = getOption("xtable.NA.string", ""), only.contents = getOption("xtable.only.contents", FALSE), add.to.row = getOption("xtable.add.to.row", NULL), - sanitize.text.function = getOption("xtable.sanitize.text.function", - function(x){x}), + sanitize.text.function = getOption("xtable.sanitize.text.function", as.is), sanitize.rownames.function = getOption("xtable.sanitize.rownames.function", sanitize.text.function), sanitize.colnames.function = getOption("xtable.sanitize.colnames.function", @@ -202,14 +201,11 @@ xtableFtable(x, caption = NULL, label = NULL, of the same length as the first component, which contains the command that should be added at the end of the specified rows. Default value is \code{NULL}, i.e. do not add commands.} - \item{sanitize.text.function}{All non-numeric entries (except row and - column names) are sanitized in an attempt to remove characters which - have special meaning for the output format. If - \code{sanitize.text.function} is not \code{NULL}, it should - be a function taking a character vector and returning one, and will - be used for the sanitization instead of the default internal - function. - Default value is \code{NULL}.} + \item{sanitize.text.function}{Since the table entries are counts no + sanitization is necessary. The default is \code{as.is}, which is the + function which makes no changes. This also applies to the labels for + the row and column variables since these are also part of the table + which is printed using a call to \code{print.xtable}.} \item{sanitize.rownames.function}{Like the \code{sanitize.text.function}, but applicable to row names. The default uses the \code{sanitize.text.function}. } diff --git a/pkg/man/xtableList.Rd b/pkg/man/xtableList.Rd index ce66636..1682689 100644 --- a/pkg/man/xtableList.Rd +++ b/pkg/man/xtableList.Rd @@ -60,8 +60,13 @@ xtableList(x, caption = NULL, label = NULL, ...) } \arguments{ - \item{x}{For \code{xtableList}, a list of \R objects all of the same - class, being a class found among \code{methods(xtable)}. + \item{x}{ + For \code{xtableList}, a list of \R objects all of the same class, + being a class found among \code{methods(xtable)}. The list may also + have attributes \code{"subheadings"} and \code{"message"}. The + attribute \code{"subheadings"} should be a character vector of the + same length as the list \code{x}. The attribute \code{"message"} + should be a character vector of any length. For \code{print.xtableList}, an object of class \code{xtableList} produced by a call to \code{xtableList}.} \item{caption}{Character vector of length 1 or 2 containing the @@ -247,14 +252,54 @@ xtableList(x, caption = NULL, label = NULL, \item{\dots}{Additional arguments. (Currently ignored.)} } \details{ -%% ~~ If necessary, more details than the description above ~~ + \code{xtableList} produces an object suitable for printing using + \code{print.xtableList}. + + The elements of the list \code{x} supplied to \code{xtableList} must + all have the same structure. When these list items are submitted to + \code{xtable} the resulting table must have the same number of columns + with the same column names and type of data. + + The values supplied to arguments \code{digits} and \code{display}, + must be composed of elements as specified in those same arguments for + the function \code{\link{xtable}}. See the help for + \code{\link{xtable}} for details. + + \code{print.xtableList} produces tables in two different formats + depending on the value of \code{col.names.format}. If + \code{col.names.format = "single"}, the resulting table has only a + single heading row. If \code{col.names.format = "multiple"} there is a + heading row for each of the subtables making up the complete table. + + By default if \code{col.names.format = "single"}, there are horizontal + lines above and below the heading row, and at the end of each + subtable. If \code{col.names.format = "multiple"}, there are + horizontal lines above and below each appearance of the heading row, + and at the end of each subtable. + + If \code{"subheadings"} is not \code{NULL}, the individual elements of + this vector (which can include newlines \verb{\\n}) produce a heading + line or lines for the subtables. When \code{col.names.format = + "multiple"} these subheadings appear \emph{above} the heading rows. + + If \code{"message"} is not \code{NULL} the vector produces a line or + lines at the end of the table. + + Consult the vignette \sQuote{The \code{xtableList} Gallery} to see + the behaviour of these functions. + + Note that at present there is no code for \code{type = "html"}. } \value{ -%% ~Describe the value returned -%% If it is a LIST, use -%% \item{comp1 }{Description of 'comp1'} -%% \item{comp2 }{Description of 'comp2'} -%% ... + \code{xtableList} produces an object of class + \code{"xtableList"}. An object of this class is a list of + \code{"xtable"} objects with some additional attributes. Each element + of the list can have a \code{"subheading"} attribute. The list can + also have a \code{"message"} attribute. + + \code{print.xtableList} produces a character string containing LaTeX + markup which produces a nicely formatted table comprised of subtables, + when included in a LaTeX document. } \author{ David Scott \email{d.scott@auckland.ac.nz}. @@ -269,8 +314,18 @@ xtableList(x, caption = NULL, label = NULL, \seealso{ \code{\link{xtable}}, \code{\link{caption}}, \code{\link{label}}, \code{\link{align}}, \code{\link{digits}}, \code{\link{display}}, - \code{\link{formatC}} + \code{\link{formatC}}, \code{\link{print.xtable}}. } \examples{ +data(mtcars) +mtcars <- mtcars[, 1:6] +mtcarsList <- split(mtcars, f = mtcars$cyl) +attr(mtcarsList, "subheadings") <- paste0("Number of cylinders = ", + names(mtcarsList)) +attr(mtcarsList, "message") <- c("Line 1 of Message", + "Line 2 of Message") +xList <- xtableList(mtcarsList) +print.xtableList(xList) +print.xtableList(xList, colnames.format = "multiple") } \keyword{ print } -- 2.39.2