Package 'ggrrr'

Description

Pick a locally installed font family that matches requested

Usage

.substitute_fonts(family, quiet = TRUE)

Arguments

Examples

try({
.substitute_fonts(c("Roboto","Arial","Kings","Unmatched"))
})

Description

A checked list is a sub class of list access operator that throws an error if you attempt to access a value that does not exist (rather than returning NULL) the point of this is to throw errors early if the data changes.

Usage

## S3 method for class 'checked_list'
x$y

Arguments

Value

the value of the list item or an error if it does not exist

Description

Reuse tidy-select syntax outside of a tidy-select function

Usage

as_vars(tidyselect, data = NULL)

Arguments

Value

a list of symbols resulting from the evaluation of the tidyselect in the context of the current call stack (or a provided data frame)

Description

Convert a rendered_plot object to a character

Usage

## S3 method for class 'rendered_plot'
as.character(x, ...)

Arguments

Value

a named vector

Description

Convert a rendered_table object to a character

Usage

## S3 method for class 'rendered_table'
as.character(x, ...)

Arguments

Value

a named vector

Examples

hux = iris %>% hux_default_layout()
tmp = hux %>% hux_save_as(tempfile())
as.character(tmp)

Description

Converts a square display table format to a long format suitable for applying as a sequence of formatting operations in a google doc or as a ggplot. Currently only plain dataframes and huxtables are supported but flextables look very doable. Only a limited subset of formatting features is implemented at present as supported by roogledocs. The output format is a simple dataframe with the following columns:

Usage

as.long_format_table(table, ...)

Arguments

Details

- Character: label - non blank text (a single space is OK but not an empty string) - Integer: row - must be an integer, 1-based from top left - Integer: col - must be an integer, 1-based from top left - Integer: rowSpan - must be an integer, minimum value 1 - Integer: colSpan - must be an integer, minimum value 1 - Character: fontName - font name as seen in font drop down of google docs e.g "Roboto","Arial","Times New Roman", unrecognised values will be displayed as Arial - Character: fontFace - one of "bold", "bold.italic", "italic", "plain" - Numeric: fontSize - in points - Character: fillColour - as a hex string e.g. "#aaaaaa". N.b. British English spelling (sorry) - Numeric: leftBorderWeight - border weight in points - minimum size that appears in google docs is 0.5 - Numeric: rightBorderWeight - Numeric: topBorderWeight - Numeric: bottomBorderWeight - Character: alignment - one of "START","CENTER","END" - Character: valignment - one of "TOP","MIDDLE","BOTTOM"

It also has an attribute 'colWidths' which is a vector the same length as the width of the table containing the relative widths of the columns. The overall table width is decided on rendering.

So not supported at the moment are border line types, border colours, control of padding, row height control, alignment on a decimal point, complex content / markup in cells.

Value

a format that is considered valid for roogledocs::RoogleDocs$updateTable()

Description

TODO: testing this empty input (must specify .class) struct_list - identity simple struct - wrapped list of struct_lists is flattened list of structs is wrapped nested plain lists / struct_lists are flattened

Usage

as.struct_list(x, .class = NULL)

Arguments

Value

a structured list

Description

Bind_rows works until there are factors with a set of different levels then it throws a wobbly. This handles that particular situation by combining factor levels.

Usage

bind_rows_with_factors(...)

Arguments

Value

the union of those dataframes. Factor levels are combined with a superset of all levels

Examples

library(tidyverse)
bind_rows_with_factors(iris,
 ggplot2::diamonds %>% dplyr::rename(Species = cut)) %>%
 dplyr::pull(Species) %>%
 levels()

Description

A scales breaks generator for log1p scales

Usage

breaks_log1p(n = 5, base = 10)

Arguments

Value

a function for ggplot scale breaks

Examples

library(tidyverse)
ggplot2::ggplot(diamonds, ggplot2::aes(x=price))+
  ggplot2::geom_density()+
  ggplot2::scale_x_continuous(trans="log1p", breaks=ggrrr::breaks_log1p())

Description

Clear data from the passthrough cache for complex or long running operations

Usage

cache_clear(
  .cache = getOption("cache.dir", default = rappdirs::user_cache_dir("ggrrr")),
  .prefix = ".*",
  interactive = TRUE
)

Arguments

Value

nothing. called for side effects

Examples

cache_clear(.prefix="example", .cache=tempdir(), interactive=FALSE)

Description

Staleness is determined by the number of days from 2am on the current day in the current time-zone. A item cached for only one day becomes stale at 2am the day after it is cached. The time is configurable and option(cache.time_day_starts = 0) would be midnight. Automated analysis using caches and updated data should ensure that analysis does not cross this time point otherwise it may end up using old data.

Usage

cache_delete_stale(
  .cache = getOption("cache.dir", default = rappdirs::user_cache_dir("ggrrr")),
  .prefix = ".*",
  .stale = getOption("cache.stale", default = Inf)
)

Arguments

Value

nothing. called for side effects.

Description

This function copies a remote file to a local cache once and makes sure it is reused.

Usage

