Package {Canton}

Canton: Helpers for Data Analysis and Graphics Workflows

Description

Canton provides focused helpers for saving plots, configuring plotting fonts, applying publication presets and themes, selecting colour palettes, loading packages, and managing analysis output directories.

Author(s)

Maintainer: Tim Holy email@timholy.com

Authors:

• Tim Holy email@timholy.com

See Also

Useful links:

• https://github.com/ScienceAdvances/Canton

• Report bugs at https://github.com/ScienceAdvances/Canton/issues

Canton colour scales for ggplot2

Description

Apply a palette returned by hue() to discrete or continuous ggplot2 colour and fill scales.

Usage

scale_colour_canton_d(palette = "NPG", ...)

scale_color_canton_d(palette = "NPG", ...)

scale_fill_canton_d(palette = "NPG", ...)

scale_colour_canton_c(palette = "NPG", ...)

scale_color_canton_c(palette = "NPG", ...)

scale_fill_canton_c(palette = "NPG", ...)

Arguments

Value

A ggplot2 scale object.

Create a figure export preset

Description

Create reusable dimensions and output settings for imagesave(). Presets are starting points rather than journal-specific guarantees; always compare them with the current author instructions for the target journal.

Usage

figure_preset(
  name = c("publication", "single_column", "double_column", "high_resolution",
    "presentation"),
  format = NULL,
  width = NULL,
  height = NULL,
  units = NULL,
  dpi = NULL,
  bg = NULL,
  quality = NULL,
  compression = NULL,
  pointsize = NULL
)

Arguments

Value

An object of class canton_figure_preset.

Examples

figure_preset("single_column")
figure_preset("publication", format = c("pdf", "png"), dpi = 600)

Check whether a plotting font is available

Description

Check whether a plotting font is available

Usage

fontcheck(family = "Arial", error = FALSE, quiet = FALSE)

Arguments

Value

A logical scalar.

Examples

fontcheck("sans", quiet = TRUE)

List available font families

Description

List font families detected by the operating system and by the systemfonts registry.

Usage

fontlist(pattern = NULL)

Arguments

Value

A sorted character vector of font family names.

Examples

head(fontlist(), 10)
fontlist("Arial")

Return a Canton colour palette

Description

Return a named colour palette. Call hue() without a name to list the available palettes.

Usage

hue(name = NULL)

Arguments

Value

A character vector of colours, or invisibly a character vector of available palette names when name is NULL.

Examples

hue("NPG")
hue("dark2")

Save plots in one or more image formats

Description

imagesave() saves ggplot2 plots, pheatmap and ComplexHeatmap objects, grid graphical objects, recorded base R plots, lattice plots, and plotting functions. When plot is NULL, the current plot is captured with grDevices::recordPlot().

Usage

imagesave(
  plot = NULL,
  name = "plot",
  outdir,
  format = "pdf",
  preset = NULL,
  width = 9,
  height = 9,
  units = "in",
  dpi = 300,
  bg = "white",
  quality = 95,
  compression = "lzw",
  pointsize = 12,
  family = base::getOption("Canton.font_family", NULL),
  overwrite = TRUE
)

Arguments

Details

ggplot2 and grid-based objects are saved with ggplot2::ggsave(). Recorded plots and plotting functions are redrawn on a format-specific graphics device.

Value

Invisibly, a named character vector containing the output paths.

Examples

p <- ggplot2::ggplot(mtcars, ggplot2::aes(mpg, wt)) +
  ggplot2::geom_point()
imagesave(p, "scatter", outdir = tempdir(), format = c("png", "pdf"))

imagesave(function() plot(mtcars$mpg, mtcars$wt),
          name = "base-plot", outdir = tempdir(), format = "png")

Create directories

Description

Create one or more directories recursively. Existing directories are left unchanged, making the function safe to call repeatedly.

Usage

mkdir(directory)

Arguments

Value

Invisibly, normalized directory paths.

Examples

mkdir(file.path(tempdir(), "canton-example"))

Return the current working directory

Description

Return the absolute path of the current working directory.

Usage

pwd()

Value

A character scalar containing the current working directory.

Examples

pwd()

Compatibility helper for scoped font settings

Description

Font settings now restore automatically when the code block in setfont() exits. This compatibility helper does not modify user settings.

Usage

resetfont(quiet = FALSE)

Arguments

Value

Invisibly, FALSE; no persistent settings need restoring.

Examples

resetfont(quiet = TRUE)

Configure a font locally

Description

Without code, validate and return a font family without changing settings. With code, apply the font during evaluation and restore the previous options, ggplot2 theme, and existing device's font on exit, including errors. No graphics device is opened and no persistent plotting hook is installed. Print ggplot objects inside the block to render them with the temporary theme.

Usage

setfont(family = "Arial", fallback = NULL, quiet = FALSE, code)

Arguments

Value

Without code, invisibly the validated family; otherwise the result of evaluating code.

Examples

family <- setfont("sans", quiet = TRUE)
theme_canton(base_family = family)
setfont("sans", quiet = TRUE, code = {
  theme_canton()
})

A publication-oriented ggplot2 theme

Description

A compact classic theme with explicit font, line, tick, legend, and grid defaults suitable as a starting point for scientific figures.

Usage

theme_canton(
  base_size = 10,
  base_family = base::getOption("Canton.font_family", "sans"),
  grid = c("none", "major", "both"),
  legend_position = "right"
)

Arguments

Value

A ggplot2 theme object.

Examples

ggplot2::ggplot(mtcars, ggplot2::aes(mpg, wt)) +
  ggplot2::geom_point() +
  theme_canton()

Load multiple packages quietly

Description

Attach one or more installed packages while suppressing startup messages. Package names may be supplied as bare names, strings, or character vectors.

Usage

using(...)

Arguments

Value

Invisibly, a named logical vector indicating which packages were loaded successfully.

Examples

using(ggplot2)
using(c("ggplot2", "grid"))