Merge pull request #628 from tbates/patch-1
minor spelling correction in footnote roxygen
diff --git a/DESCRIPTION b/DESCRIPTION
index 1335f80..a0ff256 100644
--- a/DESCRIPTION
+++ b/DESCRIPTION
@@ -26,7 +26,6 @@
users to construct complex tables and customize styles using a readable
syntax.
License: MIT + file LICENSE
-LazyData: TRUE
URL: http://haozhu233.github.io/kableExtra/, https://github.com/haozhu233/kableExtra
BugReports: https://github.com/haozhu233/kableExtra/issues
Depends:
@@ -57,5 +56,5 @@
sparkline
VignetteBuilder: knitr
Encoding: UTF-8
-RoxygenNote: 7.1.1
+RoxygenNote: 7.2.0
Roxygen: list(markdown = TRUE)
diff --git a/NAMESPACE b/NAMESPACE
index 4affb08..e4e8249 100644
--- a/NAMESPACE
+++ b/NAMESPACE
@@ -42,6 +42,7 @@
export(save_kable)
export(scroll_box)
export(spec_angle)
+export(spec_barplot)
export(spec_boxplot)
export(spec_color)
export(spec_font_size)
diff --git a/R/collapse_rows.R b/R/collapse_rows.R
index 81c8f97..cb64a8e 100644
--- a/R/collapse_rows.R
+++ b/R/collapse_rows.R
@@ -9,18 +9,21 @@
#' @param kable_input Output of `knitr::kable()` with `format` specified
#' @param columns A numeric value or vector indicating in which column(s) rows
#' need to be collapsed.
-#' @param valign Select from "top", "middle"(default), "bottom". The reason why
+#' @param valign Select from "top", "middle" (default), "bottom". The reason why
#' "top" is not default is that the multirow package on CRAN win-builder is
#' not up to date.
+#' Only used when `row_group_label_position` is `identity`.
#' @param latex_hline Option controlling the behavior of adding hlines to table.
#' Choose from `full`, `major`, `none`, `custom` and `linespace`.
#' @param custom_latex_hline Numeric column positions whose collapsed rows will
#' be separated by hlines.
#' @param row_group_label_position Option controlling positions of row group
-#' labels. Choose from `identity`, `stack`.
+#' labels. Choose from `identity`, `stack`, or `first` -- the latter behaves
+#' like `identity` when `row_group_label_position` is `top` but without using
+#' the multirow package.
#' @param row_group_label_fonts A list of arguments that can be supplied to
#' group_rows function to format the row group label when
-#' `row_group_label_position` is `stack`
+#' `row_group_label_position` is `stack`.
#' @param headers_to_remove Numeric column positions where headers should be
#' removed when they are stacked.
#' @param target If multiple columns are selected to do collapsing and a target
@@ -46,7 +49,7 @@
valign = c("middle", "top", "bottom"),
latex_hline = c("full", "major", "none", "custom",
"linespace"),
- row_group_label_position = c('identity', 'stack'),
+ row_group_label_position = c("identity", "stack", "first"),
custom_latex_hline = NULL,
row_group_label_fonts = NULL,
headers_to_remove = NULL,
@@ -72,7 +75,7 @@
if (kable_format == "latex") {
latex_hline <- match.arg(latex_hline)
row_group_label_position <- match.arg(row_group_label_position,
- c('identity', 'stack'))
+ c("identity", "stack", "first"))
return(collapse_rows_latex(kable_input, columns, latex_hline, valign,
row_group_label_position, row_group_label_fonts, custom_latex_hline,
headers_to_remove, target, col_names, longtable_clean_cut))
@@ -200,6 +203,10 @@
if(columns[j] < ncol(collapse_matrix) || collapse_matrix_rev[i, j] == 0){
new_kable_dt[i, columns[j]] <- ''
}
+ } else if(row_group_label_position == 'first'){
+ if(columns[j] <= ncol(collapse_matrix) && collapse_matrix_rev[i, j] == 0){
+ new_kable_dt[i, columns[j]] <- ''
+ }
} else {
new_kable_dt[i, columns[j]] <- collapse_new_dt_item(
kable_dt[i, columns[j]], collapse_matrix[i, j], column_width,
diff --git a/R/header_separate.R b/R/header_separate.R
index 7930d28..c01ba97 100644
--- a/R/header_separate.R
+++ b/R/header_separate.R
@@ -11,7 +11,7 @@
#' is a regular expression that matches any sequence of non-alphanumeric values.
#'
#' @export
-header_separate <- function(kable_input, sep = "[^[:alnum:]]+") {
+header_separate <- function(kable_input, sep = "[^[:alnum:]]+", ...) {
kable_format <- attr(kable_input, "format")
if (!kable_format %in% c("html", "latex")) {
warning("Please specify format in kable. kableExtra can customize either ",
@@ -20,14 +20,22 @@
return(kable_input)
}
if (kable_format == "html") {
- return(header_separate_html(kable_input, sep))
+ return(do.call(header_separate_html, list(
+ kable_input = kable_input,
+ sep = sep,
+ ...
+ )))
}
if (kable_format == "latex") {
- return(header_separate_latex(kable_input, sep))
+ return(do.call(header_separate_latex, list(
+ kable_input = kable_input,
+ sep = sep,
+ ...
+ )))
}
}
-header_separate_html <- function(kable_input, sep) {
+header_separate_html <- function(kable_input, sep, ...) {
kable_attrs <- attributes(kable_input)
kable_xml <- kable_as_xml(kable_input)
@@ -66,9 +74,14 @@
if (!"kableExtra" %in% class(out)) class(out) <- c("kableExtra", class(out))
for (l in seq(2, length(header_layers))) {
- out <- kableExtra::add_header_above(
- out, kableExtra::auto_index(header_layers[[l]])
+ out <- do.call(
+ kableExtra::add_header_above,
+ list(
+ kable_input = out,
+ kableExtra::auto_index(header_layers[[l]]),
+ ...
)
+ )
}
return(out)
}
@@ -92,7 +105,7 @@
return(header_layers)
}
-header_separate_latex <- function(kable_input, sep) {
+header_separate_latex <- function(kable_input, sep, ...) {
table_info <- magic_mirror(kable_input)
out <- solve_enc(kable_input)
@@ -124,8 +137,13 @@
attr(out, "kable_meta") <- table_info
for (l in seq(2, length(header_layers))) {
- out <- kableExtra::add_header_above(
- out, kableExtra::auto_index(header_layers[[l]])
+ out <- do.call(
+ kableExtra::add_header_above,
+ list(
+ kable_input = out,
+ kableExtra::auto_index(header_layers[[l]]),
+ ...
+ )
)
}
diff --git a/R/linebreak.R b/R/linebreak.R
index 3bc0d51..d78a242 100644
--- a/R/linebreak.R
+++ b/R/linebreak.R
@@ -1,10 +1,10 @@
#' Make linebreak in LaTeX Table cells
#'
-#' @description This function generate LaTeX code of `makecell` so that users
+#' @description This function generates LaTeX code of `makecell` so that users
#' can have linebreaks in their table
#'
#' @param x A character vector
-#' @param align Choose from "l", "c" or "r"
+#' @param align Choose from "l", "c" or "r". Defaults to "l".
#' @param double_escape Whether special character should be double escaped.
#' Default is FALSE.
#' @param linebreaker Symbol for linebreaks to replace. Default is `\\n`.
@@ -14,6 +14,8 @@
linebreaker = "\n") {
if (is.numeric(x) | is.logical(x)) return(x)
x <- as.character(x)
+ if (missing(align))
+ align <- "l"
align <- vapply(align, match.arg, 'a', choices = c("l", "c", "r"))
if (double_escape) {
ifelse(str_detect(x, linebreaker),
diff --git a/R/mini_plots.R b/R/mini_plots.R
index 8576df0..137446e 100644
--- a/R/mini_plots.R
+++ b/R/mini_plots.R
@@ -196,6 +196,99 @@
del = TRUE)
return(out)
}
+#' Helper functions to generate inline sparklines
+#'
+#' @description These functions helps you quickly generate sets of sparkline
+#' style plots using base R plotting system. Currently, we support histogram,
+#' boxplot, line, scatter, pointrange, barplot plots. You can use them together with
+#' `column_spec` to generate inline plot in tables. By default, this function
+#' will save images in a folder called "kableExtra" and return the address of
+#' the file.
+#'
+#' @param x Vector of values or List of vectors of values.
+#' @param width The width of the plot in pixel
+#' @param height The height of the plot in pixel
+#' @param res The resolution of the plot. Default is 300.
+#' @param add_label For boxplot. T/F to add labels for min, mean and max.
+#' @param label_digits If T for add_label, rounding digits for the label.
+#' Default is 2.
+#' @param same_lim T/F. If x is a list of vectors, should all the plots be
+#' plotted in the same range? Default is True.
+#' @param lim Manually specify plotting range in the form of
+#' `c(0, 10)`.
+#' @param xaxt On/Off for xaxis text
+#' @param yaxt On/Off for yaxis text
+#' @param ann On/Off for annotations (titles and axis titles)
+#' @param col Color for the fill of the histogram bar/boxplot box.
+#' @param border Color for the border.
+#' @param boxlty Boxplot - box boarder type
+#' @param medcol Boxplot - median line color
+#' @param medlwd Boxplot - median line width
+#' @param dir Directory of where the images will be saved.
+#' @param file File name. If not provided, a random name will be used
+#' @param file_type Graphic device. Can be character (e.g., `"pdf"`)
+#' or a graphics device function (`grDevices::pdf`). This defaults
+#' to `"pdf"` if the rendering is in LaTeX and `"svg"` otherwise.
+#' @param ... extraparameters passing to boxplot
+#'
+#' @export
+spec_barplot <- function(x, devwidth = 200, devheight = 40, res = 300,
+ beside = F,
+ horiz = F,
+ same_lim = TRUE, lim = NULL,
+ xaxt = 'n', yaxt = 'n', ann = FALSE,
+ col = NULL, border = NA,
+ dir = if (is_latex()) rmd_files_dir() else tempdir(),
+ file = NULL,
+ file_type = if (is_latex()) "pdf" else svglite::svglite,
+ ...) {
+ if (is.list(x)) {
+ if (same_lim & is.null(lim)) {
+ lim <- base::range(unlist(x), na.rm=TRUE)
+ }
+
+ dots <- listify_args(x, devwidth, devheight, res, beside,horiz,
+ lim, xaxt, yaxt, ann, col, border,
+ dir, file, file_type,
+ lengths = c(1, length(x)))
+ return(do.call(Map, c(list(f = spec_barplot), dots)))
+ }
+
+ if (is.null(x)) return(NULL)
+
+ if (is.null(lim)) {
+ lim <- base::range(x, na.rm=TRUE)
+ }
+
+ if (!dir.exists(dir)) {
+ dir.create(dir)
+ }
+ height<-matrix(x)
+ height<-cbind(height,0)
+ file_ext <- dev_chr(file_type)
+ if (is.null(file)) {
+ file <- normalizePath(
+ tempfile(pattern = "barplot_", tmpdir = dir, fileext = paste0(".", file_ext)),
+ winslash = "/", mustWork = FALSE)
+ }
+
+ graphics_dev(filename = file, dev = file_type,
+ width = devwidth, height = devheight, res = res,
+ bg = "transparent")
+ curdev <- grDevices::dev.cur()
+ on.exit(grDevices::dev.off(curdev), add = TRUE)
+
+ graphics::par(mar = c(0, 0, 0, 0), lwd=0.5)
+ graphics::barplot(height=height, beside = beside,horiz = horiz, col = col, border = border,xaxt = xaxt, yaxt = yaxt, ann = ann)#,xlim = lim, ann = ann, ...)
+
+ grDevices::dev.off(curdev)
+
+ out <- make_inline_plot(
+ file, file_ext, file_type,
+ devwidth, devheight, res,
+ del = TRUE)
+ return(out)
+}
is_latex <- knitr::is_latex_output
diff --git a/man/collapse_rows.Rd b/man/collapse_rows.Rd
index 8efcb55..a78e29d 100644
--- a/man/collapse_rows.Rd
+++ b/man/collapse_rows.Rd
@@ -9,7 +9,7 @@
columns = NULL,
valign = c("middle", "top", "bottom"),
latex_hline = c("full", "major", "none", "custom", "linespace"),
- row_group_label_position = c("identity", "stack"),
+ row_group_label_position = c("identity", "stack", "first"),
custom_latex_hline = NULL,
row_group_label_fonts = NULL,
headers_to_remove = NULL,
@@ -24,22 +24,25 @@
\item{columns}{A numeric value or vector indicating in which column(s) rows
need to be collapsed.}
-\item{valign}{Select from "top", "middle"(default), "bottom". The reason why
+\item{valign}{Select from "top", "middle" (default), "bottom". The reason why
"top" is not default is that the multirow package on CRAN win-builder is
-not up to date.}
+not up to date.
+Only used when \code{row_group_label_position} is \code{identity}.}
\item{latex_hline}{Option controlling the behavior of adding hlines to table.
Choose from \code{full}, \code{major}, \code{none}, \code{custom} and \code{linespace}.}
\item{row_group_label_position}{Option controlling positions of row group
-labels. Choose from \code{identity}, \code{stack}.}
+labels. Choose from \code{identity}, \code{stack}, or \code{first} -- the latter behaves
+like \code{identity} when \code{row_group_label_position} is \code{top} but without using
+the multirow package.}
\item{custom_latex_hline}{Numeric column positions whose collapsed rows will
be separated by hlines.}
\item{row_group_label_fonts}{A list of arguments that can be supplied to
group_rows function to format the row group label when
-\code{row_group_label_position} is \code{stack}}
+\code{row_group_label_position} is \code{stack}.}
\item{headers_to_remove}{Numeric column positions where headers should be
removed when they are stacked.}
diff --git a/man/header_separate.Rd b/man/header_separate.Rd
index 60a5d31..d2f69fb 100644
--- a/man/header_separate.Rd
+++ b/man/header_separate.Rd
@@ -4,7 +4,7 @@
\alias{header_separate}
\title{Separate table headers and add additional header rows based on grouping}
\usage{
-header_separate(kable_input, sep = "[^[:alnum:]]+")
+header_separate(kable_input, sep = "[^[:alnum:]]+", ...)
}
\arguments{
\item{kable_input}{Output of \code{knitr::kable()} with \code{format} specified}
diff --git a/man/kbl.Rd b/man/kbl.Rd
index 0249e69..06f1f37 100644
--- a/man/kbl.Rd
+++ b/man/kbl.Rd
@@ -67,7 +67,8 @@
\item{caption}{The table caption.}
\item{label}{The table reference label. By default, the label is obtained
-from \code{knitr::\link[knitr]{opts_current}$get('label')}.}
+from \code{knitr::\link[knitr]{opts_current}$get('label')}. To disable the label,
+use \code{label = NA}.}
\item{format.args}{A list of arguments to be passed to \code{\link{format}()}
to format table values, e.g. \code{list(big.mark = ',')}.}
@@ -126,7 +127,7 @@
default setting is to put a table environment outside of tabular if a
caption is provided.}
-\item{...}{Other arguments (see Examples).}
+\item{...}{Other arguments (see Examples and References).}
}
\description{
knitr's kable function is the foundation of this package.
diff --git a/man/linebreak.Rd b/man/linebreak.Rd
index 55adc0a..31ecbad 100644
--- a/man/linebreak.Rd
+++ b/man/linebreak.Rd
@@ -9,7 +9,7 @@
\arguments{
\item{x}{A character vector}
-\item{align}{Choose from "l", "c" or "r"}
+\item{align}{Choose from "l", "c" or "r". Defaults to "l".}
\item{double_escape}{Whether special character should be double escaped.
Default is FALSE.}
@@ -17,6 +17,6 @@
\item{linebreaker}{Symbol for linebreaks to replace. Default is \verb{\\\\n}.}
}
\description{
-This function generate LaTeX code of \code{makecell} so that users
+This function generates LaTeX code of \code{makecell} so that users
can have linebreaks in their table
}
diff --git a/man/spec_barplot.Rd b/man/spec_barplot.Rd
new file mode 100644
index 0000000..7b11fdd
--- /dev/null
+++ b/man/spec_barplot.Rd
@@ -0,0 +1,80 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/mini_plots.R
+\name{spec_barplot}
+\alias{spec_barplot}
+\title{Helper functions to generate inline sparklines}
+\usage{
+spec_barplot(
+ x,
+ devwidth = 200,
+ devheight = 40,
+ res = 300,
+ beside = F,
+ horiz = F,
+ same_lim = TRUE,
+ lim = NULL,
+ xaxt = "n",
+ yaxt = "n",
+ ann = FALSE,
+ col = NULL,
+ border = NA,
+ dir = if (is_latex()) rmd_files_dir() else tempdir(),
+ file = NULL,
+ file_type = if (is_latex()) "pdf" else svglite::svglite,
+ ...
+)
+}
+\arguments{
+\item{x}{Vector of values or List of vectors of values.}
+
+\item{res}{The resolution of the plot. Default is 300.}
+
+\item{same_lim}{T/F. If x is a list of vectors, should all the plots be
+plotted in the same range? Default is True.}
+
+\item{lim}{Manually specify plotting range in the form of
+\code{c(0, 10)}.}
+
+\item{xaxt}{On/Off for xaxis text}
+
+\item{yaxt}{On/Off for yaxis text}
+
+\item{ann}{On/Off for annotations (titles and axis titles)}
+
+\item{col}{Color for the fill of the histogram bar/boxplot box.}
+
+\item{border}{Color for the border.}
+
+\item{dir}{Directory of where the images will be saved.}
+
+\item{file}{File name. If not provided, a random name will be used}
+
+\item{file_type}{Graphic device. Can be character (e.g., \code{"pdf"})
+or a graphics device function (\code{grDevices::pdf}). This defaults
+to \code{"pdf"} if the rendering is in LaTeX and \code{"svg"} otherwise.}
+
+\item{...}{extraparameters passing to boxplot}
+
+\item{width}{The width of the plot in pixel}
+
+\item{height}{The height of the plot in pixel}
+
+\item{add_label}{For boxplot. T/F to add labels for min, mean and max.}
+
+\item{label_digits}{If T for add_label, rounding digits for the label.
+Default is 2.}
+
+\item{boxlty}{Boxplot - box boarder type}
+
+\item{medcol}{Boxplot - median line color}
+
+\item{medlwd}{Boxplot - median line width}
+}
+\description{
+These functions helps you quickly generate sets of sparkline
+style plots using base R plotting system. Currently, we support histogram,
+boxplot, line, scatter, pointrange, barplot plots. You can use them together with
+\code{column_spec} to generate inline plot in tables. By default, this function
+will save images in a folder called "kableExtra" and return the address of
+the file.
+}
diff --git a/man/spec_color.Rd b/man/spec_color.Rd
index 74cdd1d..423d4ea 100644
--- a/man/spec_color.Rd
+++ b/man/spec_color.Rd
@@ -21,16 +21,26 @@
\item{alpha}{The alpha transparency, a number in [0,1], see argument alpha in
\code{\link[grDevices]{hsv}}.}
-\item{begin}{The (corrected) hue in [0,1] at which the viridis colormap begins.}
+\item{begin}{The (corrected) hue in [0,1] at which the color map begins.}
-\item{end}{The (corrected) hue in [0,1] at which the viridis colormap ends.}
+\item{end}{The (corrected) hue in [0,1] at which the color map ends.}
-\item{direction}{Sets the order of colors in the scale. If 1, the default, colors
-are ordered from darkest to lightest. If -1, the order of colors is reversed.}
+\item{direction}{Sets the order of colors in the scale. If 1, the default,
+colors are ordered from darkest to lightest. If -1, the order of colors is
+reversed.}
-\item{option}{A character string indicating the colormap option to use. Four
-options are available: "magma" (or "A"), "inferno" (or "B"), "plasma" (or "C"),
-"viridis" (or "D", the default option) and "cividis" (or "E").}
+\item{option}{A character string indicating the color map option to use.
+Eight options are available:
+\itemize{
+ \item "magma" (or "A")
+ \item "inferno" (or "B")
+ \item "plasma" (or "C")
+ \item "viridis" (or "D")
+ \item "cividis" (or "E")
+ \item "rocket" (or "F")
+ \item "mako" (or "G")
+ \item "turbo" (or "H")
+}}
\item{na_color}{color code for NA values}
diff --git a/vignettes/awesome_table_in_html.Rmd b/vignettes/awesome_table_in_html.Rmd
index 843cea5..deed789 100644
--- a/vignettes/awesome_table_in_html.Rmd
+++ b/vignettes/awesome_table_in_html.Rmd
@@ -532,7 +532,7 @@
```
## Group rows via multi-row cell
-Function `pack_rows` is great for showing simple structural information on rows but sometimes people may need to show structural information with multiple layers. When it happens, you may consider to use `collapse_rows` instead, which will put repeating cells in columns into multi-row cells. The vertical allignment of the cell is controlled by `valign` with default as "top".
+Function `pack_rows` is great for showing simple structural information on rows but sometimes people may need to show structural information with multiple layers. When it happens, you may consider to use `collapse_rows` instead, which will put repeating cells in columns into multi-row cells. The vertical alignment of the cell is controlled by `valign` with default as "top".
```{r}
collapse_rows_dt <- data.frame(C1 = c(rep("a", 10), rep("b", 5)),
diff --git a/vignettes/awesome_table_in_pdf.Rmd b/vignettes/awesome_table_in_pdf.Rmd
index 7025dd7..25518b7 100644
--- a/vignettes/awesome_table_in_pdf.Rmd
+++ b/vignettes/awesome_table_in_pdf.Rmd
@@ -493,7 +493,9 @@
## Group rows via multi-row cell
Function `pack_rows` is great for showing simple structural information on rows but sometimes people may need to show structural information with multiple layers. When it happens, you may consider using `collapse_rows` instead, which will put repeating cells in columns into multi-row cells.
-In LaTeX, `collapse_rows` adds some extra hlines to help differentiate groups. You can customize this behavior using the `latex_hline` argument. You can choose from `full` (default), `major` and `none`. Vertical alignment of cells is controlled by the `valign` option. You can choose from "top", "middle"(default) and "bottom". Be cautious that the vertical alignment option was only introduced in multirow in 2016. If you are using a legacy LaTeX distribution, you will run into trouble if you set `valign` to be either "top" or "bottom".
+In LaTeX, `collapse_rows` adds some extra hlines to help differentiate groups. You can customize this behavior using the `latex_hline` argument. You can choose from `full` (default), `major` and `none`.
+
+Vertical alignment of cells (with the default `row_group_label_position = "identity")`) is controlled by the `valign` option. You can choose from "top", "middle" (default) and "bottom". Be cautious that the vertical alignment option was only introduced in multirow in 2016. If you are using a legacy LaTeX distribution, you will run into trouble if you set `valign` to be either "top" or "bottom". Alternatively, use `row_group_label_position = "first"`, which will put the row group labels into the first row without using the `\multirow` LaTeX command at all.
```{r}
collapse_rows_dt <- data.frame(C1 = c(rep("a", 10), rep("b", 5)),
@@ -502,7 +504,7 @@
C4 = sample(c(0,1), 15, replace = TRUE))
kbl(collapse_rows_dt, booktabs = T, align = "c") %>%
column_spec(1, bold=T) %>%
- collapse_rows(columns = 1:2, latex_hline = "major", valign = "middle")
+ collapse_rows(columns = 1:2, latex_hline = "major", row_group_label_position = "first")
```
Right now, you can't automatically make striped rows based on collapsed rows but you can do it manually via the `extra_latex_after` option in `row_spec`. This feature is not officially supported. I'm only document it here if you want to give it a try.