cache_download(
  url,
  ...,
  .nocache = getOption("cache.disable", default = FALSE),
  .cache = getOption("cache.download.dir", default =
    rappdirs::user_cache_dir("ggrrr-download")),
  .stale = getOption("cache.stale", default = Inf),
  .extn = NULL
)

Arguments

Value

the path to the downloaded file

Description

executes expr and saves the output as an RDS file indexed by has of code in expr and the hash of input variables (which should contain any variable inputs)

Usage

cached(
  .expr,
  ...,
  .nocache = getOption("cache.disable", default = FALSE),
  .cache = getOption("cache.dir", default = rappdirs::user_cache_dir("ggrrr")),
  .prefix = getOption("cache.item.prefix", default = "cached"),
  .stale = getOption("cache.stale", default = Inf)
)

Arguments

Value

the output of .expr which will usually be a value

Examples

colName = "Petal.Width"
{
  iris[[colName]]
} %>% cached(iris, colName, .prefix="example", .cache=tempdir())

Description

This checks to see if a font exists. If missing it will try and install from 'google fonts' or 'brick.io'. If nothing can be done it will suggest alternatives from 'fonts_available()'. In all cases this will make the font available to 'systemfonts' (for 'ragg' and 'svg' devices), and 'extrafonts' (for 'pdf' etc). Webfonts are automatically downloaded into the users font directory and from there will be picked up by 'cairo' devices in theory, and system pdf/svg viewers. In practice this is a bit hit and miss.

Usage

check_font(family)

Arguments

Value

the font family name if it can be located or an alternative if not.

Examples

check_font(c("Roboto","Arial","Kings","EB Garamond"))
extrafont::fonts()
fonts_available(c("Roboto","Arial","Kings","EB Garamond"))

plot = ggplot2::ggplot(ggplot2::diamonds, ggplot2::aes(x=carat,y=price,color = color))+
  ggplot2::theme_minimal(base_family="Roboto")+
  ggplot2::geom_point()+
  ggplot2::annotate("label",x=2,y=10000,label="Hello \u2014 world", family="Kings")+
  ggplot2::labs(tag = "A")+
  ggplot2::xlab("Carat\u2082")+
  ggplot2::ylab("price\u2265")


if (FALSE) {

  # font but no unicode support
  tmp = tempfile(fileext = ".pdf")
  pdf(tmp)
  plot
  dev.off()
  utils::browseURL(tmp)

  # font and unicode support
  tmp = tempfile(fileext = ".pdf")
  cairo_pdf(tmp)
  plot
  dev.off()
  utils::browseURL(tmp)

  # font and unicode support
  tmp = tempfile(fileext = ".png")
  png(tmp)
  plot
  dev.off()
  utils::browseURL(tmp)

  # font and unicode support
  tmp = tempfile(fileext = ".png")
  ragg::agg_png(tmp)
  plot
  dev.off()
  utils::browseURL(tmp)

  # font and unicode support
  tmp = tempfile(fileext = ".svg")
  svglite::svglite(tmp)
  plot
  dev.off()
  utils::browseURL(tmp)

  # Does not work - "family 'Roboto' not included in postscript() device"
  # however:  names(grDevices::postscriptFonts()) includes Roboto
  tmp = tempfile(fileext = ".eps")
  postscript(tmp)
  plot
  dev.off()
  utils::browseURL(tmp)

  # This does work but rasterises output at low fidelity
  tmp = tempfile(fileext = ".eps")
  cairo_ps(tmp)
  plot
  dev.off()
  utils::browseURL(tmp)

  # This fully works
  tmp = tempfile(fileext = ".ps")
  Cairo::CairoPS(tmp)
  plot
  dev.off()
  utils::browseURL(tmp)

}

Description

Pulls out a code snippet based on a start and end tags as comments within the code

Usage

code_snip(
  type,
  filename,
  startMatches = "START",
  endMatches = "END",
  includeStart = FALSE,
  includeEnd = FALSE,
  sep = "\n...\n"
)

Arguments

Value

a text string of the selected code

Description

Pulls out a code snippet based on a vector of start and end lines.

Usage

code_snip_by_line(type, filename, starts = 1, ends = Inf, sep = "\n...\n")

Arguments

Value

a formatted string based on the file

Description

Make sure packages available on CRAN are installed

Usage

cran(cran_deps)

Arguments

Value

nothing

Examples

# cran("tidyverse")

Description

where the periodicity of the time series is expressed as numbers of days, weeks, months quarters, or years.

Usage

cut_date(dates, full_seq = dates, factor = FALSE, ...)

Arguments

Value

a set of dates, representing the start (or end) of the period the date falls into, where the period is defined by 'full_seq' - which is usually defined by 'full_seq_dates()'

Examples

# dates = as.Date(c("2020-01-01","2020-02-01","2020-01-15","2020-02-03",NA))
# fs = full_seq_dates(dates, "2 days")
# dates - cut_date(dates, fs)
# cut_date(dates,fs,TRUE)

# A weekly set of dates:
# dates2 = Sys.Date() + floor(stats::runif(50,max=10))*7

# in this specific situation the final date is not truncated because the
# input data is seen as an exact match for the whole output period.
# cut_date(dates2, fmt = "%d/%b", factor = TRUE)

