diff --git a/DESCRIPTION b/DESCRIPTION index 9adb2063b6..48bd676acc 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -50,3 +50,4 @@ Suggests: shiny, xml2 VignetteBuilder: knitr +Roxygen: list(markdown = TRUE) diff --git a/R/as_latex.R b/R/as_latex.R index 75eff049ce..6883be4a93 100644 --- a/R/as_latex.R +++ b/R/as_latex.R @@ -1,13 +1,12 @@ #' Output a \pkg{gt} object as LaTeX #' -#' Get the LaTeX content from a \code{gt_tbl} object as a \code{knit_asis} -#' object. This object contains the LaTeX code and attributes that serve as -#' LaTeX dependencies (i.e., the LaTeX packages required for the table). Using -#' \code{as.character()} on the created object will result in a single-element -#' vector containing the LaTeX code. +#' Get the LaTeX content from a `gt_tbl` object as a `knit_asis` object. This +#' object contains the LaTeX code and attributes that serve as LaTeX +#' dependencies (i.e., the LaTeX packages required for the table). Using +#' `as.character()` on the created object will result in a single-element vector +#' containing the LaTeX code. #' -#' @param data a table object that is created using the \code{\link{gt}()} -#' function. +#' @param data A table object that is created using the [gt()] function. #' @import rlang #' @importFrom dplyr mutate group_by summarize ungroup rename arrange #' @importFrom stats setNames diff --git a/R/as_raw_html.R b/R/as_raw_html.R index 64280957a9..4a935ab35e 100644 --- a/R/as_raw_html.R +++ b/R/as_raw_html.R @@ -1,14 +1,13 @@ #' Get the HTML content of a \pkg{gt} table #' -#' Get the HTML content from a \code{gt_tbl} object as a single-element -#' character vector. By default, the generated HTML will have inlined styles, -#' where CSS styles (that were previously contained in CSS rule sets external to -#' the \code{ element}) are included as \code{style} attributes in the -#' HTML table's tags. This option is preferable when using the output HTML table -#' in an emailing context. -#' @param data a table object that is created using the \code{\link{gt}()} -#' function. -#' @param inline_css an option to supply styles to table elements as inlined CSS +#' Get the HTML content from a `gt_tbl` object as a single-element character +#' vector. By default, the generated HTML will have inlined styles, where CSS +#' styles (that were previously contained in CSS rule sets external to the +#' `
element`) are included as `style` attributes in the HTML table's +#' tags. This option is preferable when using the output HTML table in an +#' emailing context. +#' @param data A table object that is created using the [gt()] function. +#' @param inline_css An option to supply styles to table elements as inlined CSS #' styles. #' @examples #' # Use `gtcars` to create a gt table; diff --git a/R/as_rtf.R b/R/as_rtf.R index 74377f58c9..d9bda07c23 100644 --- a/R/as_rtf.R +++ b/R/as_rtf.R @@ -1,10 +1,10 @@ #' Output a \pkg{gt} object as RTF #' -#' Get the RTF content from a \code{gt_tbl} object as as a single-element -#' character vector. This object can be used with \code{writeLines()} to -#' generate a valid .rtf file that can be opened by RTF readers. +#' Get the RTF content from a `gt_tbl` object as as a single-element character +#' vector. This object can be used with `writeLines()` to generate a valid .rtf +#' file that can be opened by RTF readers. #' -#' @param data a table object that is created using the \code{gt()} function. +#' @param data a table object that is created using the `gt()` function. #' @examples #' # Use `gtcars` to create a gt table; #' # add a header and then export as diff --git a/R/data_color.R b/R/data_color.R index 66f6071428..1b379a139f 100644 --- a/R/data_color.R +++ b/R/data_color.R @@ -1,71 +1,71 @@ #' Set data cell colors using a palette or a color function #' #' It's possible to add color to data cells according to their values. The -#' \code{data_color()} function colors all rows of any \code{columns} supplied. -#' There are two ways to define how cells are colored: (1) through the use of a -#' supplied color palette, and (2) through use of a color mapping function -#' available from the \code{scales} package. The first method colorizes cell -#' data according to whether values are character or numeric. The second method -#' provides more control over how cells are colored since we provide an explicit -#' color function and thus other requirements such as bin counts, cut points, or -#' a numeric domain. Finally, we can choose whether to apply the cell-specific +#' `data_color()` function colors all rows of any `columns` supplied. There are +#' two ways to define how cells are colored: (1) through the use of a supplied +#' color palette, and (2) through use of a color mapping function available from +#' the `scales` package. The first method colorizes cell data according to +#' whether values are character or numeric. The second method provides more +#' control over how cells are colored since we provide an explicit color +#' function and thus other requirements such as bin counts, cut points, or a +#' numeric domain. Finally, we can choose whether to apply the cell-specific #' colors to either the cell background or the cell text. #' -#' The \code{col_*()} functions from the scales package can be used in the -#' \code{colors} argument. These functions map data values (\code{numeric} or -#' \code{factor}/\code{character}) to colors according to the provided palette. +#' The `col_*()` functions from the scales package can be used in the `colors` +#' argument. These functions map data values (`numeric` or `factor`/`character`) +#' to colors according to the provided palette. #' #' \itemize{ -#' \item \code{\link[scales]{col_numeric}()}: provides a simple linear mapping +#' \item [scales::col_numeric()]: provides a simple linear mapping #' from continuous numeric data to an interpolated palette. -#' \item \code{\link[scales]{col_bin}()}: provides a mapping of continuous +#' \item [scales::col_bin()]: provides a mapping of continuous #' numeric data to value-based bins. This internally uses the -#' \code{\link[base]{cut}()} function. -#' \item \code{\link[scales]{col_quantile}()}: provides a mapping of continuous +#' [base::cut()] function. +#' \item [scales::col_quantile()]: provides a mapping of continuous #' numeric data to quantiles. This internally uses the -#' \code{\link[stats]{quantile}()} function. -#' \item \code{\link[scales]{col_factor}()}: provides a mapping of factors to +#' [stats::quantile()] function. +#' \item [scales::col_factor()]: provides a mapping of factors to #' colors. If the palette is discrete and has a different number of colors than #' the number of factors, interpolation is used. #' } #' #' By default, \pkg{gt} will choose the ideal text color (for maximal contrast) #' when colorizing the background of data cells. This option can be disabled by -#' setting \code{autocolor_text} to \code{FALSE}. +#' setting `autocolor_text` to `FALSE`. #' #' Choosing the right color palette can often be difficult because it's both #' hard to discover suitable palettes and then obtain the vector of colors. To #' make this process easier we can elect to use the \pkg{paletteer} package, #' which makes a wide range of palettes from various R packages readily -#' available. The \code{\link{info_paletteer}()} information table allows us to -#' easily inspect all of the discrete color palettes available in -#' \pkg{paletteer}. We only then need to specify the \code{package} and -#' \code{palette} when calling the \code{paletteer::paletteer_d()} function, -#' and, we get the palette as a vector of hexadecimal colors. +#' available. The [info_paletteer()] information table allows us to easily +#' inspect all of the discrete color palettes available in \pkg{paletteer}. We +#' only then need to specify the `package` and `palette` when calling the +#' `paletteer::paletteer_d()` function, and, we get the palette as a vector of +#' hexadecimal colors. #' #' @inheritParams fmt_number -#' @param columns the columns wherein changes to cell data colors should occur. -#' @param colors either a color mapping function from the \code{scales} package +#' @param columns The columns wherein changes to cell data colors should occur. +#' @param colors Either a color mapping function from the `scales` package #' or a vector of colors to use for each distinct value or level in each of -#' the provided \code{columns}. The color mapping functions are: -#' \code{scales::col_quantile()}, \code{scales::col_bin()}, -#' \code{scales::col_numeric()}, and \code{scales::col_factor()}. If providing +#' the provided `columns`. The color mapping functions are: +#' `scales::col_quantile()`, `scales::col_bin()`, +#' `scales::col_numeric()`, and `scales::col_factor()`. If providing #' a vector of colors as a palette, each color value provided must either be a -#' color name (in the set of colors provided by \code{grDevices::colors()}) or +#' color name (in the set of colors provided by `grDevices::colors()`) or #' a hexadecimal string in the form of "#RRGGBB" or "#RRGGBBAA". -#' @param alpha an optional, fixed alpha transparency value that will be applied -#' to all of the \code{colors} provided if they are provided as a vector of -#' colors. If using a colorizing helper function for \code{colors} then this +#' @param alpha An optional, fixed alpha transparency value that will be applied +#' to all of the `colors` provided if they are provided as a vector of +#' colors. If using a colorizing helper function for `colors` then this #' option is ignored (each of the colorizing helper functions has its own -#' \code{alpha} argument). -#' @param apply_to which style element should the colors be applied to? Options -#' include the cell background (the default, given as \code{bkgd}) or the cell -#' text (\code{text}). -#' @param autocolor_text an option to let \pkg{gt} modify the coloring of text +#' `alpha` argument). +#' @param apply_to Which style element should the colors be applied to? Options +#' include the cell background (the default, given as `bkgd`) or the cell +#' text (`text`). +#' @param autocolor_text An option to let \pkg{gt} modify the coloring of text #' within cells undergoing background coloring. This will in some cases yield #' more optimal text-to-background color contrast. By default, this is set to -#' \code{TRUE}. -#' @return an object of class \code{gt_tbl}. +#' `TRUE`. +#' @return An object of class `gt_tbl`. #' @examples #' # library(paletteer) #' @@ -235,7 +235,9 @@ data_color <- function(data, data } -# Apply color scale styles to the gt table data +#' Apply color scale styles to the gt table data +#' +#' @noRd scale_apply_styles <- function(data, column, styles, @@ -278,17 +280,17 @@ scale_apply_styles <- function(data, #' apply greater darkening or lightening for those colors in the midrange #' compared to any very dark or very light colors in the input palette. #' -#' This function can be useful when combined with the \code{\link{data_color}()} -#' function's \code{palette} argument, which can use a vector of colors or any -#' of the \code{col_*} functions from the \pkg{scales} package (all of which -#' have a \code{palette} argument). +#' This function can be useful when combined with the [data_color()] function's +#' `palette` argument, which can use a vector of colors or any of the `col_*` +#' functions from the \pkg{scales} package (all of which have a `palette` +#' argument). #' -#' @param colors a vector of colors that will undergo an adjustment in +#' @param colors A vector of colors that will undergo an adjustment in #' luminance. Each color value provided must either be a color name (in the -#' set of colors provided by \code{grDevices::colors()}) or a hexadecimal -#' string in the form of "#RRGGBB" or "#RRGGBBAA". -#' @param steps a positive or negative factor by which the luminance will be -#' adjusted. Must be a number between \code{-2.0} and \code{2.0}. +#' set of colors provided by `grDevices::colors()`) or a hexadecimal string in +#' the form of "#RRGGBB" or "#RRGGBBAA". +#' @param steps A positive or negative factor by which the luminance will be +#' adjusted. Must be a number between `-2.0` and `2.0`. #' @examples #' # Get a palette of 8 pastel colors from #' # the RColorBrewer package @@ -378,7 +380,9 @@ adjust_luminance <- function(colors, hcl_colors } -# Extract a vector of alpha values for a vector of colors +#' Extract a vector of alpha values for a vector of colors +#' +#' @noRd get_alpha_vec <- function(colors) { alpha <- c() @@ -397,8 +401,8 @@ get_alpha_vec <- function(colors) { alpha } -# Function for determining the best `light` and `dark` colors to appear above a -# background color +#' Determining the best `light` and `dark` colors for contrast +#' #' @importFrom grDevices col2rgb #' @noRd ideal_fgnd_color <- function(bgnd_colors, diff --git a/R/datasets.R b/R/datasets.R index 3b73aa03d2..fddb231077 100644 --- a/R/datasets.R +++ b/R/datasets.R @@ -4,20 +4,19 @@ #' population is based on counts of all residents regardless of legal status or #' citizenship. Country identifiers include the English-language country names, #' and the 2- and 3-letter ISO 3166-1 country codes. Each row contains a -#' \code{population} value for a given \code{year} (from 1960 to 2017). Any -#' \code{NA} values for \code{populations} indicate the non-existence of the -#' country during that year. +#' `population` value for a given `year` (from 1960 to 2017). Any `NA` values +#' for `populations` indicate the non-existence of the country during that year. #' #' @format A tibble with 12470 rows and 5 variables: #' \describe{ -#' \item{country_name}{Name of the country} -#' \item{country_code_2}{The 2-letter ISO 3166-1 country code} -#' \item{country_code_3}{The 3-letter ISO 3166-1 country code} -#' \item{year}{The year for the population estimate} -#' \item{population}{The population estimate, midway through the year} +#' \item{country_name}{Name of the country} +#' \item{country_code_2}{The 2-letter ISO 3166-1 country code} +#' \item{country_code_3}{The 3-letter ISO 3166-1 country code} +#' \item{year}{The year for the population estimate} +#' \item{population}{The population estimate, midway through the year} #' } #' -#' @source \url{https://data.worldbank.org/indicator/SP.POP.TOTL} +#' @source #' #' @examples #' # Here is a glimpse at the data @@ -50,15 +49,15 @@ #' \item{latitude}{The latitude in decimal degrees for the observations} #' \item{month}{The measurement month; all calculations where conducted #' for the first day of each month} -#' \item{tst}{The true solar time at the given \code{latitude} and date -#' (first of \code{month}) for which the solar zenith angle is calculated} -#' \item{sza}{The solar zenith angle in degrees, where \code{NA}s -#' indicate that sunrise hadn't yet occurred by the \code{tst} value} +#' \item{tst}{The true solar time at the given `latitude` and date +#' (first of `month`) for which the solar zenith angle is calculated} +#' \item{sza}{The solar zenith angle in degrees, where `NA`s +#' indicate that sunrise hadn't yet occurred by the `tst` value} #' } #' #' @source Calculated Actinic Fluxes (290 - 700 nm) for Air Pollution #' Photochemistry Applications (Peterson, 1976), available at: -#' \url{https://nepis.epa.gov/Exe/ZyPURL.cgi?Dockey=9100JA26.txt}. +#' . #' #' @examples #' # Here is a glimpse at the data @@ -68,19 +67,19 @@ #' Deluxe automobiles from the 2014-2017 period #' -#' Expensive and fast cars. Not your father's \code{mtcars}. Each row describes -#' a car of a certain make, model, year, and trim. Basic specifications such as +#' Expensive and fast cars. Not your father's `mtcars`. Each row describes a car +#' of a certain make, model, year, and trim. Basic specifications such as #' horsepower, torque, EPA MPG ratings, type of drivetrain, and transmission #' characteristics are provided. The country of origin for the car manufacturer #' is also given. #' -#' All of the \code{gtcars} have something else in common (aside from the high -#' asking prices): they are all grand tourer vehicles. These are proper GT cars -#' that blend pure driving thrills with a level of comfort that is more expected -#' from a fine limousine (e.g., a Rolls-Royce Phantom EWB). You'll find that, -#' with these cars, comfort is emphasized over all-out performance. -#' Nevertheless, the driving experience should also mean motoring at speed, -#' doing so in style and safety. +#' All of the `gtcars` have something else in common (aside from the high asking +#' prices): they are all grand tourer vehicles. These are proper GT cars that +#' blend pure driving thrills with a level of comfort that is more expected from +#' a fine limousine (e.g., a Rolls-Royce Phantom EWB). You'll find that, with +#' these cars, comfort is emphasized over all-out performance. Nevertheless, the +#' driving experience should also mean motoring at speed, doing so in style and +#' safety. #' #' @format A tibble with 47 rows and 15 variables: #' \describe{ @@ -89,23 +88,22 @@ #' \item{year}{The car's model year} #' \item{trim}{A short description of the car model's trim} #' \item{bdy_style}{An identifier of the car's body style, which is either -#' \code{coupe}, \code{convertible}, \code{sedan}, or \code{hatchback}} +#' `coupe`, `convertible`, `sedan`, or `hatchback`} #' \item{hp, hp_rpm}{The car's horsepower and the associated RPM level} #' \item{trq, trq_rpm}{The car's torque and the associated RPM level} #' \item{mpg_c, mpg_h}{The miles per gallon fuel efficiency rating for city #' and highway driving} #' \item{drivetrain}{The car's drivetrain which, for this dataset is either -#' \code{rwd} (Rear Wheel Drive) or \code{awd} (All Wheel Drive)} +#' `rwd` (Rear Wheel Drive) or `awd` (All Wheel Drive)} #' \item{trsmn}{The codified transmission type, where the number part is #' the number of gears; the car could have automatic transmission -#' (\code{a}), manual transmission (\code{m}), an option to switch between -#' both types (\code{am}), or, direct drive (\code{dd})} +#' (`a`), manual transmission (`m`), an option to switch between +#' both types (`am`), or, direct drive (`dd`)} #' \item{ctry_origin}{The country name for where the vehicle manufacturer #' is headquartered} #' } #' -#' @source Various pages within \url{https://www.edmunds.com}. -#' +#' @source Various pages within . #' @examples #' # Here is a glimpse at the data #' # available in `gtcars` @@ -120,15 +118,14 @@ #' #' @format A tibble with 16607 rows and 7 variables: #' \describe{ -#' \item{date}{The date expressed as \code{Date} values} -#' \item{open, high, low, close}{The day's opening, high, low, and closing -#' prices in USD; the \code{close} price is adjusted for splits} -#' \item{volume}{the number of trades for the given \code{date}} -#' \item{adj_close}{The close price adjusted for both dividends and splits} +#' \item{date}{The date expressed as `Date` values} +#' \item{open, high, low, close}{The day's opening, high, low, and closing +#' prices in USD; the `close` price is adjusted for splits} +#' \item{volume}{the number of trades for the given `date`} +#' \item{adj_close}{The close price adjusted for both dividends and splits} #' } #' -#' @source Data collected from \url{https://finance.yahoo.com/quote/\%5EGSPC/history/}. -#' +#' @source Data collected from . #' @examples #' # Here is a glimpse at the data #' # available in `sp500` @@ -140,112 +137,112 @@ #' A synthetic dataset that describes pizza sales for a pizza place somewhere in #' the US. While the contents are artificial, the ingredients used to make the #' pizzas are far from it. There are 32 different pizzas that fall into 4 -#' different categories: \code{classic} (classic pizzas: 'You probably had one -#' like it before, but never like this!'), \code{chicken} (pizzas with chicken -#' as a major ingredient: 'Try the Southwest Chicken Pizza! You'll love it!'), -#' \code{supreme} (pizzas that try a little harder: 'My Soppressata pizza uses -#' only the finest salami from my personal salumist!'), and, \code{veggie} -#' (pizzas without any meats whatsoever: 'My Five Cheese pizza has so many -#' cheeses, I can only offer it in Large Size!'). +#' different categories: `classic` (classic pizzas: 'You probably had one like +#' it before, but never like this!'), `chicken` (pizzas with chicken as a major +#' ingredient: 'Try the Southwest Chicken Pizza! You'll love it!'), `supreme` +#' (pizzas that try a little harder: 'My Soppressata pizza uses only the finest +#' salami from my personal salumist!'), and, `veggie` (pizzas without any meats +#' whatsoever: 'My Five Cheese pizza has so many cheeses, I can only offer it in +#' Large Size!'). #' -#' Each pizza in the dataset is identified by a short \code{name}. The following +#' Each pizza in the dataset is identified by a short `name`. The following #' listings provide the full names of each pizza and their main ingredients. #' #' Classic Pizzas: #' \itemize{ -#' \item \code{classic_dlx}: The Classic Deluxe Pizza (Pepperoni, Mushrooms, Red +#' \item `classic_dlx`: The Classic Deluxe Pizza (Pepperoni, Mushrooms, Red #' Onions, Red Peppers, Bacon) -#' \item \code{big_meat}: The Big Meat Pizza (Bacon, Pepperoni, Italian Sausage, +#' \item `big_meat`: The Big Meat Pizza (Bacon, Pepperoni, Italian Sausage, #' Chorizo Sausage) -#' \item \code{pepperoni}: The Pepperoni Pizza (Mozzarella Cheese, Pepperoni) -#' \item \code{hawaiian}: The Hawaiian Pizza (Sliced Ham, Pineapple, Mozzarella +#' \item `pepperoni`: The Pepperoni Pizza (Mozzarella Cheese, Pepperoni) +#' \item `hawaiian`: The Hawaiian Pizza (Sliced Ham, Pineapple, Mozzarella #' Cheese) -#' \item \code{pep_msh_pep}: The Pepperoni, Mushroom, and Peppers Pizza +#' \item `pep_msh_pep`: The Pepperoni, Mushroom, and Peppers Pizza #' (Pepperoni, Mushrooms, and Green Peppers) -#' \item \code{ital_cpcllo}: The Italian Capocollo Pizza (Capocollo, Red +#' \item `ital_cpcllo`: The Italian Capocollo Pizza (Capocollo, Red #' Peppers, Tomatoes, Goat Cheese, Garlic, Oregano) -#' \item \code{napolitana}: The Napolitana Pizza (Tomatoes, Anchovies, Green +#' \item `napolitana`: The Napolitana Pizza (Tomatoes, Anchovies, Green #' Olives, Red Onions, Garlic) -#' \item \code{the_greek}: The Greek Pizza (Kalamata Olives, Feta Cheese, +#' \item `the_greek`: The Greek Pizza (Kalamata Olives, Feta Cheese, #' Tomatoes, Garlic, Beef Chuck Roast, Red Onions) #' } #' #' Chicken Pizzas: #' \itemize{ -#' \item \code{thai_ckn}: The Thai Chicken Pizza (Chicken, Pineapple, Tomatoes, +#' \item `thai_ckn`: The Thai Chicken Pizza (Chicken, Pineapple, Tomatoes, #' Red Peppers, Thai Sweet Chilli Sauce) -#' \item \code{bbq_ckn}: The Barbecue Chicken Pizza (Barbecued Chicken, Red +#' \item `bbq_ckn`: The Barbecue Chicken Pizza (Barbecued Chicken, Red #' Peppers, Green Peppers, Tomatoes, Red Onions, Barbecue Sauce) -#' \item \code{southw_ckn}: The Southwest Chicken Pizza (Chicken, Tomatoes, Red +#' \item `southw_ckn`: The Southwest Chicken Pizza (Chicken, Tomatoes, Red #' Peppers, Red Onions, Jalapeno Peppers, Corn, Cilantro, Chipotle Sauce) -#' \item \code{cali_ckn}: The California Chicken Pizza (Chicken, Artichoke, +#' \item `cali_ckn`: The California Chicken Pizza (Chicken, Artichoke, #' Spinach, Garlic, Jalapeno Peppers, Fontina Cheese, Gouda Cheese) -#' \item \code{ckn_pesto}: The Chicken Pesto Pizza (Chicken, Tomatoes, Red +#' \item `ckn_pesto`: The Chicken Pesto Pizza (Chicken, Tomatoes, Red #' Peppers, Spinach, Garlic, Pesto Sauce) -#' \item \code{ckn_alfredo}: The Chicken Alfredo Pizza (Chicken, Red Onions, +#' \item `ckn_alfredo`: The Chicken Alfredo Pizza (Chicken, Red Onions, #' Red Peppers, Mushrooms, Asiago Cheese, Alfredo Sauce) #' } #' #' Supreme Pizzas: #' \itemize{ -#' \item \code{brie_carre}: The Brie Carre Pizza (Brie Carre Cheese, Prosciutto, +#' \item `brie_carre`: The Brie Carre Pizza (Brie Carre Cheese, Prosciutto, #' Caramelized Onions, Pears, Thyme, Garlic) -#' \item \code{calabrese}: The Calabrese Pizza (‘Nduja Salami, Pancetta, +#' \item `calabrese`: The Calabrese Pizza (‘Nduja Salami, Pancetta, #' Tomatoes, Red Onions, Friggitello Peppers, Garlic) -#' \item \code{soppressata}: The Soppressata Pizza (Soppressata Salami, Fontina +#' \item `soppressata`: The Soppressata Pizza (Soppressata Salami, Fontina #' Cheese, Mozzarella Cheese, Mushrooms, Garlic) -#' \item \code{sicilian}: The Sicilian Pizza (Coarse Sicilian Salami, Tomatoes, +#' \item `sicilian`: The Sicilian Pizza (Coarse Sicilian Salami, Tomatoes, #' Green Olives, Luganega Sausage, Onions, Garlic) -#' \item \code{ital_supr}: The Italian Supreme Pizza (Calabrese Salami, +#' \item `ital_supr`: The Italian Supreme Pizza (Calabrese Salami, #' Capocollo, Tomatoes, Red Onions, Green Olives, Garlic) -#' \item \code{peppr_salami}: The Pepper Salami Pizza (Genoa Salami, Capocollo, +#' \item `peppr_salami`: The Pepper Salami Pizza (Genoa Salami, Capocollo, #' Pepperoni, Tomatoes, Asiago Cheese, Garlic) -#' \item \code{prsc_argla}: The Prosciutto and Arugula Pizza (Prosciutto di San +#' \item `prsc_argla`: The Prosciutto and Arugula Pizza (Prosciutto di San #' Daniele, Arugula, Mozzarella Cheese) -#' \item \code{spinach_supr}: The Spinach Supreme Pizza (Spinach, Red Onions, +#' \item `spinach_supr`: The Spinach Supreme Pizza (Spinach, Red Onions, #' Pepperoni, Tomatoes, Artichokes, Kalamata Olives, Garlic, Asiago Cheese) -#' \item \code{spicy_ital}: The Spicy Italian Pizza (Capocollo, Tomatoes, Goat +#' \item `spicy_ital`: The Spicy Italian Pizza (Capocollo, Tomatoes, Goat #' Cheese, Artichokes, Peperoncini verdi, Garlic) #' } #' #' Vegetable Pizzas #' \itemize{ -#' \item \code{mexicana}: The Mexicana Pizza (Tomatoes, Red Peppers, Jalapeno +#' \item `mexicana`: The Mexicana Pizza (Tomatoes, Red Peppers, Jalapeno #' Peppers, Red Onions, Cilantro, Corn, Chipotle Sauce, Garlic) -#' \item \code{four_cheese}: The Four Cheese Pizza (Ricotta Cheese, Gorgonzola +#' \item `four_cheese`: The Four Cheese Pizza (Ricotta Cheese, Gorgonzola #' Piccante Cheese, Mozzarella Cheese, Parmigiano Reggiano Cheese, Garlic) -#' \item \code{five_cheese}: The Five Cheese Pizza (Mozzarella Cheese, Provolone +#' \item `five_cheese`: The Five Cheese Pizza (Mozzarella Cheese, Provolone #' Cheese, Smoked Gouda Cheese, Romano Cheese, Blue Cheese, Garlic) -#' \item \code{spin_pesto}: The Spinach Pesto Pizza (Spinach, Artichokes, +#' \item `spin_pesto`: The Spinach Pesto Pizza (Spinach, Artichokes, #' Tomatoes, Sun-dried Tomatoes, Garlic, Pesto Sauce) -#' \item \code{veggie_veg}: The Vegetables + Vegetables Pizza (Mushrooms, +#' \item `veggie_veg`: The Vegetables + Vegetables Pizza (Mushrooms, #' Tomatoes, Red Peppers, Green Peppers, Red Onions, Zucchini, Spinach, Garlic) -#' \item \code{green_garden}: The Green Garden Pizza (Spinach, Mushrooms, +#' \item `green_garden`: The Green Garden Pizza (Spinach, Mushrooms, #' Tomatoes, Green Olives, Feta Cheese) -#' \item \code{mediterraneo}: The Mediterranean Pizza (Spinach, Artichokes, +#' \item `mediterraneo`: The Mediterranean Pizza (Spinach, Artichokes, #' Kalamata Olives, Sun-dried Tomatoes, Feta Cheese, Plum Tomatoes, Red Onions) -#' \item \code{spinach_fet}: The Spinach and Feta Pizza (Spinach, Mushrooms, +#' \item `spinach_fet`: The Spinach and Feta Pizza (Spinach, Mushrooms, #' Red Onions, Feta Cheese, Garlic) -#' \item \code{ital_veggie}: The Italian Vegetables Pizza (Eggplant, Artichokes, +#' \item `ital_veggie`: The Italian Vegetables Pizza (Eggplant, Artichokes, #' Tomatoes, Zucchini, Red Peppers, Garlic, Pesto Sauce) #' } #' #' @format A tibble with 49574 rows and 7 variables: #' \describe{ #' \item{id}{The ID for the order, which consists of one or more pizzas -#' at a give \code{date} and \code{time}} -#' \item{date}{A character representation of the \code{order} date, +#' at a give `date` and `time`} +#' \item{date}{A character representation of the `order` date, #' expressed in the ISO 8601 date format (YYYY-MM-DD)} -#' \item{time}{A character representation of the \code{order} time, +#' \item{time}{A character representation of the `order` time, #' expressed as a 24-hour time the ISO 8601 extended time format #' (hh:mm:ss)} #' \item{name}{The short name for the pizza} -#' \item{size}{The size of the pizza, which can either be \code{S}, -#' \code{M}, \code{L}, \code{XL} (rare!), or \code{XXL} (even rarer!); -#' most pizzas are available in the \code{S}, \code{M}, and \code{L} sizes +#' \item{size}{The size of the pizza, which can either be `S`, +#' `M`, `L`, `XL` (rare!), or `XXL` (even rarer!); +#' most pizzas are available in the `S`, `M`, and `L` sizes #' but exceptions apply} #' \item{type}{The category or type of pizza, which can either be -#' \code{classic}, \code{chicken}, \code{supreme}, or \code{veggie}} +#' `classic`, `chicken`, `supreme`, or `veggie`} #' \item{price}{The price of the pizza and the amount that it sold for #' (in USD)} #' } @@ -261,28 +258,27 @@ #' This tibble contains data of a few different classes, which makes it #' well-suited for quick experimentation with the functions in this package. It #' contains only eight rows with numeric, character, and factor columns. The -#' last 4 rows contain \code{NA} values in the majority of this tibble's columns -#' (1 missing value per column). The \code{date}, \code{time}, and -#' \code{datetime} columns are character-based dates/times in the familiar ISO -#' 8601 format. The \code{row} and \code{group} columns provide for unique -#' rownames and two groups (\code{grp_a} and \code{grp_b}) for experimenting -#' with the \code{\link{gt}()} function's \code{rowname_col} and -#' \code{groupname_col} arguments. +#' last 4 rows contain `NA` values in the majority of this tibble's columns (1 +#' missing value per column). The `date`, `time`, and `datetime` columns are +#' character-based dates/times in the familiar ISO 8601 format. The `row` and +#' `group` columns provide for unique rownames and two groups (`grp_a` and +#' `grp_b`) for experimenting with the [gt()] function's `rowname_col` and +#' `groupname_col` arguments. #' #' @format A tibble with 8 rows and 9 variables: #' \describe{ #' \item{num}{a numeric column ordered with increasingly larger values} -#' \item{char}{a character column composed of names of fruits from \code{a} to -#' \code{h}} +#' \item{char}{a character column composed of names of fruits from `a` to +#' `h`} #' \item{fctr}{a factor column with numbers from 1 to 8, written out} #' \item{date, time, datetime}{character columns with dates, times, and #' datetimes} #' \item{currency}{a numeric column that is useful for testing currency-based #' formatting} -#' \item{row}{a character column in the format \code{row_X} which can be +#' \item{row}{a character column in the format `row_X` which can be #' useful for testing with row captions in a table stub} -#' \item{group}{a character column with four \code{grp_a} values and four -#' \code{grp_b} values which can be useful for testing tables that contain +#' \item{group}{a character column with four `grp_a` values and four +#' `grp_b` values which can be useful for testing tables that contain #' row groups} #' } #' diff --git a/R/extract_summary.R b/R/extract_summary.R index 53af783603..e4a2ddd96b 100644 --- a/R/extract_summary.R +++ b/R/extract_summary.R @@ -1,10 +1,10 @@ #' Extract a summary list from a \pkg{gt} object #' -#' Get a list of summary row data frames from a \code{gt_tbl} object where -#' summary rows were added via the \code{\link{summary_rows}()} function. The -#' output data frames contain the \code{groupname} and \code{rowname} columns, -#' whereby \code{rowname} contains descriptive stub labels for the summary rows. -#' @param data a table object that is created using the \code{\link{gt}()} +#' Get a list of summary row data frames from a `gt_tbl` object where +#' summary rows were added via the [summary_rows()] function. The +#' output data frames contain the `groupname` and `rowname` columns, +#' whereby `rowname` contains descriptive stub labels for the summary rows. +#' @param data a table object that is created using the [gt()] #' function. #' @return a list of data frames containing summary data. #' @examples diff --git a/R/format_data.R b/R/format_data.R index 828388f595..36ad3365c8 100644 --- a/R/format_data.R +++ b/R/format_data.R @@ -18,71 +18,64 @@ #' formatting specific to the chosen locale #' } #' -#' Targeting of values is done through \code{columns} and additionally by -#' \code{rows} (if nothing is provided for \code{rows} then entire columns are -#' selected). A number of helper functions exist to make targeting more -#' effective. Conditional formatting is possible by providing a conditional -#' expression to the \code{rows} argument. See the Arguments section for more -#' information on this. -#' -#' @param data A table object that is created using the \code{\link{gt}()} -#' function. +#' Targeting of values is done through `columns` and additionally by `rows` (if +#' nothing is provided for `rows` then entire columns are selected). A number of +#' helper functions exist to make targeting more effective. Conditional +#' formatting is possible by providing a conditional expression to the `rows` +#' argument. See the Arguments section for more information on this. +#' +#' @param data A table object that is created using the [gt()] function. #' @param columns The columns to format. Can either be a series of column names -#' provided in \code{vars()}, a vector of column indices, or a helper function -#' focused on selections. The select helper functions are: -#' \code{\link{starts_with}()}, \code{\link{ends_with}()}, -#' \code{\link{contains}()}, \code{\link{matches}()}, \code{\link{one_of}()}, -#' and \code{\link{everything}()}. +#' provided in [vars()], a vector of column indices, or a helper function +#' focused on selections. The select helper functions are: [starts_with()], +#' [ends_with()], [contains()], [matches()], [one_of()], and [everything()]. #' @param rows Optional rows to format. Not providing any value results in all -#' rows in \code{columns} being formatted. Can either be a vector of row -#' captions provided \code{c()}, a vector of row indices, or a helper function -#' focused on selections. The select helper functions are: -#' \code{\link{starts_with}()}, \code{\link{ends_with}()}, -#' \code{\link{contains}()}, \code{\link{matches}()}, \code{\link{one_of}()}, -#' and \code{\link{everything}()}. We can also use expressions to filter down -#' to the rows we need (e.g., \code{[colname_1] > 100 & [colname_2] < 50}). +#' rows in `columns` being formatted. Can either be a vector of row captions +#' provided [c()], a vector of row indices, or a helper function focused on +#' selections. The select helper functions are: [starts_with()], +#' [ends_with()], [contains()], [matches()], [one_of()], and [everything()]. +#' We can also use expressions to filter down to the rows we need (e.g., +#' `[colname_1] > 100 & [colname_2] < 50`). #' @param decimals An option to specify the exact number of decimal places to -#' use. The default number of decimal places is \code{2}. +#' use. The default number of decimal places is `2`. #' @param drop_trailing_zeros A logical value that allows for removal of #' trailing zeros (those redundant zeros after the decimal mark). #' @param use_seps An option to use digit group separators. The type of digit -#' group separator is set by \code{sep_mark} and overridden if a locale ID is -#' provided to \code{locale}. This setting is \code{TRUE} by default. -#' @param scale_by A value to scale the input. The default is \code{1.0}. All -#' numeric values will be multiplied by this value first before undergoing -#' formatting. This value will be ignored if using any of the \code{suffixing} -#' options (i.e., where \code{suffixing} is not set to \code{FALSE}). +#' group separator is set by `sep_mark` and overridden if a locale ID is +#' provided to `locale`. This setting is `TRUE` by default. +#' @param scale_by A value to scale the input. The default is `1.0`. All numeric +#' values will be multiplied by this value first before undergoing formatting. +#' This value will be ignored if using any of the `suffixing` options (i.e., +#' where `suffixing` is not set to `FALSE`). #' @param suffixing An option to scale and apply suffixes to larger numbers -#' (e.g., \code{1924000} can be transformed to \code{1.92M}). This option can -#' accept a logical value, where \code{FALSE} (the default) will not perform -#' this transformation and \code{TRUE} will apply thousands (\code{K}), -#' millions (\code{M}), billions (\code{B}), and trillions (\code{T}) suffixes -#' after automatic value scaling. We can also specify which symbols to use for -#' each of the value ranges by using a character vector of the preferred -#' symbols to replace the defaults (e.g., \code{c("k", "Ml", "Bn", "Tr")}). -#' Including \code{NA} values in the vector will ensure that the particular -#' range will either not be included in the transformation (e.g, \code{c(NA, -#' "M", "B", "T")} won't modify numbers in the thousands range) or the range -#' will inherit a previous suffix (e.g., with \code{c("K", "M", NA, "T")}, all -#' numbers in the range of millions and billions will be in terms of -#' millions). Any use of \code{suffixing} (where not \code{FALSE}) means that -#' any value provided to \code{scale_by} will be ignored. +#' (e.g., `1924000` can be transformed to `1.92M`). This option can accept a +#' logical value, where `FALSE` (the default) will not perform this +#' transformation and `TRUE` will apply thousands (`K`), millions (`M`), +#' billions (`B`), and trillions (`T`) suffixes after automatic value scaling. +#' We can also specify which symbols to use for each of the value ranges by +#' using a character vector of the preferred symbols to replace the defaults +#' (e.g., `c("k", "Ml", "Bn", "Tr")`). Including `NA` values in the vector +#' will ensure that the particular range will either not be included in the +#' transformation (e.g, `c(NA, "M", "B", "T")` won't modify numbers in the +#' thousands range) or the range will inherit a previous suffix (e.g., with +#' `c("K", "M", NA, "T")`, all numbers in the range of millions and billions +#' will be in terms of millions). Any use of `suffixing` (where not `FALSE`) +#' means that any value provided to `scale_by` will be ignored. #' @param pattern A formatting pattern that allows for decoration of the -#' formatted value. The value itself is represented by \code{{x}} and all -#' other characters are taken to be string literals. +#' formatted value. The value itself is represented by `{x}` and all other +#' characters are taken to be string literals. #' @param sep_mark The mark to use as a separator between groups of digits -#' (e.g., using \code{sep_mark = ","} with \code{1000} would result in a -#' formatted value of \code{1,000}). -#' @param dec_mark The character to use as a decimal mark (e.g., using -#' \code{dec_mark = ","} with \code{0.152} would result in a formatted value -#' of \code{0,152}). +#' (e.g., using `sep_mark = ","` with `1000` would result in a formatted value +#' of `1,000`). +#' @param dec_mark The character to use as a decimal mark (e.g., using `dec_mark +#' = ","` with `0.152` would result in a formatted value of `0,152`). #' @param locale An optional locale ID that can be used for formatting the value -#' according the locale's rules. Examples include \code{"en_US"} for English -#' (United States) and \code{"fr_FR"} for French (France). The use of a valid -#' locale ID will override any values provided in \code{sep_mark} and -#' \code{dec_mark}. We can use the \code{\link{info_locales}()} function as a -#' useful reference for all of the locales that are supported. -#' @return An object of class \code{gt_tbl}. +#' according the locale's rules. Examples include `"en_US"` for English +#' (United States) and `"fr_FR"` for French (France). The use of a valid +#' locale ID will override any values provided in `sep_mark` and `dec_mark`. +#' We can use the [info_locales()] function as a useful reference for all of +#' the locales that are supported. +#' @return An object of class `gt_tbl`. #' @examples #' # Use `exibble` to create a gt table; #' # format the `num` column as numeric @@ -200,15 +193,14 @@ fmt_number <- function(data, #' formatting specific to the chosen locale #' } #' -#' Targeting of values is done through \code{columns} and additionally by -#' \code{rows} (if nothing is provided for \code{rows} then entire columns are -#' selected). A number of helper functions exist to make targeting more -#' effective. Conditional formatting is possible by providing a conditional -#' expression to the \code{rows} argument. See the Arguments section for more -#' information on this. +#' Targeting of values is done through `columns` and additionally by `rows` (if +#' nothing is provided for `rows` then entire columns are selected). A number of +#' helper functions exist to make targeting more effective. Conditional +#' formatting is possible by providing a conditional expression to the `rows` +#' argument. See the Arguments section for more information on this. #' #' @inheritParams fmt_number -#' @return An object of class \code{gt_tbl}. +#' @return An object of class `gt_tbl`. #' @examples #' # Use `exibble` to create a gt table; #' # format the `num` column as partially @@ -332,7 +324,7 @@ fmt_scientific <- function(data, #' #' @inheritParams fmt_number #' @inheritParams fmt_currency -#' @return An object of class \code{gt_tbl}. +#' @return An object of class `gt_tbl`. #' @noRd fmt_symbol <- function(data, columns, @@ -438,9 +430,9 @@ fmt_symbol <- function(data, #' #' With numeric values in a \pkg{gt} table, we can perform percentage-based #' formatting. It is assumed the input numeric values are in a fractional format -#' since the numbers will be automatically multiplied by \code{100} before -#' decorating with a percent sign. For more control over percentage formatting, -#' we can use the following options: +#' since the numbers will be automatically multiplied by `100` before decorating +#' with a percent sign. For more control over percentage formatting, we can use +#' the following options: #' \itemize{ #' \item percent sign placement: the percent sign can be placed after or #' before the values and a space can be inserted between the symbol and the @@ -455,19 +447,18 @@ fmt_symbol <- function(data, #' formatting specific to the chosen locale #' } #' -#' Targeting of values is done through \code{columns} and additionally by -#' \code{rows} (if nothing is provided for \code{rows} then entire columns are -#' selected). A number of helper functions exist to make targeting more -#' effective. Conditional formatting is possible by providing a conditional -#' expression to the \code{rows} argument. See the Arguments section for more -#' information on this. +#' Targeting of values is done through `columns` and additionally by `rows` (if +#' nothing is provided for `rows` then entire columns are selected). A number of +#' helper functions exist to make targeting more effective. Conditional +#' formatting is possible by providing a conditional expression to the `rows` +#' argument. See the Arguments section for more information on this. #' #' @inheritParams fmt_number #' @param incl_space An option for whether to include a space between the value #' and the percent sign. The default is to not introduce a space character. #' @param placement The placement of the percent sign. This can be either be -#' \code{right} (the default) or \code{left}. -#' @return an object of class \code{gt_tbl}. +#' `right` (the default) or `left`. +#' @return an object of class `gt_tbl`. #' @examples #' # Use `exibble` to create a gt table; #' # format the `num` column to have @@ -554,38 +545,35 @@ fmt_percent <- function(data, #' currency formatting specific to the chosen locale #' } #' -#' We can use the \code{\link{info_currencies}()} function for a useful -#' reference on all of the possible inputs to \code{currency}. +#' We can use the [info_currencies()] function for a useful reference on all of +#' the possible inputs to the `currency` argument. #' -#' Targeting of values is done through \code{columns} and additionally by -#' \code{rows} (if nothing is provided for \code{rows} then entire columns are -#' selected). A number of helper functions exist to make targeting more -#' effective. Conditional formatting is possible by providing a conditional -#' expression to the \code{rows} argument. See the Arguments section for more -#' information on this. +#' Targeting of values is done through `columns` and additionally by `rows` (if +#' nothing is provided for `rows` then entire columns are selected). A number of +#' helper functions exist to make targeting more effective. Conditional +#' formatting is possible by providing a conditional expression to the `rows` +#' argument. See the Arguments section for more information on this. #' #' @inheritParams fmt_number #' @param currency The currency to use for the numeric value. This input can be -#' supplied as a 3-letter currency code (e.g., \code{"USD"} for U.S. Dollars, -#' \code{"EUR"} for the Euro currency). Use \code{\link{info_currencies}()} to -#' get an information table with all of the valid currency codes and examples -#' of each. Alternatively, we can provide a common currency name (e.g., -#' \code{"dollar"}, \code{"pound"}, \code{"yen"}, etc.) to simplify the -#' process. Use \code{\link{info_currencies}()} with the \code{type == -#' "symbol"} option to view an information table with all of the supported -#' currency symbol names along with examples. If nothing is provided then -#' \code{"USD"} will be used. +#' supplied as a 3-letter currency code (e.g., `"USD"` for U.S. Dollars, +#' `"EUR"` for the Euro currency). Use [info_currencies()] to get an +#' information table with all of the valid currency codes and examples of +#' each. Alternatively, we can provide a common currency name (e.g., +#' `"dollar"`, `"pound"`, `"yen"`, etc.) to simplify the process. Use +#' [info_currencies()] with the `type == "symbol"` option to view an +#' information table with all of the supported currency symbol names along +#' with examples. If nothing is provided then `"USD"` will be used. #' @param use_subunits An option for whether the subunits portion of a currency #' value should be displayed. #' @param accounting An option to use accounting style for currency values. With -#' \code{FALSE} (the default), negative values will be shown with a negative -#' sign. Using \code{accounting = TRUE} will put negative values in -#' parentheses. +#' `FALSE` (the default), negative values will be shown with a minus sign. +#' Using `accounting = TRUE` will put negative values in parentheses. #' @param placement The placement of the currency symbol. This can be either be -#' \code{left} (the default) or \code{right}. +#' `left` (the default) or `right`. #' @param incl_space An option for whether to include a space between the value #' and the currency symbol. The default is to not introduce a space character. -#' @return An object of class \code{gt_tbl}. +#' @return An object of class `gt_tbl`. #' @examples #' # Use `exibble` to create a gt table; #' # format the `currency` column to have @@ -672,49 +660,46 @@ fmt_currency <- function(data, #' Format values as dates #' -#' Format input date values that are either of the \code{Date} type, or, are +#' Format input date values that are either of the `Date` type, or, are #' character-based and expressed according to the ISO 8601 date format -#' (\code{YYYY-MM-DD}). Once the appropriate data cells are targeted with -#' \code{columns} (and, optionally, \code{rows}), we can simply apply a preset -#' date style (see table in \code{\link{info_date_style}()} for info) to format -#' the dates. +#' (`YYYY-MM-DD`). Once the appropriate data cells are targeted with `columns` +#' (and, optionally, `rows`), we can simply apply a preset date style (see table +#' in [info_date_style()] for info) to format the dates. #' #' The following date styles are available for simpler formatting of ISO dates -#' (all using the input date of \code{2000-02-29} in the example output dates): +#' (all using the input date of `2000-02-29` in the example output dates): #' #' \enumerate{ -#' \item iso: \code{2000-02-29} -#' \item wday_month_day_year: \code{Tuesday, February 29, 2000} -#' \item wd_m_day_year: \code{Tue, Feb 29, 2000} -#' \item wday_day_month_year: \code{Tuesday 29 February 2000} -#' \item month_day_year: \code{February 29, 2000} -#' \item m_day_year: \code{Feb 29, 2000} -#' \item day_m_year: \code{29 Feb 2000} -#' \item day_month_year: \code{29 February 2000} -#' \item day_month: \code{29 February} -#' \item year: \code{2000} -#' \item month: \code{February} -#' \item day: \code{29} -#' \item year.mn.day: \code{2000/02/29} -#' \item y.mn.day: \code{0/02/29} +#' \item iso: `2000-02-29` +#' \item wday_month_day_year: `Tuesday, February 29, 2000` +#' \item wd_m_day_year: `Tue, Feb 29, 2000` +#' \item wday_day_month_year: `Tuesday 29 February 2000` +#' \item month_day_year: `February 29, 2000` +#' \item m_day_year: `Feb 29, 2000` +#' \item day_m_year: `29 Feb 2000` +#' \item day_month_year: `29 February 2000` +#' \item day_month: `29 February` +#' \item year: `2000` +#' \item month: `February` +#' \item day: `29` +#' \item year.mn.day: `2000/02/29` +#' \item y.mn.day: `0/02/29` #' } #' -#' We can use the \code{\link{info_date_style}()} function for a useful -#' reference on all of the possible inputs to \code{date_style}. +#' We can use the [info_date_style()] function for a useful reference on all of +#' the possible inputs to `date_style`. #' -#' Targeting of values is done through \code{columns} and additionally by -#' \code{rows} (if nothing is provided for \code{rows} then entire columns are -#' selected). A number of helper functions exist to make targeting more -#' effective. Conditional formatting is possible by providing a conditional -#' expression to the \code{rows} argument. See the Arguments section for more -#' information on this. +#' Targeting of values is done through `columns` and additionally by `rows` (if +#' nothing is provided for `rows` then entire columns are selected). A number of +#' helper functions exist to make targeting more effective. Conditional +#' formatting is possible by providing a conditional expression to the `rows` +#' argument. See the Arguments section for more information on this. #' #' @inheritParams fmt_number -#' @param date_style The date style to use. Supply a number (from \code{1} to -#' \code{14}) that corresponds to the preferred date style. Use -#' \code{\link{info_date_style}()} to see the different numbered and named date -#' presets. -#' @return An object of class \code{gt_tbl}. +#' @param date_style The date style to use. Supply a number (from `1` to `14`) +#' that corresponds to the preferred date style. Use [info_date_style()] to +#' see the different numbered and named date presets. +#' @return An object of class `gt_tbl`. #' @examples #' # Use `exibble` to create a gt table; #' # keep only the `date` and `time` columns; @@ -798,38 +783,36 @@ fmt_date <- function(data, #' Format values as times #' #' Format input time values that are character-based and expressed according to -#' the ISO 8601 time format (\code{HH:MM:SS}). Once the appropriate data cells -#' are targeted with \code{columns} (and, optionally, \code{rows}), we can -#' simply apply a preset time style (see table in -#' \code{\link{info_time_style}()} for info) to format the times. +#' the ISO 8601 time format (`HH:MM:SS`). Once the appropriate data cells are +#' targeted with `columns` (and, optionally, `rows`), we can simply apply a +#' preset time style (see table in [info_time_style()] for info) to format the +#' times. #' #' The following time styles are available for simpler formatting of ISO times -#' (all using the input time of \code{14:35:00} in the example output times): +#' (all using the input time of `14:35:00` in the example output times): #' #' \enumerate{ -#' \item hms: \code{14:35:00} -#' \item hm: \code{14:35} -#' \item hms_p: \code{2:35:00 PM} -#' \item hm_p: \code{2:35 PM} -#' \item h_p: \code{2 PM} +#' \item hms: `14:35:00` +#' \item hm: `14:35` +#' \item hms_p: `2:35:00 PM` +#' \item hm_p: `2:35 PM` +#' \item h_p: `2 PM` #' } #' -#' We can use the \code{\link{info_time_style}()} function for a useful -#' reference on all of the possible inputs to \code{time_style}. +#' We can use the [info_time_style()] function for a useful reference on all of +#' the possible inputs to `time_style`. #' -#' Targeting of values is done through \code{columns} and additionally by -#' \code{rows} (if nothing is provided for \code{rows} then entire columns are -#' selected). A number of helper functions exist to make targeting more -#' effective. Conditional formatting is possible by providing a conditional -#' expression to the \code{rows} argument. See the Arguments section for more -#' information on this. +#' Targeting of values is done through `columns` and additionally by `rows` (if +#' nothing is provided for `rows` then entire columns are selected). A number of +#' helper functions exist to make targeting more effective. Conditional +#' formatting is possible by providing a conditional expression to the `rows` +#' argument. See the Arguments section for more information on this. #' #' @inheritParams fmt_number -#' @param time_style The time style to use. Supply a number (from \code{1} to -#' \code{5}) that corresponds to the preferred time style. Use -#' \code{\link{info_time_style}()} to see the different numbered and named time -#' presets. -#' @return An object of class \code{gt_tbl}. +#' @param time_style The time style to use. Supply a number (from `1` to `5`) +#' that corresponds to the preferred time style. Use [info_time_style()] to +#' see the different numbered and named time presets. +#' @return An object of class `gt_tbl`. #' @examples #' # Use `exibble` to create a gt table; #' # keep only the `date` and `time` columns; @@ -907,60 +890,58 @@ fmt_time <- function(data, #' Format values as date-times #' #' Format input date-time values that are character-based and expressed -#' according to the ISO 8601 date-time format (\code{YYYY-MM-DD HH:MM:SS}). Once -#' the appropriate data cells are targeted with \code{columns} (and, optionally, -#' \code{rows}), we can simply apply preset date and time styles (see tables in -#' \code{\link{info_date_style}()} and \code{\link{info_time_style}()} for more -#' info) to format the data-time values. +#' according to the ISO 8601 date-time format (`YYYY-MM-DD HH:MM:SS`). Once the +#' appropriate data cells are targeted with `columns` (and, optionally, `rows`), +#' we can simply apply preset date and time styles (see tables in +#' [info_date_style()] and [info_time_style()] for more info) to format the +#' data-time values. #' #' The following date styles are available for simpler formatting of the date -#' portion (all using the input date of \code{2000-02-29} in the example output +#' portion (all using the input date of `2000-02-29` in the example output #' dates): #' #' \enumerate{ -#' \item iso: \code{2000-02-29} -#' \item wday_month_day_year: \code{Tuesday, February 29, 2000} -#' \item wd_m_day_year: \code{Tue, Feb 29, 2000} -#' \item wday_day_month_year: \code{Tuesday 29 February 2000} -#' \item month_day_year: \code{February 29, 2000} -#' \item m_day_year: \code{Feb 29, 2000} -#' \item day_m_year: \code{29 Feb 2000} -#' \item day_month_year: \code{29 February 2000} -#' \item day_month: \code{29 February} -#' \item year: \code{2000} -#' \item month: \code{February} -#' \item day: \code{29} -#' \item year.mn.day: \code{2000/02/29} -#' \item y.mn.day: \code{0/02/29} +#' \item iso: `2000-02-29` +#' \item wday_month_day_year: `Tuesday, February 29, 2000` +#' \item wd_m_day_year: `Tue, Feb 29, 2000` +#' \item wday_day_month_year: `Tuesday 29 February 2000` +#' \item month_day_year: `February 29, 2000` +#' \item m_day_year: `Feb 29, 2000` +#' \item day_m_year: `29 Feb 2000` +#' \item day_month_year: `29 February 2000` +#' \item day_month: `29 February` +#' \item year: `2000` +#' \item month: `February` +#' \item day: `29` +#' \item year.mn.day: `2000/02/29` +#' \item y.mn.day: `0/02/29` #' } #' #' The following time styles are available for simpler formatting of the time -#' portion (all using the input time of \code{14:35:00} in the example output -#' times): +#' portion (all using the input time of `14:35:00` in the example output times): #' #' \enumerate{ -#' \item hms: \code{14:35:00} -#' \item hm: \code{14:35} -#' \item hms_p: \code{2:35:00 PM} -#' \item hm_p: \code{2:35 PM} -#' \item h_p: \code{2 PM} +#' \item hms: `14:35:00` +#' \item hm: `14:35` +#' \item hms_p: `2:35:00 PM` +#' \item hm_p: `2:35 PM` +#' \item h_p: `2 PM` #' } #' -#' We can use the \code{\link{info_date_style}()} and -#' \code{\link{info_time_style}()} functions as useful references for all of the -#' possible inputs to \code{date_style} and \code{time_style}. +#' We can use the [info_date_style()] and [info_time_style()] functions as +#' useful references for all of the possible inputs to `date_style` and +#' `time_style`. #' -#' Targeting of values is done through \code{columns} and additionally by -#' \code{rows} (if nothing is provided for \code{rows} then entire columns are -#' selected). A number of helper functions exist to make targeting more -#' effective. Conditional formatting is possible by providing a conditional -#' expression to the \code{rows} argument. See the Arguments section for more -#' information on this. +#' Targeting of values is done through `columns` and additionally by `rows` (if +#' nothing is provided for `rows` then entire columns are selected). A number of +#' helper functions exist to make targeting more effective. Conditional +#' formatting is possible by providing a conditional expression to the `rows` +#' argument. See the Arguments section for more information on this. #' #' @inheritParams fmt_number #' @inheritParams fmt_date #' @inheritParams fmt_time -#' @return An object of class \code{gt_tbl}. +#' @return An object of class `gt_tbl`. #' @examples #' # Use `exibble` to create a gt table; #' # keep only the `datetime` column; @@ -1023,17 +1004,16 @@ fmt_datetime <- function(data, #' Format Markdown text #' #' Any Markdown-formatted text in the incoming cells will be transformed to the -#' appropriate output type during render when using \code{fmt_markdown()}. +#' appropriate output type during render when using `fmt_markdown()`. #' -#' Targeting of values is done through \code{columns} and additionally by -#' \code{rows} (if nothing is provided for \code{rows} then entire columns are -#' selected). A number of helper functions exist to make targeting more -#' effective. Conditional formatting is possible by providing a conditional -#' expression to the \code{rows} argument. See the Arguments section for more -#' information on this. +#' Targeting of values is done through `columns` and additionally by `rows` (if +#' nothing is provided for `rows` then entire columns are selected). A number of +#' helper functions exist to make targeting more effective. Conditional +#' formatting is possible by providing a conditional expression to the `rows` +#' argument. See the Arguments section for more information on this. #' #' @inheritParams fmt_number -#' @return An object of class \code{gt_tbl}. +#' @return An object of class `gt_tbl`. #' @examples #' # Create a few Markdown-based #' # text snippets @@ -1119,29 +1099,26 @@ fmt_markdown <- function(data, #' Format by simply passing data through #' #' Format by passing data through no other transformation other than: (1) -#' coercing to \code{character} (as all the \code{fmt_*()} functions do), and -#' (2) applying prefixed or suffixed text via the \code{pattern} argument (the -#' default is to apply nothing). All of this is useful when don't want to modify -#' the input data other than to decorate it within a pattern. Also, this -#' function is useful when used as a \code{formatter} function in the -#' \code{summary_rows} function, where the output may be text or useful as is -#' (that function requires a formatter function). -#' -#' Targeting of values is done through \code{columns} and additionally by -#' \code{rows} (if nothing is provided for \code{rows} then entire columns are -#' selected). A number of helper functions exist to make targeting more -#' effective. Conditional formatting is possible by providing a conditional -#' expression to the \code{rows} argument. See the Arguments section for more -#' information on this. +#' coercing to `character` (as all the `fmt_*()` functions do), and (2) applying +#' text via the `pattern` argument (the default is to apply nothing). All of +#' this is useful when don't want to modify the input data other than to +#' decorate it within a pattern. Also, this function is useful when used as the +#' `formatter` function in the [summary_rows()] function, where the output may +#' be text or useful as is. +#' +#' Targeting of values is done through `columns` and additionally by `rows` (if +#' nothing is provided for `rows` then entire columns are selected). A number of +#' helper functions exist to make targeting more effective. Conditional +#' formatting is possible by providing a conditional expression to the `rows` +#' argument. See the Arguments section for more information on this. #' #' @inheritParams fmt_number #' @param escape An option to escape text according to the final output format #' of the table. For example, if a LaTeX table is to be generated then LaTeX #' escaping would be performed during rendering. By default this is set to -#' \code{TRUE} and setting to \code{FALSE} is useful in the case where -#' LaTeX-formatted text should be passed through to the output LaTeX table -#' unchanged. -#' @return An object of class \code{gt_tbl}. +#' `TRUE` and setting to `FALSE` is useful in the case where LaTeX-formatted +#' text should be passed through to the output LaTeX table unchanged. +#' @return An object of class `gt_tbl`. #' @examples #' # Use `exibble` to create a gt table; #' # keep only the `char` column; @@ -1238,22 +1215,21 @@ fmt_passthrough <- function(data, #' Format missing values #' -#' Wherever there is missing data (i.e., \code{NA} values) a customizable mark -#' may present better than the standard \code{NA} text that would otherwise -#' appear. The \code{fmt_missing()} function allows for this replacement through -#' its \code{missing_text} argument (where an em dash serves as the default). +#' Wherever there is missing data (i.e., `NA` values) a customizable mark may +#' present better than the standard `NA` text that would otherwise appear. The +#' `fmt_missing()` function allows for this replacement through its +#' `missing_text` argument (where an em dash serves as the default). #' -#' Targeting of values is done through \code{columns} and additionally by -#' \code{rows} (if nothing is provided for \code{rows} then entire columns are -#' selected). A number of helper functions exist to make targeting more -#' effective. Conditional formatting is possible by providing a conditional -#' expression to the \code{rows} argument. See the Arguments section for more -#' information on this. +#' Targeting of values is done through `columns` and additionally by `rows` (if +#' nothing is provided for `rows` then entire columns are selected). A number of +#' helper functions exist to make targeting more effective. Conditional +#' formatting is possible by providing a conditional expression to the `rows` +#' argument. See the Arguments section for more information on this. #' #' @inheritParams fmt_number -#' @param missing_text The text to be used in place of \code{NA} values in the -#' rendered table. -#' @return An object of class \code{gt_tbl}. +#' @param missing_text The text to be used in place of `NA` values in the +#' rendered table. +#' @return An object of class `gt_tbl`. #' @examples #' # Use `exibble` to create a gt table; #' # NA values in different columns will @@ -1321,35 +1297,34 @@ fmt_missing <- function(data, #' Set a column format with a formatter function #' -#' The \code{fmt()} function provides greater control in formatting raw data -#' values than any of the specialized \code{fmt_*()} functions that are -#' available in \pkg{gt}. Along with the \code{columns} and \code{rows} -#' arguments that provide some precision in targeting data cells, the \code{fns} -#' argument allows you to define one or more functions for manipulating the raw -#' data. -#' -#' If providing a single function to \code{fns}, the recommended format is in -#' the form: \code{fns = function(x) ...}. This single function will format the -#' targeted data cells the same way regardless of the output format (e.g., HTML, -#' LaTeX, RTF). -#' -#' If you require formatting of \code{x} that depends on the output format, a -#' list of functions can be provided for the \code{html}, \code{latex}, and -#' \code{default} contexts. This can be in the form of \code{fns = list(html = -#' function(x) ..., latex = function(x) ..., default = function(x) ...)}. In -#' this multiple-function case, we recommended including the \code{default} -#' function as a fallback if all contexts aren't provided. -#' -#' As with all of the \code{fmt_*()} functions, targeting of values is done -#' through \code{columns} and additionally by \code{rows} (if nothing is -#' provided for \code{rows} then entire columns are selected). A number of -#' helper functions exist to make targeting more effective. Conditional -#' formatting is possible by providing a conditional expression to the -#' \code{rows} argument. See the Arguments section for more information on this. +#' The `fmt()` function provides greater control in formatting raw data values +#' than any of the specialized `fmt_*()` functions that are available in +#' \pkg{gt}. Along with the `columns` and `rows` arguments that provide some +#' precision in targeting data cells, the `fns` argument allows you to define +#' one or more functions for manipulating the raw data. +#' +#' If providing a single function to `fns`, the recommended format is in the +#' form: `fns = function(x) ...`. This single function will format the targeted +#' data cells the same way regardless of the output format (e.g., HTML, LaTeX, +#' RTF). +#' +#' If you require formatting of `x` that depends on the output format, a list of +#' functions can be provided for the `html`, `latex`, and `default` contexts. +#' This can be in the form of `fns = list(html = function(x) ..., latex = +#' function(x) ..., default = function(x) ...)`. In this multiple-function case, +#' we recommended including the `default` function as a fallback if all contexts +#' aren't provided. +#' +#' As with all of the `fmt_*()` functions, targeting of values is done through +#' `columns` and additionally by `rows` (if nothing is provided for `rows` then +#' entire columns are selected). A number of helper functions exist to make +#' targeting more effective. Conditional formatting is possible by providing a +#' conditional expression to the `rows` argument. See the Arguments section for +#' more information on this. #' #' @inheritParams fmt_number #' @param fns Either a single formatting function or a named list of functions. -#' @return An object of class \code{gt_tbl}. +#' @return An object of class `gt_tbl`. #' @examples #' # Use `exibble` to create a gt table; #' # format the numeric values in the `num` diff --git a/R/gt.R b/R/gt.R index 177b86c44f..990bea060e 100644 --- a/R/gt.R +++ b/R/gt.R @@ -1,37 +1,36 @@ #' Create a \pkg{gt} table object #' -#' The \code{gt()} function creates a \pkg{gt} table object when provided with -#' table data. Using this function is the first step in a typical \pkg{gt} -#' workflow. Once we have the \pkg{gt} table object, we can perform styling +#' The `gt()` function creates a \pkg{gt} table object when provided with table +#' data. Using this function is the first step in a typical \pkg{gt} workflow. +#' Once we have the \pkg{gt} table object, we can perform styling #' transformations before rendering to a display table of various formats (e.g., #' HTML, LaTeX, RTF). #' #' There are a few data ingest options we can consider at this stage. We can -#' choose to create a table stub with rowname captions using the -#' \code{rowname_col} argument. Further to this, stub row groups can be created -#' with the \code{groupname_col}. Both arguments take the name of a column in -#' the input table data. Typically, the data in the \code{groupname_col} will -#' consist of categories of data in a table and the data in the -#' \code{rowname_col} are unique labels (perhaps unique across the entire table -#' or unique within groups). +#' choose to create a table stub with rowname captions using the `rowname_col` +#' argument. Further to this, stub row groups can be created with the +#' `groupname_col`. Both arguments take the name of a column in the input table +#' data. Typically, the data in the `groupname_col` will consist of categories +#' of data in a table and the data in the `rowname_col` are unique labels +#' (perhaps unique across the entire table or unique within groups). #' -#' Row groups can also be created by passing a \code{grouped_df} to \code{gt()} -#' by using the \code{dplyr::group_by()} function on the table data. In this -#' way, two or more columns of categorical data can be used to make row groups. -#' The \code{stub_group.sep} argument allows for control in how the row group -#' label will appear in the display table. +#' Row groups can also be created by passing a `grouped_df` to `gt()` by using +#' the `dplyr::group_by()` function on the table data. In this way, two or more +#' columns of categorical data can be used to make row groups. The +#' `stub_group.sep` argument allows for control in how the row group label will +#' appear in the display table. #' -#' @param data a \code{data.frame} object or a tibble. -#' @param rowname_col the column name in the input \code{data} table to use as -#' row captions to be placed in the display table stub. -#' @param groupname_col the column name in the input \code{data} table to use as +#' @param data A `data.frame` object or a tibble. +#' @param rowname_col The column name in the input `data` table to use as row +#' captions to be placed in the display table stub. +#' @param groupname_col The column name in the input `data` table to use as #' group labels for generation of stub row groups. -#' @param rownames_to_stub an option to take rownames from the input \code{data} +#' @param rownames_to_stub An option to take rownames from the input `data` #' table as row captions in the display table stub. -#' @param stub_group.sep the separator to use between consecutive group names (a -#' possibility when providing \code{data} as a \code{grouped_df} with multiple -#' groups) in the displayed stub row group label. -#' @return an object of class \code{gt_tbl}. +#' @param stub_group.sep The separator to use between consecutive group names (a +#' possibility when providing `data` as a `grouped_df` with multiple groups) +#' in the displayed stub row group label. +#' @return An object of class `gt_tbl`. #' @examples #' # Create a table object using the #' # `exibble` dataset; use the `row` diff --git a/R/gt_preview.R b/R/gt_preview.R index 89562be090..fc2b8de09c 100644 --- a/R/gt_preview.R +++ b/R/gt_preview.R @@ -1,30 +1,28 @@ #' Preview a \pkg{gt} table object #' #' Sometimes you may want to see just a small portion of your input data. We can -#' use \code{gt_preview()} in place of \code{\link{gt}()} to get the first x -#' rows of data and the last y rows of data (which can be set by the -#' \code{top_n} and \code{bottom_n} arguments). It's not advised to use -#' additional \pkg{gt} API functions to further modify the output of -#' \code{gt_preview()}. Furthermore, you cannot pass a \pkg{gt} object to -#' \code{gt_preview()}. +#' use `gt_preview()` in place of [gt()] to get the first x rows of data and the +#' last y rows of data (which can be set by the `top_n` and `bottom_n` +#' arguments). It's not advised to use additional \pkg{gt} API functions to +#' further modify the output of `gt_preview()`. Furthermore, you cannot pass a +#' \pkg{gt} object to `gt_preview()`. #' -#' Any grouped data or magic columns such as \code{rowname} and \code{groupname} -#' will be ignored by \code{gt_preview()} and, as such, one cannot add a stub or -#' group rows in the output table. By default, the output table will include row -#' numbers in a stub (including a range of row numbers for the omitted rows). -#' This row numbering option can be deactivated by setting \code{incl_rownums} -#' to \code{FALSE}. +#' Any grouped data or magic columns such as `rowname` and `groupname` will be +#' ignored by `gt_preview()` and, as such, one cannot add a stub or group rows +#' in the output table. By default, the output table will include row numbers in +#' a stub (including a range of row numbers for the omitted rows). This row +#' numbering option can be deactivated by setting `incl_rownums` to `FALSE`. #' -#' @param data a \code{data.frame} object or a tibble. -#' @param top_n this value will be used as the number of rows from the top of -#' the table to display. The default, \code{5}, will show the first five rows -#' of the table. -#' @param bottom_n the value will be used as the number of rows from the bottom -#' of the table to display. The default, \code{1}, will show the final row of +#' @param data A `data.frame` object or a tibble. +#' @param top_n This value will be used as the number of rows from the top of +#' the table to display. The default, `5`, will show the first five rows of #' the table. -#' @param incl_rownums an option to include the row numbers for \code{data} in -#' the table stub. By default, this is \code{TRUE}. -#' @return an object of class \code{gt_tbl}. +#' @param bottom_n The value will be used as the number of rows from the bottom +#' of the table to display. The default, `1`, will show the final row of the +#' table. +#' @param incl_rownums An option to include the row numbers for `data` in the +#' table stub. By default, this is `TRUE`. +#' @return An object of class `gt_tbl`. #' @examples #' # Use `gtcars` to create a gt table #' # preview (with only a few of its diff --git a/R/gtsave.R b/R/gtsave.R index 0272c06271..2b065ab877 100644 --- a/R/gtsave.R +++ b/R/gtsave.R @@ -1,27 +1,26 @@ #' Save a \pkg{gt} table as a file #' -#' The \code{gtsave()} function makes it easy to save a \pkg{gt} table to a -#' file. The function guesses the file type by the extension provided in the -#' output filename, producing either an HTML, LaTeX, or RTF file. +#' The `gtsave()` function makes it easy to save a \pkg{gt} table to a file. The +#' function guesses the file type by the extension provided in the output +#' filename, producing either an HTML, LaTeX, or RTF file. #' -#' Output filenames with either the \code{.html} or \code{.htm} extensions will -#' produce an HTML document. In this case, we can pass a \code{TRUE} or -#' \code{FALSE} value to the \code{inline_css} option to obtain an HTML document -#' with inlined CSS styles (the default is \code{FALSE}). More details on CSS -#' inlining are available at \code{\link{as_raw_html}()}. +#' Output filenames with either the `.html` or `.htm` extensions will produce an +#' HTML document. In this case, we can pass a `TRUE` or `FALSE` value to the +#' `inline_css` option to obtain an HTML document with inlined CSS styles (the +#' default is `FALSE`). More details on CSS inlining are available at +#' [as_raw_html()]. #' -#' If the output filename is either of \code{.tex}, \code{.ltx}, or \code{.rnw}, -#' a LaTeX document is produced. An output filename of \code{.rtf} will generate -#' an RTF document. The LaTeX and RTF saving function don't have any options to -#' pass to \code{...}. +#' If the output filename is either of `.tex`, `.ltx`, or `.rnw`, a LaTeX +#' document is produced. An output filename of `.rtf` will generate an RTF +#' document. The LaTeX and RTF saving function don't have any options to pass to +#' `...`. #' -#' @param data a table object that is created using the \code{\link{gt}()} -#' function. -#' @param filename the file name to create on disk. Ensure that an extension -#' compatible with the output types is provided (\code{.html}, \code{.tex}, -#' \code{.ltx}, \code{.rtf}). If a custom save function is provided then the -#' file extension is disregarded. -#' @param ... all other options passed to the appropriate internal saving +#' @param data A table object that is created using the [gt()] function. +#' @param filename The file name to create on disk. Ensure that an extension +#' compatible with the output types is provided (`.html`, `.tex`, `.ltx`, +#' `.rtf`). If a custom save function is provided then the file extension is +#' disregarded. +#' @param ... All other options passed to the appropriate internal saving #' function. #' @export gtsave <- function(data, filename, ...) { @@ -58,7 +57,8 @@ gtsave <- function(data, filename, ...) { ) } -# Saving function for an HTML file +#' Saving function for an HTML file +#' #' @importFrom htmltools as.tags save_html HTML #' @noRd gt_save_html <- function(data, filename, ..., inline_css = FALSE) { @@ -78,7 +78,9 @@ gt_save_html <- function(data, filename, ..., inline_css = FALSE) { } } -# Saving function for a LaTeX file +#' Saving function for a LaTeX file +#' +#' @noRd gt_save_latex <- function(data, filename, ...) { data %>% @@ -86,7 +88,9 @@ gt_save_latex <- function(data, filename, ...) { writeLines(con = filename) } -# Saving function for an RTF file +#' Saving function for an RTF file +#' +#' @noRd gt_save_rtf <- function(data, filename, ...) { data %>% @@ -94,6 +98,8 @@ gt_save_rtf <- function(data, filename, ...) { writeLines(con = filename) } +#' Get the file extension from an input filename +#' #' @importFrom tools file_ext #' @noRd gtsave_file_ext <- function(filename) { diff --git a/R/helpers.R b/R/helpers.R index b6fbfbf271..4e08cf773a 100644 --- a/R/helpers.R +++ b/R/helpers.R @@ -2,42 +2,41 @@ #' #' These helper functions are used to target individual cells in different #' locations (e.g., the stub, the column labels, the title, etc.). They can be -#' used in any of these functions (which all have a \code{locations} argument): -#' \code{\link{tab_footnote}()}, \code{\link{tab_style}()}, and -#' \code{\link{text_transform}()} Furthermore, multiple locations can be -#' targeted by enclosing several \code{cells_*()} helper functions in a list. +#' used in any of these functions (which all have a `locations` argument): +#' [tab_footnote()], [tab_style()], and [text_transform()] Furthermore, multiple +#' locations can be targeted by enclosing several `cells_*()` helper functions +#' in a list. #' #' The following helper functions can be used to target cells (roughly in order #' from the top to the bottom of a table): #' #' \itemize{ #' -#' \item \code{cells_title()}: targets the table title or the table subtitle -#' depending on the value given to the \code{groups} argument (\code{"title"} or -#' \code{"subtitle"}). +#' \item `cells_title()`: targets the table title or the table subtitle +#' depending on the value given to the `groups` argument (`"title"` or +#' `"subtitle"`). #' -#' \item \code{cells_column_labels()}: targets labels in the column labels (the -#' \code{columns} argument) or the spanner column labels (the \code{groups} +#' \item `cells_column_labels()`: targets labels in the column labels (the +#' `columns` argument) or the spanner column labels (the `groups` #' argument) in the table's column labels part. #' -#' \item \code{cells_group()}: targets the row group labels in any available -#' row groups using the \code{groups} argument. +#' \item `cells_group()`: targets the row group labels in any available +#' row groups using the `groups` argument. #' -#' \item \code{cells_stub()}: targets row labels in the table stub using the -#' \code{rows} argument. +#' \item `cells_stub()`: targets row labels in the table stub using the +#' `rows` argument. #' -#' \item \code{cells_data()}: targets data cells in the table body using -#' intersections of \code{columns} and \code{rows}. +#' \item `cells_data()`: targets data cells in the table body using +#' intersections of `columns` and `rows`. #' -#' \item \code{cells_summary()}: targets summary cells in the table body using -#' the \code{groups} argument and intersections of \code{columns} and -#' \code{rows}. +#' \item `cells_summary()`: targets summary cells in the table body using +#' the `groups` argument and intersections of `columns` and +#' `rows`. #' } #' -#' @param columns,rows,groups either a vector of names, a vector of -#' indices, values provided by \code{\link{vars}()}, values provided by -#' \code{c()}, or a select helper function (see Details for information on -#' these functions). +#' @param columns,rows,groups Either a vector of names, a vector of indices, +#' values provided by [vars()], values provided by `c()`, or a select helper +#' function (see Details for information on these functions). #' #' @examples #' # Use `sp500` to create a gt table; add @@ -221,7 +220,7 @@ #' \if{html}{\figure{man_location_cells_6.svg}{options: width=100\%}} #' #' @name location_cells -#' @return a list object of class \code{location_cells}. +#' @return a list object of class `location_cells`. NULL #' @rdname location_cells @@ -389,10 +388,11 @@ cells_grand_summary <- function(columns = NULL, } #' Interpret input text as Markdown-formatted text -#' @param text the text that is understood to contain Markdown formatting. -#' @return a character object that is tagged for a Markdown-to-HTML +#' +#' @param text The text that is understood to contain Markdown formatting. +#' @return A character object that is tagged for a Markdown-to-HTML #' transformation. -#' @return a character object of class \code{from_markdown}. +#' @return a character object of class `from_markdown`. #' @examples #' # Use `exibble` to create a gt table; #' # when adding a title, use the `md()` @@ -417,11 +417,11 @@ md <- function(text) { } #' Interpret input text as HTML-formatted text -#' @param text,... the text that is understood to be HTML text, which is to be +#' @param text,... The text that is understood to be HTML text, which is to be #' preserved. -#' @return a character object that is tagged as an HTML fragment that is not to +#' @return A character object that is tagged as an HTML fragment that is not to #' be sanitized. -#' @return a character object of class \code{html}. +#' @return a character object of class `html`. #' @examples #' # Use `exibble` to create a gt table; #' # when adding a title, use the `html()` @@ -455,43 +455,40 @@ is.html <- function(x) { #' Helper for defining custom styles for table cells #' -#' This helper function is to be used with the \code{\link{tab_style}()} -#' function, which itself allows for the setting of custom styles to one or more -#' cells. We can also define several styles within a single call of -#' \code{cells_styles} and \code{\link{tab_style}()} will reliably apply those -#' styles to the targeted element. +#' This helper function is to be used with the [tab_style()] function, which +#' itself allows for the setting of custom styles to one or more cells. We can +#' also define several styles within a single call of `cells_styles` and +#' [tab_style()] will reliably apply those styles to the targeted element. #' -#' @param bkgd_color the background color of the cell. -#' @param text_color the text color. -#' @param text_font the font or collection of fonts (subsequent font names are) +#' @param bkgd_color The background color of the cell. +#' @param text_color The text color. +#' @param text_font The font or collection of fonts (subsequent font names are) #' used as fallbacks. -#' @param text_size the size of the font. Can be provided as a number that is -#' assumed to represent \code{px} values (or could be wrapped in the -#' \code{\link{px}()}) helper function. We can also use one of the following -#' absolute size keywords: \code{xx-small}, \code{x-small}, \code{small}, -#' \code{medium}, \code{large}, \code{x-large}, or \code{xx-large}. -#' @param text_style the text style. Can be one of either \code{"center"}, -#' \code{"normal"}, \code{"italic"}, or \code{"oblique"}. -#' @param text_weight the weight of the font. Can be a text-based keyword such -#' as \code{"normal"}, \code{"bold"}, \code{"lighter"}, \code{"bolder"}, or, a -#' numeric value between \code{1} and \code{1000}, inclusive. Note that only -#' variable fonts may support the numeric mapping of weight. -#' @param text_align the text alignment. Can be one of either \code{"center"}, -#' \code{"left"}, \code{"right"}, or \code{"justify"}. -#' @param text_stretch allows for text to either be condensed or expanded. We +#' @param text_size The size of the font. Can be provided as a number that is +#' assumed to represent `px` values (or could be wrapped in the [px()]) helper +#' function. We can also use one of the following absolute size keywords: +#' `xx-small`, `x-small`, `small`, `medium`, `large`, `x-large`, or +#' `xx-large`. +#' @param text_style The text style. Can be one of either `"center"`, +#' `"normal"`, `"italic"`, or `"oblique"`. +#' @param text_weight The weight of the font. Can be a text-based keyword such +#' as `"normal"`, `"bold"`, `"lighter"`, `"bolder"`, or, a numeric value +#' between `1` and `1000`, inclusive. Note that only variable fonts may +#' support the numeric mapping of weight. +#' @param text_align The text alignment. Can be one of either `"center"`, +#' `"left"`, `"right"`, or `"justify"`. +#' @param text_stretch Allows for text to either be condensed or expanded. We #' can use the following text-based keywords to describe the degree of -#' condensation/expansion: \code{ultra-condensed}, \code{extra-condensed}, -#' \code{condensed}, \code{semi-condensed}, \code{normal}, -#' \code{semi-expanded}, \code{expanded}, \code{extra-expanded}, and -#' \code{ultra-expanded}. Alternatively, we can supply percentage values from -#' \code{0\%} to \code{200\%}, inclusive. Negative percentage values are not -#' allowed. -#' @param text_indent the indentation of the text. -#' @param text_decorate allows for text decoration effect to be applied. Here, -#' we can use \code{"overline"}, \code{"line-through"}, or \code{"underline"}. -#' @param text_transform allows for the transformation of text. Options are -#' \code{"uppercase"}, \code{"lowercase"}, or \code{"capitalize"}. -#' @return a character vector containing formatted styles. +#' condensation/expansion: `ultra-condensed`, `extra-condensed`, `condensed`, +#' `semi-condensed`, `normal`, `semi-expanded`, `expanded`, `extra-expanded`, +#' and `ultra-expanded`. Alternatively, we can supply percentage values from +#' `0\%` to `200\%`, inclusive. Negative percentage values are not allowed. +#' @param text_indent The indentation of the text. +#' @param text_decorate Allows for text decoration effect to be applied. Here, +#' we can use `"overline"`, `"line-through"`, or `"underline"`. +#' @param text_transform Allows for the transformation of text. Options are +#' `"uppercase"`, `"lowercase"`, or `"capitalize"`. +#' @return A character vector containing formatted styles. #' @family helper functions #' @export cells_styles <- function(bkgd_color = NULL, @@ -576,8 +573,8 @@ cells_styles <- function(bkgd_color = NULL, #' Helper for providing a numeric value as percentage #' @param x the numeric value to format as a string percentage for some -#' \code{\link{tab_options}()} arguments that can take percentage values -#' (e.g., \code{table.width}). +#' [tab_options()] arguments that can take percentage values +#' (e.g., `table.width`). #' @family helper functions #' @export pct <- function(x) { @@ -590,9 +587,9 @@ pct <- function(x) { } #' Helper for providing a numeric value as pixels value -#' @param x the numeric value to format as a string (e.g., \code{"12px"}) for -#' some \code{\link{tab_options}()} arguments that can take values as units of -#' pixels (e.g., \code{table.font.size}). +#' @param x the numeric value to format as a string (e.g., `"12px"`) for +#' some [tab_options()] arguments that can take values as units of +#' pixels (e.g., `table.font.size`). #' @family helper functions #' @export px <- function(x) { @@ -628,12 +625,12 @@ escape_latex <- function(text) { #' including a \pkg{gt} table can be problematic if we don't have knowledge #' of the LaTeX dependencies. For the most part, these dependencies are the #' LaTeX packages that are required for rendering a \pkg{gt} table. The -#' \code{gt_latex_dependencies()} function provides an object that can be +#' `gt_latex_dependencies()` function provides an object that can be #' used to provide the LaTeX in an Rnw file, allowing \pkg{gt} tables to work #' and not yield errors due to missing packages. #' #' Here is an example Rnw document that shows how the -#' \code{gt_latex_dependencies()} can be used in conjunction with a \pkg{gt} +#' `gt_latex_dependencies()` can be used in conjunction with a \pkg{gt} #' table: #' #' \preformatted{ diff --git a/R/image.R b/R/image.R index 3c8c440a4c..91a8d322cf 100644 --- a/R/image.R +++ b/R/image.R @@ -1,30 +1,28 @@ #' Helper function for adding a local image #' #' We can flexibly add a local image (i.e., an image residing on disk) inside of -#' a table with \code{local_image()} function. The function provides a -#' convenient way to generate an HTML fragment using an on-disk PNG or SVG. -#' Because this function is currently HTML-based, it is only useful for HTML -#' table output. To use this function inside of data cells, it is recommended -#' that the \code{\link{text_transform}()} function is used. With that function, -#' we can specify which data cells to target and then include a -#' \code{local_image()} call within the required user-defined function (for the -#' \code{fn} argument). If we want to include an image in other places (e.g., in -#' the header, within footnote text, etc.) we need to use \code{local_image()} -#' within the \code{\link{html}()} helper function. +#' a table with `local_image()` function. The function provides a convenient way +#' to generate an HTML fragment using an on-disk PNG or SVG. Because this +#' function is currently HTML-based, it is only useful for HTML table output. To +#' use this function inside of data cells, it is recommended that the +#' [text_transform()] function is used. With that function, we can specify which +#' data cells to target and then include a `local_image()` call within the +#' required user-defined function (for the `fn` argument). If we want to include +#' an image in other places (e.g., in the header, within footnote text, etc.) we +#' need to use `local_image()` within the [html()] helper function. #' #' By itself, the function creates an HTML image tag with an image URI embedded #' within. We can easily experiment with a local PNG or SVG image that's -#' available in the \pkg{gt} package using the \code{\link{test_image}()} -#' function. Using that, the call \code{local_image(file = test_image(type = -#' "png"))} evaluates to: +#' available in the \pkg{gt} package using the [test_image()] function. Using +#' that, the call `local_image(file = test_image(type = "png"))` evaluates to: #' -#' \code{ src= style=\"height:30px;\">} +#' ` src= style=\"height:30px;\">` #' -#' where a height of \code{30px} is a default height chosen to work well within -#' the heights of most table rows. +#' where a height of `30px` is a default height chosen to work well within the +#' heights of most table rows. #' -#' @param file a path to an image file. -#' @param height the absolute height (px) of the image in the table cell. +#' @param file A path to an image file. +#' @param height The absolute height (px) of the image in the table cell. #' @return a character object with an HTML fragment that can be placed inside of #' a cell. #' @examples @@ -82,28 +80,28 @@ local_image <- function(file, #' Helper function for adding an image from the web #' -#' We can flexibly add a web image inside of a table with \code{web_image()} +#' We can flexibly add a web image inside of a table with `web_image()` #' function. The function provides a convenient way to generate an HTML fragment #' with an image URL. Because this function is currently HTML-based, it is only #' useful for HTML table output. To use this function inside of data cells, it -#' is recommended that the \code{\link{text_transform}()} function is used. With -#' that function, we can specify which data cells to target and then include a -#' \code{web_image()} call within the required user-defined function (for the -#' \code{fn} argument). If we want to include an image in other places (e.g., in -#' the header, within footnote text, etc.) we need to use \code{web_image()} -#' within the \code{\link{html}()} helper function. +#' is recommended that the [text_transform()] function is used. With that +#' function, we can specify which data cells to target and then include a +#' `web_image()` call within the required user-defined function (for the `fn` +#' argument). If we want to include an image in other places (e.g., in the +#' header, within footnote text, etc.) we need to use `web_image()` within the +#' [html()] helper function. #' #' By itself, the function creates an HTML image tag, so, the call -#' \code{web_image("http://some.web.site/image.png")} evaluates to: +#' `web_image("http://some.web.site/image.png")` evaluates to: #' -#' \code{} +#' `` #' -#' where a height of \code{30px} is a default height chosen to work well within -#' the heights of most table rows. +#' where a height of `30px` is a default height chosen to work well within the +#' heights of most table rows. #' -#' @param url a url that resolves to an image file. -#' @param height the absolute height (px) of the image in the table cell. -#' @return a character object with an HTML fragment that can be placed inside of +#' @param url A url that resolves to an image file. +#' @param height The absolute height (px) of the image in the table cell. +#' @return A character object with an HTML fragment that can be placed inside of #' a cell. #' @examples #' # Get the PNG-based logo for the R @@ -190,38 +188,36 @@ web_image <- function(url, #' Helper function for adding a ggplot #' #' We can add a \pkg{ggplot2} plot inside of a table with the help of the -#' \code{ggplot_image()} function. The function provides a convenient way to -#' generate an HTML fragment with a \code{ggplot} object. Because this function -#' is currently HTML-based, it is only useful for HTML table output. To use this -#' function inside of data cells, it is recommended that the -#' \code{\link{text_transform}()} function is used. With that function, we can -#' specify which data cells to target and then include a call to -#' \code{ggplot_image()} within the required user-defined function (for the -#' \code{fn} argument). If we want to include a plot in other places (e.g., in -#' the header, within footnote text, etc.) we need to use \code{ggplot_image()} -#' within the \code{\link{html}()} helper function. +#' `ggplot_image()` function. The function provides a convenient way to generate +#' an HTML fragment with a `ggplot` object. Because this function is currently +#' HTML-based, it is only useful for HTML table output. To use this function +#' inside of data cells, it is recommended that the [text_transform()] function +#' is used. With that function, we can specify which data cells to target and +#' then include a call to `ggplot_image()` within the required user-defined +#' function (for the `fn` argument). If we want to include a plot in other +#' places (e.g., in the header, within footnote text, etc.) we need to use +#' `ggplot_image()` within the [html()] helper function. #' #' By itself, the function creates an HTML image tag with an image URI embedded -#' within (a 100 dpi PNG). We can easily experiment with any \code{ggplot2} plot -#' object, and using it within \code{ggplot_image(plot_object = } +#' within (a 100 dpi PNG). We can easily experiment with any `ggplot2` plot +#' object, and using it within `ggplot_image(plot_object = ` #' evaluates to: #' -#' \code{ src= style=\"height:100px;\">} +#' ` src= style=\"height:100px;\">` #' -#' where a height of \code{100px} is a default height chosen to work well within -#' the heights of most table rows. There is the option to modify the aspect -#' ratio of the plot (the default \code{aspect_ratio} is \code{1.0}) and this is -#' useful for elongating any given plot to fit better within the table -#' construct. +#' where a height of `100px` is a default height chosen to work well within the +#' heights of most table rows. There is the option to modify the aspect ratio of +#' the plot (the default `aspect_ratio` is `1.0`) and this is useful for +#' elongating any given plot to fit better within the table construct. #' -#' @param plot_object a ggplot plot object. -#' @param height the absolute height (px) of the image in the table cell. -#' @param aspect_ratio the plot's final aspect ratio. Where the height of the -#' plot is fixed using the \code{height} argument, the \code{aspect_ratio} -#' will either compress (\code{aspect_ratio} < \code{1.0}) or expand -#' (\code{aspect_ratio} > \code{1.0}) the plot horizontally. The default value -#' of \code{1.0} will neither compress nor expand the plot. -#' @return a character object with an HTML fragment that can be placed inside of +#' @param plot_object A ggplot plot object. +#' @param height The absolute height (px) of the image in the table cell. +#' @param aspect_ratio The plot's final aspect ratio. Where the height of the +#' plot is fixed using the `height` argument, the `aspect_ratio` +#' will either compress (`aspect_ratio` < `1.0`) or expand +#' (`aspect_ratio` > `1.0`) the plot horizontally. The default value +#' of `1.0` will neither compress nor expand the plot. +#' @return A character object with an HTML fragment that can be placed inside of #' a cell. #' @examples #' library(ggplot2) @@ -296,11 +292,11 @@ ggplot_image <- function(plot_object, #' #' Two test images are available within the \pkg{gt} package. Both contain the #' same imagery (sized at 200px by 200px) but one is a PNG file while the other -#' is an SVG file. This function is most useful when paired with -#' \code{\link{local_image}()} since we test various sizes of the test image -#' within that function. -#' @param type the type of the image, which can either be \code{png} (the -#' default) or \code{svg}. +#' is an SVG file. This function is most useful when paired with [local_image()] +#' since we test various sizes of the test image within that function. +#' +#' @param type The type of the image, which can either be `png` (the default) or +#' `svg`. #' @family image addition functions #' @export test_image <- function(type = c("png", "svg")) { diff --git a/R/info_tables.R b/R/info_tables.R index 853bd2d487..875015e5f9 100644 --- a/R/info_tables.R +++ b/R/info_tables.R @@ -1,10 +1,11 @@ #' View a table with info on date styles #' -#' The \code{fmt_date()} function lets us format date-based values in a -#' convenient manner using preset styles. The table generated by the -#' \code{info_date_style()} function provides a quick reference to all 14 -#' styles, with associated number codes, the format names, and example outputs -#' using a fixed date (\code{2000-02-29}). +#' The `fmt_date()` function lets us format date-based values in a convenient +#' manner using preset styles. The table generated by the `info_date_style()` +#' function provides a quick reference to all 14 styles, with associated number +#' codes, the format names, and example outputs using a fixed date +#' (`2000-02-29`). +#' #' @examples #' # Get a table of info on the different #' # date-formatting styles (which are used @@ -51,11 +52,12 @@ info_date_style <- function() { #' View a table with info on time styles #' -#' The \code{fmt_time()} function lets us format time-based values in a -#' convenient manner using preset styles. The table generated by the -#' \code{info_time_style()} function provides a quick reference to all five -#' styles, with associated number codes, the format names, and example outputs -#' using a fixed time (\code{14:35}). +#' The `fmt_time()` function lets us format time-based values in a convenient +#' manner using preset styles. The table generated by the `info_time_style()` +#' function provides a quick reference to all five styles, with associated +#' number codes, the format names, and example outputs using a fixed time +#' (`14:35`). +#' #' @examples #' # Get a table of info on the different #' # time-formatting styles (which are used @@ -91,28 +93,29 @@ info_time_style <- function() { #' View a table with info on supported currencies #' -#' The \code{fmt_currency()} function lets us format numeric values as -#' currencies. The table generated by the \code{info_currencies()} function -#' provides a quick reference to all the available currencies. The currency -#' identifiers are provided (name, 3-letter currency code, and 3-digit currency -#' code) along with the each currency's exponent value (number of digits of the -#' currency subunits). A formatted example is provided (based on the value of -#' \code{49.95}) to demonstrate the default formatting of each currency. +#' The `fmt_currency()` function lets us format numeric values as currencies. +#' The table generated by the `info_currencies()` function provides a quick +#' reference to all the available currencies. The currency identifiers are +#' provided (name, 3-letter currency code, and 3-digit currency code) along with +#' the each currency's exponent value (number of digits of the currency +#' subunits). A formatted example is provided (based on the value of `49.95`) to +#' demonstrate the default formatting of each currency. #' #' There are 172 currencies, which can lead to a verbose display table. To make #' this presentation more focused on retrieval, we can provide an initial letter -#' corresponding to the 3-letter currency code to \code{begins_with}. This will +#' corresponding to the 3-letter currency code to `begins_with`. This will #' filter currencies in the info table to just the set beginning with the #' supplied letter. #' -#' @param type the type of currency information provided. Can either be -#' \code{code} where currency information corresponding to 3-letter currency -#' codes is provided, or \code{symbol} where currency info for common currency -#' names (e.g., dollar, pound, yen, etc.) is returned. -#' @param begins_with providing a single letter will filter currencies to only +#' @param type The type of currency information provided. Can either be `code` +#' where currency information corresponding to 3-letter currency codes is +#' provided, or `symbol` where currency info for common currency names (e.g., +#' dollar, pound, yen, etc.) is returned. +#' @param begins_with Providing a single letter will filter currencies to only #' those that begin with that letter in their currency code. The default -#' (\code{NULL}) will produce a table with all currencies displayed. This -#' option only constrains the information table where \code{type == "code"}. +#' (`NULL`) will produce a table with all currencies displayed. This option +#' only constrains the information table where `type == "code"`. +#' #' @examples #' # Get a table of info on all of #' # the currencies where the three- @@ -229,23 +232,22 @@ info_currencies <- function(type = c("code", "symbol"), #' View a table with info on supported locales #' -#' Many of the \code{fmt_*()} functions have a \code{locale} argument that makes -#' locale-based formatting easier. The table generated by the -#' \code{info_locales()} function provides a quick reference to all the -#' available locales. The locale identifiers are provided (base locale ID, -#' common display name) along with the each locale's group and decimal separator -#' marks. A formatted numeric example is provided (based on the value of -#' \code{11027}) to demonstrate the default formatting of each locale. +#' Many of the `fmt_*()` functions have a `locale` argument that makes +#' locale-based formatting easier. The table generated by the `info_locales()` +#' function provides a quick reference to all the available locales. The locale +#' identifiers are provided (base locale ID, common display name) along with the +#' each locale's group and decimal separator marks. A formatted numeric example +#' is provided (based on the value of `11027`) to demonstrate the default +#' formatting of each locale. #' #' There are 712 locales, which means that a very long display table is provided #' by default. To trim down the output table size, we can provide an initial -#' letter corresponding to the base locale ID to \code{begins_with}. This will -#' filter locales in the info table to just the set beginning with the supplied -#' letter. +#' letter corresponding to the base locale ID to `begins_with`. This will filter +#' locales in the info table to just the set beginning with the supplied letter. #' -#' @param begins_with providing a single letter will filter locales to only +#' @param begins_with Providing a single letter will filter locales to only #' those that begin with that letter in their base locale ID. The default -#' (\code{NULL}) will produce a table with all locales displayed. +#' (`NULL`) will produce a table with all locales displayed. #' @examples #' # Get a table of info on all of #' # the locales where the base @@ -329,25 +331,25 @@ info_locales <- function(begins_with = NULL) { #' View a table with info on color palettes #' -#' While the \code{\link{data_color}()} function allows us to flexibly color -#' data cells in our \pkg{gt} table, the harder part of this process is -#' discovering and choosing color palettes that are suitable for the table -#' output. We can make this process much easier in two ways: (1) by using the -#' \pkg{paletteer} package, which makes a wide range of palettes from various R -#' packages readily available, and (2) calling the \code{info_paletteer()} -#' function to give us an information table that serves as a quick reference for -#' all of the discrete color palettes available in \pkg{paletteer}. +#' While the [data_color()] function allows us to flexibly color data cells in +#' our \pkg{gt} table, the harder part of this process is discovering and +#' choosing color palettes that are suitable for the table output. We can make +#' this process much easier in two ways: (1) by using the \pkg{paletteer} +#' package, which makes a wide range of palettes from various R packages readily +#' available, and (2) calling the `info_paletteer()` function to give us an +#' information table that serves as a quick reference for all of the discrete +#' color palettes available in \pkg{paletteer}. #' #' The palettes displayed are organized by package and by palette name. These #' values are required when obtaining a palette (as a vector of hexadecimal -#' colors), from the the \code{paletteer::paletteer_d()} function. Once we are +#' colors), from the the `paletteer::paletteer_d()` function. Once we are #' familiar with the names of the color palette packages (e.g., #' \pkg{RColorBrewer}, \pkg{ggthemes}, \pkg{wesanderson}), we can narrow down #' the content of this information table by supplying a vector of such package -#' names to \code{color_pkgs}. +#' names to `color_pkgs`. #' #' Colors from the following color packages (all supported by \pkg{paletteer}) -#' are shown by default with \code{info_paletteer()}: +#' are shown by default with `info_paletteer()`: #' \itemize{ #' \item awtools, 5 palettes #' \item dichromat, 17 palettes @@ -373,9 +375,9 @@ info_locales <- function(begins_with = NULL) { #' \item yarrr, 21 palettes #' } #' -#' @param color_pkgs a vector of color packages that determines which sets of +#' @param color_pkgs A vector of color packages that determines which sets of #' palettes should be displayed in the information table. If this is -#' \code{NULL} (the default) then all of the discrete palettes from all of the +#' `NULL` (the default) then all of the discrete palettes from all of the #' color packages represented in \pkg{paletteer} will be displayed. #' @examples #' # Get a table of info on just the diff --git a/R/modify_columns.R b/R/modify_columns.R index 3e55886fe9..b57c8484d1 100644 --- a/R/modify_columns.R +++ b/R/modify_columns.R @@ -2,28 +2,26 @@ #' #' The individual alignments of columns (which includes the column labels and #' all of their data cells) can be modified. We have the option to align text to -#' the \code{left}, the \code{center}, and the \code{right}. In a less explicit -#' manner, we can allow \pkg{gt} to automatically choose the alignment of each -#' column based on the data type (with the \code{auto} option). -#' -#' When you create a \pkg{gt} table object using \code{\link{gt}()}, automatic -#' alignment of column labels and their data cells is performed. By default, -#' left-alignment is applied to columns of class \code{character}, \code{Date}, -#' or \code{POSIXct}; center-alignment is for columns of class \code{logical}, -#' \code{factor}, or \code{list}; and right-alignment is used for the -#' \code{numeric} and \code{integer} columns. -#' -#' @param data a table object that is created using the \code{\link{gt}()} -#' function. -#' @param align the alignment type. This can be any of \code{"center"}, -#' \code{"left"}, or \code{"right"} for center-, left-, or center-alignment. -#' Alternatively, the \code{"auto"} option (the default), will automatically -#' align values in columns according to the data type (see the Details section -#' for specifics on which alignments are applied). -#' @param columns an optional vector of column names for which the alignment -#' should be applied. If nothing is supplied, or if \code{columns} is -#' \code{TRUE}), then the chosen alignment affects all columns. -#' @return an object of class \code{gt_tbl}. +#' the `left`, the `center`, and the `right`. In a less explicit manner, we can +#' allow \pkg{gt} to automatically choose the alignment of each column based on +#' the data type (with the `auto` option). +#' +#' When you create a \pkg{gt} table object using [gt()], automatic alignment of +#' column labels and their data cells is performed. By default, left-alignment +#' is applied to columns of class `character`, `Date`, or `POSIXct`; +#' center-alignment is for columns of class `logical`, `factor`, or `list`; and +#' right-alignment is used for the `numeric` and `integer` columns. +#' +#' @param data A table object that is created using the [gt()] function. +#' @param align The alignment type. This can be any of `"center"`, `"left"`, or +#' `"right"` for center-, left-, or center-alignment. Alternatively, the +#' `"auto"` option (the default), will automatically align values in columns +#' according to the data type (see the Details section for specifics on which +#' alignments are applied). +#' @param columns An optional vector of column names for which the alignment +#' should be applied. If nothing is supplied, or if `columns` is `TRUE`), then +#' the chosen alignment affects all columns. +#' @return An object of class `gt_tbl`. #' @examples #' # Use `countrypops` to create a gt table; #' # align the `population` column data to @@ -91,31 +89,30 @@ cols_align <- function(data, #' #' Column labels can be modified from their default values (the names of the #' columns from the input table data). When you create a \pkg{gt} table object -#' using \code{\link{gt}()}, column names effectively become the column labels. -#' While this serves as a good first approximation, column names aren't often -#' appealing as column labels in a \pkg{gt} output table. The -#' \code{cols_label()} function provides the flexibility to relabel one or more -#' columns and we even have the option to use the \code{\link{md}()} or -#' \code{\link{html}()} helper functions for rendering column labels from -#' Markdown or using HTML. +#' using [gt()], column names effectively become the column labels. While this +#' serves as a good first approximation, column names aren't often appealing as +#' column labels in a \pkg{gt} output table. The `cols_label()` function +#' provides the flexibility to relabel one or more columns and we even have the +#' option to use the [md()] or [html()] helper functions for rendering column +#' labels from Markdown or using HTML. #' #' It's important to note that while columns can be freely relabeled, we #' continue to refer to columns by their original column names. Column names in -#' a tibble or data frame must be unique whereas column labels in \pkg{gt} -#' have no requirement for uniqueness (which is useful for labeling columns as, -#' say, measurement units that may be repeated several times---usually under +#' a tibble or data frame must be unique whereas column labels in \pkg{gt} have +#' no requirement for uniqueness (which is useful for labeling columns as, say, +#' measurement units that may be repeated several times---usually under #' different spanner column labels). Thus, we can still easily distinguish #' between columns in other \pkg{gt} function calls (e.g., in all of the -#' \code{fmt*()} functions) even though we may lose distinguishability in column +#' `fmt*()` functions) even though we may lose distinguishability in column #' labels once they have been relabeled. #' #' @inheritParams cols_align -#' @param ... one or more named arguments of column names from the input `data` +#' @param ... One or more named arguments of column names from the input `data` #' table along with their labels for display as the column labels. We can -#' optionally wrap the column labels with \code{\link{md}()} (to interpret -#' text as Markdown) or \code{\link{html}()} (to interpret text as HTML). -#' @param .list allows for the use of a list as an input alternative to -#' \code{...}. +#' optionally wrap the column labels with [md()] (to interpret text as +#' Markdown) or [html()] (to interpret text as HTML). +#' @param .list Allows for the use of a list as an input alternative to `...`. +#' @return An object of class `gt_tbl`. #' @examples #' # Use `countrypops` to create a gt table; #' # label all the table's columns to @@ -204,28 +201,27 @@ cols_label <- function(data, #' Move one or more columns #' #' On those occasions where you need to move columns this way or that way, we -#' can make use of the \code{cols_move()} function. While it's true that the -#' movement of columns can be done upstream of \pkg{gt}'s API, it is much easier -#' and less error prone to use the function provided here. The movement -#' procedure here takes one or more specified columns (in the \code{columns} -#' argument) and places them to the right of a different column (the -#' \code{after} argument). The ordering of the \code{columns} to be moved is -#' preserved, as is the ordering of all other columns in the table. -#' -#' The columns supplied in \code{columns} must all exist in the table and none -#' of them can be in the \code{after} argument. The \code{after} column must -#' also exist and only one column should be provided here. If you need to place -#' one or columns at the beginning of the column series, the -#' \code{\link{cols_move_to_start}()} function should be used. Similarly, if -#' those columns to move should be placed at the end of the column series then -#' use \code{\link{cols_move_to_end}()}. +#' can make use of the `cols_move()` function. While it's true that the movement +#' of columns can be done upstream of \pkg{gt}'s API, it is much easier and less +#' error prone to use the function provided here. The movement procedure here +#' takes one or more specified columns (in the `columns` argument) and places +#' them to the right of a different column (the `after` argument). The ordering +#' of the `columns` to be moved is preserved, as is the ordering of all other +#' columns in the table. +#' +#' The columns supplied in `columns` must all exist in the table and none of +#' them can be in the `after` argument. The `after` column must also exist and +#' only one column should be provided here. If you need to place one or columns +#' at the beginning of the column series, the [cols_move_to_start()] function +#' should be used. Similarly, if those columns to move should be placed at the +#' end of the column series then use [cols_move_to_end()]. #' #' @inheritParams cols_align -#' @param columns the column names to move to as a group to a different +#' @param columns The column names to move to as a group to a different #' position. The order of the remaining columns will be preserved. -#' @param after a column name used to anchor the insertion of the moved columns. +#' @param after A column name used to anchor the insertion of the moved columns. #' All of the moved columns will be placed to the right of this column. -#' @return an object of class \code{gt_tbl}. +#' @return An object of class `gt_tbl`. #' @examples #' # Use `countrypops` to create a gt table; #' # With the remaining columns, position @@ -318,23 +314,23 @@ cols_move <- function(data, #' Move one or more columns to the start #' #' We can easily move set of columns to the beginning of the column series and -#' we only need to specify which \code{columns}. It's possible to do this -#' upstream of \pkg{gt}'s API, however, it is easier with this function and it -#' presents less possibility for error. The ordering of the \code{columns} that -#' are moved to the start is preserved (same with the ordering of all other -#' columns in the table). -#' -#' The columns supplied in \code{columns} must all exist in the table. If you -#' need to place one or columns at the end of the column series, the -#' \code{\link{cols_move_to_end}()} function should be used. More control is -#' offered with the \code{\link{cols_move}()} function, where columns could be -#' placed after a specific column. +#' we only need to specify which `columns`. It's possible to do this upstream of +#' \pkg{gt}'s API, however, it is easier with this function and it presents less +#' possibility for error. The ordering of the `columns` that are moved to the +#' start is preserved (same with the ordering of all other columns in the +#' table). +#' +#' The columns supplied in `columns` must all exist in the table. If you need to +#' place one or columns at the end of the column series, the +#' [cols_move_to_end()] function should be used. More control is offered with +#' the [cols_move()] function, where columns could be placed after a specific +#' column. #' #' @inheritParams cols_align -#' @param columns the column names to move to the left-most side of the table. +#' @param columns The column names to move to the left-most side of the table. #' The order in which columns are provided will be preserved (as is the case #' with the remaining columns). -#' @return an object of class \code{gt_tbl}. +#' @return An object of class `gt_tbl`. #' @examples #' # Use `countrypops` to create a gt table; #' # With the remaining columns, move the @@ -406,23 +402,22 @@ cols_move_to_start <- function(data, #' Move one or more columns to the end #' #' It's possible to move a set of columns to the end of the column series, we -#' only need to specify which \code{columns} are to be moved. While this can be -#' done upstream of \pkg{gt}'s API, this function makes to process much easier -#' and it's less error prone. The ordering of the \code{columns} that are moved -#' to the end is preserved (same with the ordering of all other columns in the -#' table). +#' only need to specify which `columns` are to be moved. While this can be done +#' upstream of \pkg{gt}'s API, this function makes to process much easier and +#' it's less error prone. The ordering of the `columns` that are moved to the +#' end is preserved (same with the ordering of all other columns in the table). #' -#' The columns supplied in \code{columns} must all exist in the table. If you -#' need to place one or columns at the start of the column series, the -#' \code{\link{cols_move_to_start}()} function should be used. More control is -#' offered with the \code{\link{cols_move}()} function, where columns could be -#' placed after a specific column. +#' The columns supplied in `columns` must all exist in the table. If you need to +#' place one or columns at the start of the column series, the +#' [cols_move_to_start()] function should be used. More control is offered with +#' the [cols_move()] function, where columns could be placed after a specific +#' column. #' #' @inheritParams cols_align -#' @param columns the column names to move to the right-most side of the table. +#' @param columns The column names to move to the right-most side of the table. #' The order in which columns are provided will be preserved (as is the case #' with the remaining columns). -#' @return an object of class \code{gt_tbl}. +#' @return An object of class `gt_tbl`. #' @examples #' # Use `countrypops` to create a gt table; #' # With the remaining columns, move the @@ -496,26 +491,26 @@ cols_move_to_end <- function(data, #' Hide one or more columns #' -#' The \code{cols_hide()} function allows us to hide one or more columns from +#' The `cols_hide()` function allows us to hide one or more columns from #' appearing in the final output table. While it's possible and often desirable -#' to omit columns from the input table data before introduction to the -#' \code{\link{gt}()} function, there can be cases where the data in certain -#' columns is useful (as a column reference during formatting of other columns) -#' but the final display of those columns is not necessary. +#' to omit columns from the input table data before introduction to the [gt()] +#' function, there can be cases where the data in certain columns is useful (as +#' a column reference during formatting of other columns) but the final display +#' of those columns is not necessary. #' #' The hiding of columns is internally a rendering directive, so, all columns #' that are 'hidden' are still accessible and useful in any expression provided -#' to a \code{rows} argument. Furthermore, the \code{cols_hide()} function (as -#' with many \pkg{gt} functions) can be placed anywhere in a pipeline of -#' \pkg{gt} function calls (acting as a promise to hide columns when the timing -#' is right). However there's perhaps greater readability when placing this call -#' closer to the end of such a pipeline. +#' to a `rows` argument. Furthermore, the `cols_hide()` function (as with many +#' \pkg{gt} functions) can be placed anywhere in a pipeline of \pkg{gt} function +#' calls (acting as a promise to hide columns when the timing is right). However +#' there's perhaps greater readability when placing this call closer to the end +#' of such a pipeline. #' #' @inheritParams cols_align -#' @param columns the column names to hide from the output display table. The +#' @param columns The column names to hide from the output display table. The #' order of the remaining columns will be preserved. Values provided that do #' not correspond to column names will be disregarded. -#' @return an object of class \code{gt_tbl}. +#' @return An object of class `gt_tbl`. #' @examples #' # Use `countrypops` to create a gt table; #' # Hide the columns `country_code_2` and @@ -591,26 +586,25 @@ cols_hide <- function(data, #' reference to individual columns must continue to be the column names from the #' input table data (which are unique by necessity). #' -#' If we look to the column names in the \code{iris} dataset as an example of -#' how \code{cols_split_delim()} might be useful, we find the names -#' \code{Sepal.Length}, \code{Sepal.Width}, \code{Petal.Length}, -#' \code{Petal.Width}. From this naming system, it's easy to see that the -#' \code{Sepal} and \code{Petal} can group together the repeated common -#' \code{Length} and \code{Width} values. In your own datasets, we can avoid a -#' lengthy relabeling with \code{\link{cols_label}()} if column names can be -#' fashioned beforehand to contain both the spanner column label and the column -#' label. An additional advantage is that the column names in the input table -#' data remain unique even though there may eventually be repeated column labels -#' in the rendered output table). +#' If we look to the column names in the `iris` dataset as an example of how +#' `cols_split_delim()` might be useful, we find the names `Sepal.Length`, +#' `Sepal.Width`, `Petal.Length`, `Petal.Width`. From this naming system, it's +#' easy to see that the `Sepal` and `Petal` can group together the repeated +#' common `Length` and `Width` values. In your own datasets, we can avoid a +#' lengthy relabeling with [cols_label()] if column names can be fashioned +#' beforehand to contain both the spanner column label and the column label. An +#' additional advantage is that the column names in the input table data remain +#' unique even though there may eventually be repeated column labels in the +#' rendered output table). #' #' @inheritParams cols_align -#' @param delim the delimiter to use to split an input column name. The +#' @param delim The delimiter to use to split an input column name. The #' delimiter supplied will be autoescaped for the internal splitting #' procedure. The first component of the split will become the group name and #' the second component will be the column label. -#' @param columns an optional vector of column names that this operation should +#' @param columns An optional vector of column names that this operation should #' be limited to. The default is to consider all columns in the table. -#' @return an object of class \code{gt_tbl}. +#' @return An object of class `gt_tbl`. #' @examples #' # Use `iris` to create a gt table; split #' # any columns that are dot-separated @@ -673,31 +667,30 @@ cols_split_delim <- function(data, #' #' This function takes any two columns and merges them into a single column, #' using a pattern that specifies how the values in the data cells are combined. -#' We specify the columns to merge together in the \code{col_1} and \code{col_2} -#' arguments and the string-combining pattern is specified in \code{pattern}. -#' The column that is retained is that of \code{col_1} whereas the column -#' specified in \code{col_2} is dropped from the output table. +#' We specify the columns to merge together in the `col_1` and `col_2` arguments +#' and the string-combining pattern is specified in `pattern`. The column that +#' is retained is that of `col_1` whereas the column specified in `col_2` is +#' dropped from the output table. #' #' There are two other column-merging functions that offer specialized behavior -#' that is optimized for common table tasks: \code{\link{cols_merge_range}()} -#' and \code{\link{cols_merge_uncert}()}. These functions operate similarly, -#' where the second column specified is dropped from the output table. For all -#' of the \code{cols_merge*()} functions, column removal occurs late in the -#' rendering lifecycle so those secondary columns are still usable as column -#' references (e.g., inside expressions provided to `rows` in the \code{fmt*()} -#' functions). +#' that is optimized for common table tasks: [cols_merge_range()] and +#' [cols_merge_uncert()]. These functions operate similarly, where the second +#' column specified is dropped from the output table. For all of the +#' `cols_merge*()` functions, column removal occurs late in the rendering +#' lifecycle so those secondary columns are still usable as column references +#' (e.g., inside expressions provided to `rows` in the `fmt*()` functions). #' #' @inheritParams cols_align -#' @param col_1 a retained column that contains values to be merged with those -#' in \code{col_2}. -#' @param col_2 a column that contains values to be merged with those in -#' \code{col_1}. This column will be discarded but is still useful as a -#' reference in other \pkg{gt} functions. -#' @param pattern a formatting pattern that specifies the arrangement of the -#' \code{col_1} and \code{col_1} values and any string literals. The -#' \code{col_1} column is represented as \code{{1}} whereas \code{col_2} is -#' \code{{2}}. All other characters are taken to be string literals. -#' @return an object of class \code{gt_tbl}. +#' @param col_1 A retained column that contains values to be merged with those +#' in `col_2`. +#' @param col_2 A column that contains values to be merged with those in +#' `col_1`. This column will be discarded but is still useful as a reference +#' in other \pkg{gt} functions. +#' @param pattern A formatting pattern that specifies the arrangement of the +#' `col_1` and `col_1` values and any string literals. The `col_1` column is +#' represented as `{1}` whereas `col_2` is `{2}`. All other characters are +#' taken to be string literals. +#' @return An object of class `gt_tbl`. #' @examples #' # Use `sp500` to create a gt table; #' # merge the `open` & `close` columns @@ -779,48 +772,46 @@ cols_merge <- function(data, #' Merge two columns to a value & uncertainty column #' -#' The \code{cols_merge_uncert()} function is a specialized variant of the -#' \code{\link{cols_merge}()} function. It operates by taking a base value -#' column (\code{col_val}) and an uncertainty column (\code{col_uncert}) and -#' merges them into a single column. What results is a column with values and -#' associated uncertainties (e.g., \code{12.0 ± 0.1}), and, the column specified -#' in \code{col_uncert} is dropped from the output table. +#' The `cols_merge_uncert()` function is a specialized variant of the +#' [cols_merge()] function. It operates by taking a base value column +#' (`col_val`) and an uncertainty column (`col_uncert`) and merges them into a +#' single column. What results is a column with values and associated +#' uncertainties (e.g., `12.0 ± 0.1`), and, the column specified in `col_uncert` +#' is dropped from the output table. #' -#' This function could be somewhat replicated using \code{\link{cols_merge}()}, -#' however, \code{cols_merge_uncert()} employs the following specialized -#' semantics for \code{NA} handling: +#' This function could be somewhat replicated using [cols_merge()], however, +#' `cols_merge_uncert()` employs the following specialized semantics for `NA` +#' handling: #' #' \enumerate{ #' -#' \item \code{NA}s in \code{col_val} result in missing values for the merged -#' column (e.g., \code{NA} + \code{0.1} = \code{NA}) +#' \item `NA`s in `col_val` result in missing values for the merged +#' column (e.g., `NA` + `0.1` = `NA`) #' -#' \item \code{NA}s in \code{col_uncert} (but not \code{col_val}) result in +#' \item `NA`s in `col_uncert` (but not `col_val`) result in #' base values only for the merged column (e.g., -#' \code{12.0} + \code{NA} = \code{12.0}) +#' `12.0` + `NA` = `12.0`) #' -#' \item \code{NA}s both \code{col_val} and \code{col_uncert} result in -#' missing values for the merged column (e.g., \code{NA} + \code{NA} = -#' \code{NA}) +#' \item `NA`s both `col_val` and `col_uncert` result in +#' missing values for the merged column (e.g., `NA` + `NA` = +#' `NA`) #' } #' -#' Any resulting \code{NA} values in the \code{col_val} column following the -#' merge operation can be easily formatted using the \code{\link{fmt_missing}()} -#' function. +#' Any resulting `NA` values in the `col_val` column following the merge +#' operation can be easily formatted using the [fmt_missing()] function. #' #' This function is part of a set of three column-merging functions. The other -#' two are the general \code{\link{cols_merge}()} function and the specialized -#' \code{\link{cols_merge_range}()} function. These functions operate similarly, -#' where the second column specified is dropped from the output table. For all -#' of the \code{cols_merge*()} functions, column removal occurs late in the -#' rendering lifecycle so those secondary columns are still usable as column -#' references (e.g., inside expressions provided to `rows` in the \code{fmt*()} -#' functions). +#' two are the general [cols_merge()] function and the specialized +#' [cols_merge_range()] function. These functions operate similarly, where the +#' second column specified is dropped from the output table. For all of the +#' `cols_merge*()` functions, column removal occurs late in the rendering +#' lifecycle so those secondary columns are still usable as column references +#' (e.g., inside expressions provided to `rows` in the `fmt*()` functions). #' #' @inheritParams cols_align -#' @param col_val a single column name that contains the base values. -#' @param col_uncert a single column name that contains the uncertainty values. -#' @return an object of class \code{gt_tbl}. +#' @param col_val A single column name that contains the base values. +#' @param col_uncert A single column name that contains the uncertainty values. +#' @return An object of class `gt_tbl`. #' @examples #' # Use `exibble` to create a gt table, #' # keeping only the `currency` and `num` @@ -901,48 +892,46 @@ cols_merge_uncert <- function(data, #' Merge two columns to a value range column #' -#' The \code{cols_merge_range()} function is a specialized variant of the -#' \code{\link{cols_merge}()} function. It operates by taking a two columns that -#' constitute a range of values (\code{col_begin} and \code{col_end}) and merges -#' them into a single column. What results is a column containing both values -#' separated by a long dash (e.g., \code{12.0 — 20.0}). The column specified in -#' \code{col_end} is dropped from the output table. +#' The `cols_merge_range()` function is a specialized variant of the +#' [cols_merge()] function. It operates by taking a two columns that constitute +#' a range of values (`col_begin` and `col_end`) and merges them into a single +#' column. What results is a column containing both values separated by a long +#' dash (e.g., `12.0 — 20.0`). The column specified in `col_end` is dropped from +#' the output table. #' -#' This function could be somewhat replicated using \code{\link{cols_merge}()}, -#' however, \code{cols_merge_range()} employs the following specialized -#' semantics for \code{NA} handling: +#' This function could be somewhat replicated using [cols_merge()], however, +#' `cols_merge_range()` employs the following specialized semantics for `NA` +#' handling: #' #' \enumerate{ #' -#' \item \code{NA}s in \code{col_begin} result in missing values for the merged -#' column (e.g., \code{NA} + \code{20.0} = \code{NA}) +#' \item `NA`s in `col_begin` result in missing values for the merged +#' column (e.g., `NA` + `20.0` = `NA`) #' -#' \item \code{NA}s in \code{col_end} (but not \code{col_begin}) result in -#' a display of only the \code{col_begin} values only for the merged column -#' (e.g., \code{12.0} + \code{NA} = \code{12.0}) +#' \item `NA`s in `col_end` (but not `col_begin`) result in +#' a display of only the `col_begin` values only for the merged column +#' (e.g., `12.0` + `NA` = `12.0`) #' -#' \item \code{NA}s both \code{col_begin} and \code{col_end} result in -#' missing values for the merged column (e.g., \code{NA} + \code{NA} = -#' \code{NA}) +#' \item `NA`s both `col_begin` and `col_end` result in +#' missing values for the merged column (e.g., `NA` + `NA` = +#' `NA`) #' } #' -#' Any resulting \code{NA} values in the \code{col_begin} column following the -#' merge operation can be easily formatted using the \code{\link{fmt_missing}()} -#' function. +#' Any resulting `NA` values in the `col_begin` column following the merge +#' operation can be easily formatted using the [fmt_missing()] function. #' #' This function is part of a set of three column-merging functions. The other -#' two are the general \code{\link{cols_merge}()} function and the specialized -#' \code{\link{cols_merge_uncert}()} function. These functions operate -#' similarly, where the second column specified is dropped from the output -#' table. For all of the \code{cols_merge*()} functions, column removal occurs -#' late in the rendering lifecycle so those secondary columns are still usable -#' as column references (e.g., inside expressions provided to `rows` in the -#' \code{fmt*()} functions). +#' two are the general [cols_merge()] function and the specialized +#' [cols_merge_uncert()] function. These functions operate similarly, where the +#' second column specified is dropped from the output table. For all of the +#' `cols_merge*()` functions, column removal occurs late in the rendering +#' lifecycle so those secondary columns are still usable as column references +#' (e.g., inside expressions provided to `rows` in the `fmt*()` functions). #' #' @inheritParams cols_align -#' @param col_begin a column that contains values for the start of the range. -#' @param col_end a column that contains values for the end of the range. -#' @return an object of class \code{gt_tbl}. +#' @param col_begin A column that contains values for the start of the range. +#' @param col_end A column that contains values for the end of the range. +#' @return An object of class `gt_tbl`. #' @examples #' # Use `gtcars` to create a gt table, #' # keeping only the `model`, `mpg_c`, diff --git a/R/modify_rows.R b/R/modify_rows.R index 6e844fa036..8153d32652 100644 --- a/R/modify_rows.R +++ b/R/modify_rows.R @@ -1,20 +1,20 @@ #' Modify the ordering of any row groups #' #' We can modify the display order of any row groups in a \pkg{gt} object with -#' the \code{row_group_order()} function. The \code{groups} argument can either -#' take a vector of row group names or a numeric vector of row group indices; -#' whichever is provided, the row groups will adhere to this revised ordering. -#' It isn't necessary to provide all row group names in \code{groups}, rather, -#' what is provided will assume the specified ordering at the top of the table -#' and the remaining row groups will follow in their original ordering. +#' the `row_group_order()` function. The `groups` argument can either take a +#' vector of row group names or a numeric vector of row group indices; whichever +#' is provided, the row groups will adhere to this revised ordering. It isn't +#' necessary to provide all row group names in `groups`, rather, what is +#' provided will assume the specified ordering at the top of the table and the +#' remaining row groups will follow in their original ordering. #' @inheritParams cols_align -#' @param groups a vector of row group names, or, a numeric vector of indices +#' @param groups A vector of row group names, or, a numeric vector of indices #' corresponding to the new ordering. Either vector must correspond to #' assigned group names or the index positions. Also, either type of vector is #' not required to have all of the row group names or available index #' positions within it; any omitted values will be added to the end while #' preserving the original ordering. -#' @return an object of class \code{gt_tbl}. +#' @return An object of class `gt_tbl`. #' @examples #' # Use `exibble` to create a gt table #' # with a stub and with row groups; diff --git a/R/print.R b/R/print.R index 8441ae666b..0339e5cda1 100644 --- a/R/print.R +++ b/R/print.R @@ -1,7 +1,7 @@ #' Print the table #' #' This facilitates printing of the HTML table to the R console. -#' @param x an object of class \code{gt_tbl}. +#' @param x An object of class `gt_tbl`. #' @keywords internal #' @export print.gt_tbl <- function(x, ..., view = interactive()) { @@ -20,7 +20,7 @@ knitr_is_rtf_output <- function() { #' Knit print the table #' #' This facilitates printing of the HTML table within a knitr code chunk. -#' @param x an object of class \code{gt_tbl}. +#' @param x An object of class `gt_tbl`. #' @keywords internal knit_print.gt_tbl <- function(x, ...) { diff --git a/R/render_as_html.R b/R/render_as_html.R index 60c2f2233a..7afe41a9ec 100644 --- a/R/render_as_html.R +++ b/R/render_as_html.R @@ -1,8 +1,8 @@ #' Transform a \pkg{gt} table object to an HTML table #' -#' Take a \code{gt_tbl} table object and transform it to an HTML table. -#' @param data a table object that is created using the \code{gt()} function. -#' @return a character object with an HTML table +#' Take a `gt_tbl` table object and transform it to an HTML table. +#' @param data A table object that is created using the `gt()` function. +#' @return A character object with an HTML table #' @import checkmate #' @import rlang #' @family table export functions diff --git a/R/resolver.R b/R/resolver.R index 981eac16bb..941bad0a37 100644 --- a/R/resolver.R +++ b/R/resolver.R @@ -1,6 +1,7 @@ #' Resolve the `cells_data` object once it has access to the `data` object -#' @param data a table object that is created using the \code{gt()} function. -#' @param object the list object created by the \code{cells_data()} function. +#' +#' @param data A table object that is created using the `gt()` function. +#' @param object The list object created by the `cells_data()` function. #' @importFrom dplyr arrange distinct #' @noRd resolve_cells_data <- function(data, @@ -46,8 +47,9 @@ resolve_cells_data <- function(data, } #' Resolve the `cells_stub` object once it has access to the `data` object -#' @param data a table object that is created using the \code{gt()} function. -#' @param object the list object created by the \code{cells_stub()} function. +#' +#' @param data A table object that is created using the `gt()` function. +#' @param object The list object created by the `cells_stub()` function. #' @noRd resolve_cells_stub <- function(data, object) { @@ -81,8 +83,9 @@ resolve_cells_stub <- function(data, #' Resolve the `cells_column_labels` object once it has access to the `data` #' object -#' @param data a table object that is created using the \code{gt()} function. -#' @param object the list object created by the \code{cells_column_labels()} +#' +#' @param data A table object that is created using the `gt()` function. +#' @param object The list object created by the `cells_column_labels()` #' function. #' @noRd resolve_cells_column_labels <- function(data, @@ -110,9 +113,9 @@ resolve_cells_column_labels <- function(data, #' Resolve expressions to obtain column indices #' #' @param var_expr An expression to evaluate. This is passed directly to -#' \code{rlang::eval_tidy()} as a value for the \code{expr} argument. -#' @param data The input table available in \code{data} (usually accessed -#' through \code{as.data.frame(data)}). +#' `rlang::eval_tidy()` as a value for the `expr` argument. +#' @param data The input table available in `data` (usually accessed through +#' `as.data.frame(data)`). #' @noRd resolve_vars_idx <- function(var_expr, data) { @@ -129,10 +132,10 @@ resolve_vars_idx <- function(var_expr, #' Resolve expressions to obtain row indices #' #' @param var_expr An expression to evaluate. This is passed directly to -#' \code{rlang::eval_tidy()} as a value for the \code{expr} argument. -#' @param data The input table available in \code{data} (usually accessed -#' through \code{as.data.frame(data)}). -#' @param vals The names of columns or rows in \code{data}. +#' `rlang::eval_tidy()` as a value for the `expr` argument. +#' @param data The input table available in `data` (usually accessed through +#' `as.data.frame(data)`). +#' @param vals The names of columns or rows in `data`. #' @import tidyselect #' @import rlang #' @importFrom dplyr between @@ -213,8 +216,7 @@ resolve_data_vals_idx <- function(var_expr, #' Resolve expressions to obtain column names #' #' @param var_expr The immutable column names from the input table. -#' @param data A table object that is created using the \code{\link{gt}()} -#' function. +#' @param data A table object that is created using the [gt()] function. #' @noRd resolve_vars <- function(var_expr, data) { diff --git a/R/shiny.R b/R/shiny.R index 377a1a70b6..87f0c6b265 100644 --- a/R/shiny.R +++ b/R/shiny.R @@ -1,11 +1,12 @@ #' A \pkg{gt} display table render function for use in Shiny -#' @param expr an expression that creates a \pkg{gt} table object. -#' @param env the environment in which to evaluate the \code{expr}. -#' @param quoted is expr a quoted expression (with \code{quote()})? This is -#' useful if you want to save an expression in a variable. +#' +#' @param expr An expression that creates a \pkg{gt} table object. +#' @param env The environment in which to evaluate the `expr`. +#' @param quoted Is `expr`` a quoted expression (with `quote()`)? This is useful +#' if you want to save an expression in a variable. #' @param outputArgs A list of arguments to be passed through to the implicit -#' call to \code{\link{gt_output}()} when \code{render_gt} is used in an -#' interactive R Markdown document. +#' call to [gt_output()] when `render_gt` is used in an interactive R Markdown +#' document. #' @seealso \link{gt_output}() #' @family Shiny functions #' @importFrom htmltools resolveDependencies findDependencies doRenderTags @@ -45,7 +46,8 @@ render_gt <- function(expr, } #' Create a \pkg{gt} display table output element for Shiny -#' @param outputId an output variable from which to read the table. +#' +#' @param outputId An output variable from which to read the table. #' @return A \pkg{gt} table output element that can be included in a panel. #' @seealso \link{render_gt}() #' @family Shiny functions diff --git a/R/summary_rows.R b/R/summary_rows.R index db345bc761..0d8742af9b 100644 --- a/R/summary_rows.R +++ b/R/summary_rows.R @@ -1,49 +1,46 @@ #' Add summary rows using aggregation functions #' #' Add groupwise summary rows to one or more row groups by using the input data -#' already provided in the \code{\link{gt}()} function alongside any suitable -#' aggregation functions. Or, add a grand summary that incorporates all -#' available data, regardless of grouping. You choose how to format the values -#' in the resulting summary cells by use of a \code{formatter} function (e.g, -#' \code{\link{fmt_number}()}) and any relevant options. +#' already provided in the [gt()] function alongside any suitable aggregation +#' functions. Or, add a grand summary that incorporates all available data, +#' regardless of grouping. You choose how to format the values in the resulting +#' summary cells by use of a `formatter` function (e.g, `fmt_number`) and any +#' relevant options. #' #' Should we need to obtain the summary data for external purposes, the -#' \code{\link{extract_summary}()} function can be used with a \code{gt_tbl} -#' object where summary rows were added via \code{summary_rows()}. +#' [extract_summary()] function can be used with a `gt_tbl` object where summary +#' rows were added via `summary_rows()`. #' -#' @param data A table object that is created using the \code{gt()} function. +#' @param data A table object that is created using the [gt()] function. #' @param groups The groups to consider for generation of groupwise summary -#' rows. By default this is set to \code{NULL}, which results in the formation -#' of grand summary rows (a grand summary operates on all table data). -#' Providing the names of row groups in \code{c()} will create a groupwise -#' summary and generate summary rows for the specified groups. Setting this to -#' \code{TRUE} indicates that all available groups will receive groupwise -#' summary rows. +#' rows. By default this is set to `NULL`, which results in the formation of +#' grand summary rows (a grand summary operates on all table data). Providing +#' the names of row groups in [c()] will create a groupwise summary and +#' generate summary rows for the specified groups. Setting this to `TRUE` +#' indicates that all available groups will receive groupwise summary rows. #' @param columns The columns for which the summaries should be calculated. #' @param fns Functions used for aggregations. This can include base functions -#' like \code{mean}, \code{min}, \code{max}, \code{median}, \code{sd}, or -#' \code{sum} or any other user-defined aggregation function. The function(s) -#' should be supplied within a \code{list()}. Within that list, we can specify -#' the functions by use of function names in quotes (e.g., \code{"sum"}), as -#' bare functions (e.g., \code{sum}), or as one-sided R formulas using a -#' leading \code{~}. In the formula representation, a \code{.} serves as the -#' data to be summarized (e.g., \code{sum(., na.rm = TRUE)}). The use of named -#' arguments is recommended as the names will serve as summary row labels for -#' the corresponding summary rows data (the labels can derived from the -#' function names but only when not providing bare function names). -#' @param missing_text The text to be used in place of \code{NA} values in -#' summary cells with no data outputs. -#' @param formatter A formatter function name. These can be any of the -#' \code{fmt_*()}functions available in the package (e.g., -#' \code{\link{fmt_number}()}, \code{link{fmt_percent}()}, etc.), or a custom -#' function using \code{\link{fmt}()}. The default function is -#' \code{\link{fmt_number}()} and its options can be accessed through -#' \code{...}. -#' @param ... Values passed to the \code{formatter} function, where the provided +#' like `mean`, `min`, `max`, `median`, `sd`, or `sum` or any other +#' user-defined aggregation function. The function(s) should be supplied +#' within a `list()`. Within that list, we can specify the functions by use of +#' function names in quotes (e.g., `"sum"`), as bare functions (e.g., `sum`), +#' or as one-sided R formulas using a leading `~`. In the formula +#' representation, a `.` serves as the data to be summarized (e.g., `sum(., +#' na.rm = TRUE)`). The use of named arguments is recommended as the names +#' will serve as summary row labels for the corresponding summary rows data +#' (the labels can derived from the function names but only when not providing +#' bare function names). +#' @param missing_text The text to be used in place of `NA` values in summary +#' cells with no data outputs. +#' @param formatter A formatter function name. These can be any of the `fmt_*()` +#' functions available in the package (e.g., [fmt_number()], [fmt_percent()], +#' etc.), or a custom function using `fmt()`. The default function is +#' [fmt_number()] and its options can be accessed through `...`. +#' @param ... Values passed to the `formatter` function, where the provided #' values are to be in the form of named vectors. For example, when using the -#' default \code{formatter} function, \code{\link{fmt_number}()}, options such -#' as \code{decimals}, \code{use_seps}, and \code{locale} can be used. -#' @return An object of class \code{gt_tbl}. +#' default `formatter` function, [fmt_number()], options such as `decimals`, +#' `use_seps`, and `locale` can be used. +#' @return An object of class `gt_tbl`. #' @examples #' # Use `sp500` to create a gt table with #' # row groups; create summary rows (`min`, diff --git a/R/tab_footnote.R b/R/tab_footnote.R index eaee3b47dd..ac25cabd18 100644 --- a/R/tab_footnote.R +++ b/R/tab_footnote.R @@ -1,46 +1,39 @@ #' Add a table footnote #' -#' The \code{tab_footnote()} function can make it a painless process to add a +#' The `tab_footnote()` function can make it a painless process to add a #' footnote to a \pkg{gt} table. There are two components to a footnote: (1) a #' glyph that is attached to the targeted cell text, and (2) the footnote text #' (that starts with the corresponding glyph) that is placed in the table's -#' footer area. Each call of \code{tab_footnote()} will add a different note, -#' and one or more cells can be targeted via the location helper functions -#' (e.g., \code{\link{cells_data}()}, \code{\link{cells_column_labels}()}, -#' etc.). +#' footer area. Each call of `tab_footnote()` will add a different note, and one +#' or more cells can be targeted via the location helper functions (e.g., +#' [cells_data()], [cells_column_labels()], etc.). #' #' The formatting of the footnotes can be controlled through the use of various -#' parameters in the \code{\link{tab_options}()} function: +#' parameters in the [tab_options()] function: #' -#' \itemize{ -#' \item \code{footnote.sep}: allows for a choice of the separator between +#' \itemize{ \item `footnote.sep`: allows for a choice of the separator between #' consecutive footnotes in the table footer. By default, this is set to a -#' linebreak. -#' \item \code{footnote.glyph}: the set of sequential characters or numbers -#' used to identify the footnotes. -#' \item \code{footnote.font.size}: the size of the font used in the footnote -#' section. -#' \item \code{footnote.padding}: the amount of padding to apply between the -#' footnote and source note sections in the table footer. -#' } +#' linebreak. \item `footnote.glyph`: the set of sequential characters or +#' numbers used to identify the footnotes. \item `footnote.font.size`: the size +#' of the font used in the footnote section. \item `footnote.padding`: the +#' amount of padding to apply between the footnote and source note sections in +#' the table footer. } #' #' @inheritParams fmt_number -#' @param footnote the text to be used in the footnote. We can optionally use -#' the \code{\link{md}()} and \code{\link{html}()} functions to style the text -#' as Markdown or to retain HTML elements in the footnote text. -#' @param locations the cell or set of cells to be associated with the footnote. -#' Supplying any of the \code{cells_*()} helper functions is a useful way to -#' target the location cells that are associated with the footnote text. These -#' helper functions are: \code{\link{cells_title}()}, -#' \code{\link{cells_column_labels}()}, \code{\link{cells_group}()}, -#' \code{\link{cells_stub}()}, \code{\link{cells_data}()}, and -#' \code{\link{cells_summary}()}. Please see the help article -#' \link{location_cells} for more information on how these helper functions -#' can be used. Additionally, we can enclose several \code{cells_*()} calls -#' within a \code{list()} if we wish to link the footnote text to different +#' @param footnote The text to be used in the footnote. We can optionally use +#' the [md()] and [html()] functions to style the text as Markdown or to +#' retain HTML elements in the footnote text. +#' @param locations The cell or set of cells to be associated with the footnote. +#' Supplying any of the `cells_*()` helper functions is a useful way to target +#' the location cells that are associated with the footnote text. These helper +#' functions are: [cells_title()], [cells_column_labels()], [cells_group()], +#' [cells_stub()], [cells_data()], and [cells_summary()]. Please see the help +#' article \link{location_cells} for more information on how these helper +#' functions can be used. Additionally, we can enclose several `cells_*()` +#' calls within a `list()` if we wish to link the footnote text to different #' types of locations (e.g., cell data values, stub group headings, the table #' title, etc.). -#' @return an object of class \code{gt_tbl}. +#' @return An object of class `gt_tbl`. #' @examples #' # Use `sza` to create a gt table; color #' # the `sza` column using the `data_color()` diff --git a/R/tab_options.R b/R/tab_options.R index 39e15ac117..6cbcf7b1c8 100644 --- a/R/tab_options.R +++ b/R/tab_options.R @@ -3,63 +3,61 @@ #' Modify the options available in a table. These options are named by the #' components, the subcomponents, and the element that can adjusted. #' @inheritParams fmt_number -#' @param table.width the width of the table. Can be specified as a +#' @param table.width The width of the table. Can be specified as a #' single-length character with units of pixels or as a percentage. If #' provided as a single-length numeric vector, it is assumed that the value is -#' given in units of pixels. The \code{\link{px}()} and \code{\link{pct}()} -#' helper functions can also be used to pass in numeric values and obtain -#' values as pixel or percent units. +#' given in units of pixels. The [px()] and [pct()] helper functions can also +#' be used to pass in numeric values and obtain values as pixel or percent +#' units. #' @param table.font.size,heading.title.font.size,heading.subtitle.font.size,column_labels.font.size,row_group.font.size,footnote.font.size,sourcenote.font.size -#' font sizes for the parent text element \code{table} and the following child -#' elements: \code{heading.title}, \code{heading.subtitle}, \code{columns}, -#' \code{row_group}, \code{footnote}, and \code{sourcenote}. Can be specified -#' as a single-length character vector with units of pixels (e.g., -#' \code{12px}) or as a percentage (e.g., \code{80\%}). If provided as a -#' single-length numeric vector, it is assumed that the value is given in -#' units of pixels. The \code{\link{px}()} and \code{\link{pct}()} helper +#' Font sizes for the parent text element `table` and the following child +#' elements: `heading.title`, `heading.subtitle`, `columns`, `row_group`, +#' `footnote`, and `sourcenote`. Can be specified as a single-length character +#' vector with units of pixels (e.g., `12px`) or as a percentage (e.g., +#' `80\%`). If provided as a single-length numeric vector, it is assumed that +#' the value is given in units of pixels. The [px()] and [pct()] helper #' functions can also be used to pass in numeric values and obtain values as #' pixel or percent units. #' @param column_labels.font.weight,row_group.font.weight the font weight of -#' the \code{columns} and \code{row_group} text element. +#' the `columns` and `row_group` text element. #' @param summary_row.text_transform,grand_summary_row.text_transform an option #' to apply text transformations to the label text in each summary row. #' @param table.background.color,heading.background.color,column_labels.background.color,row_group.background.color,summary_row.background.color,grand_summary_row.background.color -#' background colors for the parent element \code{table} and the following -#' child elements: \code{heading}, \code{columns}, \code{row_group}, -#' \code{summary_row}, and \code{table_body}. A color name or a hexadecimal -#' color code should be provided. +#' background colors for the parent element `table` and the following child +#' elements: `heading`, `columns`, `row_group`, `summary_row`, and +#' `table_body`. A color name or a hexadecimal color code should be provided. #' @param table.border.top.style,table.border.top.width,table.border.top.color -#' the style, width, and color of the table's top border. +#' The style, width, and color of the table's top border. #' @param heading.border.bottom.style,heading.border.bottom.width,heading.border.bottom.color -#' the style, width, and color of the heading's bottom border. +#' The style, width, and color of the heading's bottom border. #' @param row_group.border.top.style,row_group.border.top.width,row_group.border.top.color -#' the style, width, and color of the row group's top border. +#' The style, width, and color of the row group's top border. #' @param row_group.border.bottom.style,row_group.border.bottom.width,row_group.border.bottom.color -#' the style, width, and color of the row group's bottom border. +#' The style, width, and color of the row group's bottom border. #' @param table_body.border.top.style,table_body.border.top.width,table_body.border.top.color -#' the style, width, and color of the table body's top border. +#' The style, width, and color of the table body's top border. #' @param table_body.border.bottom.style,table_body.border.bottom.width,table_body.border.bottom.color #' the style, width, and color of the table body's bottom border. #' @param row.padding,summary_row.padding,grand_summary_row.padding the amount #' of padding in each row and in each type of summary row. #' @param footnote.sep the separating characters between adjacent footnotes in #' the footnotes section. The default value produces a linebreak. -#' @param footnote.glyph the set of sequential figures or characters used to -#' identify the footnotes. We can either supply the keyword \code{"numbers"} -#' (the default, indicating that we want numeric glyphs), the keywords -#' \code{"letters"} or \code{"LETTERS"} (indicating that we want letters as -#' glyphs, either lowercase or uppercase), or, a vector of character values -#' representing the series of glyphs. A series of glyphs is recycled when its -#' usage goes beyond the length of the set. At each cycle, the glyphs are -#' simply combined (e.g., \code{*} -> \code{**} -> \code{***}). -#' @param footnote.padding,sourcenote.padding the amount of padding to apply to +#' @param footnote.glyph The set of sequential figures or characters used to +#' identify the footnotes. We can either supply the keyword `"numbers"` (the +#' default, indicating that we want numeric glyphs), the keywords `"letters"` +#' or `"LETTERS"` (indicating that we want letters as glyphs, either lowercase +#' or uppercase), or, a vector of character values representing the series of +#' glyphs. A series of glyphs is recycled when its usage goes beyond the +#' length of the set. At each cycle, the glyphs are simply combined (e.g., `*` +#' -> `**` -> `***`). +#' @param footnote.padding,sourcenote.padding The amount of padding to apply to #' the footnote and source note sections. -#' @param row.striping.include_stub an option for whether to include the stub +#' @param row.striping.include_stub An option for whether to include the stub #' when striping rows. -#' @param row.striping.include_table_body an option for whether to include the +#' @param row.striping.include_table_body An option for whether to include the #' table body when striping rows. -#' @param column_labels.hidden an option to hide the column labels. -#' @return an object of class \code{gt_tbl}. +#' @param column_labels.hidden An option to hide the column labels. +#' @return an object of class `gt_tbl`. #' @examples #' # Use `exibble` to create a gt table with #' # all the main parts added; we can use this diff --git a/R/tab_style.R b/R/tab_style.R index f73ecea785..1801ec9f08 100644 --- a/R/tab_style.R +++ b/R/tab_style.R @@ -1,45 +1,45 @@ #' Add custom styles to one or more cells #' -#' With the \code{tab_style()} function we can target specific cells and apply +#' With the `tab_style()` function we can target specific cells and apply #' styles to them. This is best done in conjunction with the -#' \code{\link{cells_styles}()} helper function. At present this function is +#' [cells_styles()] helper function. At present this function is #' focused on the application of styles for HTML output only (as such, other -#' output formats will ignore all \code{tab_style()} calls). With the help of -#' \code{\link{cells_styles}()}, we can set the following styles: +#' output formats will ignore all `tab_style()` calls). With the help of +#' [cells_styles()], we can set the following styles: #' \itemize{ -#' \item the background color of the cell (\code{bkgd_color}) -#' \item the cell's text color (\code{text_color}), font (\code{text_font}), or -#' size (\code{text_size}) -#' \item the text style (\code{text_style}), enabling the use of italics or +#' \item the background color of the cell (`bkgd_color`) +#' \item the cell's text color (`text_color`), font (`text_font`), or +#' size (`text_size`) +#' \item the text style (`text_style`), enabling the use of italics or #' oblique text. -#' \item text decoration (\code{text_decorate}): use overlines, line-throughs, +#' \item text decoration (`text_decorate`): use overlines, line-throughs, #' or underlines -#' \item text transformations (\code{text_transform}) that result in lowercased, +#' \item text transformations (`text_transform`) that result in lowercased, #' uppercased, or capitalized text -#' \item the text weight (\code{text_weight}), allowing the use of thin to +#' \item the text weight (`text_weight`), allowing the use of thin to #' bold text (the degree of choice is greater with variable fonts) -#' \item the alignment of text (\code{text_align}) +#' \item the alignment of text (`text_align`) #' \item a stretching property for text that condenses or expands text -#' (\code{text_stretch}) -#' \item the text indentation (\code{text_indent}) +#' (`text_stretch`) +#' \item the text indentation (`text_indent`) #' } #' #' @inheritParams fmt_number -#' @param style a vector of styles to use. The \code{\link{cells_styles}()} +#' @param style a vector of styles to use. The [cells_styles()] #' helper function can be used here to more easily generate valid styles. #' @param locations the cell or set of cells to be associated with the style -#' Supplying any of the \code{cells_*()} helper functions is a useful way to +#' Supplying any of the `cells_*()` helper functions is a useful way to #' target the location cells that are associated with the style application. -#' These helper functions are: \code{\link{cells_title}()}, -#' \code{\link{cells_column_labels}()}, \code{\link{cells_group}()}, -#' \code{\link{cells_stub}()}, \code{\link{cells_data}()}, and -#' \code{\link{cells_summary}()}. Please see the help article +#' These helper functions are: [cells_title()], +#' [cells_column_labels()], [cells_group()], +#' [cells_stub()], [cells_data()], and +#' [cells_summary()]. Please see the help article #' \link{location_cells} for more information on how these helper functions -#' can be used. Additionally, we can enclose several \code{cells_*()} calls -#' within a \code{list()} if we wish to apply styles to different types of +#' can be used. Additionally, we can enclose several `cells_*()` calls +#' within a `list()` if we wish to apply styles to different types of #' locations (e.g., cell data values, stub group headings, the table title, #' etc.). -#' @return an object of class \code{gt_tbl}. +#' @return an object of class `gt_tbl`. #' @examples #' # Use `exibble` to create a gt table; #' # add styles that are to be applied @@ -101,8 +101,8 @@ #' \if{html}{\figure{man_tab_style_2.svg}{options: width=100\%}} #' #' @family table-part creation/modification functions -#' @seealso \code{\link{cells_styles}()} as a helper for defining custom styles -#' and \code{\link{cells_data}()} as a useful helper function for targeting +#' @seealso [cells_styles()] as a helper for defining custom styles +#' and [cells_data()] as a useful helper function for targeting #' one or more data cells to be styled. #' @importFrom stats setNames #' @export diff --git a/R/table_parts.R b/R/table_parts.R index 638e3a14e0..d4b29106f7 100644 --- a/R/table_parts.R +++ b/R/table_parts.R @@ -6,11 +6,11 @@ #' header's title and subtitle. Furthermore, if the table is intended for HTML #' output, we can use HTML in either of the title or subtitle. #' @inheritParams fmt_number -#' @param title,subtitle text to be used in the table title and, optionally, for -#' the table subtitle. We can elect to use the \code{\link{md}()} and -#' \code{\link{html}()} helper functions to style the text as Markdown or to -#' retain HTML elements in the text. -#' @return an object of class \code{gt_tbl}. +#' @param title,subtitle Text to be used in the table title and, optionally, for +#' the table subtitle. We can elect to use the [md()] and [html()] helper +#' functions to style the text as Markdown or to retain HTML elements in the +#' text. +#' @return An object of class `gt_tbl`. #' @examples #' # Use `gtcars` to create a gt table; #' # add a header part to contain a title @@ -56,10 +56,10 @@ tab_header <- function(data, #' Markdown formatting for the stubhead label. Furthermore, if the table is #' intended for HTML output, we can use HTML for the stubhead label. #' @inheritParams fmt_number -#' @param label the text to be used as the stubhead label We can optionally -#' use the \code{\link{md}()} and \code{\link{html}()} functions to style the -#' text as Markdown or to retain HTML elements in the text. -#' @return an object of class \code{gt_tbl}. +#' @param label The text to be used as the stubhead label We can optionally use +#' the [md()] and [html()] functions to style the text as Markdown or to +#' retain HTML elements in the text. +#' @return An object of class `gt_tbl`. #' @examples #' # Use `gtcars` to create a gt table; add #' # a stubhead label to describe what is @@ -89,25 +89,24 @@ tab_stubhead_label <- function(data, #' #' Create a row group with a collection of rows. This requires specification of #' the rows to be included, either by supplying row labels, row indices, or -#' through use of a select helper function like \code{starts_with()}. +#' through use of a select helper function like `starts_with()`. #' @inheritParams fmt_number -#' @param group the name of the row group. This text will also serve as the row +#' @param group The name of the row group. This text will also serve as the row #' group label. -#' @param rows the rows to be made components of the row group. Can either be a -#' vector of row captions provided \code{c()}, a vector of row indices, or a -#' helper function focused on selections. The select helper functions are: -#' \code{\link{starts_with}()}, \code{\link{ends_with}()}, -#' \code{\link{contains}()}, \code{\link{matches}()}, \code{\link{one_of}()}, -#' and \code{\link{everything}()}. -#' @param others an option to set a default row group label for any rows not -#' formally placed in a row group named by \code{group} in any call of -#' \code{tab_row_group()}. A separate call to \code{tab_row_group()} with only -#' a value to \code{others} is possible and makes explicit that the call is -#' meant to provide a default row group label. If this is not set and -#' there are rows that haven't been placed into a row group (where one or -#' more row groups already exist), those rows will be automatically placed into -#' a row group without a label. -#' @return an object of class \code{gt_tbl}. +#' @param rows The rows to be made components of the row group. Can either be a +#' vector of row captions provided `c()`, a vector of row indices, or a helper +#' function focused on selections. The select helper functions are: +#' [starts_with()], [ends_with()], [contains()], [matches()], [one_of()], and +#' [everything()]. +#' @param others An option to set a default row group label for any rows not +#' formally placed in a row group named by `group` in any call of +#' `tab_row_group()`. A separate call to `tab_row_group()` with only a value +#' to `others` is possible and makes explicit that the call is meant to +#' provide a default row group label. If this is not set and there are rows +#' that haven't been placed into a row group (where one or more row groups +#' already exist), those rows will be automatically placed into a row group +#' without a label. +#' @return An object of class `gt_tbl`. #' @examples #' # Use `gtcars` to create a gt table and #' # add two row groups with the labels: @@ -222,12 +221,12 @@ tab_row_group <- function(data, #' This label is placed above one or more column labels, spanning the width of #' those columns and column labels. #' @inheritParams fmt_number -#' @param label the text to use for the spanner column label. -#' @param columns the columns to be components of the spanner heading. -#' @param gather an option to move the specified \code{columns} such that they -#' are unified under the spanner column label. Ordering of the -#' moved-into-place columns will be preserved in all cases. -#' @return an object of class \code{gt_tbl}. +#' @param label The text to use for the spanner column label. +#' @param columns The columns to be components of the spanner heading. +#' @param gather An option to move the specified `columns` such that they are +#' unified under the spanner column label. Ordering of the moved-into-place +#' columns will be preserved in all cases. +#' @return An object of class `gt_tbl`. #' @examples #' # Use `gtcars` to create a gt table; #' # Group several columns related to car @@ -311,15 +310,14 @@ tab_spanner <- function(data, #' #' Add a source note to the footer part of the \pkg{gt} table. A source note is #' useful for citing the data included in the table. Several can be added to the -#' footer, simply use multiple calls of \code{tab_source_note()} and they will -#' be inserted in the order provided. We can use Markdown formatting for the -#' note, or, if the table is intended for HTML output, we can include HTML -#' formatting. +#' footer, simply use multiple calls of `tab_source_note()` and they will be +#' inserted in the order provided. We can use Markdown formatting for the note, +#' or, if the table is intended for HTML output, we can include HTML formatting. #' @inheritParams fmt_number -#' @param source_note text to be used in the source note. We can optionally use -#' the \code{\link{md}()} and \code{\link{html}()} functions to style the text -#' as Markdown or to retain HTML elements in the text. -#' @return an object of class \code{gt_tbl}. +#' @param source_note Text to be used in the source note. We can optionally use +#' the [md()] and [html()] functions to style the text as Markdown or to +#' retain HTML elements in the text. +#' @return An object of class `gt_tbl`. #' @examples #' # Use `gtcars` to create a gt table; #' # add a source note to the table diff --git a/R/text_transform.R b/R/text_transform.R index d92504d515..44165f508c 100644 --- a/R/text_transform.R +++ b/R/text_transform.R @@ -1,19 +1,17 @@ #' Perform targeted text transformation with a function #' @inheritParams cols_align -#' @param locations the cell or set of cells to be associated with the text -#' transformation. Supplying any of the \code{cells_*()} helper functions is a +#' @param locations The cell or set of cells to be associated with the text +#' transformation. Supplying any of the `cells_*()` helper functions is a #' useful way to target the location cells that are associated with the -#' footnote text. These helper functions are: \code{\link{cells_title}()}, -#' \code{\link{cells_column_labels}()}, \code{\link{cells_group}()}, -#' \code{\link{cells_stub}()}, \code{\link{cells_data}()}, and -#' \code{\link{cells_summary}()}. Please see the help article -#' \link{location_cells} for more information on how these helper functions -#' can be used. Additionally, we can enclose several \code{cells_*()} calls -#' within a \code{list()} if we wish to link the footnote text to different -#' types of locations (e.g., cell data values, stub group headings, the table -#' title, etc.). -#' @param fn the function to use for text transformation. -#' @return an object of class \code{gt_tbl}. +#' footnote text. These helper functions are: [cells_title()], +#' [cells_column_labels()], [cells_group()], [cells_stub()], [cells_data()], +#' and [cells_summary()]. Please see the help article \link{location_cells} +#' for more information on how these helper functions can be used. +#' Additionally, we can enclose several `cells_*()` calls within a `list()` if +#' we wish to link the footnote text to different types of locations (e.g., +#' cell data values, stub group headings, the table title, etc.). +#' @param fn The function to use for text transformation. +#' @return An object of class `gt_tbl`. #' @examples #' # Use `exibble` to create a gt table; #' # transform the formatted text in the diff --git a/R/utils.R b/R/utils.R index 74c7178599..599a5e317c 100644 --- a/R/utils.R +++ b/R/utils.R @@ -180,7 +180,7 @@ get_currency_exponent <- function(currency) { #' helper function), then the text will be sanitized and transformed to HTML #' from Markdown. If the incoming text has the class `html` (applied by `html()` #' helper function), then the text will be seen as HTML and it won't undergo -#' sanitization +#' sanitization. #' @importFrom stringr str_replace_all #' @importFrom htmltools htmlEscape #' @importFrom commonmark markdown_html @@ -277,7 +277,7 @@ process_text <- function(text, #' Reverse HTML escaping #' #' Find common HTML entities resulting from HTML escaping and restore them back -#' to ASCII characters +#' to ASCII characters. #' @noRd unescape_html <- function(text) { @@ -365,17 +365,17 @@ markdown_to_text <- function(text) { unname() } -#' Handle formatting of a pattern in a \code{fmt_*()} function +#' Handle formatting of a pattern in a `fmt_*()` function #' -#' Within the context of a \code{fmt_*()} function, we always have the -#' single-length character vector of \code{pattern} available to describe a -#' final decoration of the formatted values. We use \pkg{glue}'s semantics here -#' and reserve \code{x} to be the formatted values, and, we can use \code{x} +#' Within the context of a `fmt_*()`` function, we always have the +#' single-length character vector of `pattern` available to describe a +#' final decoration of the formatted values. We use glue's semantics here +#' and reserve `x` to be the formatted values, and, we can use `x` #' multiple times in the pattern. #' @param values The values (as a character vector) that are formatted within -#' the \code{fmt_*()} function. +#' the `fmt_*()` function. #' @param pattern A formatting pattern that allows for decoration of the -#' formatted value (defined here as \code{x}). +#' formatted value (defined here as `x`). #' @noRd apply_pattern_fmt_x <- function(values, pattern) { @@ -452,7 +452,7 @@ non_na_index <- function(values, #' #' The `num_suffix()` function operates on a vector of numerical values and #' returns a tibble where each row represents a scaled value for `x` and the -#' correct suffix to use during `x`'s character-based formatting +#' correct suffix to use during `x`'s character-based formatting. #' @importFrom dplyr tibble #' @noRd num_suffix <- function(x, @@ -540,7 +540,7 @@ is_false = function(x) { #' #' This function normalizes the `suffixing` input to a character vector which is #' later appended to scaled numerical values; the input can either be a single -#' logical value or a character vector +#' logical value or a character vector. #' @param suffixing,scale_by The `suffixing` and `scale_by` options in some #' `fmt_*()` functions. #' @noRd @@ -914,8 +914,7 @@ footnote_glyphs <- function(x, #' Determine whether an object is a `gt_tbl` #' -#' @param data A table object that is created using the \code{\link{gt}()} -#' function. +#' @param data A table object that is created using the [gt()] function. #' @importFrom checkmate test_class #' @noRd is_gt <- function(data) { @@ -925,8 +924,7 @@ is_gt <- function(data) { #' Stop any function if object is not a `gt_tbl` object #' -#' @param data A table object that is created using the \code{\link{gt}()} -#' function. +#' @param data A table object that is created using the [gt()] function. #' @noRd stop_if_not_gt <- function(data) { diff --git a/R/zzz.R b/R/zzz.R index d8a042d1d9..6fcda7ab59 100644 --- a/R/zzz.R +++ b/R/zzz.R @@ -84,10 +84,10 @@ globalVariables( #' #' @section Package options: #' -#' \pkg{gt} uses the following \code{\link{options}} to configure behavior: +#' \pkg{gt} uses the following [options()] to configure behavior: #' #' \itemize{ -#' \item \code{gt.stub_group.sep}: a separator between groups for the +#' \item `gt.stub_group.sep`: a separator between groups for the #' stub group label. #' #' } diff --git a/man/adjust_luminance.Rd b/man/adjust_luminance.Rd index 46be69dede..4c4f044f3e 100644 --- a/man/adjust_luminance.Rd +++ b/man/adjust_luminance.Rd @@ -7,12 +7,12 @@ adjust_luminance(colors, steps) } \arguments{ -\item{colors}{a vector of colors that will undergo an adjustment in +\item{colors}{A vector of colors that will undergo an adjustment in luminance. Each color value provided must either be a color name (in the -set of colors provided by \code{grDevices::colors()}) or a hexadecimal -string in the form of "#RRGGBB" or "#RRGGBBAA".} +set of colors provided by \code{grDevices::colors()}) or a hexadecimal string in +the form of "#RRGGBB" or "#RRGGBBAA".} -\item{steps}{a positive or negative factor by which the luminance will be +\item{steps}{A positive or negative factor by which the luminance will be adjusted. Must be a number between \code{-2.0} and \code{2.0}.} } \description{ @@ -23,10 +23,10 @@ apply greater darkening or lightening for those colors in the midrange compared to any very dark or very light colors in the input palette. } \details{ -This function can be useful when combined with the \code{\link{data_color}()} -function's \code{palette} argument, which can use a vector of colors or any -of the \code{col_*} functions from the \pkg{scales} package (all of which -have a \code{palette} argument). +This function can be useful when combined with the \code{\link[=data_color]{data_color()}} function's +\code{palette} argument, which can use a vector of colors or any of the \code{col_*} +functions from the \pkg{scales} package (all of which have a \code{palette} +argument). } \section{Figures}{ diff --git a/man/as_latex.Rd b/man/as_latex.Rd index ecc4def5e9..657b7143ad 100644 --- a/man/as_latex.Rd +++ b/man/as_latex.Rd @@ -7,15 +7,14 @@ as_latex(data) } \arguments{ -\item{data}{a table object that is created using the \code{\link{gt}()} -function.} +\item{data}{A table object that is created using the \code{\link[=gt]{gt()}} function.} } \description{ -Get the LaTeX content from a \code{gt_tbl} object as a \code{knit_asis} -object. This object contains the LaTeX code and attributes that serve as -LaTeX dependencies (i.e., the LaTeX packages required for the table). Using -\code{as.character()} on the created object will result in a single-element -vector containing the LaTeX code. +Get the LaTeX content from a \code{gt_tbl} object as a \code{knit_asis} object. This +object contains the LaTeX code and attributes that serve as LaTeX +dependencies (i.e., the LaTeX packages required for the table). Using +\code{as.character()} on the created object will result in a single-element vector +containing the LaTeX code. } \examples{ # Use `gtcars` to create a gt table; diff --git a/man/as_raw_html.Rd b/man/as_raw_html.Rd index e212622572..bbefd72e2d 100644 --- a/man/as_raw_html.Rd +++ b/man/as_raw_html.Rd @@ -7,19 +7,18 @@ as_raw_html(data, inline_css = TRUE) } \arguments{ -\item{data}{a table object that is created using the \code{\link{gt}()} -function.} +\item{data}{A table object that is created using the \code{\link[=gt]{gt()}} function.} -\item{inline_css}{an option to supply styles to table elements as inlined CSS +\item{inline_css}{An option to supply styles to table elements as inlined CSS styles.} } \description{ -Get the HTML content from a \code{gt_tbl} object as a single-element -character vector. By default, the generated HTML will have inlined styles, -where CSS styles (that were previously contained in CSS rule sets external to -the \code{
element}) are included as \code{style} attributes in the -HTML table's tags. This option is preferable when using the output HTML table -in an emailing context. +Get the HTML content from a \code{gt_tbl} object as a single-element character +vector. By default, the generated HTML will have inlined styles, where CSS +styles (that were previously contained in CSS rule sets external to the +\code{
element}) are included as \code{style} attributes in the HTML table's +tags. This option is preferable when using the output HTML table in an +emailing context. } \examples{ # Use `gtcars` to create a gt table; diff --git a/man/as_rtf.Rd b/man/as_rtf.Rd index 28d5d07359..276fb01460 100644 --- a/man/as_rtf.Rd +++ b/man/as_rtf.Rd @@ -10,9 +10,9 @@ as_rtf(data) \item{data}{a table object that is created using the \code{gt()} function.} } \description{ -Get the RTF content from a \code{gt_tbl} object as as a single-element -character vector. This object can be used with \code{writeLines()} to -generate a valid .rtf file that can be opened by RTF readers. +Get the RTF content from a \code{gt_tbl} object as as a single-element character +vector. This object can be used with \code{writeLines()} to generate a valid .rtf +file that can be opened by RTF readers. } \examples{ # Use `gtcars` to create a gt table; diff --git a/man/cells_styles.Rd b/man/cells_styles.Rd index 2c057d0337..41fd56ae95 100644 --- a/man/cells_styles.Rd +++ b/man/cells_styles.Rd @@ -10,56 +10,53 @@ cells_styles(bkgd_color = NULL, text_color = NULL, text_font = NULL, text_decorate = NULL, text_transform = NULL) } \arguments{ -\item{bkgd_color}{the background color of the cell.} +\item{bkgd_color}{The background color of the cell.} -\item{text_color}{the text color.} +\item{text_color}{The text color.} -\item{text_font}{the font or collection of fonts (subsequent font names are) +\item{text_font}{The font or collection of fonts (subsequent font names are) used as fallbacks.} -\item{text_size}{the size of the font. Can be provided as a number that is -assumed to represent \code{px} values (or could be wrapped in the -\code{\link{px}()}) helper function. We can also use one of the following -absolute size keywords: \code{xx-small}, \code{x-small}, \code{small}, -\code{medium}, \code{large}, \code{x-large}, or \code{xx-large}.} +\item{text_size}{The size of the font. Can be provided as a number that is +assumed to represent \code{px} values (or could be wrapped in the \code{\link[=px]{px()}}) helper +function. We can also use one of the following absolute size keywords: +\code{xx-small}, \code{x-small}, \code{small}, \code{medium}, \code{large}, \code{x-large}, or +\code{xx-large}.} -\item{text_align}{the text alignment. Can be one of either \code{"center"}, +\item{text_align}{The text alignment. Can be one of either \code{"center"}, \code{"left"}, \code{"right"}, or \code{"justify"}.} -\item{text_style}{the text style. Can be one of either \code{"center"}, +\item{text_style}{The text style. Can be one of either \code{"center"}, \code{"normal"}, \code{"italic"}, or \code{"oblique"}.} -\item{text_weight}{the weight of the font. Can be a text-based keyword such -as \code{"normal"}, \code{"bold"}, \code{"lighter"}, \code{"bolder"}, or, a -numeric value between \code{1} and \code{1000}, inclusive. Note that only -variable fonts may support the numeric mapping of weight.} +\item{text_weight}{The weight of the font. Can be a text-based keyword such +as \code{"normal"}, \code{"bold"}, \code{"lighter"}, \code{"bolder"}, or, a numeric value +between \code{1} and \code{1000}, inclusive. Note that only variable fonts may +support the numeric mapping of weight.} -\item{text_stretch}{allows for text to either be condensed or expanded. We +\item{text_stretch}{Allows for text to either be condensed or expanded. We can use the following text-based keywords to describe the degree of -condensation/expansion: \code{ultra-condensed}, \code{extra-condensed}, -\code{condensed}, \code{semi-condensed}, \code{normal}, -\code{semi-expanded}, \code{expanded}, \code{extra-expanded}, and -\code{ultra-expanded}. Alternatively, we can supply percentage values from -\code{0\%} to \code{200\%}, inclusive. Negative percentage values are not -allowed.} +condensation/expansion: \code{ultra-condensed}, \code{extra-condensed}, \code{condensed}, +\code{semi-condensed}, \code{normal}, \code{semi-expanded}, \code{expanded}, \code{extra-expanded}, +and \code{ultra-expanded}. Alternatively, we can supply percentage values from +\code{0\\\%} to \code{200\\\%}, inclusive. Negative percentage values are not allowed.} -\item{text_indent}{the indentation of the text.} +\item{text_indent}{The indentation of the text.} -\item{text_decorate}{allows for text decoration effect to be applied. Here, +\item{text_decorate}{Allows for text decoration effect to be applied. Here, we can use \code{"overline"}, \code{"line-through"}, or \code{"underline"}.} -\item{text_transform}{allows for the transformation of text. Options are +\item{text_transform}{Allows for the transformation of text. Options are \code{"uppercase"}, \code{"lowercase"}, or \code{"capitalize"}.} } \value{ -a character vector containing formatted styles. +A character vector containing formatted styles. } \description{ -This helper function is to be used with the \code{\link{tab_style}()} -function, which itself allows for the setting of custom styles to one or more -cells. We can also define several styles within a single call of -\code{cells_styles} and \code{\link{tab_style}()} will reliably apply those -styles to the targeted element. +This helper function is to be used with the \code{\link[=tab_style]{tab_style()}} function, which +itself allows for the setting of custom styles to one or more cells. We can +also define several styles within a single call of \code{cells_styles} and +\code{\link[=tab_style]{tab_style()}} will reliably apply those styles to the targeted element. } \seealso{ Other helper functions: \code{\link{escape_latex}}, diff --git a/man/cols_align.Rd b/man/cols_align.Rd index 7b6ee7be62..e63fa3856d 100644 --- a/man/cols_align.Rd +++ b/man/cols_align.Rd @@ -8,36 +8,34 @@ cols_align(data, align = c("auto", "left", "center", "right"), columns = TRUE) } \arguments{ -\item{data}{a table object that is created using the \code{\link{gt}()} -function.} +\item{data}{A table object that is created using the \code{\link[=gt]{gt()}} function.} -\item{align}{the alignment type. This can be any of \code{"center"}, -\code{"left"}, or \code{"right"} for center-, left-, or center-alignment. -Alternatively, the \code{"auto"} option (the default), will automatically -align values in columns according to the data type (see the Details section -for specifics on which alignments are applied).} +\item{align}{The alignment type. This can be any of \code{"center"}, \code{"left"}, or +\code{"right"} for center-, left-, or center-alignment. Alternatively, the +\code{"auto"} option (the default), will automatically align values in columns +according to the data type (see the Details section for specifics on which +alignments are applied).} -\item{columns}{an optional vector of column names for which the alignment -should be applied. If nothing is supplied, or if \code{columns} is -\code{TRUE}), then the chosen alignment affects all columns.} +\item{columns}{An optional vector of column names for which the alignment +should be applied. If nothing is supplied, or if \code{columns} is \code{TRUE}), then +the chosen alignment affects all columns.} } \value{ -an object of class \code{gt_tbl}. +An object of class \code{gt_tbl}. } \description{ The individual alignments of columns (which includes the column labels and all of their data cells) can be modified. We have the option to align text to -the \code{left}, the \code{center}, and the \code{right}. In a less explicit -manner, we can allow \pkg{gt} to automatically choose the alignment of each -column based on the data type (with the \code{auto} option). +the \code{left}, the \code{center}, and the \code{right}. In a less explicit manner, we can +allow \pkg{gt} to automatically choose the alignment of each column based on +the data type (with the \code{auto} option). } \details{ -When you create a \pkg{gt} table object using \code{\link{gt}()}, automatic -alignment of column labels and their data cells is performed. By default, -left-alignment is applied to columns of class \code{character}, \code{Date}, -or \code{POSIXct}; center-alignment is for columns of class \code{logical}, -\code{factor}, or \code{list}; and right-alignment is used for the -\code{numeric} and \code{integer} columns. +When you create a \pkg{gt} table object using \code{\link[=gt]{gt()}}, automatic alignment of +column labels and their data cells is performed. By default, left-alignment +is applied to columns of class \code{character}, \code{Date}, or \code{POSIXct}; +center-alignment is for columns of class \code{logical}, \code{factor}, or \code{list}; and +right-alignment is used for the \code{numeric} and \code{integer} columns. } \section{Figures}{ diff --git a/man/cols_hide.Rd b/man/cols_hide.Rd index 0f901a8421..87820e3031 100644 --- a/man/cols_hide.Rd +++ b/man/cols_hide.Rd @@ -7,32 +7,31 @@ cols_hide(data, columns) } \arguments{ -\item{data}{a table object that is created using the \code{\link{gt}()} -function.} +\item{data}{A table object that is created using the \code{\link[=gt]{gt()}} function.} -\item{columns}{the column names to hide from the output display table. The +\item{columns}{The column names to hide from the output display table. The order of the remaining columns will be preserved. Values provided that do not correspond to column names will be disregarded.} } \value{ -an object of class \code{gt_tbl}. +An object of class \code{gt_tbl}. } \description{ The \code{cols_hide()} function allows us to hide one or more columns from appearing in the final output table. While it's possible and often desirable -to omit columns from the input table data before introduction to the -\code{\link{gt}()} function, there can be cases where the data in certain -columns is useful (as a column reference during formatting of other columns) -but the final display of those columns is not necessary. +to omit columns from the input table data before introduction to the \code{\link[=gt]{gt()}} +function, there can be cases where the data in certain columns is useful (as +a column reference during formatting of other columns) but the final display +of those columns is not necessary. } \details{ The hiding of columns is internally a rendering directive, so, all columns that are 'hidden' are still accessible and useful in any expression provided -to a \code{rows} argument. Furthermore, the \code{cols_hide()} function (as -with many \pkg{gt} functions) can be placed anywhere in a pipeline of -\pkg{gt} function calls (acting as a promise to hide columns when the timing -is right). However there's perhaps greater readability when placing this call -closer to the end of such a pipeline. +to a \code{rows} argument. Furthermore, the \code{cols_hide()} function (as with many +\pkg{gt} functions) can be placed anywhere in a pipeline of \pkg{gt} function +calls (acting as a promise to hide columns when the timing is right). However +there's perhaps greater readability when placing this call closer to the end +of such a pipeline. } \section{Figures}{ diff --git a/man/cols_label.Rd b/man/cols_label.Rd index a38ddd878e..d252a01aea 100644 --- a/man/cols_label.Rd +++ b/man/cols_label.Rd @@ -7,34 +7,34 @@ cols_label(data, ..., .list = list2(...)) } \arguments{ -\item{data}{a table object that is created using the \code{\link{gt}()} -function.} +\item{data}{A table object that is created using the \code{\link[=gt]{gt()}} function.} -\item{...}{one or more named arguments of column names from the input `data` +\item{...}{One or more named arguments of column names from the input \code{data} table along with their labels for display as the column labels. We can -optionally wrap the column labels with \code{\link{md}()} (to interpret -text as Markdown) or \code{\link{html}()} (to interpret text as HTML).} +optionally wrap the column labels with \code{\link[=md]{md()}} (to interpret text as +Markdown) or \code{\link[=html]{html()}} (to interpret text as HTML).} -\item{.list}{allows for the use of a list as an input alternative to -\code{...}.} +\item{.list}{Allows for the use of a list as an input alternative to \code{...}.} +} +\value{ +An object of class \code{gt_tbl}. } \description{ Column labels can be modified from their default values (the names of the columns from the input table data). When you create a \pkg{gt} table object -using \code{\link{gt}()}, column names effectively become the column labels. -While this serves as a good first approximation, column names aren't often -appealing as column labels in a \pkg{gt} output table. The -\code{cols_label()} function provides the flexibility to relabel one or more -columns and we even have the option to use the \code{\link{md}()} or -\code{\link{html}()} helper functions for rendering column labels from -Markdown or using HTML. +using \code{\link[=gt]{gt()}}, column names effectively become the column labels. While this +serves as a good first approximation, column names aren't often appealing as +column labels in a \pkg{gt} output table. The \code{cols_label()} function +provides the flexibility to relabel one or more columns and we even have the +option to use the \code{\link[=md]{md()}} or \code{\link[=html]{html()}} helper functions for rendering column +labels from Markdown or using HTML. } \details{ It's important to note that while columns can be freely relabeled, we continue to refer to columns by their original column names. Column names in -a tibble or data frame must be unique whereas column labels in \pkg{gt} -have no requirement for uniqueness (which is useful for labeling columns as, -say, measurement units that may be repeated several times---usually under +a tibble or data frame must be unique whereas column labels in \pkg{gt} have +no requirement for uniqueness (which is useful for labeling columns as, say, +measurement units that may be repeated several times---usually under different spanner column labels). Thus, we can still easily distinguish between columns in other \pkg{gt} function calls (e.g., in all of the \code{fmt*()} functions) even though we may lose distinguishability in column diff --git a/man/cols_merge.Rd b/man/cols_merge.Rd index 77dec50ff9..498610919b 100644 --- a/man/cols_merge.Rd +++ b/man/cols_merge.Rd @@ -7,41 +7,39 @@ cols_merge(data, col_1, col_2, pattern = "{1} {2}") } \arguments{ -\item{data}{a table object that is created using the \code{\link{gt}()} -function.} +\item{data}{A table object that is created using the \code{\link[=gt]{gt()}} function.} -\item{col_1}{a retained column that contains values to be merged with those +\item{col_1}{A retained column that contains values to be merged with those in \code{col_2}.} -\item{col_2}{a column that contains values to be merged with those in -\code{col_1}. This column will be discarded but is still useful as a -reference in other \pkg{gt} functions.} +\item{col_2}{A column that contains values to be merged with those in +\code{col_1}. This column will be discarded but is still useful as a reference +in other \pkg{gt} functions.} -\item{pattern}{a formatting pattern that specifies the arrangement of the -\code{col_1} and \code{col_1} values and any string literals. The -\code{col_1} column is represented as \code{{1}} whereas \code{col_2} is -\code{{2}}. All other characters are taken to be string literals.} +\item{pattern}{A formatting pattern that specifies the arrangement of the +\code{col_1} and \code{col_1} values and any string literals. The \code{col_1} column is +represented as \code{{1}} whereas \code{col_2} is \code{{2}}. All other characters are +taken to be string literals.} } \value{ -an object of class \code{gt_tbl}. +An object of class \code{gt_tbl}. } \description{ This function takes any two columns and merges them into a single column, using a pattern that specifies how the values in the data cells are combined. -We specify the columns to merge together in the \code{col_1} and \code{col_2} -arguments and the string-combining pattern is specified in \code{pattern}. -The column that is retained is that of \code{col_1} whereas the column -specified in \code{col_2} is dropped from the output table. +We specify the columns to merge together in the \code{col_1} and \code{col_2} arguments +and the string-combining pattern is specified in \code{pattern}. The column that +is retained is that of \code{col_1} whereas the column specified in \code{col_2} is +dropped from the output table. } \details{ There are two other column-merging functions that offer specialized behavior -that is optimized for common table tasks: \code{\link{cols_merge_range}()} -and \code{\link{cols_merge_uncert}()}. These functions operate similarly, -where the second column specified is dropped from the output table. For all -of the \code{cols_merge*()} functions, column removal occurs late in the -rendering lifecycle so those secondary columns are still usable as column -references (e.g., inside expressions provided to `rows` in the \code{fmt*()} -functions). +that is optimized for common table tasks: \code{\link[=cols_merge_range]{cols_merge_range()}} and +\code{\link[=cols_merge_uncert]{cols_merge_uncert()}}. These functions operate similarly, where the second +column specified is dropped from the output table. For all of the +\code{cols_merge*()} functions, column removal occurs late in the rendering +lifecycle so those secondary columns are still usable as column references +(e.g., inside expressions provided to \code{rows} in the \code{fmt*()} functions). } \section{Figures}{ diff --git a/man/cols_merge_range.Rd b/man/cols_merge_range.Rd index c822f87fc4..b7781adb23 100644 --- a/man/cols_merge_range.Rd +++ b/man/cols_merge_range.Rd @@ -4,31 +4,30 @@ \alias{cols_merge_range} \title{Merge two columns to a value range column} \usage{ -cols_merge_range(data, col_begin, col_end) +cols_merge_range(data, col_begin, col_end, sep = "---") } \arguments{ -\item{data}{a table object that is created using the \code{\link{gt}()} -function.} +\item{data}{A table object that is created using the \code{\link[=gt]{gt()}} function.} -\item{col_begin}{a column that contains values for the start of the range.} +\item{col_begin}{A column that contains values for the start of the range.} -\item{col_end}{a column that contains values for the end of the range.} +\item{col_end}{A column that contains values for the end of the range.} } \value{ -an object of class \code{gt_tbl}. +An object of class \code{gt_tbl}. } \description{ The \code{cols_merge_range()} function is a specialized variant of the -\code{\link{cols_merge}()} function. It operates by taking a two columns that -constitute a range of values (\code{col_begin} and \code{col_end}) and merges -them into a single column. What results is a column containing both values -separated by a long dash (e.g., \code{12.0 — 20.0}). The column specified in -\code{col_end} is dropped from the output table. +\code{\link[=cols_merge]{cols_merge()}} function. It operates by taking a two columns that constitute +a range of values (\code{col_begin} and \code{col_end}) and merges them into a single +column. What results is a column containing both values separated by a long +dash (e.g., \code{12.0 — 20.0}). The column specified in \code{col_end} is dropped from +the output table. } \details{ -This function could be somewhat replicated using \code{\link{cols_merge}()}, -however, \code{cols_merge_range()} employs the following specialized -semantics for \code{NA} handling: +This function could be somewhat replicated using \code{\link[=cols_merge]{cols_merge()}}, however, +\code{cols_merge_range()} employs the following specialized semantics for \code{NA} +handling: \enumerate{ @@ -44,18 +43,16 @@ missing values for the merged column (e.g., \code{NA} + \code{NA} = \code{NA}) } -Any resulting \code{NA} values in the \code{col_begin} column following the -merge operation can be easily formatted using the \code{\link{fmt_missing}()} -function. +Any resulting \code{NA} values in the \code{col_begin} column following the merge +operation can be easily formatted using the \code{\link[=fmt_missing]{fmt_missing()}} function. This function is part of a set of three column-merging functions. The other -two are the general \code{\link{cols_merge}()} function and the specialized -\code{\link{cols_merge_uncert}()} function. These functions operate -similarly, where the second column specified is dropped from the output -table. For all of the \code{cols_merge*()} functions, column removal occurs -late in the rendering lifecycle so those secondary columns are still usable -as column references (e.g., inside expressions provided to `rows` in the -\code{fmt*()} functions). +two are the general \code{\link[=cols_merge]{cols_merge()}} function and the specialized +\code{\link[=cols_merge_uncert]{cols_merge_uncert()}} function. These functions operate similarly, where the +second column specified is dropped from the output table. For all of the +\code{cols_merge*()} functions, column removal occurs late in the rendering +lifecycle so those secondary columns are still usable as column references +(e.g., inside expressions provided to \code{rows} in the \code{fmt*()} functions). } \section{Figures}{ diff --git a/man/cols_merge_uncert.Rd b/man/cols_merge_uncert.Rd index 037b505fa4..814560019b 100644 --- a/man/cols_merge_uncert.Rd +++ b/man/cols_merge_uncert.Rd @@ -7,28 +7,27 @@ cols_merge_uncert(data, col_val, col_uncert) } \arguments{ -\item{data}{a table object that is created using the \code{\link{gt}()} -function.} +\item{data}{A table object that is created using the \code{\link[=gt]{gt()}} function.} -\item{col_val}{a single column name that contains the base values.} +\item{col_val}{A single column name that contains the base values.} -\item{col_uncert}{a single column name that contains the uncertainty values.} +\item{col_uncert}{A single column name that contains the uncertainty values.} } \value{ -an object of class \code{gt_tbl}. +An object of class \code{gt_tbl}. } \description{ The \code{cols_merge_uncert()} function is a specialized variant of the -\code{\link{cols_merge}()} function. It operates by taking a base value -column (\code{col_val}) and an uncertainty column (\code{col_uncert}) and -merges them into a single column. What results is a column with values and -associated uncertainties (e.g., \code{12.0 ± 0.1}), and, the column specified -in \code{col_uncert} is dropped from the output table. +\code{\link[=cols_merge]{cols_merge()}} function. It operates by taking a base value column +(\code{col_val}) and an uncertainty column (\code{col_uncert}) and merges them into a +single column. What results is a column with values and associated +uncertainties (e.g., \code{12.0 ± 0.1}), and, the column specified in \code{col_uncert} +is dropped from the output table. } \details{ -This function could be somewhat replicated using \code{\link{cols_merge}()}, -however, \code{cols_merge_uncert()} employs the following specialized -semantics for \code{NA} handling: +This function could be somewhat replicated using \code{\link[=cols_merge]{cols_merge()}}, however, +\code{cols_merge_uncert()} employs the following specialized semantics for \code{NA} +handling: \enumerate{ @@ -44,18 +43,16 @@ missing values for the merged column (e.g., \code{NA} + \code{NA} = \code{NA}) } -Any resulting \code{NA} values in the \code{col_val} column following the -merge operation can be easily formatted using the \code{\link{fmt_missing}()} -function. +Any resulting \code{NA} values in the \code{col_val} column following the merge +operation can be easily formatted using the \code{\link[=fmt_missing]{fmt_missing()}} function. This function is part of a set of three column-merging functions. The other -two are the general \code{\link{cols_merge}()} function and the specialized -\code{\link{cols_merge_range}()} function. These functions operate similarly, -where the second column specified is dropped from the output table. For all -of the \code{cols_merge*()} functions, column removal occurs late in the -rendering lifecycle so those secondary columns are still usable as column -references (e.g., inside expressions provided to `rows` in the \code{fmt*()} -functions). +two are the general \code{\link[=cols_merge]{cols_merge()}} function and the specialized +\code{\link[=cols_merge_range]{cols_merge_range()}} function. These functions operate similarly, where the +second column specified is dropped from the output table. For all of the +\code{cols_merge*()} functions, column removal occurs late in the rendering +lifecycle so those secondary columns are still usable as column references +(e.g., inside expressions provided to \code{rows} in the \code{fmt*()} functions). } \section{Figures}{ diff --git a/man/cols_move.Rd b/man/cols_move.Rd index fab3ab31e5..7a75c44c5c 100644 --- a/man/cols_move.Rd +++ b/man/cols_move.Rd @@ -7,36 +7,34 @@ cols_move(data, columns, after) } \arguments{ -\item{data}{a table object that is created using the \code{\link{gt}()} -function.} +\item{data}{A table object that is created using the \code{\link[=gt]{gt()}} function.} -\item{columns}{the column names to move to as a group to a different +\item{columns}{The column names to move to as a group to a different position. The order of the remaining columns will be preserved.} -\item{after}{a column name used to anchor the insertion of the moved columns. +\item{after}{A column name used to anchor the insertion of the moved columns. All of the moved columns will be placed to the right of this column.} } \value{ -an object of class \code{gt_tbl}. +An object of class \code{gt_tbl}. } \description{ On those occasions where you need to move columns this way or that way, we -can make use of the \code{cols_move()} function. While it's true that the -movement of columns can be done upstream of \pkg{gt}'s API, it is much easier -and less error prone to use the function provided here. The movement -procedure here takes one or more specified columns (in the \code{columns} -argument) and places them to the right of a different column (the -\code{after} argument). The ordering of the \code{columns} to be moved is -preserved, as is the ordering of all other columns in the table. +can make use of the \code{cols_move()} function. While it's true that the movement +of columns can be done upstream of \pkg{gt}'s API, it is much easier and less +error prone to use the function provided here. The movement procedure here +takes one or more specified columns (in the \code{columns} argument) and places +them to the right of a different column (the \code{after} argument). The ordering +of the \code{columns} to be moved is preserved, as is the ordering of all other +columns in the table. } \details{ -The columns supplied in \code{columns} must all exist in the table and none -of them can be in the \code{after} argument. The \code{after} column must -also exist and only one column should be provided here. If you need to place -one or columns at the beginning of the column series, the -\code{\link{cols_move_to_start}()} function should be used. Similarly, if -those columns to move should be placed at the end of the column series then -use \code{\link{cols_move_to_end}()}. +The columns supplied in \code{columns} must all exist in the table and none of +them can be in the \code{after} argument. The \code{after} column must also exist and +only one column should be provided here. If you need to place one or columns +at the beginning of the column series, the \code{\link[=cols_move_to_start]{cols_move_to_start()}} function +should be used. Similarly, if those columns to move should be placed at the +end of the column series then use \code{\link[=cols_move_to_end]{cols_move_to_end()}}. } \section{Figures}{ diff --git a/man/cols_move_to_end.Rd b/man/cols_move_to_end.Rd index 02ec267f36..37131925ef 100644 --- a/man/cols_move_to_end.Rd +++ b/man/cols_move_to_end.Rd @@ -7,30 +7,28 @@ cols_move_to_end(data, columns) } \arguments{ -\item{data}{a table object that is created using the \code{\link{gt}()} -function.} +\item{data}{A table object that is created using the \code{\link[=gt]{gt()}} function.} -\item{columns}{the column names to move to the right-most side of the table. +\item{columns}{The column names to move to the right-most side of the table. The order in which columns are provided will be preserved (as is the case with the remaining columns).} } \value{ -an object of class \code{gt_tbl}. +An object of class \code{gt_tbl}. } \description{ It's possible to move a set of columns to the end of the column series, we -only need to specify which \code{columns} are to be moved. While this can be -done upstream of \pkg{gt}'s API, this function makes to process much easier -and it's less error prone. The ordering of the \code{columns} that are moved -to the end is preserved (same with the ordering of all other columns in the -table). +only need to specify which \code{columns} are to be moved. While this can be done +upstream of \pkg{gt}'s API, this function makes to process much easier and +it's less error prone. The ordering of the \code{columns} that are moved to the +end is preserved (same with the ordering of all other columns in the table). } \details{ -The columns supplied in \code{columns} must all exist in the table. If you -need to place one or columns at the start of the column series, the -\code{\link{cols_move_to_start}()} function should be used. More control is -offered with the \code{\link{cols_move}()} function, where columns could be -placed after a specific column. +The columns supplied in \code{columns} must all exist in the table. If you need to +place one or columns at the start of the column series, the +\code{\link[=cols_move_to_start]{cols_move_to_start()}} function should be used. More control is offered with +the \code{\link[=cols_move]{cols_move()}} function, where columns could be placed after a specific +column. } \section{Figures}{ diff --git a/man/cols_move_to_start.Rd b/man/cols_move_to_start.Rd index 9d598395ac..91c6987a64 100644 --- a/man/cols_move_to_start.Rd +++ b/man/cols_move_to_start.Rd @@ -7,30 +7,29 @@ cols_move_to_start(data, columns) } \arguments{ -\item{data}{a table object that is created using the \code{\link{gt}()} -function.} +\item{data}{A table object that is created using the \code{\link[=gt]{gt()}} function.} -\item{columns}{the column names to move to the left-most side of the table. +\item{columns}{The column names to move to the left-most side of the table. The order in which columns are provided will be preserved (as is the case with the remaining columns).} } \value{ -an object of class \code{gt_tbl}. +An object of class \code{gt_tbl}. } \description{ We can easily move set of columns to the beginning of the column series and -we only need to specify which \code{columns}. It's possible to do this -upstream of \pkg{gt}'s API, however, it is easier with this function and it -presents less possibility for error. The ordering of the \code{columns} that -are moved to the start is preserved (same with the ordering of all other -columns in the table). +we only need to specify which \code{columns}. It's possible to do this upstream of +\pkg{gt}'s API, however, it is easier with this function and it presents less +possibility for error. The ordering of the \code{columns} that are moved to the +start is preserved (same with the ordering of all other columns in the +table). } \details{ -The columns supplied in \code{columns} must all exist in the table. If you -need to place one or columns at the end of the column series, the -\code{\link{cols_move_to_end}()} function should be used. More control is -offered with the \code{\link{cols_move}()} function, where columns could be -placed after a specific column. +The columns supplied in \code{columns} must all exist in the table. If you need to +place one or columns at the end of the column series, the +\code{\link[=cols_move_to_end]{cols_move_to_end()}} function should be used. More control is offered with +the \code{\link[=cols_move]{cols_move()}} function, where columns could be placed after a specific +column. } \section{Figures}{ diff --git a/man/cols_split_delim.Rd b/man/cols_split_delim.Rd index 60ee95082a..4889862950 100644 --- a/man/cols_split_delim.Rd +++ b/man/cols_split_delim.Rd @@ -7,19 +7,18 @@ cols_split_delim(data, delim, columns = NULL) } \arguments{ -\item{data}{a table object that is created using the \code{\link{gt}()} -function.} +\item{data}{A table object that is created using the \code{\link[=gt]{gt()}} function.} -\item{delim}{the delimiter to use to split an input column name. The +\item{delim}{The delimiter to use to split an input column name. The delimiter supplied will be autoescaped for the internal splitting procedure. The first component of the split will become the group name and the second component will be the column label.} -\item{columns}{an optional vector of column names that this operation should +\item{columns}{An optional vector of column names that this operation should be limited to. The default is to consider all columns in the table.} } \value{ -an object of class \code{gt_tbl}. +An object of class \code{gt_tbl}. } \description{ This function will split selected delimited column names such that the first @@ -29,17 +28,16 @@ reference to individual columns must continue to be the column names from the input table data (which are unique by necessity). } \details{ -If we look to the column names in the \code{iris} dataset as an example of -how \code{cols_split_delim()} might be useful, we find the names -\code{Sepal.Length}, \code{Sepal.Width}, \code{Petal.Length}, -\code{Petal.Width}. From this naming system, it's easy to see that the -\code{Sepal} and \code{Petal} can group together the repeated common -\code{Length} and \code{Width} values. In your own datasets, we can avoid a -lengthy relabeling with \code{\link{cols_label}()} if column names can be -fashioned beforehand to contain both the spanner column label and the column -label. An additional advantage is that the column names in the input table -data remain unique even though there may eventually be repeated column labels -in the rendered output table). +If we look to the column names in the \code{iris} dataset as an example of how +\code{cols_split_delim()} might be useful, we find the names \code{Sepal.Length}, +\code{Sepal.Width}, \code{Petal.Length}, \code{Petal.Width}. From this naming system, it's +easy to see that the \code{Sepal} and \code{Petal} can group together the repeated +common \code{Length} and \code{Width} values. In your own datasets, we can avoid a +lengthy relabeling with \code{\link[=cols_label]{cols_label()}} if column names can be fashioned +beforehand to contain both the spanner column label and the column label. An +additional advantage is that the column names in the input table data remain +unique even though there may eventually be repeated column labels in the +rendered output table). } \section{Figures}{ diff --git a/man/countrypops.Rd b/man/countrypops.Rd index 6db177799a..ed61eaa095 100644 --- a/man/countrypops.Rd +++ b/man/countrypops.Rd @@ -6,11 +6,11 @@ \title{Yearly populations of countries from 1960 to 2017} \format{A tibble with 12470 rows and 5 variables: \describe{ - \item{country_name}{Name of the country} - \item{country_code_2}{The 2-letter ISO 3166-1 country code} - \item{country_code_3}{The 3-letter ISO 3166-1 country code} - \item{year}{The year for the population estimate} - \item{population}{The population estimate, midway through the year} +\item{country_name}{Name of the country} +\item{country_code_2}{The 2-letter ISO 3166-1 country code} +\item{country_code_3}{The 3-letter ISO 3166-1 country code} +\item{year}{The year for the population estimate} +\item{population}{The population estimate, midway through the year} }} \source{ \url{https://data.worldbank.org/indicator/SP.POP.TOTL} @@ -23,9 +23,8 @@ A dataset that presents yearly, total populations of countries. Total population is based on counts of all residents regardless of legal status or citizenship. Country identifiers include the English-language country names, and the 2- and 3-letter ISO 3166-1 country codes. Each row contains a -\code{population} value for a given \code{year} (from 1960 to 2017). Any -\code{NA} values for \code{populations} indicate the non-existence of the -country during that year. +\code{population} value for a given \code{year} (from 1960 to 2017). Any \code{NA} values +for \code{populations} indicate the non-existence of the country during that year. } \examples{ # Here is a glimpse at the data diff --git a/man/data_color.Rd b/man/data_color.Rd index 69e8d5c709..ab1be49495 100644 --- a/man/data_color.Rd +++ b/man/data_color.Rd @@ -8,12 +8,11 @@ data_color(data, columns, colors, alpha = NULL, apply_to = "bkgd", autocolor_text = TRUE) } \arguments{ -\item{data}{A table object that is created using the \code{\link{gt}()} -function.} +\item{data}{A table object that is created using the \code{\link[=gt]{gt()}} function.} -\item{columns}{the columns wherein changes to cell data colors should occur.} +\item{columns}{The columns wherein changes to cell data colors should occur.} -\item{colors}{either a color mapping function from the \code{scales} package +\item{colors}{Either a color mapping function from the \code{scales} package or a vector of colors to use for each distinct value or level in each of the provided \code{columns}. The color mapping functions are: \code{scales::col_quantile()}, \code{scales::col_bin()}, @@ -22,51 +21,51 @@ a vector of colors as a palette, each color value provided must either be a color name (in the set of colors provided by \code{grDevices::colors()}) or a hexadecimal string in the form of "#RRGGBB" or "#RRGGBBAA".} -\item{alpha}{an optional, fixed alpha transparency value that will be applied +\item{alpha}{An optional, fixed alpha transparency value that will be applied to all of the \code{colors} provided if they are provided as a vector of colors. If using a colorizing helper function for \code{colors} then this option is ignored (each of the colorizing helper functions has its own \code{alpha} argument).} -\item{apply_to}{which style element should the colors be applied to? Options +\item{apply_to}{Which style element should the colors be applied to? Options include the cell background (the default, given as \code{bkgd}) or the cell text (\code{text}).} -\item{autocolor_text}{an option to let \pkg{gt} modify the coloring of text +\item{autocolor_text}{An option to let \pkg{gt} modify the coloring of text within cells undergoing background coloring. This will in some cases yield more optimal text-to-background color contrast. By default, this is set to \code{TRUE}.} } \value{ -an object of class \code{gt_tbl}. +An object of class \code{gt_tbl}. } \description{ It's possible to add color to data cells according to their values. The -\code{data_color()} function colors all rows of any \code{columns} supplied. -There are two ways to define how cells are colored: (1) through the use of a -supplied color palette, and (2) through use of a color mapping function -available from the \code{scales} package. The first method colorizes cell -data according to whether values are character or numeric. The second method -provides more control over how cells are colored since we provide an explicit -color function and thus other requirements such as bin counts, cut points, or -a numeric domain. Finally, we can choose whether to apply the cell-specific +\code{data_color()} function colors all rows of any \code{columns} supplied. There are +two ways to define how cells are colored: (1) through the use of a supplied +color palette, and (2) through use of a color mapping function available from +the \code{scales} package. The first method colorizes cell data according to +whether values are character or numeric. The second method provides more +control over how cells are colored since we provide an explicit color +function and thus other requirements such as bin counts, cut points, or a +numeric domain. Finally, we can choose whether to apply the cell-specific colors to either the cell background or the cell text. } \details{ -The \code{col_*()} functions from the scales package can be used in the -\code{colors} argument. These functions map data values (\code{numeric} or -\code{factor}/\code{character}) to colors according to the provided palette. +The \code{col_*()} functions from the scales package can be used in the \code{colors} +argument. These functions map data values (\code{numeric} or \code{factor}/\code{character}) +to colors according to the provided palette. \itemize{ -\item \code{\link[scales]{col_numeric}()}: provides a simple linear mapping +\item \code{\link[scales:col_numeric]{scales::col_numeric()}}: provides a simple linear mapping from continuous numeric data to an interpolated palette. -\item \code{\link[scales]{col_bin}()}: provides a mapping of continuous +\item \code{\link[scales:col_bin]{scales::col_bin()}}: provides a mapping of continuous numeric data to value-based bins. This internally uses the -\code{\link[base]{cut}()} function. -\item \code{\link[scales]{col_quantile}()}: provides a mapping of continuous +\code{\link[base:cut]{base::cut()}} function. +\item \code{\link[scales:col_quantile]{scales::col_quantile()}}: provides a mapping of continuous numeric data to quantiles. This internally uses the -\code{\link[stats]{quantile}()} function. -\item \code{\link[scales]{col_factor}()}: provides a mapping of factors to +\code{\link[stats:quantile]{stats::quantile()}} function. +\item \code{\link[scales:col_factor]{scales::col_factor()}}: provides a mapping of factors to colors. If the palette is discrete and has a different number of colors than the number of factors, interpolation is used. } @@ -79,11 +78,11 @@ Choosing the right color palette can often be difficult because it's both hard to discover suitable palettes and then obtain the vector of colors. To make this process easier we can elect to use the \pkg{paletteer} package, which makes a wide range of palettes from various R packages readily -available. The \code{\link{info_paletteer}()} information table allows us to -easily inspect all of the discrete color palettes available in -\pkg{paletteer}. We only then need to specify the \code{package} and -\code{palette} when calling the \code{paletteer::paletteer_d()} function, -and, we get the palette as a vector of hexadecimal colors. +available. The \code{\link[=info_paletteer]{info_paletteer()}} information table allows us to easily +inspect all of the discrete color palettes available in \pkg{paletteer}. We +only then need to specify the \code{package} and \code{palette} when calling the +\code{paletteer::paletteer_d()} function, and, we get the palette as a vector of +hexadecimal colors. } \section{Figures}{ diff --git a/man/exibble.Rd b/man/exibble.Rd index ba8624e04b..787483cfbb 100644 --- a/man/exibble.Rd +++ b/man/exibble.Rd @@ -6,19 +6,19 @@ \title{A toy example tibble for testing with gt: exibble} \format{A tibble with 8 rows and 9 variables: \describe{ - \item{num}{a numeric column ordered with increasingly larger values} - \item{char}{a character column composed of names of fruits from \code{a} to - \code{h}} - \item{fctr}{a factor column with numbers from 1 to 8, written out} - \item{date, time, datetime}{character columns with dates, times, and - datetimes} - \item{currency}{a numeric column that is useful for testing currency-based - formatting} - \item{row}{a character column in the format \code{row_X} which can be - useful for testing with row captions in a table stub} - \item{group}{a character column with four \code{grp_a} values and four - \code{grp_b} values which can be useful for testing tables that contain - row groups} +\item{num}{a numeric column ordered with increasingly larger values} +\item{char}{a character column composed of names of fruits from \code{a} to +\code{h}} +\item{fctr}{a factor column with numbers from 1 to 8, written out} +\item{date, time, datetime}{character columns with dates, times, and +datetimes} +\item{currency}{a numeric column that is useful for testing currency-based +formatting} +\item{row}{a character column in the format \code{row_X} which can be +useful for testing with row captions in a table stub} +\item{group}{a character column with four \code{grp_a} values and four +\code{grp_b} values which can be useful for testing tables that contain +row groups} }} \usage{ exibble @@ -27,12 +27,11 @@ exibble This tibble contains data of a few different classes, which makes it well-suited for quick experimentation with the functions in this package. It contains only eight rows with numeric, character, and factor columns. The -last 4 rows contain \code{NA} values in the majority of this tibble's columns -(1 missing value per column). The \code{date}, \code{time}, and -\code{datetime} columns are character-based dates/times in the familiar ISO -8601 format. The \code{row} and \code{group} columns provide for unique -rownames and two groups (\code{grp_a} and \code{grp_b}) for experimenting -with the \code{\link{gt}()} function's \code{rowname_col} and +last 4 rows contain \code{NA} values in the majority of this tibble's columns (1 +missing value per column). The \code{date}, \code{time}, and \code{datetime} columns are +character-based dates/times in the familiar ISO 8601 format. The \code{row} and +\code{group} columns provide for unique rownames and two groups (\code{grp_a} and +\code{grp_b}) for experimenting with the \code{\link[=gt]{gt()}} function's \code{rowname_col} and \code{groupname_col} arguments. } \examples{ diff --git a/man/extract_summary.Rd b/man/extract_summary.Rd index b361f15dea..cd9924dc3f 100644 --- a/man/extract_summary.Rd +++ b/man/extract_summary.Rd @@ -7,7 +7,7 @@ extract_summary(data) } \arguments{ -\item{data}{a table object that is created using the \code{\link{gt}()} +\item{data}{a table object that is created using the \code{\link[=gt]{gt()}} function.} } \value{ @@ -15,7 +15,7 @@ a list of data frames containing summary data. } \description{ Get a list of summary row data frames from a \code{gt_tbl} object where -summary rows were added via the \code{\link{summary_rows}()} function. The +summary rows were added via the \code{\link[=summary_rows]{summary_rows()}} function. The output data frames contain the \code{groupname} and \code{rowname} columns, whereby \code{rowname} contains descriptive stub labels for the summary rows. } diff --git a/man/fmt.Rd b/man/fmt.Rd index 7b3fc6fe21..8b6728135f 100644 --- a/man/fmt.Rd +++ b/man/fmt.Rd @@ -7,24 +7,20 @@ fmt(data, columns = NULL, rows = NULL, fns) } \arguments{ -\item{data}{A table object that is created using the \code{\link{gt}()} -function.} +\item{data}{A table object that is created using the \code{\link[=gt]{gt()}} function.} \item{columns}{The columns to format. Can either be a series of column names -provided in \code{vars()}, a vector of column indices, or a helper function -focused on selections. The select helper functions are: -\code{\link{starts_with}()}, \code{\link{ends_with}()}, -\code{\link{contains}()}, \code{\link{matches}()}, \code{\link{one_of}()}, -and \code{\link{everything}()}.} +provided in \code{\link[=vars]{vars()}}, a vector of column indices, or a helper function +focused on selections. The select helper functions are: \code{\link[=starts_with]{starts_with()}}, +\code{\link[=ends_with]{ends_with()}}, \code{\link[=contains]{contains()}}, \code{\link[=matches]{matches()}}, \code{\link[=one_of]{one_of()}}, and \code{\link[=everything]{everything()}}.} \item{rows}{Optional rows to format. Not providing any value results in all -rows in \code{columns} being formatted. Can either be a vector of row -captions provided \code{c()}, a vector of row indices, or a helper function -focused on selections. The select helper functions are: -\code{\link{starts_with}()}, \code{\link{ends_with}()}, -\code{\link{contains}()}, \code{\link{matches}()}, \code{\link{one_of}()}, -and \code{\link{everything}()}. We can also use expressions to filter down -to the rows we need (e.g., \code{[colname_1] > 100 & [colname_2] < 50}).} +rows in \code{columns} being formatted. Can either be a vector of row captions +provided \code{\link[=c]{c()}}, a vector of row indices, or a helper function focused on +selections. The select helper functions are: \code{\link[=starts_with]{starts_with()}}, +\code{\link[=ends_with]{ends_with()}}, \code{\link[=contains]{contains()}}, \code{\link[=matches]{matches()}}, \code{\link[=one_of]{one_of()}}, and \code{\link[=everything]{everything()}}. +We can also use expressions to filter down to the rows we need (e.g., +\code{[colname_1] > 100 & [colname_2] < 50}).} \item{fns}{Either a single formatting function or a named list of functions.} } @@ -32,32 +28,30 @@ to the rows we need (e.g., \code{[colname_1] > 100 & [colname_2] < 50}).} An object of class \code{gt_tbl}. } \description{ -The \code{fmt()} function provides greater control in formatting raw data -values than any of the specialized \code{fmt_*()} functions that are -available in \pkg{gt}. Along with the \code{columns} and \code{rows} -arguments that provide some precision in targeting data cells, the \code{fns} -argument allows you to define one or more functions for manipulating the raw -data. +The \code{fmt()} function provides greater control in formatting raw data values +than any of the specialized \code{fmt_*()} functions that are available in +\pkg{gt}. Along with the \code{columns} and \code{rows} arguments that provide some +precision in targeting data cells, the \code{fns} argument allows you to define +one or more functions for manipulating the raw data. } \details{ -If providing a single function to \code{fns}, the recommended format is in -the form: \code{fns = function(x) ...}. This single function will format the -targeted data cells the same way regardless of the output format (e.g., HTML, -LaTeX, RTF). +If providing a single function to \code{fns}, the recommended format is in the +form: \code{fns = function(x) ...}. This single function will format the targeted +data cells the same way regardless of the output format (e.g., HTML, LaTeX, +RTF). -If you require formatting of \code{x} that depends on the output format, a -list of functions can be provided for the \code{html}, \code{latex}, and -\code{default} contexts. This can be in the form of \code{fns = list(html = -function(x) ..., latex = function(x) ..., default = function(x) ...)}. In -this multiple-function case, we recommended including the \code{default} -function as a fallback if all contexts aren't provided. +If you require formatting of \code{x} that depends on the output format, a list of +functions can be provided for the \code{html}, \code{latex}, and \code{default} contexts. +This can be in the form of \code{fns = list(html = function(x) ..., latex = function(x) ..., default = function(x) ...)}. In this multiple-function case, +we recommended including the \code{default} function as a fallback if all contexts +aren't provided. -As with all of the \code{fmt_*()} functions, targeting of values is done -through \code{columns} and additionally by \code{rows} (if nothing is -provided for \code{rows} then entire columns are selected). A number of -helper functions exist to make targeting more effective. Conditional -formatting is possible by providing a conditional expression to the -\code{rows} argument. See the Arguments section for more information on this. +As with all of the \code{fmt_*()} functions, targeting of values is done through +\code{columns} and additionally by \code{rows} (if nothing is provided for \code{rows} then +entire columns are selected). A number of helper functions exist to make +targeting more effective. Conditional formatting is possible by providing a +conditional expression to the \code{rows} argument. See the Arguments section for +more information on this. } \section{Figures}{ diff --git a/man/fmt_currency.Rd b/man/fmt_currency.Rd index e828856699..e31e8f78be 100644 --- a/man/fmt_currency.Rd +++ b/man/fmt_currency.Rd @@ -11,43 +11,37 @@ fmt_currency(data, columns, rows = NULL, currency = "USD", placement = "left", incl_space = FALSE, locale = NULL) } \arguments{ -\item{data}{A table object that is created using the \code{\link{gt}()} -function.} +\item{data}{A table object that is created using the \code{\link[=gt]{gt()}} function.} \item{columns}{The columns to format. Can either be a series of column names -provided in \code{vars()}, a vector of column indices, or a helper function -focused on selections. The select helper functions are: -\code{\link{starts_with}()}, \code{\link{ends_with}()}, -\code{\link{contains}()}, \code{\link{matches}()}, \code{\link{one_of}()}, -and \code{\link{everything}()}.} +provided in \code{\link[=vars]{vars()}}, a vector of column indices, or a helper function +focused on selections. The select helper functions are: \code{\link[=starts_with]{starts_with()}}, +\code{\link[=ends_with]{ends_with()}}, \code{\link[=contains]{contains()}}, \code{\link[=matches]{matches()}}, \code{\link[=one_of]{one_of()}}, and \code{\link[=everything]{everything()}}.} \item{rows}{Optional rows to format. Not providing any value results in all -rows in \code{columns} being formatted. Can either be a vector of row -captions provided \code{c()}, a vector of row indices, or a helper function -focused on selections. The select helper functions are: -\code{\link{starts_with}()}, \code{\link{ends_with}()}, -\code{\link{contains}()}, \code{\link{matches}()}, \code{\link{one_of}()}, -and \code{\link{everything}()}. We can also use expressions to filter down -to the rows we need (e.g., \code{[colname_1] > 100 & [colname_2] < 50}).} +rows in \code{columns} being formatted. Can either be a vector of row captions +provided \code{\link[=c]{c()}}, a vector of row indices, or a helper function focused on +selections. The select helper functions are: \code{\link[=starts_with]{starts_with()}}, +\code{\link[=ends_with]{ends_with()}}, \code{\link[=contains]{contains()}}, \code{\link[=matches]{matches()}}, \code{\link[=one_of]{one_of()}}, and \code{\link[=everything]{everything()}}. +We can also use expressions to filter down to the rows we need (e.g., +\code{[colname_1] > 100 & [colname_2] < 50}).} \item{currency}{The currency to use for the numeric value. This input can be supplied as a 3-letter currency code (e.g., \code{"USD"} for U.S. Dollars, -\code{"EUR"} for the Euro currency). Use \code{\link{info_currencies}()} to -get an information table with all of the valid currency codes and examples -of each. Alternatively, we can provide a common currency name (e.g., -\code{"dollar"}, \code{"pound"}, \code{"yen"}, etc.) to simplify the -process. Use \code{\link{info_currencies}()} with the \code{type == -"symbol"} option to view an information table with all of the supported -currency symbol names along with examples. If nothing is provided then -\code{"USD"} will be used.} +\code{"EUR"} for the Euro currency). Use \code{\link[=info_currencies]{info_currencies()}} to get an +information table with all of the valid currency codes and examples of +each. Alternatively, we can provide a common currency name (e.g., +\code{"dollar"}, \code{"pound"}, \code{"yen"}, etc.) to simplify the process. Use +\code{\link[=info_currencies]{info_currencies()}} with the \code{type == "symbol"} option to view an +information table with all of the supported currency symbol names along +with examples. If nothing is provided then \code{"USD"} will be used.} \item{use_subunits}{An option for whether the subunits portion of a currency value should be displayed.} \item{accounting}{An option to use accounting style for currency values. With -\code{FALSE} (the default), negative values will be shown with a negative -sign. Using \code{accounting = TRUE} will put negative values in -parentheses.} +\code{FALSE} (the default), negative values will be shown with a minus sign. +Using \code{accounting = TRUE} will put negative values in parentheses.} \item{decimals}{An option to specify the exact number of decimal places to use. The default number of decimal places is \code{2}.} @@ -56,38 +50,35 @@ use. The default number of decimal places is \code{2}.} group separator is set by \code{sep_mark} and overridden if a locale ID is provided to \code{locale}. This setting is \code{TRUE} by default.} -\item{scale_by}{A value to scale the input. The default is \code{1.0}. All -numeric values will be multiplied by this value first before undergoing -formatting. This value will be ignored if using any of the \code{suffixing} -options (i.e., where \code{suffixing} is not set to \code{FALSE}).} +\item{scale_by}{A value to scale the input. The default is \code{1.0}. All numeric +values will be multiplied by this value first before undergoing formatting. +This value will be ignored if using any of the \code{suffixing} options (i.e., +where \code{suffixing} is not set to \code{FALSE}).} \item{suffixing}{An option to scale and apply suffixes to larger numbers -(e.g., \code{1924000} can be transformed to \code{1.92M}). This option can -accept a logical value, where \code{FALSE} (the default) will not perform -this transformation and \code{TRUE} will apply thousands (\code{K}), -millions (\code{M}), billions (\code{B}), and trillions (\code{T}) suffixes -after automatic value scaling. We can also specify which symbols to use for -each of the value ranges by using a character vector of the preferred -symbols to replace the defaults (e.g., \code{c("k", "Ml", "Bn", "Tr")}). -Including \code{NA} values in the vector will ensure that the particular -range will either not be included in the transformation (e.g, \code{c(NA, -"M", "B", "T")} won't modify numbers in the thousands range) or the range -will inherit a previous suffix (e.g., with \code{c("K", "M", NA, "T")}, all -numbers in the range of millions and billions will be in terms of -millions). Any use of \code{suffixing} (where not \code{FALSE}) means that -any value provided to \code{scale_by} will be ignored.} +(e.g., \code{1924000} can be transformed to \code{1.92M}). This option can accept a +logical value, where \code{FALSE} (the default) will not perform this +transformation and \code{TRUE} will apply thousands (\code{K}), millions (\code{M}), +billions (\code{B}), and trillions (\code{T}) suffixes after automatic value scaling. +We can also specify which symbols to use for each of the value ranges by +using a character vector of the preferred symbols to replace the defaults +(e.g., \code{c("k", "Ml", "Bn", "Tr")}). Including \code{NA} values in the vector +will ensure that the particular range will either not be included in the +transformation (e.g, \code{c(NA, "M", "B", "T")} won't modify numbers in the +thousands range) or the range will inherit a previous suffix (e.g., with +\code{c("K", "M", NA, "T")}, all numbers in the range of millions and billions +will be in terms of millions). Any use of \code{suffixing} (where not \code{FALSE}) +means that any value provided to \code{scale_by} will be ignored.} \item{pattern}{A formatting pattern that allows for decoration of the -formatted value. The value itself is represented by \code{{x}} and all -other characters are taken to be string literals.} +formatted value. The value itself is represented by \code{{x}} and all other +characters are taken to be string literals.} \item{sep_mark}{The mark to use as a separator between groups of digits -(e.g., using \code{sep_mark = ","} with \code{1000} would result in a -formatted value of \code{1,000}).} +(e.g., using \code{sep_mark = ","} with \code{1000} would result in a formatted value +of \code{1,000}).} -\item{dec_mark}{The character to use as a decimal mark (e.g., using -\code{dec_mark = ","} with \code{0.152} would result in a formatted value -of \code{0,152}).} +\item{dec_mark}{The character to use as a decimal mark (e.g., using \code{dec_mark = ","} with \code{0.152} would result in a formatted value of \code{0,152}).} \item{placement}{The placement of the currency symbol. This can be either be \code{left} (the default) or \code{right}.} @@ -98,9 +89,9 @@ and the currency symbol. The default is to not introduce a space character.} \item{locale}{An optional locale ID that can be used for formatting the value according the locale's rules. Examples include \code{"en_US"} for English (United States) and \code{"fr_FR"} for French (France). The use of a valid -locale ID will override any values provided in \code{sep_mark} and -\code{dec_mark}. We can use the \code{\link{info_locales}()} function as a -useful reference for all of the locales that are supported.} +locale ID will override any values provided in \code{sep_mark} and \code{dec_mark}. +We can use the \code{\link[=info_locales]{info_locales()}} function as a useful reference for all of +the locales that are supported.} } \value{ An object of class \code{gt_tbl}. @@ -133,15 +124,14 @@ currency formatting specific to the chosen locale } } \details{ -We can use the \code{\link{info_currencies}()} function for a useful -reference on all of the possible inputs to \code{currency}. - -Targeting of values is done through \code{columns} and additionally by -\code{rows} (if nothing is provided for \code{rows} then entire columns are -selected). A number of helper functions exist to make targeting more -effective. Conditional formatting is possible by providing a conditional -expression to the \code{rows} argument. See the Arguments section for more -information on this. +We can use the \code{\link[=info_currencies]{info_currencies()}} function for a useful reference on all of +the possible inputs to the \code{currency} argument. + +Targeting of values is done through \code{columns} and additionally by \code{rows} (if +nothing is provided for \code{rows} then entire columns are selected). A number of +helper functions exist to make targeting more effective. Conditional +formatting is possible by providing a conditional expression to the \code{rows} +argument. See the Arguments section for more information on this. } \section{Figures}{ diff --git a/man/fmt_date.Rd b/man/fmt_date.Rd index 413237405a..f958c035db 100644 --- a/man/fmt_date.Rd +++ b/man/fmt_date.Rd @@ -7,29 +7,24 @@ fmt_date(data, columns, rows = NULL, date_style = 2) } \arguments{ -\item{data}{A table object that is created using the \code{\link{gt}()} -function.} +\item{data}{A table object that is created using the \code{\link[=gt]{gt()}} function.} \item{columns}{The columns to format. Can either be a series of column names -provided in \code{vars()}, a vector of column indices, or a helper function -focused on selections. The select helper functions are: -\code{\link{starts_with}()}, \code{\link{ends_with}()}, -\code{\link{contains}()}, \code{\link{matches}()}, \code{\link{one_of}()}, -and \code{\link{everything}()}.} +provided in \code{\link[=vars]{vars()}}, a vector of column indices, or a helper function +focused on selections. The select helper functions are: \code{\link[=starts_with]{starts_with()}}, +\code{\link[=ends_with]{ends_with()}}, \code{\link[=contains]{contains()}}, \code{\link[=matches]{matches()}}, \code{\link[=one_of]{one_of()}}, and \code{\link[=everything]{everything()}}.} \item{rows}{Optional rows to format. Not providing any value results in all -rows in \code{columns} being formatted. Can either be a vector of row -captions provided \code{c()}, a vector of row indices, or a helper function -focused on selections. The select helper functions are: -\code{\link{starts_with}()}, \code{\link{ends_with}()}, -\code{\link{contains}()}, \code{\link{matches}()}, \code{\link{one_of}()}, -and \code{\link{everything}()}. We can also use expressions to filter down -to the rows we need (e.g., \code{[colname_1] > 100 & [colname_2] < 50}).} +rows in \code{columns} being formatted. Can either be a vector of row captions +provided \code{\link[=c]{c()}}, a vector of row indices, or a helper function focused on +selections. The select helper functions are: \code{\link[=starts_with]{starts_with()}}, +\code{\link[=ends_with]{ends_with()}}, \code{\link[=contains]{contains()}}, \code{\link[=matches]{matches()}}, \code{\link[=one_of]{one_of()}}, and \code{\link[=everything]{everything()}}. +We can also use expressions to filter down to the rows we need (e.g., +\code{[colname_1] > 100 & [colname_2] < 50}).} -\item{date_style}{The date style to use. Supply a number (from \code{1} to -\code{14}) that corresponds to the preferred date style. Use -\code{\link{info_date_style}()} to see the different numbered and named date -presets.} +\item{date_style}{The date style to use. Supply a number (from \code{1} to \code{14}) +that corresponds to the preferred date style. Use \code{\link[=info_date_style]{info_date_style()}} to +see the different numbered and named date presets.} } \value{ An object of class \code{gt_tbl}. @@ -37,10 +32,9 @@ An object of class \code{gt_tbl}. \description{ Format input date values that are either of the \code{Date} type, or, are character-based and expressed according to the ISO 8601 date format -(\code{YYYY-MM-DD}). Once the appropriate data cells are targeted with -\code{columns} (and, optionally, \code{rows}), we can simply apply a preset -date style (see table in \code{\link{info_date_style}()} for info) to format -the dates. +(\code{YYYY-MM-DD}). Once the appropriate data cells are targeted with \code{columns} +(and, optionally, \code{rows}), we can simply apply a preset date style (see table +in \code{\link[=info_date_style]{info_date_style()}} for info) to format the dates. } \details{ The following date styles are available for simpler formatting of ISO dates @@ -63,15 +57,14 @@ The following date styles are available for simpler formatting of ISO dates \item y.mn.day: \code{0/02/29} } -We can use the \code{\link{info_date_style}()} function for a useful -reference on all of the possible inputs to \code{date_style}. +We can use the \code{\link[=info_date_style]{info_date_style()}} function for a useful reference on all of +the possible inputs to \code{date_style}. -Targeting of values is done through \code{columns} and additionally by -\code{rows} (if nothing is provided for \code{rows} then entire columns are -selected). A number of helper functions exist to make targeting more -effective. Conditional formatting is possible by providing a conditional -expression to the \code{rows} argument. See the Arguments section for more -information on this. +Targeting of values is done through \code{columns} and additionally by \code{rows} (if +nothing is provided for \code{rows} then entire columns are selected). A number of +helper functions exist to make targeting more effective. Conditional +formatting is possible by providing a conditional expression to the \code{rows} +argument. See the Arguments section for more information on this. } \section{Figures}{ diff --git a/man/fmt_datetime.Rd b/man/fmt_datetime.Rd index b778472de9..6fded89bcf 100644 --- a/man/fmt_datetime.Rd +++ b/man/fmt_datetime.Rd @@ -8,45 +8,39 @@ fmt_datetime(data, columns, rows = NULL, date_style = 2, time_style = 2) } \arguments{ -\item{data}{A table object that is created using the \code{\link{gt}()} -function.} +\item{data}{A table object that is created using the \code{\link[=gt]{gt()}} function.} \item{columns}{The columns to format. Can either be a series of column names -provided in \code{vars()}, a vector of column indices, or a helper function -focused on selections. The select helper functions are: -\code{\link{starts_with}()}, \code{\link{ends_with}()}, -\code{\link{contains}()}, \code{\link{matches}()}, \code{\link{one_of}()}, -and \code{\link{everything}()}.} +provided in \code{\link[=vars]{vars()}}, a vector of column indices, or a helper function +focused on selections. The select helper functions are: \code{\link[=starts_with]{starts_with()}}, +\code{\link[=ends_with]{ends_with()}}, \code{\link[=contains]{contains()}}, \code{\link[=matches]{matches()}}, \code{\link[=one_of]{one_of()}}, and \code{\link[=everything]{everything()}}.} \item{rows}{Optional rows to format. Not providing any value results in all -rows in \code{columns} being formatted. Can either be a vector of row -captions provided \code{c()}, a vector of row indices, or a helper function -focused on selections. The select helper functions are: -\code{\link{starts_with}()}, \code{\link{ends_with}()}, -\code{\link{contains}()}, \code{\link{matches}()}, \code{\link{one_of}()}, -and \code{\link{everything}()}. We can also use expressions to filter down -to the rows we need (e.g., \code{[colname_1] > 100 & [colname_2] < 50}).} +rows in \code{columns} being formatted. Can either be a vector of row captions +provided \code{\link[=c]{c()}}, a vector of row indices, or a helper function focused on +selections. The select helper functions are: \code{\link[=starts_with]{starts_with()}}, +\code{\link[=ends_with]{ends_with()}}, \code{\link[=contains]{contains()}}, \code{\link[=matches]{matches()}}, \code{\link[=one_of]{one_of()}}, and \code{\link[=everything]{everything()}}. +We can also use expressions to filter down to the rows we need (e.g., +\code{[colname_1] > 100 & [colname_2] < 50}).} -\item{date_style}{The date style to use. Supply a number (from \code{1} to -\code{14}) that corresponds to the preferred date style. Use -\code{\link{info_date_style}()} to see the different numbered and named date -presets.} +\item{date_style}{The date style to use. Supply a number (from \code{1} to \code{14}) +that corresponds to the preferred date style. Use \code{\link[=info_date_style]{info_date_style()}} to +see the different numbered and named date presets.} -\item{time_style}{The time style to use. Supply a number (from \code{1} to -\code{5}) that corresponds to the preferred time style. Use -\code{\link{info_time_style}()} to see the different numbered and named time -presets.} +\item{time_style}{The time style to use. Supply a number (from \code{1} to \code{5}) +that corresponds to the preferred time style. Use \code{\link[=info_time_style]{info_time_style()}} to +see the different numbered and named time presets.} } \value{ An object of class \code{gt_tbl}. } \description{ Format input date-time values that are character-based and expressed -according to the ISO 8601 date-time format (\code{YYYY-MM-DD HH:MM:SS}). Once -the appropriate data cells are targeted with \code{columns} (and, optionally, -\code{rows}), we can simply apply preset date and time styles (see tables in -\code{\link{info_date_style}()} and \code{\link{info_time_style}()} for more -info) to format the data-time values. +according to the ISO 8601 date-time format (\code{YYYY-MM-DD HH:MM:SS}). Once the +appropriate data cells are targeted with \code{columns} (and, optionally, \code{rows}), +we can simply apply preset date and time styles (see tables in +\code{\link[=info_date_style]{info_date_style()}} and \code{\link[=info_time_style]{info_time_style()}} for more info) to format the +data-time values. } \details{ The following date styles are available for simpler formatting of the date @@ -71,8 +65,7 @@ dates): } The following time styles are available for simpler formatting of the time -portion (all using the input time of \code{14:35:00} in the example output -times): +portion (all using the input time of \code{14:35:00} in the example output times): \enumerate{ \item hms: \code{14:35:00} @@ -82,16 +75,15 @@ times): \item h_p: \code{2 PM} } -We can use the \code{\link{info_date_style}()} and -\code{\link{info_time_style}()} functions as useful references for all of the -possible inputs to \code{date_style} and \code{time_style}. +We can use the \code{\link[=info_date_style]{info_date_style()}} and \code{\link[=info_time_style]{info_time_style()}} functions as +useful references for all of the possible inputs to \code{date_style} and +\code{time_style}. -Targeting of values is done through \code{columns} and additionally by -\code{rows} (if nothing is provided for \code{rows} then entire columns are -selected). A number of helper functions exist to make targeting more -effective. Conditional formatting is possible by providing a conditional -expression to the \code{rows} argument. See the Arguments section for more -information on this. +Targeting of values is done through \code{columns} and additionally by \code{rows} (if +nothing is provided for \code{rows} then entire columns are selected). A number of +helper functions exist to make targeting more effective. Conditional +formatting is possible by providing a conditional expression to the \code{rows} +argument. See the Arguments section for more information on this. } \section{Figures}{ diff --git a/man/fmt_markdown.Rd b/man/fmt_markdown.Rd index c5b6e6acbb..c989f8cc49 100644 --- a/man/fmt_markdown.Rd +++ b/man/fmt_markdown.Rd @@ -7,24 +7,20 @@ fmt_markdown(data, columns, rows = NULL) } \arguments{ -\item{data}{A table object that is created using the \code{\link{gt}()} -function.} +\item{data}{A table object that is created using the \code{\link[=gt]{gt()}} function.} \item{columns}{The columns to format. Can either be a series of column names -provided in \code{vars()}, a vector of column indices, or a helper function -focused on selections. The select helper functions are: -\code{\link{starts_with}()}, \code{\link{ends_with}()}, -\code{\link{contains}()}, \code{\link{matches}()}, \code{\link{one_of}()}, -and \code{\link{everything}()}.} +provided in \code{\link[=vars]{vars()}}, a vector of column indices, or a helper function +focused on selections. The select helper functions are: \code{\link[=starts_with]{starts_with()}}, +\code{\link[=ends_with]{ends_with()}}, \code{\link[=contains]{contains()}}, \code{\link[=matches]{matches()}}, \code{\link[=one_of]{one_of()}}, and \code{\link[=everything]{everything()}}.} \item{rows}{Optional rows to format. Not providing any value results in all -rows in \code{columns} being formatted. Can either be a vector of row -captions provided \code{c()}, a vector of row indices, or a helper function -focused on selections. The select helper functions are: -\code{\link{starts_with}()}, \code{\link{ends_with}()}, -\code{\link{contains}()}, \code{\link{matches}()}, \code{\link{one_of}()}, -and \code{\link{everything}()}. We can also use expressions to filter down -to the rows we need (e.g., \code{[colname_1] > 100 & [colname_2] < 50}).} +rows in \code{columns} being formatted. Can either be a vector of row captions +provided \code{\link[=c]{c()}}, a vector of row indices, or a helper function focused on +selections. The select helper functions are: \code{\link[=starts_with]{starts_with()}}, +\code{\link[=ends_with]{ends_with()}}, \code{\link[=contains]{contains()}}, \code{\link[=matches]{matches()}}, \code{\link[=one_of]{one_of()}}, and \code{\link[=everything]{everything()}}. +We can also use expressions to filter down to the rows we need (e.g., +\code{[colname_1] > 100 & [colname_2] < 50}).} } \value{ An object of class \code{gt_tbl}. @@ -34,12 +30,11 @@ Any Markdown-formatted text in the incoming cells will be transformed to the appropriate output type during render when using \code{fmt_markdown()}. } \details{ -Targeting of values is done through \code{columns} and additionally by -\code{rows} (if nothing is provided for \code{rows} then entire columns are -selected). A number of helper functions exist to make targeting more -effective. Conditional formatting is possible by providing a conditional -expression to the \code{rows} argument. See the Arguments section for more -information on this. +Targeting of values is done through \code{columns} and additionally by \code{rows} (if +nothing is provided for \code{rows} then entire columns are selected). A number of +helper functions exist to make targeting more effective. Conditional +formatting is possible by providing a conditional expression to the \code{rows} +argument. See the Arguments section for more information on this. } \section{Figures}{ diff --git a/man/fmt_missing.Rd b/man/fmt_missing.Rd index ad231fcdd7..35ec6a1d9e 100644 --- a/man/fmt_missing.Rd +++ b/man/fmt_missing.Rd @@ -7,24 +7,20 @@ fmt_missing(data, columns, rows = NULL, missing_text = "---") } \arguments{ -\item{data}{A table object that is created using the \code{\link{gt}()} -function.} +\item{data}{A table object that is created using the \code{\link[=gt]{gt()}} function.} \item{columns}{The columns to format. Can either be a series of column names -provided in \code{vars()}, a vector of column indices, or a helper function -focused on selections. The select helper functions are: -\code{\link{starts_with}()}, \code{\link{ends_with}()}, -\code{\link{contains}()}, \code{\link{matches}()}, \code{\link{one_of}()}, -and \code{\link{everything}()}.} +provided in \code{\link[=vars]{vars()}}, a vector of column indices, or a helper function +focused on selections. The select helper functions are: \code{\link[=starts_with]{starts_with()}}, +\code{\link[=ends_with]{ends_with()}}, \code{\link[=contains]{contains()}}, \code{\link[=matches]{matches()}}, \code{\link[=one_of]{one_of()}}, and \code{\link[=everything]{everything()}}.} \item{rows}{Optional rows to format. Not providing any value results in all -rows in \code{columns} being formatted. Can either be a vector of row -captions provided \code{c()}, a vector of row indices, or a helper function -focused on selections. The select helper functions are: -\code{\link{starts_with}()}, \code{\link{ends_with}()}, -\code{\link{contains}()}, \code{\link{matches}()}, \code{\link{one_of}()}, -and \code{\link{everything}()}. We can also use expressions to filter down -to the rows we need (e.g., \code{[colname_1] > 100 & [colname_2] < 50}).} +rows in \code{columns} being formatted. Can either be a vector of row captions +provided \code{\link[=c]{c()}}, a vector of row indices, or a helper function focused on +selections. The select helper functions are: \code{\link[=starts_with]{starts_with()}}, +\code{\link[=ends_with]{ends_with()}}, \code{\link[=contains]{contains()}}, \code{\link[=matches]{matches()}}, \code{\link[=one_of]{one_of()}}, and \code{\link[=everything]{everything()}}. +We can also use expressions to filter down to the rows we need (e.g., +\code{[colname_1] > 100 & [colname_2] < 50}).} \item{missing_text}{The text to be used in place of \code{NA} values in the rendered table.} @@ -33,18 +29,17 @@ rendered table.} An object of class \code{gt_tbl}. } \description{ -Wherever there is missing data (i.e., \code{NA} values) a customizable mark -may present better than the standard \code{NA} text that would otherwise -appear. The \code{fmt_missing()} function allows for this replacement through -its \code{missing_text} argument (where an em dash serves as the default). +Wherever there is missing data (i.e., \code{NA} values) a customizable mark may +present better than the standard \code{NA} text that would otherwise appear. The +\code{fmt_missing()} function allows for this replacement through its +\code{missing_text} argument (where an em dash serves as the default). } \details{ -Targeting of values is done through \code{columns} and additionally by -\code{rows} (if nothing is provided for \code{rows} then entire columns are -selected). A number of helper functions exist to make targeting more -effective. Conditional formatting is possible by providing a conditional -expression to the \code{rows} argument. See the Arguments section for more -information on this. +Targeting of values is done through \code{columns} and additionally by \code{rows} (if +nothing is provided for \code{rows} then entire columns are selected). A number of +helper functions exist to make targeting more effective. Conditional +formatting is possible by providing a conditional expression to the \code{rows} +argument. See the Arguments section for more information on this. } \section{Figures}{ diff --git a/man/fmt_number.Rd b/man/fmt_number.Rd index da2129b4fe..86123e2ec6 100644 --- a/man/fmt_number.Rd +++ b/man/fmt_number.Rd @@ -10,24 +10,20 @@ fmt_number(data, columns, rows = NULL, decimals = 2, dec_mark = ".", locale = NULL) } \arguments{ -\item{data}{A table object that is created using the \code{\link{gt}()} -function.} +\item{data}{A table object that is created using the \code{\link[=gt]{gt()}} function.} \item{columns}{The columns to format. Can either be a series of column names -provided in \code{vars()}, a vector of column indices, or a helper function -focused on selections. The select helper functions are: -\code{\link{starts_with}()}, \code{\link{ends_with}()}, -\code{\link{contains}()}, \code{\link{matches}()}, \code{\link{one_of}()}, -and \code{\link{everything}()}.} +provided in \code{\link[=vars]{vars()}}, a vector of column indices, or a helper function +focused on selections. The select helper functions are: \code{\link[=starts_with]{starts_with()}}, +\code{\link[=ends_with]{ends_with()}}, \code{\link[=contains]{contains()}}, \code{\link[=matches]{matches()}}, \code{\link[=one_of]{one_of()}}, and \code{\link[=everything]{everything()}}.} \item{rows}{Optional rows to format. Not providing any value results in all -rows in \code{columns} being formatted. Can either be a vector of row -captions provided \code{c()}, a vector of row indices, or a helper function -focused on selections. The select helper functions are: -\code{\link{starts_with}()}, \code{\link{ends_with}()}, -\code{\link{contains}()}, \code{\link{matches}()}, \code{\link{one_of}()}, -and \code{\link{everything}()}. We can also use expressions to filter down -to the rows we need (e.g., \code{[colname_1] > 100 & [colname_2] < 50}).} +rows in \code{columns} being formatted. Can either be a vector of row captions +provided \code{\link[=c]{c()}}, a vector of row indices, or a helper function focused on +selections. The select helper functions are: \code{\link[=starts_with]{starts_with()}}, +\code{\link[=ends_with]{ends_with()}}, \code{\link[=contains]{contains()}}, \code{\link[=matches]{matches()}}, \code{\link[=one_of]{one_of()}}, and \code{\link[=everything]{everything()}}. +We can also use expressions to filter down to the rows we need (e.g., +\code{[colname_1] > 100 & [colname_2] < 50}).} \item{decimals}{An option to specify the exact number of decimal places to use. The default number of decimal places is \code{2}.} @@ -39,45 +35,42 @@ trailing zeros (those redundant zeros after the decimal mark).} group separator is set by \code{sep_mark} and overridden if a locale ID is provided to \code{locale}. This setting is \code{TRUE} by default.} -\item{scale_by}{A value to scale the input. The default is \code{1.0}. All -numeric values will be multiplied by this value first before undergoing -formatting. This value will be ignored if using any of the \code{suffixing} -options (i.e., where \code{suffixing} is not set to \code{FALSE}).} +\item{scale_by}{A value to scale the input. The default is \code{1.0}. All numeric +values will be multiplied by this value first before undergoing formatting. +This value will be ignored if using any of the \code{suffixing} options (i.e., +where \code{suffixing} is not set to \code{FALSE}).} \item{suffixing}{An option to scale and apply suffixes to larger numbers -(e.g., \code{1924000} can be transformed to \code{1.92M}). This option can -accept a logical value, where \code{FALSE} (the default) will not perform -this transformation and \code{TRUE} will apply thousands (\code{K}), -millions (\code{M}), billions (\code{B}), and trillions (\code{T}) suffixes -after automatic value scaling. We can also specify which symbols to use for -each of the value ranges by using a character vector of the preferred -symbols to replace the defaults (e.g., \code{c("k", "Ml", "Bn", "Tr")}). -Including \code{NA} values in the vector will ensure that the particular -range will either not be included in the transformation (e.g, \code{c(NA, -"M", "B", "T")} won't modify numbers in the thousands range) or the range -will inherit a previous suffix (e.g., with \code{c("K", "M", NA, "T")}, all -numbers in the range of millions and billions will be in terms of -millions). Any use of \code{suffixing} (where not \code{FALSE}) means that -any value provided to \code{scale_by} will be ignored.} +(e.g., \code{1924000} can be transformed to \code{1.92M}). This option can accept a +logical value, where \code{FALSE} (the default) will not perform this +transformation and \code{TRUE} will apply thousands (\code{K}), millions (\code{M}), +billions (\code{B}), and trillions (\code{T}) suffixes after automatic value scaling. +We can also specify which symbols to use for each of the value ranges by +using a character vector of the preferred symbols to replace the defaults +(e.g., \code{c("k", "Ml", "Bn", "Tr")}). Including \code{NA} values in the vector +will ensure that the particular range will either not be included in the +transformation (e.g, \code{c(NA, "M", "B", "T")} won't modify numbers in the +thousands range) or the range will inherit a previous suffix (e.g., with +\code{c("K", "M", NA, "T")}, all numbers in the range of millions and billions +will be in terms of millions). Any use of \code{suffixing} (where not \code{FALSE}) +means that any value provided to \code{scale_by} will be ignored.} \item{pattern}{A formatting pattern that allows for decoration of the -formatted value. The value itself is represented by \code{{x}} and all -other characters are taken to be string literals.} +formatted value. The value itself is represented by \code{{x}} and all other +characters are taken to be string literals.} \item{sep_mark}{The mark to use as a separator between groups of digits -(e.g., using \code{sep_mark = ","} with \code{1000} would result in a -formatted value of \code{1,000}).} +(e.g., using \code{sep_mark = ","} with \code{1000} would result in a formatted value +of \code{1,000}).} -\item{dec_mark}{The character to use as a decimal mark (e.g., using -\code{dec_mark = ","} with \code{0.152} would result in a formatted value -of \code{0,152}).} +\item{dec_mark}{The character to use as a decimal mark (e.g., using \code{dec_mark = ","} with \code{0.152} would result in a formatted value of \code{0,152}).} \item{locale}{An optional locale ID that can be used for formatting the value according the locale's rules. Examples include \code{"en_US"} for English (United States) and \code{"fr_FR"} for French (France). The use of a valid -locale ID will override any values provided in \code{sep_mark} and -\code{dec_mark}. We can use the \code{\link{info_locales}()} function as a -useful reference for all of the locales that are supported.} +locale ID will override any values provided in \code{sep_mark} and \code{dec_mark}. +We can use the \code{\link[=info_locales]{info_locales()}} function as a useful reference for all of +the locales that are supported.} } \value{ An object of class \code{gt_tbl}. @@ -102,12 +95,11 @@ formatting specific to the chosen locale } } \details{ -Targeting of values is done through \code{columns} and additionally by -\code{rows} (if nothing is provided for \code{rows} then entire columns are -selected). A number of helper functions exist to make targeting more -effective. Conditional formatting is possible by providing a conditional -expression to the \code{rows} argument. See the Arguments section for more -information on this. +Targeting of values is done through \code{columns} and additionally by \code{rows} (if +nothing is provided for \code{rows} then entire columns are selected). A number of +helper functions exist to make targeting more effective. Conditional +formatting is possible by providing a conditional expression to the \code{rows} +argument. See the Arguments section for more information on this. } \section{Figures}{ diff --git a/man/fmt_passthrough.Rd b/man/fmt_passthrough.Rd index 889865bd27..e9b33ab630 100644 --- a/man/fmt_passthrough.Rd +++ b/man/fmt_passthrough.Rd @@ -8,56 +8,49 @@ fmt_passthrough(data, columns, rows = NULL, escape = TRUE, pattern = "{x}") } \arguments{ -\item{data}{A table object that is created using the \code{\link{gt}()} -function.} +\item{data}{A table object that is created using the \code{\link[=gt]{gt()}} function.} \item{columns}{The columns to format. Can either be a series of column names -provided in \code{vars()}, a vector of column indices, or a helper function -focused on selections. The select helper functions are: -\code{\link{starts_with}()}, \code{\link{ends_with}()}, -\code{\link{contains}()}, \code{\link{matches}()}, \code{\link{one_of}()}, -and \code{\link{everything}()}.} +provided in \code{\link[=vars]{vars()}}, a vector of column indices, or a helper function +focused on selections. The select helper functions are: \code{\link[=starts_with]{starts_with()}}, +\code{\link[=ends_with]{ends_with()}}, \code{\link[=contains]{contains()}}, \code{\link[=matches]{matches()}}, \code{\link[=one_of]{one_of()}}, and \code{\link[=everything]{everything()}}.} \item{rows}{Optional rows to format. Not providing any value results in all -rows in \code{columns} being formatted. Can either be a vector of row -captions provided \code{c()}, a vector of row indices, or a helper function -focused on selections. The select helper functions are: -\code{\link{starts_with}()}, \code{\link{ends_with}()}, -\code{\link{contains}()}, \code{\link{matches}()}, \code{\link{one_of}()}, -and \code{\link{everything}()}. We can also use expressions to filter down -to the rows we need (e.g., \code{[colname_1] > 100 & [colname_2] < 50}).} +rows in \code{columns} being formatted. Can either be a vector of row captions +provided \code{\link[=c]{c()}}, a vector of row indices, or a helper function focused on +selections. The select helper functions are: \code{\link[=starts_with]{starts_with()}}, +\code{\link[=ends_with]{ends_with()}}, \code{\link[=contains]{contains()}}, \code{\link[=matches]{matches()}}, \code{\link[=one_of]{one_of()}}, and \code{\link[=everything]{everything()}}. +We can also use expressions to filter down to the rows we need (e.g., +\code{[colname_1] > 100 & [colname_2] < 50}).} \item{escape}{An option to escape text according to the final output format of the table. For example, if a LaTeX table is to be generated then LaTeX escaping would be performed during rendering. By default this is set to -\code{TRUE} and setting to \code{FALSE} is useful in the case where -LaTeX-formatted text should be passed through to the output LaTeX table -unchanged.} +\code{TRUE} and setting to \code{FALSE} is useful in the case where LaTeX-formatted +text should be passed through to the output LaTeX table unchanged.} \item{pattern}{A formatting pattern that allows for decoration of the -formatted value. The value itself is represented by \code{{x}} and all -other characters are taken to be string literals.} +formatted value. The value itself is represented by \code{{x}} and all other +characters are taken to be string literals.} } \value{ An object of class \code{gt_tbl}. } \description{ Format by passing data through no other transformation other than: (1) -coercing to \code{character} (as all the \code{fmt_*()} functions do), and -(2) applying prefixed or suffixed text via the \code{pattern} argument (the -default is to apply nothing). All of this is useful when don't want to modify -the input data other than to decorate it within a pattern. Also, this -function is useful when used as a \code{formatter} function in the -\code{summary_rows} function, where the output may be text or useful as is -(that function requires a formatter function). +coercing to \code{character} (as all the \code{fmt_*()} functions do), and (2) applying +text via the \code{pattern} argument (the default is to apply nothing). All of +this is useful when don't want to modify the input data other than to +decorate it within a pattern. Also, this function is useful when used as the +\code{formatter} function in the \code{\link[=summary_rows]{summary_rows()}} function, where the output may +be text or useful as is. } \details{ -Targeting of values is done through \code{columns} and additionally by -\code{rows} (if nothing is provided for \code{rows} then entire columns are -selected). A number of helper functions exist to make targeting more -effective. Conditional formatting is possible by providing a conditional -expression to the \code{rows} argument. See the Arguments section for more -information on this. +Targeting of values is done through \code{columns} and additionally by \code{rows} (if +nothing is provided for \code{rows} then entire columns are selected). A number of +helper functions exist to make targeting more effective. Conditional +formatting is possible by providing a conditional expression to the \code{rows} +argument. See the Arguments section for more information on this. } \section{Figures}{ diff --git a/man/fmt_percent.Rd b/man/fmt_percent.Rd index 8a99e6969d..8120398ba5 100644 --- a/man/fmt_percent.Rd +++ b/man/fmt_percent.Rd @@ -10,24 +10,20 @@ fmt_percent(data, columns, rows = NULL, decimals = 2, placement = "right", locale = NULL) } \arguments{ -\item{data}{A table object that is created using the \code{\link{gt}()} -function.} +\item{data}{A table object that is created using the \code{\link[=gt]{gt()}} function.} \item{columns}{The columns to format. Can either be a series of column names -provided in \code{vars()}, a vector of column indices, or a helper function -focused on selections. The select helper functions are: -\code{\link{starts_with}()}, \code{\link{ends_with}()}, -\code{\link{contains}()}, \code{\link{matches}()}, \code{\link{one_of}()}, -and \code{\link{everything}()}.} +provided in \code{\link[=vars]{vars()}}, a vector of column indices, or a helper function +focused on selections. The select helper functions are: \code{\link[=starts_with]{starts_with()}}, +\code{\link[=ends_with]{ends_with()}}, \code{\link[=contains]{contains()}}, \code{\link[=matches]{matches()}}, \code{\link[=one_of]{one_of()}}, and \code{\link[=everything]{everything()}}.} \item{rows}{Optional rows to format. Not providing any value results in all -rows in \code{columns} being formatted. Can either be a vector of row -captions provided \code{c()}, a vector of row indices, or a helper function -focused on selections. The select helper functions are: -\code{\link{starts_with}()}, \code{\link{ends_with}()}, -\code{\link{contains}()}, \code{\link{matches}()}, \code{\link{one_of}()}, -and \code{\link{everything}()}. We can also use expressions to filter down -to the rows we need (e.g., \code{[colname_1] > 100 & [colname_2] < 50}).} +rows in \code{columns} being formatted. Can either be a vector of row captions +provided \code{\link[=c]{c()}}, a vector of row indices, or a helper function focused on +selections. The select helper functions are: \code{\link[=starts_with]{starts_with()}}, +\code{\link[=ends_with]{ends_with()}}, \code{\link[=contains]{contains()}}, \code{\link[=matches]{matches()}}, \code{\link[=one_of]{one_of()}}, and \code{\link[=everything]{everything()}}. +We can also use expressions to filter down to the rows we need (e.g., +\code{[colname_1] > 100 & [colname_2] < 50}).} \item{decimals}{An option to specify the exact number of decimal places to use. The default number of decimal places is \code{2}.} @@ -40,16 +36,14 @@ group separator is set by \code{sep_mark} and overridden if a locale ID is provided to \code{locale}. This setting is \code{TRUE} by default.} \item{pattern}{A formatting pattern that allows for decoration of the -formatted value. The value itself is represented by \code{{x}} and all -other characters are taken to be string literals.} +formatted value. The value itself is represented by \code{{x}} and all other +characters are taken to be string literals.} \item{sep_mark}{The mark to use as a separator between groups of digits -(e.g., using \code{sep_mark = ","} with \code{1000} would result in a -formatted value of \code{1,000}).} +(e.g., using \code{sep_mark = ","} with \code{1000} would result in a formatted value +of \code{1,000}).} -\item{dec_mark}{The character to use as a decimal mark (e.g., using -\code{dec_mark = ","} with \code{0.152} would result in a formatted value -of \code{0,152}).} +\item{dec_mark}{The character to use as a decimal mark (e.g., using \code{dec_mark = ","} with \code{0.152} would result in a formatted value of \code{0,152}).} \item{incl_space}{An option for whether to include a space between the value and the percent sign. The default is to not introduce a space character.} @@ -60,9 +54,9 @@ and the percent sign. The default is to not introduce a space character.} \item{locale}{An optional locale ID that can be used for formatting the value according the locale's rules. Examples include \code{"en_US"} for English (United States) and \code{"fr_FR"} for French (France). The use of a valid -locale ID will override any values provided in \code{sep_mark} and -\code{dec_mark}. We can use the \code{\link{info_locales}()} function as a -useful reference for all of the locales that are supported.} +locale ID will override any values provided in \code{sep_mark} and \code{dec_mark}. +We can use the \code{\link[=info_locales]{info_locales()}} function as a useful reference for all of +the locales that are supported.} } \value{ an object of class \code{gt_tbl}. @@ -70,9 +64,9 @@ an object of class \code{gt_tbl}. \description{ With numeric values in a \pkg{gt} table, we can perform percentage-based formatting. It is assumed the input numeric values are in a fractional format -since the numbers will be automatically multiplied by \code{100} before -decorating with a percent sign. For more control over percentage formatting, -we can use the following options: +since the numbers will be automatically multiplied by \code{100} before decorating +with a percent sign. For more control over percentage formatting, we can use +the following options: \itemize{ \item percent sign placement: the percent sign can be placed after or before the values and a space can be inserted between the symbol and the @@ -88,12 +82,11 @@ formatting specific to the chosen locale } } \details{ -Targeting of values is done through \code{columns} and additionally by -\code{rows} (if nothing is provided for \code{rows} then entire columns are -selected). A number of helper functions exist to make targeting more -effective. Conditional formatting is possible by providing a conditional -expression to the \code{rows} argument. See the Arguments section for more -information on this. +Targeting of values is done through \code{columns} and additionally by \code{rows} (if +nothing is provided for \code{rows} then entire columns are selected). A number of +helper functions exist to make targeting more effective. Conditional +formatting is possible by providing a conditional expression to the \code{rows} +argument. See the Arguments section for more information on this. } \section{Figures}{ diff --git a/man/fmt_scientific.Rd b/man/fmt_scientific.Rd index 28d7aa20f1..2a49fcf0f5 100644 --- a/man/fmt_scientific.Rd +++ b/man/fmt_scientific.Rd @@ -9,24 +9,20 @@ fmt_scientific(data, columns, rows = NULL, decimals = 2, sep_mark = ",", dec_mark = ".", locale = NULL) } \arguments{ -\item{data}{A table object that is created using the \code{\link{gt}()} -function.} +\item{data}{A table object that is created using the \code{\link[=gt]{gt()}} function.} \item{columns}{The columns to format. Can either be a series of column names -provided in \code{vars()}, a vector of column indices, or a helper function -focused on selections. The select helper functions are: -\code{\link{starts_with}()}, \code{\link{ends_with}()}, -\code{\link{contains}()}, \code{\link{matches}()}, \code{\link{one_of}()}, -and \code{\link{everything}()}.} +provided in \code{\link[=vars]{vars()}}, a vector of column indices, or a helper function +focused on selections. The select helper functions are: \code{\link[=starts_with]{starts_with()}}, +\code{\link[=ends_with]{ends_with()}}, \code{\link[=contains]{contains()}}, \code{\link[=matches]{matches()}}, \code{\link[=one_of]{one_of()}}, and \code{\link[=everything]{everything()}}.} \item{rows}{Optional rows to format. Not providing any value results in all -rows in \code{columns} being formatted. Can either be a vector of row -captions provided \code{c()}, a vector of row indices, or a helper function -focused on selections. The select helper functions are: -\code{\link{starts_with}()}, \code{\link{ends_with}()}, -\code{\link{contains}()}, \code{\link{matches}()}, \code{\link{one_of}()}, -and \code{\link{everything}()}. We can also use expressions to filter down -to the rows we need (e.g., \code{[colname_1] > 100 & [colname_2] < 50}).} +rows in \code{columns} being formatted. Can either be a vector of row captions +provided \code{\link[=c]{c()}}, a vector of row indices, or a helper function focused on +selections. The select helper functions are: \code{\link[=starts_with]{starts_with()}}, +\code{\link[=ends_with]{ends_with()}}, \code{\link[=contains]{contains()}}, \code{\link[=matches]{matches()}}, \code{\link[=one_of]{one_of()}}, and \code{\link[=everything]{everything()}}. +We can also use expressions to filter down to the rows we need (e.g., +\code{[colname_1] > 100 & [colname_2] < 50}).} \item{decimals}{An option to specify the exact number of decimal places to use. The default number of decimal places is \code{2}.} @@ -34,29 +30,27 @@ use. The default number of decimal places is \code{2}.} \item{drop_trailing_zeros}{A logical value that allows for removal of trailing zeros (those redundant zeros after the decimal mark).} -\item{scale_by}{A value to scale the input. The default is \code{1.0}. All -numeric values will be multiplied by this value first before undergoing -formatting. This value will be ignored if using any of the \code{suffixing} -options (i.e., where \code{suffixing} is not set to \code{FALSE}).} +\item{scale_by}{A value to scale the input. The default is \code{1.0}. All numeric +values will be multiplied by this value first before undergoing formatting. +This value will be ignored if using any of the \code{suffixing} options (i.e., +where \code{suffixing} is not set to \code{FALSE}).} \item{pattern}{A formatting pattern that allows for decoration of the -formatted value. The value itself is represented by \code{{x}} and all -other characters are taken to be string literals.} +formatted value. The value itself is represented by \code{{x}} and all other +characters are taken to be string literals.} \item{sep_mark}{The mark to use as a separator between groups of digits -(e.g., using \code{sep_mark = ","} with \code{1000} would result in a -formatted value of \code{1,000}).} +(e.g., using \code{sep_mark = ","} with \code{1000} would result in a formatted value +of \code{1,000}).} -\item{dec_mark}{The character to use as a decimal mark (e.g., using -\code{dec_mark = ","} with \code{0.152} would result in a formatted value -of \code{0,152}).} +\item{dec_mark}{The character to use as a decimal mark (e.g., using \code{dec_mark = ","} with \code{0.152} would result in a formatted value of \code{0,152}).} \item{locale}{An optional locale ID that can be used for formatting the value according the locale's rules. Examples include \code{"en_US"} for English (United States) and \code{"fr_FR"} for French (France). The use of a valid -locale ID will override any values provided in \code{sep_mark} and -\code{dec_mark}. We can use the \code{\link{info_locales}()} function as a -useful reference for all of the locales that are supported.} +locale ID will override any values provided in \code{sep_mark} and \code{dec_mark}. +We can use the \code{\link[=info_locales]{info_locales()}} function as a useful reference for all of +the locales that are supported.} } \value{ An object of class \code{gt_tbl}. @@ -76,12 +70,11 @@ formatting specific to the chosen locale } } \details{ -Targeting of values is done through \code{columns} and additionally by -\code{rows} (if nothing is provided for \code{rows} then entire columns are -selected). A number of helper functions exist to make targeting more -effective. Conditional formatting is possible by providing a conditional -expression to the \code{rows} argument. See the Arguments section for more -information on this. +Targeting of values is done through \code{columns} and additionally by \code{rows} (if +nothing is provided for \code{rows} then entire columns are selected). A number of +helper functions exist to make targeting more effective. Conditional +formatting is possible by providing a conditional expression to the \code{rows} +argument. See the Arguments section for more information on this. } \section{Figures}{ diff --git a/man/fmt_time.Rd b/man/fmt_time.Rd index 7569b2af22..c647e53b2f 100644 --- a/man/fmt_time.Rd +++ b/man/fmt_time.Rd @@ -7,39 +7,34 @@ fmt_time(data, columns, rows = NULL, time_style = 2) } \arguments{ -\item{data}{A table object that is created using the \code{\link{gt}()} -function.} +\item{data}{A table object that is created using the \code{\link[=gt]{gt()}} function.} \item{columns}{The columns to format. Can either be a series of column names -provided in \code{vars()}, a vector of column indices, or a helper function -focused on selections. The select helper functions are: -\code{\link{starts_with}()}, \code{\link{ends_with}()}, -\code{\link{contains}()}, \code{\link{matches}()}, \code{\link{one_of}()}, -and \code{\link{everything}()}.} +provided in \code{\link[=vars]{vars()}}, a vector of column indices, or a helper function +focused on selections. The select helper functions are: \code{\link[=starts_with]{starts_with()}}, +\code{\link[=ends_with]{ends_with()}}, \code{\link[=contains]{contains()}}, \code{\link[=matches]{matches()}}, \code{\link[=one_of]{one_of()}}, and \code{\link[=everything]{everything()}}.} \item{rows}{Optional rows to format. Not providing any value results in all -rows in \code{columns} being formatted. Can either be a vector of row -captions provided \code{c()}, a vector of row indices, or a helper function -focused on selections. The select helper functions are: -\code{\link{starts_with}()}, \code{\link{ends_with}()}, -\code{\link{contains}()}, \code{\link{matches}()}, \code{\link{one_of}()}, -and \code{\link{everything}()}. We can also use expressions to filter down -to the rows we need (e.g., \code{[colname_1] > 100 & [colname_2] < 50}).} +rows in \code{columns} being formatted. Can either be a vector of row captions +provided \code{\link[=c]{c()}}, a vector of row indices, or a helper function focused on +selections. The select helper functions are: \code{\link[=starts_with]{starts_with()}}, +\code{\link[=ends_with]{ends_with()}}, \code{\link[=contains]{contains()}}, \code{\link[=matches]{matches()}}, \code{\link[=one_of]{one_of()}}, and \code{\link[=everything]{everything()}}. +We can also use expressions to filter down to the rows we need (e.g., +\code{[colname_1] > 100 & [colname_2] < 50}).} -\item{time_style}{The time style to use. Supply a number (from \code{1} to -\code{5}) that corresponds to the preferred time style. Use -\code{\link{info_time_style}()} to see the different numbered and named time -presets.} +\item{time_style}{The time style to use. Supply a number (from \code{1} to \code{5}) +that corresponds to the preferred time style. Use \code{\link[=info_time_style]{info_time_style()}} to +see the different numbered and named time presets.} } \value{ An object of class \code{gt_tbl}. } \description{ Format input time values that are character-based and expressed according to -the ISO 8601 time format (\code{HH:MM:SS}). Once the appropriate data cells -are targeted with \code{columns} (and, optionally, \code{rows}), we can -simply apply a preset time style (see table in -\code{\link{info_time_style}()} for info) to format the times. +the ISO 8601 time format (\code{HH:MM:SS}). Once the appropriate data cells are +targeted with \code{columns} (and, optionally, \code{rows}), we can simply apply a +preset time style (see table in \code{\link[=info_time_style]{info_time_style()}} for info) to format the +times. } \details{ The following time styles are available for simpler formatting of ISO times @@ -53,15 +48,14 @@ The following time styles are available for simpler formatting of ISO times \item h_p: \code{2 PM} } -We can use the \code{\link{info_time_style}()} function for a useful -reference on all of the possible inputs to \code{time_style}. +We can use the \code{\link[=info_time_style]{info_time_style()}} function for a useful reference on all of +the possible inputs to \code{time_style}. -Targeting of values is done through \code{columns} and additionally by -\code{rows} (if nothing is provided for \code{rows} then entire columns are -selected). A number of helper functions exist to make targeting more -effective. Conditional formatting is possible by providing a conditional -expression to the \code{rows} argument. See the Arguments section for more -information on this. +Targeting of values is done through \code{columns} and additionally by \code{rows} (if +nothing is provided for \code{rows} then entire columns are selected). A number of +helper functions exist to make targeting more effective. Conditional +formatting is possible by providing a conditional expression to the \code{rows} +argument. See the Arguments section for more information on this. } \section{Figures}{ diff --git a/man/ggplot_image.Rd b/man/ggplot_image.Rd index 616c8dfe6e..1b2953b90d 100644 --- a/man/ggplot_image.Rd +++ b/man/ggplot_image.Rd @@ -7,32 +7,31 @@ ggplot_image(plot_object, height = 100, aspect_ratio = 1) } \arguments{ -\item{plot_object}{a ggplot plot object.} +\item{plot_object}{A ggplot plot object.} -\item{height}{the absolute height (px) of the image in the table cell.} +\item{height}{The absolute height (px) of the image in the table cell.} -\item{aspect_ratio}{the plot's final aspect ratio. Where the height of the +\item{aspect_ratio}{The plot's final aspect ratio. Where the height of the plot is fixed using the \code{height} argument, the \code{aspect_ratio} will either compress (\code{aspect_ratio} < \code{1.0}) or expand (\code{aspect_ratio} > \code{1.0}) the plot horizontally. The default value of \code{1.0} will neither compress nor expand the plot.} } \value{ -a character object with an HTML fragment that can be placed inside of - a cell. +A character object with an HTML fragment that can be placed inside of +a cell. } \description{ We can add a \pkg{ggplot2} plot inside of a table with the help of the -\code{ggplot_image()} function. The function provides a convenient way to -generate an HTML fragment with a \code{ggplot} object. Because this function -is currently HTML-based, it is only useful for HTML table output. To use this -function inside of data cells, it is recommended that the -\code{\link{text_transform}()} function is used. With that function, we can -specify which data cells to target and then include a call to -\code{ggplot_image()} within the required user-defined function (for the -\code{fn} argument). If we want to include a plot in other places (e.g., in -the header, within footnote text, etc.) we need to use \code{ggplot_image()} -within the \code{\link{html}()} helper function. +\code{ggplot_image()} function. The function provides a convenient way to generate +an HTML fragment with a \code{ggplot} object. Because this function is currently +HTML-based, it is only useful for HTML table output. To use this function +inside of data cells, it is recommended that the \code{\link[=text_transform]{text_transform()}} function +is used. With that function, we can specify which data cells to target and +then include a call to \code{ggplot_image()} within the required user-defined +function (for the \code{fn} argument). If we want to include a plot in other +places (e.g., in the header, within footnote text, etc.) we need to use +\code{ggplot_image()} within the \code{\link[=html]{html()}} helper function. } \details{ By itself, the function creates an HTML image tag with an image URI embedded @@ -42,11 +41,10 @@ evaluates to: \code{ src= style=\"height:100px;\">} -where a height of \code{100px} is a default height chosen to work well within -the heights of most table rows. There is the option to modify the aspect -ratio of the plot (the default \code{aspect_ratio} is \code{1.0}) and this is -useful for elongating any given plot to fit better within the table -construct. +where a height of \code{100px} is a default height chosen to work well within the +heights of most table rows. There is the option to modify the aspect ratio of +the plot (the default \code{aspect_ratio} is \code{1.0}) and this is useful for +elongating any given plot to fit better within the table construct. } \section{Figures}{ diff --git a/man/gt-options.Rd b/man/gt-options.Rd index 88265c3872..b40a1492ad 100644 --- a/man/gt-options.Rd +++ b/man/gt-options.Rd @@ -9,11 +9,11 @@ \section{Package options}{ -\pkg{gt} uses the following \code{\link{options}} to configure behavior: +\pkg{gt} uses the following \code{\link[=options]{options()}} to configure behavior: \itemize{ - \item \code{gt.stub_group.sep}: a separator between groups for the - stub group label. +\item \code{gt.stub_group.sep}: a separator between groups for the +stub group label. } } diff --git a/man/gt.Rd b/man/gt.Rd index 00a220568b..2c2fe9b9eb 100644 --- a/man/gt.Rd +++ b/man/gt.Rd @@ -9,46 +9,45 @@ gt(data, rowname_col = "rowname", groupname_col = "groupname", stub_group.sep = getOption("gt.stub_group.sep", " - ")) } \arguments{ -\item{data}{a \code{data.frame} object or a tibble.} +\item{data}{A \code{data.frame} object or a tibble.} -\item{rowname_col}{the column name in the input \code{data} table to use as -row captions to be placed in the display table stub.} +\item{rowname_col}{The column name in the input \code{data} table to use as row +captions to be placed in the display table stub.} -\item{groupname_col}{the column name in the input \code{data} table to use as +\item{groupname_col}{The column name in the input \code{data} table to use as group labels for generation of stub row groups.} -\item{rownames_to_stub}{an option to take rownames from the input \code{data} +\item{rownames_to_stub}{An option to take rownames from the input \code{data} table as row captions in the display table stub.} -\item{stub_group.sep}{the separator to use between consecutive group names (a -possibility when providing \code{data} as a \code{grouped_df} with multiple -groups) in the displayed stub row group label.} +\item{stub_group.sep}{The separator to use between consecutive group names (a +possibility when providing \code{data} as a \code{grouped_df} with multiple groups) +in the displayed stub row group label.} } \value{ -an object of class \code{gt_tbl}. +An object of class \code{gt_tbl}. } \description{ -The \code{gt()} function creates a \pkg{gt} table object when provided with -table data. Using this function is the first step in a typical \pkg{gt} -workflow. Once we have the \pkg{gt} table object, we can perform styling +The \code{gt()} function creates a \pkg{gt} table object when provided with table +data. Using this function is the first step in a typical \pkg{gt} workflow. +Once we have the \pkg{gt} table object, we can perform styling transformations before rendering to a display table of various formats (e.g., HTML, LaTeX, RTF). } \details{ There are a few data ingest options we can consider at this stage. We can -choose to create a table stub with rowname captions using the -\code{rowname_col} argument. Further to this, stub row groups can be created -with the \code{groupname_col}. Both arguments take the name of a column in -the input table data. Typically, the data in the \code{groupname_col} will -consist of categories of data in a table and the data in the -\code{rowname_col} are unique labels (perhaps unique across the entire table -or unique within groups). +choose to create a table stub with rowname captions using the \code{rowname_col} +argument. Further to this, stub row groups can be created with the +\code{groupname_col}. Both arguments take the name of a column in the input table +data. Typically, the data in the \code{groupname_col} will consist of categories +of data in a table and the data in the \code{rowname_col} are unique labels +(perhaps unique across the entire table or unique within groups). -Row groups can also be created by passing a \code{grouped_df} to \code{gt()} -by using the \code{dplyr::group_by()} function on the table data. In this -way, two or more columns of categorical data can be used to make row groups. -The \code{stub_group.sep} argument allows for control in how the row group -label will appear in the display table. +Row groups can also be created by passing a \code{grouped_df} to \code{gt()} by using +the \code{dplyr::group_by()} function on the table data. In this way, two or more +columns of categorical data can be used to make row groups. The +\code{stub_group.sep} argument allows for control in how the row group label will +appear in the display table. } \section{Figures}{ diff --git a/man/gt_output.Rd b/man/gt_output.Rd index aefa028b7e..da10b8a906 100644 --- a/man/gt_output.Rd +++ b/man/gt_output.Rd @@ -7,7 +7,7 @@ gt_output(outputId) } \arguments{ -\item{outputId}{an output variable from which to read the table.} +\item{outputId}{An output variable from which to read the table.} } \value{ A \pkg{gt} table output element that can be included in a panel. diff --git a/man/gt_preview.Rd b/man/gt_preview.Rd index 0053b14680..c648a20c17 100644 --- a/man/gt_preview.Rd +++ b/man/gt_preview.Rd @@ -7,38 +7,36 @@ gt_preview(data, top_n = 5, bottom_n = 1, incl_rownums = TRUE) } \arguments{ -\item{data}{a \code{data.frame} object or a tibble.} +\item{data}{A \code{data.frame} object or a tibble.} -\item{top_n}{this value will be used as the number of rows from the top of -the table to display. The default, \code{5}, will show the first five rows -of the table.} - -\item{bottom_n}{the value will be used as the number of rows from the bottom -of the table to display. The default, \code{1}, will show the final row of +\item{top_n}{This value will be used as the number of rows from the top of +the table to display. The default, \code{5}, will show the first five rows of the table.} -\item{incl_rownums}{an option to include the row numbers for \code{data} in -the table stub. By default, this is \code{TRUE}.} +\item{bottom_n}{The value will be used as the number of rows from the bottom +of the table to display. The default, \code{1}, will show the final row of the +table.} + +\item{incl_rownums}{An option to include the row numbers for \code{data} in the +table stub. By default, this is \code{TRUE}.} } \value{ -an object of class \code{gt_tbl}. +An object of class \code{gt_tbl}. } \description{ Sometimes you may want to see just a small portion of your input data. We can -use \code{gt_preview()} in place of \code{\link{gt}()} to get the first x -rows of data and the last y rows of data (which can be set by the -\code{top_n} and \code{bottom_n} arguments). It's not advised to use -additional \pkg{gt} API functions to further modify the output of -\code{gt_preview()}. Furthermore, you cannot pass a \pkg{gt} object to -\code{gt_preview()}. +use \code{gt_preview()} in place of \code{\link[=gt]{gt()}} to get the first x rows of data and the +last y rows of data (which can be set by the \code{top_n} and \code{bottom_n} +arguments). It's not advised to use additional \pkg{gt} API functions to +further modify the output of \code{gt_preview()}. Furthermore, you cannot pass a +\pkg{gt} object to \code{gt_preview()}. } \details{ -Any grouped data or magic columns such as \code{rowname} and \code{groupname} -will be ignored by \code{gt_preview()} and, as such, one cannot add a stub or -group rows in the output table. By default, the output table will include row -numbers in a stub (including a range of row numbers for the omitted rows). -This row numbering option can be deactivated by setting \code{incl_rownums} -to \code{FALSE}. +Any grouped data or magic columns such as \code{rowname} and \code{groupname} will be +ignored by \code{gt_preview()} and, as such, one cannot add a stub or group rows +in the output table. By default, the output table will include row numbers in +a stub (including a range of row numbers for the omitted rows). This row +numbering option can be deactivated by setting \code{incl_rownums} to \code{FALSE}. } \section{Figures}{ diff --git a/man/gtcars.Rd b/man/gtcars.Rd index f28b3a3fc0..d04bb2febb 100644 --- a/man/gtcars.Rd +++ b/man/gtcars.Rd @@ -6,24 +6,24 @@ \title{Deluxe automobiles from the 2014-2017 period} \format{A tibble with 47 rows and 15 variables: \describe{ - \item{mfr}{The name of the car manufacturer} - \item{model}{The car's model name} - \item{year}{The car's model year} - \item{trim}{A short description of the car model's trim} - \item{bdy_style}{An identifier of the car's body style, which is either - \code{coupe}, \code{convertible}, \code{sedan}, or \code{hatchback}} - \item{hp, hp_rpm}{The car's horsepower and the associated RPM level} - \item{trq, trq_rpm}{The car's torque and the associated RPM level} - \item{mpg_c, mpg_h}{The miles per gallon fuel efficiency rating for city - and highway driving} - \item{drivetrain}{The car's drivetrain which, for this dataset is either - \code{rwd} (Rear Wheel Drive) or \code{awd} (All Wheel Drive)} - \item{trsmn}{The codified transmission type, where the number part is - the number of gears; the car could have automatic transmission - (\code{a}), manual transmission (\code{m}), an option to switch between - both types (\code{am}), or, direct drive (\code{dd})} - \item{ctry_origin}{The country name for where the vehicle manufacturer - is headquartered} +\item{mfr}{The name of the car manufacturer} +\item{model}{The car's model name} +\item{year}{The car's model year} +\item{trim}{A short description of the car model's trim} +\item{bdy_style}{An identifier of the car's body style, which is either +\code{coupe}, \code{convertible}, \code{sedan}, or \code{hatchback}} +\item{hp, hp_rpm}{The car's horsepower and the associated RPM level} +\item{trq, trq_rpm}{The car's torque and the associated RPM level} +\item{mpg_c, mpg_h}{The miles per gallon fuel efficiency rating for city +and highway driving} +\item{drivetrain}{The car's drivetrain which, for this dataset is either +\code{rwd} (Rear Wheel Drive) or \code{awd} (All Wheel Drive)} +\item{trsmn}{The codified transmission type, where the number part is +the number of gears; the car could have automatic transmission +(\code{a}), manual transmission (\code{m}), an option to switch between +both types (\code{am}), or, direct drive (\code{dd})} +\item{ctry_origin}{The country name for where the vehicle manufacturer +is headquartered} }} \source{ Various pages within \url{https://www.edmunds.com}. @@ -32,20 +32,20 @@ Various pages within \url{https://www.edmunds.com}. gtcars } \description{ -Expensive and fast cars. Not your father's \code{mtcars}. Each row describes -a car of a certain make, model, year, and trim. Basic specifications such as +Expensive and fast cars. Not your father's \code{mtcars}. Each row describes a car +of a certain make, model, year, and trim. Basic specifications such as horsepower, torque, EPA MPG ratings, type of drivetrain, and transmission characteristics are provided. The country of origin for the car manufacturer is also given. } \details{ -All of the \code{gtcars} have something else in common (aside from the high -asking prices): they are all grand tourer vehicles. These are proper GT cars -that blend pure driving thrills with a level of comfort that is more expected -from a fine limousine (e.g., a Rolls-Royce Phantom EWB). You'll find that, -with these cars, comfort is emphasized over all-out performance. -Nevertheless, the driving experience should also mean motoring at speed, -doing so in style and safety. +All of the \code{gtcars} have something else in common (aside from the high asking +prices): they are all grand tourer vehicles. These are proper GT cars that +blend pure driving thrills with a level of comfort that is more expected from +a fine limousine (e.g., a Rolls-Royce Phantom EWB). You'll find that, with +these cars, comfort is emphasized over all-out performance. Nevertheless, the +driving experience should also mean motoring at speed, doing so in style and +safety. } \examples{ # Here is a glimpse at the data diff --git a/man/gtsave.Rd b/man/gtsave.Rd index 1ba00a7dca..588d69d9ad 100644 --- a/man/gtsave.Rd +++ b/man/gtsave.Rd @@ -7,31 +7,30 @@ gtsave(data, filename, ...) } \arguments{ -\item{data}{a table object that is created using the \code{\link{gt}()} -function.} +\item{data}{A table object that is created using the \code{\link[=gt]{gt()}} function.} -\item{filename}{the file name to create on disk. Ensure that an extension -compatible with the output types is provided (\code{.html}, \code{.tex}, -\code{.ltx}, \code{.rtf}). If a custom save function is provided then the -file extension is disregarded.} +\item{filename}{The file name to create on disk. Ensure that an extension +compatible with the output types is provided (\code{.html}, \code{.tex}, \code{.ltx}, +\code{.rtf}). If a custom save function is provided then the file extension is +disregarded.} -\item{...}{all other options passed to the appropriate internal saving +\item{...}{All other options passed to the appropriate internal saving function.} } \description{ -The \code{gtsave()} function makes it easy to save a \pkg{gt} table to a -file. The function guesses the file type by the extension provided in the -output filename, producing either an HTML, LaTeX, or RTF file. +The \code{gtsave()} function makes it easy to save a \pkg{gt} table to a file. The +function guesses the file type by the extension provided in the output +filename, producing either an HTML, LaTeX, or RTF file. } \details{ -Output filenames with either the \code{.html} or \code{.htm} extensions will -produce an HTML document. In this case, we can pass a \code{TRUE} or -\code{FALSE} value to the \code{inline_css} option to obtain an HTML document -with inlined CSS styles (the default is \code{FALSE}). More details on CSS -inlining are available at \code{\link{as_raw_html}()}. +Output filenames with either the \code{.html} or \code{.htm} extensions will produce an +HTML document. In this case, we can pass a \code{TRUE} or \code{FALSE} value to the +\code{inline_css} option to obtain an HTML document with inlined CSS styles (the +default is \code{FALSE}). More details on CSS inlining are available at +\code{\link[=as_raw_html]{as_raw_html()}}. -If the output filename is either of \code{.tex}, \code{.ltx}, or \code{.rnw}, -a LaTeX document is produced. An output filename of \code{.rtf} will generate -an RTF document. The LaTeX and RTF saving function don't have any options to -pass to \code{...}. +If the output filename is either of \code{.tex}, \code{.ltx}, or \code{.rnw}, a LaTeX +document is produced. An output filename of \code{.rtf} will generate an RTF +document. The LaTeX and RTF saving function don't have any options to pass to +\code{...}. } diff --git a/man/html.Rd b/man/html.Rd index 8f0355116c..de978a5a55 100644 --- a/man/html.Rd +++ b/man/html.Rd @@ -7,12 +7,12 @@ html(text, ...) } \arguments{ -\item{text, ...}{the text that is understood to be HTML text, which is to be +\item{text, ...}{The text that is understood to be HTML text, which is to be preserved.} } \value{ -a character object that is tagged as an HTML fragment that is not to - be sanitized. +A character object that is tagged as an HTML fragment that is not to +be sanitized. a character object of class \code{html}. } diff --git a/man/info_currencies.Rd b/man/info_currencies.Rd index 7036cdc006..3f3ce2d313 100644 --- a/man/info_currencies.Rd +++ b/man/info_currencies.Rd @@ -7,24 +7,24 @@ info_currencies(type = c("code", "symbol"), begins_with = NULL) } \arguments{ -\item{type}{the type of currency information provided. Can either be -\code{code} where currency information corresponding to 3-letter currency -codes is provided, or \code{symbol} where currency info for common currency -names (e.g., dollar, pound, yen, etc.) is returned.} +\item{type}{The type of currency information provided. Can either be \code{code} +where currency information corresponding to 3-letter currency codes is +provided, or \code{symbol} where currency info for common currency names (e.g., +dollar, pound, yen, etc.) is returned.} -\item{begins_with}{providing a single letter will filter currencies to only +\item{begins_with}{Providing a single letter will filter currencies to only those that begin with that letter in their currency code. The default -(\code{NULL}) will produce a table with all currencies displayed. This -option only constrains the information table where \code{type == "code"}.} +(\code{NULL}) will produce a table with all currencies displayed. This option +only constrains the information table where \code{type == "code"}.} } \description{ -The \code{fmt_currency()} function lets us format numeric values as -currencies. The table generated by the \code{info_currencies()} function -provides a quick reference to all the available currencies. The currency -identifiers are provided (name, 3-letter currency code, and 3-digit currency -code) along with the each currency's exponent value (number of digits of the -currency subunits). A formatted example is provided (based on the value of -\code{49.95}) to demonstrate the default formatting of each currency. +The \code{fmt_currency()} function lets us format numeric values as currencies. +The table generated by the \code{info_currencies()} function provides a quick +reference to all the available currencies. The currency identifiers are +provided (name, 3-letter currency code, and 3-digit currency code) along with +the each currency's exponent value (number of digits of the currency +subunits). A formatted example is provided (based on the value of \code{49.95}) to +demonstrate the default formatting of each currency. } \details{ There are 172 currencies, which can lead to a verbose display table. To make diff --git a/man/info_date_style.Rd b/man/info_date_style.Rd index 3da4ea5322..d6397f7197 100644 --- a/man/info_date_style.Rd +++ b/man/info_date_style.Rd @@ -7,11 +7,11 @@ info_date_style() } \description{ -The \code{fmt_date()} function lets us format date-based values in a -convenient manner using preset styles. The table generated by the -\code{info_date_style()} function provides a quick reference to all 14 -styles, with associated number codes, the format names, and example outputs -using a fixed date (\code{2000-02-29}). +The \code{fmt_date()} function lets us format date-based values in a convenient +manner using preset styles. The table generated by the \code{info_date_style()} +function provides a quick reference to all 14 styles, with associated number +codes, the format names, and example outputs using a fixed date +(\code{2000-02-29}). } \section{Figures}{ diff --git a/man/info_locales.Rd b/man/info_locales.Rd index a76492f25f..31e88c9332 100644 --- a/man/info_locales.Rd +++ b/man/info_locales.Rd @@ -7,25 +7,24 @@ info_locales(begins_with = NULL) } \arguments{ -\item{begins_with}{providing a single letter will filter locales to only +\item{begins_with}{Providing a single letter will filter locales to only those that begin with that letter in their base locale ID. The default (\code{NULL}) will produce a table with all locales displayed.} } \description{ Many of the \code{fmt_*()} functions have a \code{locale} argument that makes -locale-based formatting easier. The table generated by the -\code{info_locales()} function provides a quick reference to all the -available locales. The locale identifiers are provided (base locale ID, -common display name) along with the each locale's group and decimal separator -marks. A formatted numeric example is provided (based on the value of -\code{11027}) to demonstrate the default formatting of each locale. +locale-based formatting easier. The table generated by the \code{info_locales()} +function provides a quick reference to all the available locales. The locale +identifiers are provided (base locale ID, common display name) along with the +each locale's group and decimal separator marks. A formatted numeric example +is provided (based on the value of \code{11027}) to demonstrate the default +formatting of each locale. } \details{ There are 712 locales, which means that a very long display table is provided by default. To trim down the output table size, we can provide an initial -letter corresponding to the base locale ID to \code{begins_with}. This will -filter locales in the info table to just the set beginning with the supplied -letter. +letter corresponding to the base locale ID to \code{begins_with}. This will filter +locales in the info table to just the set beginning with the supplied letter. } \examples{ # Get a table of info on all of diff --git a/man/info_paletteer.Rd b/man/info_paletteer.Rd index 3a79eef62a..5687dac3f2 100644 --- a/man/info_paletteer.Rd +++ b/man/info_paletteer.Rd @@ -7,20 +7,20 @@ info_paletteer(color_pkgs = NULL) } \arguments{ -\item{color_pkgs}{a vector of color packages that determines which sets of +\item{color_pkgs}{A vector of color packages that determines which sets of palettes should be displayed in the information table. If this is \code{NULL} (the default) then all of the discrete palettes from all of the color packages represented in \pkg{paletteer} will be displayed.} } \description{ -While the \code{\link{data_color}()} function allows us to flexibly color -data cells in our \pkg{gt} table, the harder part of this process is -discovering and choosing color palettes that are suitable for the table -output. We can make this process much easier in two ways: (1) by using the -\pkg{paletteer} package, which makes a wide range of palettes from various R -packages readily available, and (2) calling the \code{info_paletteer()} -function to give us an information table that serves as a quick reference for -all of the discrete color palettes available in \pkg{paletteer}. +While the \code{\link[=data_color]{data_color()}} function allows us to flexibly color data cells in +our \pkg{gt} table, the harder part of this process is discovering and +choosing color palettes that are suitable for the table output. We can make +this process much easier in two ways: (1) by using the \pkg{paletteer} +package, which makes a wide range of palettes from various R packages readily +available, and (2) calling the \code{info_paletteer()} function to give us an +information table that serves as a quick reference for all of the discrete +color palettes available in \pkg{paletteer}. } \details{ The palettes displayed are organized by package and by palette name. These diff --git a/man/info_time_style.Rd b/man/info_time_style.Rd index d3bf4022ab..0a1482a3b6 100644 --- a/man/info_time_style.Rd +++ b/man/info_time_style.Rd @@ -7,11 +7,11 @@ info_time_style() } \description{ -The \code{fmt_time()} function lets us format time-based values in a -convenient manner using preset styles. The table generated by the -\code{info_time_style()} function provides a quick reference to all five -styles, with associated number codes, the format names, and example outputs -using a fixed time (\code{14:35}). +The \code{fmt_time()} function lets us format time-based values in a convenient +manner using preset styles. The table generated by the \code{info_time_style()} +function provides a quick reference to all five styles, with associated +number codes, the format names, and example outputs using a fixed time +(\code{14:35}). } \section{Figures}{ diff --git a/man/knit_print.gt_tbl.Rd b/man/knit_print.gt_tbl.Rd index 69301c8d40..ee42eaa2b6 100644 --- a/man/knit_print.gt_tbl.Rd +++ b/man/knit_print.gt_tbl.Rd @@ -7,7 +7,7 @@ knit_print.gt_tbl(x, ...) } \arguments{ -\item{x}{an object of class \code{gt_tbl}.} +\item{x}{An object of class \code{gt_tbl}.} } \description{ This facilitates printing of the HTML table within a knitr code chunk. diff --git a/man/local_image.Rd b/man/local_image.Rd index 2750ab7b7d..9bcff4fabf 100644 --- a/man/local_image.Rd +++ b/man/local_image.Rd @@ -7,38 +7,36 @@ local_image(file, height = 30) } \arguments{ -\item{file}{a path to an image file.} +\item{file}{A path to an image file.} -\item{height}{the absolute height (px) of the image in the table cell.} +\item{height}{The absolute height (px) of the image in the table cell.} } \value{ a character object with an HTML fragment that can be placed inside of - a cell. +a cell. } \description{ We can flexibly add a local image (i.e., an image residing on disk) inside of -a table with \code{local_image()} function. The function provides a -convenient way to generate an HTML fragment using an on-disk PNG or SVG. -Because this function is currently HTML-based, it is only useful for HTML -table output. To use this function inside of data cells, it is recommended -that the \code{\link{text_transform}()} function is used. With that function, -we can specify which data cells to target and then include a -\code{local_image()} call within the required user-defined function (for the -\code{fn} argument). If we want to include an image in other places (e.g., in -the header, within footnote text, etc.) we need to use \code{local_image()} -within the \code{\link{html}()} helper function. +a table with \code{local_image()} function. The function provides a convenient way +to generate an HTML fragment using an on-disk PNG or SVG. Because this +function is currently HTML-based, it is only useful for HTML table output. To +use this function inside of data cells, it is recommended that the +\code{\link[=text_transform]{text_transform()}} function is used. With that function, we can specify which +data cells to target and then include a \code{local_image()} call within the +required user-defined function (for the \code{fn} argument). If we want to include +an image in other places (e.g., in the header, within footnote text, etc.) we +need to use \code{local_image()} within the \code{\link[=html]{html()}} helper function. } \details{ By itself, the function creates an HTML image tag with an image URI embedded within. We can easily experiment with a local PNG or SVG image that's -available in the \pkg{gt} package using the \code{\link{test_image}()} -function. Using that, the call \code{local_image(file = test_image(type = -"png"))} evaluates to: +available in the \pkg{gt} package using the \code{\link[=test_image]{test_image()}} function. Using +that, the call \code{local_image(file = test_image(type = "png"))} evaluates to: \code{ src= style=\"height:30px;\">} -where a height of \code{30px} is a default height chosen to work well within -the heights of most table rows. +where a height of \code{30px} is a default height chosen to work well within the +heights of most table rows. } \section{Figures}{ diff --git a/man/location_cells.Rd b/man/location_cells.Rd index fec9154807..7f76fcb72a 100644 --- a/man/location_cells.Rd +++ b/man/location_cells.Rd @@ -26,10 +26,9 @@ cells_summary(groups = NULL, columns = NULL, rows = NULL) cells_grand_summary(columns = NULL, rows = NULL) } \arguments{ -\item{columns, rows, groups}{either a vector of names, a vector of -indices, values provided by \code{\link{vars}()}, values provided by -\code{c()}, or a select helper function (see Details for information on -these functions).} +\item{columns, rows, groups}{Either a vector of names, a vector of indices, +values provided by \code{\link[=vars]{vars()}}, values provided by \code{c()}, or a select helper +function (see Details for information on these functions).} } \value{ a list object of class \code{location_cells}. @@ -38,9 +37,9 @@ a list object of class \code{location_cells}. These helper functions are used to target individual cells in different locations (e.g., the stub, the column labels, the title, etc.). They can be used in any of these functions (which all have a \code{locations} argument): -\code{\link{tab_footnote}()}, \code{\link{tab_style}()}, and -\code{\link{text_transform}()} Furthermore, multiple locations can be -targeted by enclosing several \code{cells_*()} helper functions in a list. +\code{\link[=tab_footnote]{tab_footnote()}}, \code{\link[=tab_style]{tab_style()}}, and \code{\link[=text_transform]{text_transform()}} Furthermore, multiple +locations can be targeted by enclosing several \code{cells_*()} helper functions +in a list. } \details{ The following helper functions can be used to target cells (roughly in order diff --git a/man/md.Rd b/man/md.Rd index 18db87b6a0..4464d09bf5 100644 --- a/man/md.Rd +++ b/man/md.Rd @@ -7,11 +7,11 @@ md(text) } \arguments{ -\item{text}{the text that is understood to contain Markdown formatting.} +\item{text}{The text that is understood to contain Markdown formatting.} } \value{ -a character object that is tagged for a Markdown-to-HTML - transformation. +A character object that is tagged for a Markdown-to-HTML +transformation. a character object of class \code{from_markdown}. } diff --git a/man/pct.Rd b/man/pct.Rd index c5bee2254f..1433a9511c 100644 --- a/man/pct.Rd +++ b/man/pct.Rd @@ -8,7 +8,7 @@ pct(x) } \arguments{ \item{x}{the numeric value to format as a string percentage for some -\code{\link{tab_options}()} arguments that can take percentage values +\code{\link[=tab_options]{tab_options()}} arguments that can take percentage values (e.g., \code{table.width}).} } \description{ diff --git a/man/pizzaplace.Rd b/man/pizzaplace.Rd index 66b1e94ed5..1b83196480 100644 --- a/man/pizzaplace.Rd +++ b/man/pizzaplace.Rd @@ -6,22 +6,22 @@ \title{A year of pizza sales from a pizza place} \format{A tibble with 49574 rows and 7 variables: \describe{ - \item{id}{The ID for the order, which consists of one or more pizzas - at a give \code{date} and \code{time}} - \item{date}{A character representation of the \code{order} date, - expressed in the ISO 8601 date format (YYYY-MM-DD)} - \item{time}{A character representation of the \code{order} time, - expressed as a 24-hour time the ISO 8601 extended time format - (hh:mm:ss)} - \item{name}{The short name for the pizza} - \item{size}{The size of the pizza, which can either be \code{S}, - \code{M}, \code{L}, \code{XL} (rare!), or \code{XXL} (even rarer!); - most pizzas are available in the \code{S}, \code{M}, and \code{L} sizes - but exceptions apply} - \item{type}{The category or type of pizza, which can either be - \code{classic}, \code{chicken}, \code{supreme}, or \code{veggie}} - \item{price}{The price of the pizza and the amount that it sold for - (in USD)} +\item{id}{The ID for the order, which consists of one or more pizzas +at a give \code{date} and \code{time}} +\item{date}{A character representation of the \code{order} date, +expressed in the ISO 8601 date format (YYYY-MM-DD)} +\item{time}{A character representation of the \code{order} time, +expressed as a 24-hour time the ISO 8601 extended time format +(hh:mm:ss)} +\item{name}{The short name for the pizza} +\item{size}{The size of the pizza, which can either be \code{S}, +\code{M}, \code{L}, \code{XL} (rare!), or \code{XXL} (even rarer!); +most pizzas are available in the \code{S}, \code{M}, and \code{L} sizes +but exceptions apply} +\item{type}{The category or type of pizza, which can either be +\code{classic}, \code{chicken}, \code{supreme}, or \code{veggie}} +\item{price}{The price of the pizza and the amount that it sold for +(in USD)} }} \usage{ pizzaplace @@ -30,13 +30,13 @@ pizzaplace A synthetic dataset that describes pizza sales for a pizza place somewhere in the US. While the contents are artificial, the ingredients used to make the pizzas are far from it. There are 32 different pizzas that fall into 4 -different categories: \code{classic} (classic pizzas: 'You probably had one -like it before, but never like this!'), \code{chicken} (pizzas with chicken -as a major ingredient: 'Try the Southwest Chicken Pizza! You'll love it!'), -\code{supreme} (pizzas that try a little harder: 'My Soppressata pizza uses -only the finest salami from my personal salumist!'), and, \code{veggie} -(pizzas without any meats whatsoever: 'My Five Cheese pizza has so many -cheeses, I can only offer it in Large Size!'). +different categories: \code{classic} (classic pizzas: 'You probably had one like +it before, but never like this!'), \code{chicken} (pizzas with chicken as a major +ingredient: 'Try the Southwest Chicken Pizza! You'll love it!'), \code{supreme} +(pizzas that try a little harder: 'My Soppressata pizza uses only the finest +salami from my personal salumist!'), and, \code{veggie} (pizzas without any meats +whatsoever: 'My Five Cheese pizza has so many cheeses, I can only offer it in +Large Size!'). } \details{ Each pizza in the dataset is identified by a short \code{name}. The following @@ -80,7 +80,7 @@ Red Peppers, Mushrooms, Asiago Cheese, Alfredo Sauce) Supreme Pizzas: \itemize{ \item \code{brie_carre}: The Brie Carre Pizza (Brie Carre Cheese, Prosciutto, - Caramelized Onions, Pears, Thyme, Garlic) +Caramelized Onions, Pears, Thyme, Garlic) \item \code{calabrese}: The Calabrese Pizza (‘Nduja Salami, Pancetta, Tomatoes, Red Onions, Friggitello Peppers, Garlic) \item \code{soppressata}: The Soppressata Pizza (Soppressata Salami, Fontina diff --git a/man/print.gt_tbl.Rd b/man/print.gt_tbl.Rd index 962dbe26c7..f33052d278 100644 --- a/man/print.gt_tbl.Rd +++ b/man/print.gt_tbl.Rd @@ -7,7 +7,7 @@ \method{print}{gt_tbl}(x, ..., view = interactive()) } \arguments{ -\item{x}{an object of class \code{gt_tbl}.} +\item{x}{An object of class \code{gt_tbl}.} } \description{ This facilitates printing of the HTML table to the R console. diff --git a/man/px.Rd b/man/px.Rd index 5c6bf96cb0..027f7e2281 100644 --- a/man/px.Rd +++ b/man/px.Rd @@ -8,7 +8,7 @@ px(x) } \arguments{ \item{x}{the numeric value to format as a string (e.g., \code{"12px"}) for -some \code{\link{tab_options}()} arguments that can take values as units of +some \code{\link[=tab_options]{tab_options()}} arguments that can take values as units of pixels (e.g., \code{table.font.size}).} } \description{ diff --git a/man/render_gt.Rd b/man/render_gt.Rd index 2685ccf985..1b8c843b36 100644 --- a/man/render_gt.Rd +++ b/man/render_gt.Rd @@ -8,16 +8,16 @@ render_gt(expr, env = parent.frame(), quoted = FALSE, outputArgs = list()) } \arguments{ -\item{expr}{an expression that creates a \pkg{gt} table object.} +\item{expr}{An expression that creates a \pkg{gt} table object.} -\item{env}{the environment in which to evaluate the \code{expr}.} +\item{env}{The environment in which to evaluate the \code{expr}.} -\item{quoted}{is expr a quoted expression (with \code{quote()})? This is -useful if you want to save an expression in a variable.} +\item{quoted}{Is \code{expr`` a quoted expression (with }quote()`)? This is useful +if you want to save an expression in a variable.} \item{outputArgs}{A list of arguments to be passed through to the implicit -call to \code{\link{gt_output}()} when \code{render_gt} is used in an -interactive R Markdown document.} +call to \code{\link[=gt_output]{gt_output()}} when \code{render_gt} is used in an interactive R Markdown +document.} } \description{ A \pkg{gt} display table render function for use in Shiny diff --git a/man/row_group_order.Rd b/man/row_group_order.Rd index e19023ee7b..67d8479eb6 100644 --- a/man/row_group_order.Rd +++ b/man/row_group_order.Rd @@ -7,10 +7,9 @@ row_group_order(data, groups) } \arguments{ -\item{data}{a table object that is created using the \code{\link{gt}()} -function.} +\item{data}{A table object that is created using the \code{\link[=gt]{gt()}} function.} -\item{groups}{a vector of row group names, or, a numeric vector of indices +\item{groups}{A vector of row group names, or, a numeric vector of indices corresponding to the new ordering. Either vector must correspond to assigned group names or the index positions. Also, either type of vector is not required to have all of the row group names or available index @@ -18,16 +17,16 @@ positions within it; any omitted values will be added to the end while preserving the original ordering.} } \value{ -an object of class \code{gt_tbl}. +An object of class \code{gt_tbl}. } \description{ We can modify the display order of any row groups in a \pkg{gt} object with -the \code{row_group_order()} function. The \code{groups} argument can either -take a vector of row group names or a numeric vector of row group indices; -whichever is provided, the row groups will adhere to this revised ordering. -It isn't necessary to provide all row group names in \code{groups}, rather, -what is provided will assume the specified ordering at the top of the table -and the remaining row groups will follow in their original ordering. +the \code{row_group_order()} function. The \code{groups} argument can either take a +vector of row group names or a numeric vector of row group indices; whichever +is provided, the row groups will adhere to this revised ordering. It isn't +necessary to provide all row group names in \code{groups}, rather, what is +provided will assume the specified ordering at the top of the table and the +remaining row groups will follow in their original ordering. } \section{Figures}{ diff --git a/man/sp500.Rd b/man/sp500.Rd index 967ce05ba6..d694929c1a 100644 --- a/man/sp500.Rd +++ b/man/sp500.Rd @@ -6,14 +6,14 @@ \title{Daily S&P 500 Index data from 1950 to 2015} \format{A tibble with 16607 rows and 7 variables: \describe{ - \item{date}{The date expressed as \code{Date} values} - \item{open, high, low, close}{The day's opening, high, low, and closing - prices in USD; the \code{close} price is adjusted for splits} - \item{volume}{the number of trades for the given \code{date}} - \item{adj_close}{The close price adjusted for both dividends and splits} +\item{date}{The date expressed as \code{Date} values} +\item{open, high, low, close}{The day's opening, high, low, and closing +prices in USD; the \code{close} price is adjusted for splits} +\item{volume}{the number of trades for the given \code{date}} +\item{adj_close}{The close price adjusted for both dividends and splits} }} \source{ -Data collected from \url{https://finance.yahoo.com/quote/\%5EGSPC/history/}. +Data collected from \url{https://finance.yahoo.com/quote/\\\%5EGSPC/history/}. } \usage{ sp500 diff --git a/man/summary_rows.Rd b/man/summary_rows.Rd index 2ce924814c..6d709b9aa5 100644 --- a/man/summary_rows.Rd +++ b/man/summary_rows.Rd @@ -8,60 +8,56 @@ summary_rows(data, groups = NULL, columns = TRUE, fns, missing_text = "---", formatter = fmt_number, ...) } \arguments{ -\item{data}{A table object that is created using the \code{gt()} function.} +\item{data}{A table object that is created using the \code{\link[=gt]{gt()}} function.} \item{groups}{The groups to consider for generation of groupwise summary -rows. By default this is set to \code{NULL}, which results in the formation -of grand summary rows (a grand summary operates on all table data). -Providing the names of row groups in \code{c()} will create a groupwise -summary and generate summary rows for the specified groups. Setting this to -\code{TRUE} indicates that all available groups will receive groupwise -summary rows.} +rows. By default this is set to \code{NULL}, which results in the formation of +grand summary rows (a grand summary operates on all table data). Providing +the names of row groups in \code{\link[=c]{c()}} will create a groupwise summary and +generate summary rows for the specified groups. Setting this to \code{TRUE} +indicates that all available groups will receive groupwise summary rows.} \item{columns}{The columns for which the summaries should be calculated.} \item{fns}{Functions used for aggregations. This can include base functions -like \code{mean}, \code{min}, \code{max}, \code{median}, \code{sd}, or -\code{sum} or any other user-defined aggregation function. The function(s) -should be supplied within a \code{list()}. Within that list, we can specify -the functions by use of function names in quotes (e.g., \code{"sum"}), as -bare functions (e.g., \code{sum}), or as one-sided R formulas using a -leading \code{~}. In the formula representation, a \code{.} serves as the -data to be summarized (e.g., \code{sum(., na.rm = TRUE)}). The use of named -arguments is recommended as the names will serve as summary row labels for -the corresponding summary rows data (the labels can derived from the -function names but only when not providing bare function names).} +like \code{mean}, \code{min}, \code{max}, \code{median}, \code{sd}, or \code{sum} or any other +user-defined aggregation function. The function(s) should be supplied +within a \code{list()}. Within that list, we can specify the functions by use of +function names in quotes (e.g., \code{"sum"}), as bare functions (e.g., \code{sum}), +or as one-sided R formulas using a leading \code{~}. In the formula +representation, a \code{.} serves as the data to be summarized (e.g., \code{sum(., na.rm = TRUE)}). The use of named arguments is recommended as the names +will serve as summary row labels for the corresponding summary rows data +(the labels can derived from the function names but only when not providing +bare function names).} -\item{missing_text}{The text to be used in place of \code{NA} values in -summary cells with no data outputs.} +\item{missing_text}{The text to be used in place of \code{NA} values in summary +cells with no data outputs.} -\item{formatter}{A formatter function name. These can be any of the -\code{fmt_*()}functions available in the package (e.g., -\code{\link{fmt_number}()}, \code{link{fmt_percent}()}, etc.), or a custom -function using \code{\link{fmt}()}. The default function is -\code{\link{fmt_number}()} and its options can be accessed through -\code{...}.} +\item{formatter}{A formatter function name. These can be any of the \code{fmt_*()} +functions available in the package (e.g., \code{\link[=fmt_number]{fmt_number()}}, \code{\link[=fmt_percent]{fmt_percent()}}, +etc.), or a custom function using \code{fmt()}. The default function is +\code{\link[=fmt_number]{fmt_number()}} and its options can be accessed through \code{...}.} \item{...}{Values passed to the \code{formatter} function, where the provided values are to be in the form of named vectors. For example, when using the -default \code{formatter} function, \code{\link{fmt_number}()}, options such -as \code{decimals}, \code{use_seps}, and \code{locale} can be used.} +default \code{formatter} function, \code{\link[=fmt_number]{fmt_number()}}, options such as \code{decimals}, +\code{use_seps}, and \code{locale} can be used.} } \value{ An object of class \code{gt_tbl}. } \description{ Add groupwise summary rows to one or more row groups by using the input data -already provided in the \code{\link{gt}()} function alongside any suitable -aggregation functions. Or, add a grand summary that incorporates all -available data, regardless of grouping. You choose how to format the values -in the resulting summary cells by use of a \code{formatter} function (e.g, -\code{\link{fmt_number}()}) and any relevant options. +already provided in the \code{\link[=gt]{gt()}} function alongside any suitable aggregation +functions. Or, add a grand summary that incorporates all available data, +regardless of grouping. You choose how to format the values in the resulting +summary cells by use of a \code{formatter} function (e.g, \code{fmt_number}) and any +relevant options. } \details{ Should we need to obtain the summary data for external purposes, the -\code{\link{extract_summary}()} function can be used with a \code{gt_tbl} -object where summary rows were added via \code{summary_rows()}. +\code{\link[=extract_summary]{extract_summary()}} function can be used with a \code{gt_tbl} object where summary +rows were added via \code{summary_rows()}. } \section{Figures}{ diff --git a/man/sza.Rd b/man/sza.Rd index 085eca45b3..f9b9319b37 100644 --- a/man/sza.Rd +++ b/man/sza.Rd @@ -6,13 +6,13 @@ \title{Twice hourly solar zenith angles by month & latitude} \format{A tibble with 816 rows and 4 variables: \describe{ - \item{latitude}{The latitude in decimal degrees for the observations} - \item{month}{The measurement month; all calculations where conducted - for the first day of each month} - \item{tst}{The true solar time at the given \code{latitude} and date - (first of \code{month}) for which the solar zenith angle is calculated} - \item{sza}{The solar zenith angle in degrees, where \code{NA}s - indicate that sunrise hadn't yet occurred by the \code{tst} value} +\item{latitude}{The latitude in decimal degrees for the observations} +\item{month}{The measurement month; all calculations where conducted +for the first day of each month} +\item{tst}{The true solar time at the given \code{latitude} and date +(first of \code{month}) for which the solar zenith angle is calculated} +\item{sza}{The solar zenith angle in degrees, where \code{NA}s +indicate that sunrise hadn't yet occurred by the \code{tst} value} }} \source{ Calculated Actinic Fluxes (290 - 700 nm) for Air Pollution diff --git a/man/tab_footnote.Rd b/man/tab_footnote.Rd index d9644360da..ab725ab990 100644 --- a/man/tab_footnote.Rd +++ b/man/tab_footnote.Rd @@ -7,54 +7,46 @@ tab_footnote(data, footnote, locations) } \arguments{ -\item{data}{A table object that is created using the \code{\link{gt}()} -function.} +\item{data}{A table object that is created using the \code{\link[=gt]{gt()}} function.} -\item{footnote}{the text to be used in the footnote. We can optionally use -the \code{\link{md}()} and \code{\link{html}()} functions to style the text -as Markdown or to retain HTML elements in the footnote text.} +\item{footnote}{The text to be used in the footnote. We can optionally use +the \code{\link[=md]{md()}} and \code{\link[=html]{html()}} functions to style the text as Markdown or to +retain HTML elements in the footnote text.} -\item{locations}{the cell or set of cells to be associated with the footnote. -Supplying any of the \code{cells_*()} helper functions is a useful way to -target the location cells that are associated with the footnote text. These -helper functions are: \code{\link{cells_title}()}, -\code{\link{cells_column_labels}()}, \code{\link{cells_group}()}, -\code{\link{cells_stub}()}, \code{\link{cells_data}()}, and -\code{\link{cells_summary}()}. Please see the help article -\link{location_cells} for more information on how these helper functions -can be used. Additionally, we can enclose several \code{cells_*()} calls -within a \code{list()} if we wish to link the footnote text to different +\item{locations}{The cell or set of cells to be associated with the footnote. +Supplying any of the \code{cells_*()} helper functions is a useful way to target +the location cells that are associated with the footnote text. These helper +functions are: \code{\link[=cells_title]{cells_title()}}, \code{\link[=cells_column_labels]{cells_column_labels()}}, \code{\link[=cells_group]{cells_group()}}, +\code{\link[=cells_stub]{cells_stub()}}, \code{\link[=cells_data]{cells_data()}}, and \code{\link[=cells_summary]{cells_summary()}}. Please see the help +article \link{location_cells} for more information on how these helper +functions can be used. Additionally, we can enclose several \code{cells_*()} +calls within a \code{list()} if we wish to link the footnote text to different types of locations (e.g., cell data values, stub group headings, the table title, etc.).} } \value{ -an object of class \code{gt_tbl}. +An object of class \code{gt_tbl}. } \description{ The \code{tab_footnote()} function can make it a painless process to add a footnote to a \pkg{gt} table. There are two components to a footnote: (1) a glyph that is attached to the targeted cell text, and (2) the footnote text (that starts with the corresponding glyph) that is placed in the table's -footer area. Each call of \code{tab_footnote()} will add a different note, -and one or more cells can be targeted via the location helper functions -(e.g., \code{\link{cells_data}()}, \code{\link{cells_column_labels}()}, -etc.). +footer area. Each call of \code{tab_footnote()} will add a different note, and one +or more cells can be targeted via the location helper functions (e.g., +\code{\link[=cells_data]{cells_data()}}, \code{\link[=cells_column_labels]{cells_column_labels()}}, etc.). } \details{ The formatting of the footnotes can be controlled through the use of various -parameters in the \code{\link{tab_options}()} function: +parameters in the \code{\link[=tab_options]{tab_options()}} function: -\itemize{ -\item \code{footnote.sep}: allows for a choice of the separator between +\itemize{ \item \code{footnote.sep}: allows for a choice of the separator between consecutive footnotes in the table footer. By default, this is set to a -linebreak. -\item \code{footnote.glyph}: the set of sequential characters or numbers -used to identify the footnotes. -\item \code{footnote.font.size}: the size of the font used in the footnote -section. -\item \code{footnote.padding}: the amount of padding to apply between the -footnote and source note sections in the table footer. -} +linebreak. \item \code{footnote.glyph}: the set of sequential characters or +numbers used to identify the footnotes. \item \code{footnote.font.size}: the size +of the font used in the footnote section. \item \code{footnote.padding}: the +amount of padding to apply between the footnote and source note sections in +the table footer. } } \section{Figures}{ diff --git a/man/tab_header.Rd b/man/tab_header.Rd index 9c76a43d97..37118eff40 100644 --- a/man/tab_header.Rd +++ b/man/tab_header.Rd @@ -7,16 +7,15 @@ tab_header(data, title, subtitle = NULL) } \arguments{ -\item{data}{A table object that is created using the \code{\link{gt}()} -function.} +\item{data}{A table object that is created using the \code{\link[=gt]{gt()}} function.} -\item{title, subtitle}{text to be used in the table title and, optionally, for -the table subtitle. We can elect to use the \code{\link{md}()} and -\code{\link{html}()} helper functions to style the text as Markdown or to -retain HTML elements in the text.} +\item{title, subtitle}{Text to be used in the table title and, optionally, for +the table subtitle. We can elect to use the \code{\link[=md]{md()}} and \code{\link[=html]{html()}} helper +functions to style the text as Markdown or to retain HTML elements in the +text.} } \value{ -an object of class \code{gt_tbl}. +An object of class \code{gt_tbl}. } \description{ We can add a table header to the \pkg{gt} table with a title and even a diff --git a/man/tab_options.Rd b/man/tab_options.Rd index e0ea146906..3b479633c5 100644 --- a/man/tab_options.Rd +++ b/man/tab_options.Rd @@ -38,45 +38,42 @@ tab_options(data, table.width = NULL, table.font.size = NULL, row.striping.include_table_body = NULL) } \arguments{ -\item{data}{A table object that is created using the \code{\link{gt}()} -function.} +\item{data}{A table object that is created using the \code{\link[=gt]{gt()}} function.} -\item{table.width}{the width of the table. Can be specified as a +\item{table.width}{The width of the table. Can be specified as a single-length character with units of pixels or as a percentage. If provided as a single-length numeric vector, it is assumed that the value is -given in units of pixels. The \code{\link{px}()} and \code{\link{pct}()} -helper functions can also be used to pass in numeric values and obtain -values as pixel or percent units.} - -\item{table.font.size, heading.title.font.size, heading.subtitle.font.size, column_labels.font.size, row_group.font.size, footnote.font.size, sourcenote.font.size}{font sizes for the parent text element \code{table} and the following child -elements: \code{heading.title}, \code{heading.subtitle}, \code{columns}, -\code{row_group}, \code{footnote}, and \code{sourcenote}. Can be specified -as a single-length character vector with units of pixels (e.g., -\code{12px}) or as a percentage (e.g., \code{80\%}). If provided as a -single-length numeric vector, it is assumed that the value is given in -units of pixels. The \code{\link{px}()} and \code{\link{pct}()} helper +given in units of pixels. The \code{\link[=px]{px()}} and \code{\link[=pct]{pct()}} helper functions can also +be used to pass in numeric values and obtain values as pixel or percent +units.} + +\item{table.font.size, heading.title.font.size, heading.subtitle.font.size, column_labels.font.size, row_group.font.size, footnote.font.size, sourcenote.font.size}{Font sizes for the parent text element \code{table} and the following child +elements: \code{heading.title}, \code{heading.subtitle}, \code{columns}, \code{row_group}, +\code{footnote}, and \code{sourcenote}. Can be specified as a single-length character +vector with units of pixels (e.g., \code{12px}) or as a percentage (e.g., +\code{80\\\%}). If provided as a single-length numeric vector, it is assumed that +the value is given in units of pixels. The \code{\link[=px]{px()}} and \code{\link[=pct]{pct()}} helper functions can also be used to pass in numeric values and obtain values as pixel or percent units.} -\item{table.background.color, heading.background.color, column_labels.background.color, row_group.background.color, summary_row.background.color, grand_summary_row.background.color}{background colors for the parent element \code{table} and the following -child elements: \code{heading}, \code{columns}, \code{row_group}, -\code{summary_row}, and \code{table_body}. A color name or a hexadecimal -color code should be provided.} +\item{table.background.color, heading.background.color, column_labels.background.color, row_group.background.color, summary_row.background.color, grand_summary_row.background.color}{background colors for the parent element \code{table} and the following child +elements: \code{heading}, \code{columns}, \code{row_group}, \code{summary_row}, and +\code{table_body}. A color name or a hexadecimal color code should be provided.} -\item{table.border.top.style, table.border.top.width, table.border.top.color}{the style, width, and color of the table's top border.} +\item{table.border.top.style, table.border.top.width, table.border.top.color}{The style, width, and color of the table's top border.} -\item{heading.border.bottom.style, heading.border.bottom.width, heading.border.bottom.color}{the style, width, and color of the heading's bottom border.} +\item{heading.border.bottom.style, heading.border.bottom.width, heading.border.bottom.color}{The style, width, and color of the heading's bottom border.} \item{column_labels.font.weight, row_group.font.weight}{the font weight of the \code{columns} and \code{row_group} text element.} -\item{column_labels.hidden}{an option to hide the column labels.} +\item{column_labels.hidden}{An option to hide the column labels.} -\item{row_group.border.top.style, row_group.border.top.width, row_group.border.top.color}{the style, width, and color of the row group's top border.} +\item{row_group.border.top.style, row_group.border.top.width, row_group.border.top.color}{The style, width, and color of the row group's top border.} -\item{row_group.border.bottom.style, row_group.border.bottom.width, row_group.border.bottom.color}{the style, width, and color of the row group's bottom border.} +\item{row_group.border.bottom.style, row_group.border.bottom.width, row_group.border.bottom.color}{The style, width, and color of the row group's bottom border.} -\item{table_body.border.top.style, table_body.border.top.width, table_body.border.top.color}{the style, width, and color of the table body's top border.} +\item{table_body.border.top.style, table_body.border.top.width, table_body.border.top.color}{The style, width, and color of the table body's top border.} \item{table_body.border.bottom.style, table_body.border.bottom.width, table_body.border.bottom.color}{the style, width, and color of the table body's bottom border.} @@ -89,22 +86,22 @@ to apply text transformations to the label text in each summary row.} \item{footnote.sep}{the separating characters between adjacent footnotes in the footnotes section. The default value produces a linebreak.} -\item{footnote.glyph}{the set of sequential figures or characters used to -identify the footnotes. We can either supply the keyword \code{"numbers"} -(the default, indicating that we want numeric glyphs), the keywords -\code{"letters"} or \code{"LETTERS"} (indicating that we want letters as -glyphs, either lowercase or uppercase), or, a vector of character values -representing the series of glyphs. A series of glyphs is recycled when its -usage goes beyond the length of the set. At each cycle, the glyphs are -simply combined (e.g., \code{*} -> \code{**} -> \code{***}).} +\item{footnote.glyph}{The set of sequential figures or characters used to +identify the footnotes. We can either supply the keyword \code{"numbers"} (the +default, indicating that we want numeric glyphs), the keywords \code{"letters"} +or \code{"LETTERS"} (indicating that we want letters as glyphs, either lowercase +or uppercase), or, a vector of character values representing the series of +glyphs. A series of glyphs is recycled when its usage goes beyond the +length of the set. At each cycle, the glyphs are simply combined (e.g., \code{*} +-> \code{**} -> \code{***}).} -\item{footnote.padding, sourcenote.padding}{the amount of padding to apply to +\item{footnote.padding, sourcenote.padding}{The amount of padding to apply to the footnote and source note sections.} -\item{row.striping.include_stub}{an option for whether to include the stub +\item{row.striping.include_stub}{An option for whether to include the stub when striping rows.} -\item{row.striping.include_table_body}{an option for whether to include the +\item{row.striping.include_table_body}{An option for whether to include the table body when striping rows.} } \value{ diff --git a/man/tab_row_group.Rd b/man/tab_row_group.Rd index 43c897fb26..b40195ce1d 100644 --- a/man/tab_row_group.Rd +++ b/man/tab_row_group.Rd @@ -7,30 +7,28 @@ tab_row_group(data, group = NULL, rows = NULL, others = NULL) } \arguments{ -\item{data}{A table object that is created using the \code{\link{gt}()} -function.} +\item{data}{A table object that is created using the \code{\link[=gt]{gt()}} function.} -\item{group}{the name of the row group. This text will also serve as the row +\item{group}{The name of the row group. This text will also serve as the row group label.} -\item{rows}{the rows to be made components of the row group. Can either be a -vector of row captions provided \code{c()}, a vector of row indices, or a -helper function focused on selections. The select helper functions are: -\code{\link{starts_with}()}, \code{\link{ends_with}()}, -\code{\link{contains}()}, \code{\link{matches}()}, \code{\link{one_of}()}, -and \code{\link{everything}()}.} +\item{rows}{The rows to be made components of the row group. Can either be a +vector of row captions provided \code{c()}, a vector of row indices, or a helper +function focused on selections. The select helper functions are: +\code{\link[=starts_with]{starts_with()}}, \code{\link[=ends_with]{ends_with()}}, \code{\link[=contains]{contains()}}, \code{\link[=matches]{matches()}}, \code{\link[=one_of]{one_of()}}, and +\code{\link[=everything]{everything()}}.} -\item{others}{an option to set a default row group label for any rows not +\item{others}{An option to set a default row group label for any rows not formally placed in a row group named by \code{group} in any call of -\code{tab_row_group()}. A separate call to \code{tab_row_group()} with only -a value to \code{others} is possible and makes explicit that the call is -meant to provide a default row group label. If this is not set and -there are rows that haven't been placed into a row group (where one or -more row groups already exist), those rows will be automatically placed into -a row group without a label.} +\code{tab_row_group()}. A separate call to \code{tab_row_group()} with only a value +to \code{others} is possible and makes explicit that the call is meant to +provide a default row group label. If this is not set and there are rows +that haven't been placed into a row group (where one or more row groups +already exist), those rows will be automatically placed into a row group +without a label.} } \value{ -an object of class \code{gt_tbl}. +An object of class \code{gt_tbl}. } \description{ Create a row group with a collection of rows. This requires specification of diff --git a/man/tab_source_note.Rd b/man/tab_source_note.Rd index 00467ad610..1f82c4a753 100644 --- a/man/tab_source_note.Rd +++ b/man/tab_source_note.Rd @@ -7,23 +7,21 @@ tab_source_note(data, source_note) } \arguments{ -\item{data}{A table object that is created using the \code{\link{gt}()} -function.} +\item{data}{A table object that is created using the \code{\link[=gt]{gt()}} function.} -\item{source_note}{text to be used in the source note. We can optionally use -the \code{\link{md}()} and \code{\link{html}()} functions to style the text -as Markdown or to retain HTML elements in the text.} +\item{source_note}{Text to be used in the source note. We can optionally use +the \code{\link[=md]{md()}} and \code{\link[=html]{html()}} functions to style the text as Markdown or to +retain HTML elements in the text.} } \value{ -an object of class \code{gt_tbl}. +An object of class \code{gt_tbl}. } \description{ Add a source note to the footer part of the \pkg{gt} table. A source note is useful for citing the data included in the table. Several can be added to the -footer, simply use multiple calls of \code{tab_source_note()} and they will -be inserted in the order provided. We can use Markdown formatting for the -note, or, if the table is intended for HTML output, we can include HTML -formatting. +footer, simply use multiple calls of \code{tab_source_note()} and they will be +inserted in the order provided. We can use Markdown formatting for the note, +or, if the table is intended for HTML output, we can include HTML formatting. } \section{Figures}{ diff --git a/man/tab_spanner.Rd b/man/tab_spanner.Rd index ccf94a1d4b..66a422856f 100644 --- a/man/tab_spanner.Rd +++ b/man/tab_spanner.Rd @@ -7,19 +7,18 @@ tab_spanner(data, label, columns, gather = TRUE) } \arguments{ -\item{data}{A table object that is created using the \code{\link{gt}()} -function.} +\item{data}{A table object that is created using the \code{\link[=gt]{gt()}} function.} -\item{label}{the text to use for the spanner column label.} +\item{label}{The text to use for the spanner column label.} -\item{columns}{the columns to be components of the spanner heading.} +\item{columns}{The columns to be components of the spanner heading.} -\item{gather}{an option to move the specified \code{columns} such that they -are unified under the spanner column label. Ordering of the -moved-into-place columns will be preserved in all cases.} +\item{gather}{An option to move the specified \code{columns} such that they are +unified under the spanner column label. Ordering of the moved-into-place +columns will be preserved in all cases.} } \value{ -an object of class \code{gt_tbl}. +An object of class \code{gt_tbl}. } \description{ Set a spanner column label by mapping it to columns already in the table. diff --git a/man/tab_stubhead_label.Rd b/man/tab_stubhead_label.Rd index 9e1156e9ad..ef9fefd3d3 100644 --- a/man/tab_stubhead_label.Rd +++ b/man/tab_stubhead_label.Rd @@ -7,15 +7,14 @@ tab_stubhead_label(data, label) } \arguments{ -\item{data}{A table object that is created using the \code{\link{gt}()} -function.} +\item{data}{A table object that is created using the \code{\link[=gt]{gt()}} function.} -\item{label}{the text to be used as the stubhead label We can optionally -use the \code{\link{md}()} and \code{\link{html}()} functions to style the -text as Markdown or to retain HTML elements in the text.} +\item{label}{The text to be used as the stubhead label We can optionally use +the \code{\link[=md]{md()}} and \code{\link[=html]{html()}} functions to style the text as Markdown or to +retain HTML elements in the text.} } \value{ -an object of class \code{gt_tbl}. +An object of class \code{gt_tbl}. } \description{ Add a label to the stubhead of a \pkg{gt} table. The stubhead is the lone diff --git a/man/tab_style.Rd b/man/tab_style.Rd index 5d0f9d6584..900ee04d3e 100644 --- a/man/tab_style.Rd +++ b/man/tab_style.Rd @@ -7,19 +7,18 @@ tab_style(data, style, locations) } \arguments{ -\item{data}{A table object that is created using the \code{\link{gt}()} -function.} +\item{data}{A table object that is created using the \code{\link[=gt]{gt()}} function.} -\item{style}{a vector of styles to use. The \code{\link{cells_styles}()} +\item{style}{a vector of styles to use. The \code{\link[=cells_styles]{cells_styles()}} helper function can be used here to more easily generate valid styles.} \item{locations}{the cell or set of cells to be associated with the style Supplying any of the \code{cells_*()} helper functions is a useful way to target the location cells that are associated with the style application. -These helper functions are: \code{\link{cells_title}()}, -\code{\link{cells_column_labels}()}, \code{\link{cells_group}()}, -\code{\link{cells_stub}()}, \code{\link{cells_data}()}, and -\code{\link{cells_summary}()}. Please see the help article +These helper functions are: \code{\link[=cells_title]{cells_title()}}, +\code{\link[=cells_column_labels]{cells_column_labels()}}, \code{\link[=cells_group]{cells_group()}}, +\code{\link[=cells_stub]{cells_stub()}}, \code{\link[=cells_data]{cells_data()}}, and +\code{\link[=cells_summary]{cells_summary()}}. Please see the help article \link{location_cells} for more information on how these helper functions can be used. Additionally, we can enclose several \code{cells_*()} calls within a \code{list()} if we wish to apply styles to different types of @@ -32,10 +31,10 @@ an object of class \code{gt_tbl}. \description{ With the \code{tab_style()} function we can target specific cells and apply styles to them. This is best done in conjunction with the -\code{\link{cells_styles}()} helper function. At present this function is +\code{\link[=cells_styles]{cells_styles()}} helper function. At present this function is focused on the application of styles for HTML output only (as such, other output formats will ignore all \code{tab_style()} calls). With the help of -\code{\link{cells_styles}()}, we can set the following styles: +\code{\link[=cells_styles]{cells_styles()}}, we can set the following styles: \itemize{ \item the background color of the cell (\code{bkgd_color}) \item the cell's text color (\code{text_color}), font (\code{text_font}), or @@ -118,9 +117,9 @@ tab_2 <- } \seealso{ -\code{\link{cells_styles}()} as a helper for defining custom styles - and \code{\link{cells_data}()} as a useful helper function for targeting - one or more data cells to be styled. +\code{\link[=cells_styles]{cells_styles()}} as a helper for defining custom styles +and \code{\link[=cells_data]{cells_data()}} as a useful helper function for targeting +one or more data cells to be styled. Other table-part creation/modification functions: \code{\link{gt_preview}}, \code{\link{gt}}, \code{\link{tab_footnote}}, diff --git a/man/test_image.Rd b/man/test_image.Rd index 30068001ea..de394fc7ff 100644 --- a/man/test_image.Rd +++ b/man/test_image.Rd @@ -7,15 +7,14 @@ test_image(type = c("png", "svg")) } \arguments{ -\item{type}{the type of the image, which can either be \code{png} (the -default) or \code{svg}.} +\item{type}{The type of the image, which can either be \code{png} (the default) or +\code{svg}.} } \description{ Two test images are available within the \pkg{gt} package. Both contain the same imagery (sized at 200px by 200px) but one is a PNG file while the other -is an SVG file. This function is most useful when paired with -\code{\link{local_image}()} since we test various sizes of the test image -within that function. +is an SVG file. This function is most useful when paired with \code{\link[=local_image]{local_image()}} +since we test various sizes of the test image within that function. } \seealso{ Other image addition functions: \code{\link{ggplot_image}}, diff --git a/man/text_transform.Rd b/man/text_transform.Rd index 1fbe7bea41..da229fb5d0 100644 --- a/man/text_transform.Rd +++ b/man/text_transform.Rd @@ -7,26 +7,23 @@ text_transform(data, locations, fn) } \arguments{ -\item{data}{a table object that is created using the \code{\link{gt}()} -function.} +\item{data}{A table object that is created using the \code{\link[=gt]{gt()}} function.} -\item{locations}{the cell or set of cells to be associated with the text +\item{locations}{The cell or set of cells to be associated with the text transformation. Supplying any of the \code{cells_*()} helper functions is a useful way to target the location cells that are associated with the -footnote text. These helper functions are: \code{\link{cells_title}()}, -\code{\link{cells_column_labels}()}, \code{\link{cells_group}()}, -\code{\link{cells_stub}()}, \code{\link{cells_data}()}, and -\code{\link{cells_summary}()}. Please see the help article -\link{location_cells} for more information on how these helper functions -can be used. Additionally, we can enclose several \code{cells_*()} calls -within a \code{list()} if we wish to link the footnote text to different -types of locations (e.g., cell data values, stub group headings, the table -title, etc.).} +footnote text. These helper functions are: \code{\link[=cells_title]{cells_title()}}, +\code{\link[=cells_column_labels]{cells_column_labels()}}, \code{\link[=cells_group]{cells_group()}}, \code{\link[=cells_stub]{cells_stub()}}, \code{\link[=cells_data]{cells_data()}}, +and \code{\link[=cells_summary]{cells_summary()}}. Please see the help article \link{location_cells} +for more information on how these helper functions can be used. +Additionally, we can enclose several \code{cells_*()} calls within a \code{list()} if +we wish to link the footnote text to different types of locations (e.g., +cell data values, stub group headings, the table title, etc.).} -\item{fn}{the function to use for text transformation.} +\item{fn}{The function to use for text transformation.} } \value{ -an object of class \code{gt_tbl}. +An object of class \code{gt_tbl}. } \description{ Perform targeted text transformation with a function diff --git a/man/web_image.Rd b/man/web_image.Rd index 64f18f403a..0f0b76bf10 100644 --- a/man/web_image.Rd +++ b/man/web_image.Rd @@ -7,25 +7,25 @@ web_image(url, height = 30) } \arguments{ -\item{url}{a url that resolves to an image file.} +\item{url}{A url that resolves to an image file.} -\item{height}{the absolute height (px) of the image in the table cell.} +\item{height}{The absolute height (px) of the image in the table cell.} } \value{ -a character object with an HTML fragment that can be placed inside of - a cell. +A character object with an HTML fragment that can be placed inside of +a cell. } \description{ We can flexibly add a web image inside of a table with \code{web_image()} function. The function provides a convenient way to generate an HTML fragment with an image URL. Because this function is currently HTML-based, it is only useful for HTML table output. To use this function inside of data cells, it -is recommended that the \code{\link{text_transform}()} function is used. With -that function, we can specify which data cells to target and then include a -\code{web_image()} call within the required user-defined function (for the -\code{fn} argument). If we want to include an image in other places (e.g., in -the header, within footnote text, etc.) we need to use \code{web_image()} -within the \code{\link{html}()} helper function. +is recommended that the \code{\link[=text_transform]{text_transform()}} function is used. With that +function, we can specify which data cells to target and then include a +\code{web_image()} call within the required user-defined function (for the \code{fn} +argument). If we want to include an image in other places (e.g., in the +header, within footnote text, etc.) we need to use \code{web_image()} within the +\code{\link[=html]{html()}} helper function. } \details{ By itself, the function creates an HTML image tag, so, the call @@ -33,8 +33,8 @@ By itself, the function creates an HTML image tag, so, the call \code{} -where a height of \code{30px} is a default height chosen to work well within -the heights of most table rows. +where a height of \code{30px} is a default height chosen to work well within the +heights of most table rows. } \section{Figures}{