From 41ae90301fcd0387d7d7ffacdfac4c897bedda8d Mon Sep 17 00:00:00 2001 From: Thomas Mock Date: Sat, 9 Sep 2023 15:33:14 -0500 Subject: [PATCH] update news and document - closes #99 --- NEWS.md | 1 + man/gt_plt_bar_pct.Rd | 97 +++++++++++++++++++++++++++++++++++++++++ man/gt_plt_sparkline.Rd | 73 +++++++++++++++++++++++++++++++ 3 files changed, 171 insertions(+) create mode 100644 man/gt_plt_bar_pct.Rd create mode 100644 man/gt_plt_sparkline.Rd diff --git a/NEWS.md b/NEWS.md index 556e3dc..7d9b73a 100644 --- a/NEWS.md +++ b/NEWS.md @@ -11,6 +11,7 @@ - Accommodate small values in `gt_plt_bullet()` - [#87](https://github.com/jthomasmock/gtExtras/issues/87) - Address some small bugs #94 and #95 - Add an expandable tag to `gt_plt_summary()` - [Request](https://twitter.com/AdriMichelson/status/1697020677952557103?s=20) +- Add a labelling feature to `gt_plt_bar_pct()` - thanks to @andreweatherman and [PR](https://github.com/jthomasmock/gtExtras/pull/100) # gtExtras 0.4.5 - Refactor many functions to account for upstream changes in `gt` v0.8.0 diff --git a/man/gt_plt_bar_pct.Rd b/man/gt_plt_bar_pct.Rd new file mode 100644 index 0000000..b8adeee --- /dev/null +++ b/man/gt_plt_bar_pct.Rd @@ -0,0 +1,97 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/gt-bar-html.R +\name{gt_plt_bar_pct} +\alias{gt_plt_bar_pct} +\title{Add HTML-based bar plots into rows of a \code{gt} table} +\usage{ +gt_plt_bar_pct( + gt_object, + column, + height = 16, + width = 100, + fill = "purple", + background = "#e1e1e1", + scaled = FALSE, + labels = FALSE, + label_cutoff = 0.4, + decimals = 1, + font_style = "bold", + font_size = "10px" +) +} +\arguments{ +\item{gt_object}{An existing gt table object of class \code{gt_tbl}} + +\item{column}{The column wherein the bar plot should replace existing data.} + +\item{height}{A number representing the vertical height of the plot in pixels. Defaults to 16 px.} + +\item{width}{A number representing the horizontal width of the plot in pixels. Defaults to 100 px. Importantly, this interacts with the label_cutoff argument, so if you want to change the cutoff, you may need to adjust the width as well.} + +\item{fill}{A character representing the fill for the bar, defaults to purple. Accepts a named color (eg 'purple') or a hex color.} + +\item{background}{A character representing the background filling out the 100\% mark of the bar, defaults to light grey. Accepts a named color (eg 'white') or a hex color.} + +\item{scaled}{\code{TRUE}/\code{FALSE} logical indicating if the value is already scaled to a percent of max (\code{TRUE}) or if it needs to be scaled (\code{FALSE}). Defaults to \code{FALSE}, meaning the value will be divided by the max value in that column and then multiplied by 100.} + +\item{labels}{\code{TRUE}/\code{FALSE} logical representing if labels should be plotted. Defaults to \code{FALSE}, meaning that no value labels will be plotted.} + +\item{label_cutoff}{A number, 0 to 1, representing where to set the inside/outside label boundary. Defaults to 0.40 (40\%) of the column's maximum value. If the value in that row is less than the cutoff, the label will be placed outside the bar, otherwise it will be placed within the bar. This interacts with the overall width of the bar, so if you are not happy with the placement of the labels you may try adjusting the \code{width} argument as well.} + +\item{decimals}{A number representing how many decimal places to be used in label rounding. Defaults to 1.} + +\item{font_style}{A character representing the font style of the labels. Accepts one of 'bold' (default), 'italic', or 'normal'.} + +\item{font_size}{A character representing the font size of the labels. Defaults to '12px'.} +} +\value{ +An object of class \code{gt_tbl}. +} +\description{ +The \code{gt_plt_bar_pct} function takes an existing \code{gt_tbl} object and +adds horizontal barplots via native HTML. Note that values +default to being normalized to the percent of the maximum observed value +in the specified column. You can turn this off if the values already +represent a percentage value representing 0-100. +} +\section{Examples}{ + + +\if{html}{\out{
}}\preformatted{library(gt) + gt_bar_plot_tab <- mtcars \%>\% + head() \%>\% + dplyr::select(cyl, mpg) \%>\% + dplyr::mutate(mpg_pct_max = round(mpg/max(mpg) * 100, digits = 2), + mpg_scaled = mpg/max(mpg) * 100) \%>\% + dplyr::mutate(mpg_unscaled = mpg) \%>\% + gt() \%>\% + gt_plt_bar_pct(column = mpg_scaled, scaled = TRUE) \%>\% + gt_plt_bar_pct(column = mpg_unscaled, scaled = FALSE, + fill = "blue", background = "lightblue") \%>\% + cols_align("center", contains("scale")) \%>\% + cols_width(4 ~ px(125), + 5 ~ px(125)) +}\if{html}{\out{
}} +} + +\section{Figures}{ + +\if{html}{\figure{gt_bar_plot.png}{options: width=100\%}} +} + +\section{Function ID}{ + +3-5 +} + +\seealso{ +Other Plotting: +\code{\link{gt_plt_bar_stack}()}, +\code{\link{gt_plt_bar}()}, +\code{\link{gt_plt_dist}()}, +\code{\link{gt_plt_percentile}()}, +\code{\link{gt_plt_point}()}, +\code{\link{gt_plt_sparkline}()}, +\code{\link{gt_plt_winloss}()} +} +\concept{Plotting} diff --git a/man/gt_plt_sparkline.Rd b/man/gt_plt_sparkline.Rd new file mode 100644 index 0000000..f096665 --- /dev/null +++ b/man/gt_plt_sparkline.Rd @@ -0,0 +1,73 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/gt_plt_sparkline.R +\name{gt_plt_sparkline} +\alias{gt_plt_sparkline} +\title{Add sparklines into rows of a \code{gt} table} +\usage{ +gt_plt_sparkline( + gt_object, + column, + type = "default", + fig_dim = c(5, 30), + palette = c("black", "black", "purple", "green", "lightgrey"), + same_limit = TRUE, + label = TRUE +) +} +\arguments{ +\item{gt_object}{An existing gt table object of class \code{gt_tbl}} + +\item{column}{The column wherein the sparkline plot should replace existing data. Note that the data \emph{must} be represented as a list of numeric values ahead of time.} + +\item{type}{A string indicating the type of plot to generate, accepts \code{"default"}, \code{"points"}, \code{"shaded"}, \code{"ref_median"}, \code{'ref_mean'}, \code{"ref_iqr"}, \code{"ref_last"}. "points" will add points to every observation instead of just the high/low and final. "shaded" will add shading below the sparkline. The "ref_" options add a thin reference line based off the summary statistic chosen} + +\item{fig_dim}{A vector of two numbers indicating the height/width of the plot in mm at a DPI of 25.4, defaults to \code{c(5,30)}} + +\item{palette}{A character string with 5 elements indicating the colors of various components. Order matters, and palette = sparkline color, final value color, range color low, range color high, and 'type' color (eg shading or reference lines). To show a plot with no points (only the line itself), use: \code{palette = c("black", rep("transparent", 4))}.} + +\item{same_limit}{A logical indicating that the plots will use the same axis range (\code{TRUE}) or have individual axis ranges (\code{FALSE}).} + +\item{label}{A logical indicating whether the sparkline will have a numeric label for the last value in the vector, placed at the end of the plot.} +} +\value{ +An object of class \code{gt_tbl}. +} +\description{ +The \code{gt_plt_sparkline} function takes an existing \code{gt_tbl} object and +adds sparklines via the \code{ggplot2}. Note that if you'd rather plot summary +distributions (ie density/histograms) you can instead use: \code{gtExtras::gt_plt_dist()} +} +\section{Examples}{ + + +\if{html}{\out{
}}\preformatted{ library(gt) + gt_sparkline_tab <- mtcars \%>\% + dplyr::group_by(cyl) \%>\% + # must end up with list of data for each row in the input dataframe + dplyr::summarize(mpg_data = list(mpg), .groups = "drop") \%>\% + gt() \%>\% + gt_plt_sparkline(mpg_data) +}\if{html}{\out{
}} +} + +\section{Figures}{ + +\if{html}{\figure{gt_plt_sparkline.png}{options: width=50\%}} +} + +\section{Function ID}{ + +1-4 +} + +\seealso{ +Other Plotting: +\code{\link{gt_plt_bar_pct}()}, +\code{\link{gt_plt_bar_stack}()}, +\code{\link{gt_plt_bar}()}, +\code{\link{gt_plt_dist}()}, +\code{\link{gt_plt_percentile}()}, +\code{\link{gt_plt_point}()}, +\code{\link{gt_plt_winloss}()} +} +\concept{Plotting}