# if the input dates don't line up with the output dates
# there may be incomplete coverage of the first and last category.
# where the cutting results in short periods. In this
# instance the first and last periods are truncated to prevent them
# being counted as complete when they are in fact potentially missing a few days worth of data:
# cut_date(dates2, fmt = "%d/%b", factor = TRUE, period = "-2 weeks", anchor="sun")

Description

Deals with some annoying issues classifying integer data sets, such as ages, into groups. where you want to specify just the change over points as integers and clearly label the resulting ordered factor.

Usage

cut_integer(
  x,
  cut_points,
  glue = "{label}",
  lower_limit = -Inf,
  upper_limit = Inf,
  ...
)

Arguments

Value

an ordered factor of the integer

Examples

cut_integer(stats::rbinom(20,20,0.5), c(5,10,15))
cut_integer(floor(stats::runif(100,-10,10)), cut_points = c(2,3,4,6), lower_limit=0, upper_limit=10)

Description

where the periodicity of the time series is expressed as numbers of days, weeks, months quarters, or years.

Usage

cut_time(
  timepoints,
  full_seq = timepoints,
  unit = attr(timepoints, "unit"),
  day_zero = attr(timepoints, "day_zero"),
  factor = FALSE,
  ...
)

Arguments

Value

a set of dates, representing the start (or end) of the period the date falls into, where the period is defined by 'full_seq' - which is usually defined by 'full_seq_dates()'

Examples

#dates = as.Date(c("2020-01-01","2020-02-01","2020-01-15","2020-02-03",NA))
#fs = full_seq_dates(dates, "2 days")
#dates - cut_date(dates, fs)
#cut_date(dates,fs,TRUE)

# A weekly set of dates:
# dates2 = Sys.Date() + floor(stats::runif(50,max=10))*7
#times2 = date_to_time(dates2)

# in this specific situation the final date is not truncated because the
# input data is seen as an exact match for the whole output period.
#cut_time(times2, fmt = "%d/%b", factor = TRUE)

# if the input dates don't line up with the output dates
# there may be incomplete coverage of the first and last category.
# where the cutting results in short periods. In this instance
# the first and last periods are truncated to prevent them
# being counted as complete when they are in fact potentially missing a few days worth of data:
#cut_time(times2, fmt = "%d/%b", factor = TRUE, period = "-2 weeks", anchor="sun")
#times2 - cut_time(times2, fmt = "%d/%b", factor = FALSE, period = "-2 weeks", anchor="sun")

Description

This function encapsulates a excel output file as a destination for data tables. With the output of this function you can add extra data to the supplement as a new sheet, or you can write the spreadsheet to disk. When each data table is written either the table can be written silently or returned so that it is included in a knitr document. This is controlled by 'option("hide.supplementary.tables"=TRUE)'.

Usage

data_supplement(
  ...,
  filename = "supplementary-material.xlsx",
  out = ggrrr::outputter(...),
  nameGlue = "Supplementary Table {index}"
)

Arguments

Value

a list of 2 functions. $add_table(hux, caption, footnote, index), which takes a huxtable, caption, and index a writes the huxtable into a supplementary. $write() which writes the collection of tables to the excel file.

Description

Using a day_zero and a unit specification or a full sequence of dates (see 'full_seq_dates()')

Usage

date_to_time(
  dates,
  unit = .day_interval(dates),
  day_zero = getOption("day_zero", "2019-12-29")
)

Arguments

Value

a sequence of numeric time points as the number of periods since day zero

Examples

# DEPRECATED
# times = date_to_time(as.Date("2019-12-29")+0:100, "1 week")
# dates = time_to_date(times)

Description

Internal function for drawing watermark on ggplots

Usage

## S3 method for class 'watermark'
drawDetails(x, recording)

Arguments

Value

a grid object

Description

Widths are based on dataframe or huxtable content ignoring rowspans and potential for wrapping.

Usage

fit_col_widths(table)

Arguments

Value

a vector of column widths

Examples

library(tidyverse)
iris %>% fit_col_widths()

Description

Which fonts are available on this system without hitting webfonts.

Usage

fonts_available(family)

Arguments

Value

the font family name if it can be located or an empty list otherwise

Examples

fonts_available(c("Arial","sdfdsfsd"))

Description

Convert a vector of observation dates to a ordered sequence of every day in the time series

Usage

full_seq_dates(dates, period = "1 day", anchor = "start", fmt = "%d %b")

Arguments

Value

a vector of dates for complete between the minimum and maximum of dates, on the day of week of the anchoring date

Examples

# full_seq_dates(c("2020-01-01","2020-02-01","2020-01-15","2020-02-01",NA), "2 days")

Description

Generate a full regular timepoint sequence

Usage

full_seq_times(
  timepoints,
  period = unit,
  unit = attr(timepoints, "unit"),
  day_zero = attr(timepoints, "day_zero"),
  ...
)

Arguments

Value

a complete set of timepoints on the same scale as the original but with potentially different frequency. This will probably involve non integer times

Examples

# DEPRECATED
# times = date_to_time(as.Date("2019-12-29")+0:100, "1 week")
# tmp = full_seq_times(times)

