From 244856c14284dee20759e19f13f51ef665b5c023 Mon Sep 17 00:00:00 2001
From: dscott <dscott@edb9625f-4e0d-4859-8d74-9fd3b1da38cb>
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 <sme@iysik.com> 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 <don@donarmstrong.com>, 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 <jonathan@swintons.net>, Uwe Ligges
<ligges@statistik.uni-dortmund.de>, and probably David B. Dahl
<dahl@stat.byu.edu>.
+ \code{as.is} and \code{as.math} suggested and provided by Stefan
+ Edwards <sme@iysik.com>.
}
\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.5