Description

This function examines a dataframe and returns a list of the columns with sub-lists as all the options for factors. This provides programmatic access (and autocomplete) to the values available in a dataframe, and throws and early error if we try and access data by a variable that does not exist.

Usage

get_value_sets(df)

Arguments

Value

a list of lists with the column name and the factor levels as list, as a 'checked list'.

Description

Resolves any missing fonts in a ggplot and tries to resolve them against webfont providers (Brick and Google Fonts) locally cacheing them. This function is the default for 'gg_save_as'

Usage

gg_find_webfonts(plot)

Arguments

Value

a list of css webfont specifications

Description

This is useful if you want to combine a formatted table with a plot in a multi-panel patchwork.

Usage

gg_formatted_table(
  longFormatTable,
  colWidths = NULL,
  tableWidthInches = 5.9,
  font = "Roboto",
  ...
)

Arguments

Value

a ggplot object containing the table as a ggplot.

Description

Hide the legend of a plot

Usage

gg_hide_legend()

Value

a theme

Description

Hide the x axis of a plot

Usage

gg_hide_X_axis()

Value

a theme

Description

Hide the y axis of a plot

Usage

gg_hide_Y_axis()

Value

a theme

Description

Labels like geom_text are in a random unit size which is only mysteriously connected to the size of text on axes

Usage

gg_label_size(pts)

Arguments

Value

a ggplot size aesthetic for labels

Description

Make a plot narrower

Usage

gg_narrow(ang = 90)

Arguments

Value

a theme

Description

This is a set of styles with a focus on making plots compact, and minimally fussy, and ensuring fonts are consistent between axes and labels. It sets default sizes for line widths and point sizes. It also switched the default png renderer in knitr to 'ragg::ragg_png' to allow for modern font support.

Usage

gg_pedantic(
  lineSize = 0.25,
  fontSize = 8,
  font = "Roboto",
  size = lineSize * 2,
  ...
)

Arguments

Value

nothing

Description

Make the legend smaller

Usage

gg_resize_legend(pointSize = 0.75, textSize = 6, spaceLegend = 0.75)

Arguments

Value

a theme

Description

Saves a ggplot object to disk at a set physical size. Allows specific maximum dimensions with an optional target aspect ratio to fit into specific configurations for publication. e.g. a half page plot or a third of a 2 column page. Allows output in pdf for journal publication or png for inclusion in documents, and makes sure that the outputs are near identical.

Usage

gg_save_as(...)

Arguments

Details

For maximum cross platform reproducibility we are using the combination of 'systemfonts' for font management, 'svglite' to render the canonical output 'rsvg' to convert that to pdf, and 'ragg' to for bitmap formats. In some situations 'rsvg' fails in which case we fall back to rendering in a headless chrome instance. This rather complicated pipeline ensures modern webfont support, and editable SVG or PDF.

Value

the output is an sensible default object that can be displayed given the context it is called in, for example if knitting an RMarkdown document a link to the png file for embedding, if latex a link to the pdf file.

Examples

try({
.gg_pedantic(fontSize = 6)
p = ggplot2::ggplot(mtcars, ggplot2::aes(mpg, wt, colour=as.factor(cyl))) +
  ggplot2::geom_point()
# p %>% .gg_save_as(filename="~/tmp/plot_example",maxWidth=4,maxHeight=4)
p %>% .gg_save_as(filename=tempfile(),maxWidth=2,maxHeight=1.5)

plot = ggplot2::ggplot(ggplot2::diamonds, ggplot2::aes(x=carat,y=price,color = color))+
  ggplot2::geom_point()+
  ggplot2::annotate("label",x=2,y=10000,label="Hello \u2014 world", family="Kings")+
  ggplot2::labs(tag = "A")+
  ggplot2::xlab("Carat\u2082")+
  ggplot2::ylab("price\u2265")

# plot %>% .gg_save_as(filename="~/tmp/plot_example_2")
res = plot %>% .gg_save_as(filename=tempfile(), formats=c("png","eps"))
as.character(res)
res
})

Description

Set the default sizes of lines, points and fonts in ggplot geoms, and text labels in ggplot axes to get a single consistent look and feel.

Usage

gg_set_size_defaults(
  lineSize = 0.5,
  fontSizePts = 4 + lineSize * 8,
  font = "Roboto",
  size = lineSize * 2
)

Arguments

Value

nothing

Examples

library(tidyverse)
gg_set_size_defaults(lineSize = 0.25)

Description

Also sets horizontal and vertical alignment correctly, and does top and bottom axes.

Usage

gg_set_X_angle(ang = 60)

Arguments

Value

a theme

Description

A simple table as a ggplot patchwork object, no customisation allowed

Usage

gg_simple_table(df, pts = 8, font = "sans", unwrapped = FALSE)

Arguments

Value

A gtable object (i.e. a grob) optionally wrapped as a patchwork plot.

Examples

if (FALSE) {
  gg_simple_table(tibble::tibble(x=c(1,2,3),y=c(5,4,3)),pts=10)
}

Description

A ggplot theme with minimal fluff and with the defaults set small.

Usage

gg_tiny_theme(baseSize = 8, font = "Roboto")

Arguments

Value

a ggplot theme

Examples

if (interactive()) {
  ggplot2::ggplot(ggplot2::diamonds,
    ggplot2::aes(x=carat,y=price,color=color))+
    ggplot2::geom_point()+
    gg_tiny_theme()
}

Description

Add in a watermark to plots

Usage

gg_watermark(
  lab = "DRAFT",
  disable = getOption("ggrrr.disable.watermark", default = FALSE)
)

Arguments

Value

a watermark layer

Description

Drop in replacement for 'here' ('here' pkg)

Usage

here(..., projRoot = .locate_project())

Arguments

Value

a path

Examples

try(.here("vignettes"))

Description

If html2pdfr is installed it will use that by default, if not it will fall back to a headless chrome instance.

Usage

html_pdf_converter(html, filename, maxWidth, maxHeight)

Arguments

Value

nothing called for side effects

Description

Calculate a sensible column and table width for a huxtable based on its content.

Usage

hux_auto_widths(hux, target = "html", including_headers = FALSE)

Arguments

Value

the huxtable with the width options set.

Description

Sometimes vanilla bind_rows gets confused.

Usage

hux_bind_rows(...)

Arguments

Value

a single huxtable

Description

The main aim is to get something that works with google docs when you copy and paste.

Usage

hux_default_layout(
  hux,
  defaultFontSize = 8,
  defaultFont = "Roboto",
  headerRows = 1
)

Arguments

Value

the formatted huxtable.

Examples

library(tidyverse)
hux = iris %>% hux_default_layout()

Description

Insert row at start maintaining format

Usage

hux_insert_start(hux, ..., fill = "", colspan = 1)

Arguments

Value

a huxtable with row inserted at start in the same format

Description

Converts row spanning columns into column spanning header rows making a table narrower but longer. The column that is being moved is retained to allow for the appearance of indentation.

Usage

hux_nest_group(t, col = 1)

Arguments

Value

a narrower huxtable

Description

depending on the context return the correct format for a document. The basic output here is to use HTML as an output if possible and convert it to an image or a PDF that can then be included into a latex document for example.

Usage

hux_save_as(...)

Arguments

Value

the output depends on if the function is called in a knitr session. It maybe the HTML or a link to the pdf output for example.

Examples

try({
 hux = iris %>% huxtable::as_hux() %>%
   huxtable::theme_mondrian(font="Roboto")
 out = .hux_save_as(hux, tempfile())
 # browseURL(out$html)

 out2 = .hux_save_as(hux, tempfile(), formats=c("pdf","png"))
 as.character(out2)

 # The resulting pdf has fonts embedded & is multipage.
})

Description

Keeps the same formatting as the rest of the table

Usage

hux_set_caption(hux, caption)

Arguments

Value

a huxtable with first row caption

Description

Set the font family and size in a huxtable globally

Usage

hux_set_font(hux, defaultFontSize = 8, defaultFont = "Roboto")

Arguments

Value

the altered huxtable

Description

Keeps the same formatting as the rest of the table except for borders

Usage

hux_set_footer(hux, footer)

Arguments

Value

a huxtable with last row footer

Description

A sprintf alternative that handles NA values gracefully (ish)

Usage

hux_sprintf(fmt, ..., na.text = "—")

Arguments

Value

a string value

Description

The assumption here is that the input data is a long format tidy dataframe with both rows and columns specified by values of the 'rowGroupVars' and 'colGroupVars' columns. The long format (sparse) table is translated into a nested tree of rows (using 'rowGroupVars') and a nested tree of columns (from 'colGroupVars'). Individual data items are placed in the cell intersecting these two trees. If there are multiple matches an additional layer of grouping is added to the columns.

Usage

hux_tidy(
  tidyDf,
  rowGroupVars,
  colGroupVars,
  missing = "—",
  na = "—",
  displayRedundantColumnNames = FALSE,
  ...
)

Arguments

Value

a huxtable table

Description

Useful if you need to include a formatted table in a figure with a plot

Usage

hux_to_ggplot(hux, width = 5.9)

Arguments

Value

a ggplot object of the right width

Description

Create a new data frame including duplicate rows where the rows fulfil a potentially overlapping set of conditions specified as named predicates (as formulae)

Usage

intersecting_group_by(.data, ..., .colname)

Arguments

Value

a new dataframe containing the overlapping groups which may create duplicates of individual rows.

Examples

library(tidyverse)
iris %>% dplyr::group_by(Species) %>% intersecting_group_by(
  Sepal.Length > mean(Sepal.Length) ~ "Long",
  Sepal.Width > mean(Sepal.Width) ~ "Wide"
)

Description

Knit a rendered_plot object

Usage

## S3 method for class 'rendered_plot'
knit_print(x, options, ...)

Arguments

Value

nothing - used for side effects

Description

Knit a rendered_table object

Usage

## S3 method for class 'rendered_table'
knit_print(x, ...)

Arguments

Value

nothing - used for side effects

Description

used in a knitr preamble to direct the output to a subdirectory of the project — title: "Analysis 1" output: html_document knit: ggrrr::knit_versioned("output/analysis-1") —

Usage

knit_versioned(
  directory = NULL,
  ...,
  datedFile = !datedSubdirectory,
  datedSubdirectory = FALSE
)

Arguments

Details

This can only work when deployed as a library and hence no standalone version of it exists, because the fully qualified packagename has to be used.

Value

nothing. called for side effects

Description

Perform logit scaling with right axis formatting. To not be used directly but with ggplot (e.g. ggplot2::scale_y_continuous(trans = "logit")

Usage

logit_trans(n = 5, ...)

Arguments

Value

A scales object

Examples

tibble::tibble(pvalue = c(0.001, 0.05, 0.1), fold_change = 1:3) %>%
  ggplot2::ggplot(ggplot2::aes(fold_change , pvalue)) +
  ggplot2::geom_point() +
  ggplot2::scale_y_continuous(trans = "logit")

Description

The map functions transform their input by applying a function to each element of a list or atomic vector and returning an object of the same length as the input.

• map() always returns a list. See the modify() family for versions that return an object of the same type as the input.

• map_lgl(), map_int(), map_dbl() and map_chr() return an atomic vector of the indicated type (or die trying). For these functions, .f must return a length-1 vector of the appropriate type.

• map_vec() simplifies to the common type of the output. It works with most types of simple vectors like Date, POSIXct, factors, etc.

• walk() calls .f for its side-effect and returns the input .x.

Usage

map_struct(.x, .f, ..., .progress = FALSE)

Arguments

# Instead of
x |> map(f, 1, 2, collapse = ",")
# do:
x |> map(\(x) f(x, 1, 2, collapse = ","))

Value

a 'struct_list'

Description

These functions are variants of map() that iterate over two arguments at a time.

Usage

map2_struct(.x, .y, .f, ..., .progress = FALSE)

Arguments

# Instead of
x |> map(f, 1, 2, collapse = ",")
# do:
x |> map(\(x) f(x, 1, 2, collapse = ","))

Value

a 'struct_list'

Description

Use a locally checked out version if available.

Usage

non_cran(name, github, force = FALSE, subdir = "", ...)

Arguments

Value

nothing

Examples

# non_cran("patchwork", "thomasp85/patchwork")

Description

You want to use a function if it is installed but don't want it to be installed as part of your package and you don't want to reference it as part of the Imports or Suggests fields in a package DESCRIPTION.

Usage

optional_fn(
  pkg,
  name,
  alt = function(...) {
     stop("function `", pkg, "::", name, "(...)` not available")

    }
)

Arguments

Value

the function you want if available or the alternative

Examples

fn = .optional_fn("openssl", "md5", digest::digest)
as.character(fn(as.raw(c(1,2,3))))

Description

This function generates a function that resolves a file path fragment to a specific file location, accounting for a versioning strategy involving the current date. The defaults create a naming strategy that places an file in the "output" sub-directory of the current project with a filename suffix including the date.

Usage

outputter(
  directory = .here("output"),
  ...,
  datedFile = !datedSubdirectory,
  datedSubdirectory = FALSE
)

Arguments

Value

a function that takes a filename and boolean delete parameter. When called with a filename component this function will return the absolute path of a file which is versioned with date. If the file exists and delete=TRUE it is deleted. (allowing for libraries that refuse to overwrite existing files)

Examples

out = outputter("~/output",datedSubdirectory=TRUE)
out("file.png")

Description

display a 0-1 scale as 0-100

Usage

percent_trans()

Details

'r lifecycle::badge(stage = "deprecated")'

Value

A scales object

Description

These functions are variants of map() that iterate over multiple arguments simultaneously. They are parallel in the sense that each input is processed in parallel with the others, not in the sense of multicore computing, i.e. they share the same notion of "parallel" as base::pmax() and base::pmin().

Usage

pmap_struct(.l, .f, ..., .progress = FALSE)

Arguments

# Instead of
x |> map(f, 1, 2, collapse = ",")
# do:
x |> map(\(x) f(x, 1, 2, collapse = ","))

Value

a 'struct_list'

Description

'r lifecycle::badge("deprecated")'

Usage

pmixnorm(q, means, sds, weights = rep(1, length(means)), na.rm = FALSE)

Arguments

Value

the pdf of the mixture distribution.

Examples

pmixnorm(q=c(2,20), means=c(10,13,14), sds=c(1,1,2), weights=c(2,2,3))

Description

Print a rendered_plot object

Usage

## S3 method for class 'rendered_plot'
print(x, ...)

Arguments

Value

nothing - used for side effects

Description

Print a rendered_table object

Usage

## S3 method for class 'rendered_table'
print(x, ...)

Arguments

Value

nothing - used for side effects

Description

'r lifecycle::badge("deprecated")'

Usage

qmixnorm(p, means, sds, weights = rep(1, length(means)), na.rm = FALSE)

Arguments

Value

the value of the yth quantile

Examples

qmixnorm(p=c(0.025,0.5,0.975), means=c(10,13,14), sds=c(1,1,2))

Description

This repopulates 'systemfonts' from the webfont cache and then 'extrafont' from 'systemfonts'. This does a full rebuild and will be slow (depending a bit )

Usage

rebuild_fonts()

Value

nothing

Description

This wipes a lot of cached font data.

Usage

reset_fonts(
  confirm = utils::askYesNo(msg = "Are you sure?", default = FALSE),
  web = FALSE,
  fonts = FALSE
)

Arguments

Value

nothing

Description

Applies an expression to each row and assignes it to a new column. Per-row failures are handled with default values (NAs) or can be intercepted by the user with a tryCatch(...) expression. There are many other ways to do a similar thing in 'dplyr' and 'purrr' but they are all more complicated than I expect them to be.

Usage

rowwise_mutate(.data, ..., .onerror = function(e, ...) NA)

Arguments

Value

a dataframe the same length as input with additional or altered columns

Examples

# calculations are scoped only to current row. Hence max(x) == x always:
iris %>% rowwise_mutate(
  widths = Sepal.Width+max(Petal.Width),
  lengths = Sepal.Length+max(Petal.Length),
  tmp = tibble::tibble(a=1, b=2)) %>%
dplyr::glimpse()

# This is different to standard dplyr behaviour when the additional tibble
# column is considered. standard dplyr rowwise does something unexpected:
iris %>% dplyr::rowwise() %>% dplyr::mutate(
  widths = Sepal.Width+max(Petal.Width),
  lengths = Sepal.Length+max(Petal.Length),
  tmp = tibble::tibble(a=1, b=2)) %>%
dplyr::glimpse()

# As expressions are not vectorised we can use normal if ... else ... statements
# and errors can be handled and default values provided.
suppressWarnings(
iris %>% rowwise_mutate(
  tmp = if (Petal.Width > 2.0) stop("error message: ",Petal.Width) else Petal.Width,
  .onerror = function(e) -Petal.Width
) %>%
dplyr::glimpse()
)

# The default values
# are evaluated in the same context as the original expression, but only are
# defaults for all the columns so makes most sense when a default value is given

suppressWarnings(
iris %>% rowwise_mutate(
  tmp = if (Petal.Width > 2.0) stop("too wide petals: ",Petal.Width) else Petal.Width,
  tmp2 = if (Sepal.Width > 4) stop("too wide sepals: ",Sepal.Width) else Sepal.Width,
  .onerror = function(e) Inf
) %>%
dplyr::glimpse()
)

Description

This is intended to combine with 'scale_fill_subtype' when we want to divide major groupings differently to minor groups

Usage

scale_colour_subtype(
  subclasses,
  class_colour = "black",
  subclass_colour = "grey50",
  na.value = "grey50",
  aesthetics = "color",
  ...
)

Arguments

Value

a ggplot scale

Examples

library(tidyverse)

# prep some data:
data = ggplot2::diamonds %>%
  dplyr::mutate(color_cut = sprintf("%s (%s)",color,cut)) %>%
  dplyr::group_by(color,cut,color_cut) %>%
  dplyr::count() %>%
  dplyr::ungroup() %>%
  dplyr::mutate(color_cut = ordered(color_cut))

# work out the number of subgroups for each group:
subgroups = data %>%
  dplyr::select(color,cut) %>%
  dplyr::distinct() %>%
  dplyr::group_by(color) %>%
  dplyr::count() %>%
  dplyr::pull(n)

# plot as a horizontal stacked bar chart using color brewer as the main
# colour axis. N.b. having enough different colours here is important
ggplot2::ggplot(data, ggplot2::aes(y=1,x=n, fill=color_cut, color=color_cut))+
  ggplot2::geom_bar(stat="identity",orientation = "y")+
  ggrrr::scale_fill_subtype(.palette = scales::brewer_pal,
    palette="Accent", subclasses = subgroups)+
  ggrrr::scale_colour_subtype(subclasses=subgroups)+
  ggrrr::gg_hide_Y_axis()+
  ggrrr::gg_narrow()

Description

If you have a categorical variable defining colour or fill and it has a natural grouping you can use this to have a colour scale involving major colors defining the major groupings, and these are progressively lightened for each of the subcategories.

Usage

scale_fill_subtype(
  .palette,
  subclasses,
  ...,
  undefined = "#606060",
  lighten = NA,
  na.value = "grey50",
  aesthetics = "fill"
)

Arguments

Value

a ggplot scale

Examples

library(tidyverse)

# prep some data:
data = ggplot2::diamonds %>%
  dplyr::mutate(color_cut = sprintf("%s (%s)",color,cut)) %>%
  dplyr::group_by(color,cut,color_cut) %>%
  dplyr::count() %>%
  dplyr::ungroup() %>%
  dplyr::mutate(color_cut = ordered(color_cut))

# work out the number of subgroups for each group:
subgroups = data %>%
  dplyr::select(color,cut) %>%
  dplyr::distinct() %>%
  dplyr::group_by(color) %>%
  dplyr::count() %>%
  dplyr::pull(n)

# plot as a horizontal stacked bar chart using color brewer as the main
# colour axis. N.b. having enough different colours here is important
ggplot2::ggplot(data, ggplot2::aes(y=1,x=n, fill=color_cut, color=color_cut))+
  ggplot2::geom_bar(stat="identity",orientation = "y")+
  scale_fill_subtype(.palette = scales::brewer_pal,
    palette="Accent", subclasses = subgroups)+
  scale_colour_subtype(subclasses=subgroups)+
  gg_hide_Y_axis()+
  gg_narrow()

Description

A log1p x scale

Usage

scale_x_log1p(..., n = 5, base = 10, sf = 2)

Arguments

Value

a ggplot scale

Description

A logit x scale

Usage

scale_x_logit(..., n = 5, sf = 2)

Arguments

Value

a ggplot scale

Description

A percentage x scale

Usage

scale_x_percent(..., sf = 2)

Arguments

Value

a ggplot scale

Description

A log1p y scale

Usage

scale_y_log1p(..., n = 5, base = 10, sf = 2)

Arguments

Value

a ggplot scale

Description

A logit y scale

Usage

scale_y_logit(..., n = 5, sf = 2)

Arguments

Value

a ggplot scale

Examples

tibble::tibble(pvalue = c(0.001, 0.05, 0.1), fold_change = 1:3) %>%
 ggplot2::ggplot(ggplot2::aes(fold_change , pvalue)) +
 ggplot2::geom_point() +
 scale_y_logit(n=8)

Description

A percentage y scale

Usage

scale_y_percent(..., sf = 2)

Arguments

Value

a ggplot scale

Examples

tibble::tibble(pvalue = c(0.001, 0.05, 0.1), fold_change = 1:3) %>%
 ggplot2::ggplot(ggplot2::aes(fold_change , pvalue)) +
 ggplot2::geom_point() +
 scale_y_percent()

Description

A variant of sprintf that work well with inputs that are in the format of a list. Good examples of which are the quantile functions

Usage

sprintf_list(format, params, na.replace = "―")

Arguments

Value

the formatted string

Examples

# generate a mixture confidence interval from a set of distributions
sprintf_list("%1.2f [%1.2f\u2013%1.2f]",
 qmixnorm(p=c(0.5,0.025,0.975),
 means=c(10,13,14), sds=c(1,1,2)))

Description

The width and height of images to fit scientific publication standards.

Usage

std_size

Format

A list with width and height in inches

Description

Unlike 'purrr::list_flatten' this is recursive for one reason which is that a 'struct_list' must only contain 'structs'.

Usage

struct_flatten(x)

Arguments

Value

a flat 'struct_list' of 'structs'

Description

These functions allow generic list behaviour.

Usage

## S3 method for class 'struct_list'
c(...)

## S3 method for class 'struct_list'
rep(x, ...)

## S3 method for class 'struct_list'
x$y

## S3 method for class 'struct_list'
x[...]

## S3 replacement method for class 'struct_list'
x[...] <- value

## S3 method for class 'struct_list'
x[[...]]

## S3 replacement method for class 'struct_list'
x[[...]] <- value

Arguments

Value

a 'struct_list' with all the items

Functions

• c(struct_list): Repeat a 'struct_list'

• rep(struct_list): Repeat a 'struct_list'

• $: Subset a 'struct_list'

• [: Subset a 'struct_list'

• `[`(struct_list) <- value: Assign a subset to a 'struct_list'

• [[: get a value from a 'struct_list'

• `[[`(struct_list) <- value: set a single value in a 'struct_list'

Examples

x = struct(a=1,b=2,c=1:3,.class="test")
y = struct(a=4,b=5,c=1:3,.class="test")
z= tibble::tibble(a= 1:10, b=rep(c(x,y),5))

z$b

c(x,y)
c(rep(x,5),y)
class(c(rep(x,5),rep(y,5))[[1]])

as.struct_list(list(x,y))

#' x = struct(a=1,b=2,c=1:3,.class="test")
class(rep(c(x,y),5)[[1]]) == "test"
class(rep(x,5))

a = (rep(c(x,y),5))
a[[1]] = y
a

Description

Summarise and include a total row, or a row including the summary for the whole group, into a factor list. This looks and feels like a natural summarisation step, but applies the summarisation both to the subgroups and to the data ungrouped by one level. The additional group result is included as a new row. allows for a natural grouped and ungrouped summarisation

Usage

summarise_with_totals(
  .data,
  ...,
  .groups = NULL,
  .total = "Total",
  .total_first = FALSE
)

Arguments

Value

a summarised dataframe with the additional totals or group row

Examples

library(tidyverse)
diamonds %>%
 dplyr::group_by(color,cut) %>%
 summarise_with_totals(
    mpg = sprintf("%1.1f \u00B1 %1.1f", mean(price), stats::sd(price)),
    .total = "Overall"
 )

Description

Convert a set of timepoints to dates

Usage

time_to_date(
  timepoints,
  unit = attr(timepoints, "unit"),
  day_zero = getOption("day_zero", "2019-12-29")
)

Arguments

Value

a vector of dates

Examples

# DEPRECATED
# times = date_to_time(as.Date("2019-12-29")+0:100, "1 week")
# dates = time_to_date(times)

Description

reboot a library reloading from a local development copy if it exists locally alternatively get the most up to date github package.

Usage

unstable(pkg = "ggrrr", org = "terminological")

Arguments

Value

nothing

Examples

# ggrrr::unstable()