Package 'doestyle'

Title: NSW Department of Education branding for figures and tables
Description: doestyle is an R package containing functions to help produce brand-compliant figures for NSW Department of Education publications.
Authors: Samuel Gardiner [aut, cre] (ORCID: <https://orcid.org/0000-0002-6752-6969>), Matthew Finkbeiner [aut] (ORCID: <https://orcid.org/0000-0003-0373-8150>), Jonathan McGuire [aut], United States Web Design System [cph] (Author of included Public Sans font face), Dan Williams [cph] (Author of included Public Sans font face), Pablo Impallari [cph] (Author of included Public Sans font face), Rodrigo Fuenzalida [cph] (Author of included Public Sans font face)
Maintainer: Samuel Gardiner <[email protected]>
License: MIT + file LICENSE
Version: 0.4.0
Built: 2026-05-31 11:47:26 UTC
Source: https://github.com/nsw-education/doestyle

Help Index

Activate showtext and check for presence of Public Sans font family

Description

theme_doe() uses showtext to allow R graphics devices to render the Public Sans font family. Use check_font_families() to check that Public Sans is available and to activate showtext. If Public Sans is not installed on the system or user font search paths, doestyle's embedded copy of the files will be used.

Usage

check_font_families()

Value

check_font_families() does not have a return value and is called for its side effects.

See Also

showtext::showtext_auto() and Public Sans.

Colours provided by doestyle

Description

A dataset containing names, hex and RGB values, and other identifiers for each colour provided in doestyle. Its content can be visualised with show_colours() or further manipulated.

Usage

colourdata

Format

An object of class tbl_df (inherits from tbl, data.frame) with 51 rows and 13 columns.

Source

See Also

show_colours()

Compute the contrast ratio between pairs of colours

Description

Compute contrast ratios between pairs of colours, using the WCAG 2.1 formula.

Usage

contrast_ratio(colour1, colour2)

Arguments

colour1, colour2

Character vectors of hexadecimal colour values.

Details

Contrast ratio is defined as L1+0.05L2+0.05\frac{L_1 + 0.05}{L_2 + 0.05} where L1L_1 and L2L_2 are the relative luminances of the lighter and darker colours being compared.

Contrast ratios range from 1 (no colour contrast) to 21 (maximum contrast). To meet WCAG 2.1 minimum (AA) criteria for accessibility, the contrast ratios between adjacent colours must be:

  • For text, at least 4.5

  • For large text (18pt or larger, or 14pt bold), at least 3

  • For non-text plot elements (e.g. patterns, lines, points, borders etc.), at least 3

To meet WCAG 2.1 enhanced (AAA) contrast requirements, generally a ratio above 7 is required.

See WCAG 2.1 success criteria 1.4.3 Contrast (Minimum), 1.4.6 Contrast (Enhanced) and 1.4.11 Non-text Contrast.

Value

contrast_ratio() returns a numeric vector of contrast ratios, of the same length as colour1 and colour2.

Examples

backgrounds <- doe_cols("white", "black", "blue-01", "grey-04", "black")
foregrounds <- doe_cols("black", "white", "blue-03", "grey-03", "black")

contrast_ratio(colour1 = backgrounds, colour2 = foregrounds)

Palettes provided by doestyle

Description

A list of palettes, organised by type.

Usage

doe_palettes

Format

An object of class palettes_palette (inherits from vctrs_list_of, vctrs_vctr, list) of length 6.

Details

  • Qualitative: designed to show differences between nominal classes

  • Sequential: designed to show differences in ordered data that progress in value from low to high (or vice versa)

  • Diverging: designed to show differences in ordered data that progress away from a central value to extremes at either end of a scale

Palettes can be accessed by their type and name.

Examples

# Examine one palette at a time
doe_palettes$default
doe_palettes$seq.blues

# List all palettes and their colours
print(doe_palettes)

# If you've loaded `palettes`, visualise the available palettes
library(palettes)
plot(doe_palettes)

Add a down errorbar to a ggplot2 plot

Description

Add the lower portion of an errorbar to a ggplot plot. This allows the halves of the errorbars to be different colours.

Usage

geom_downerrorbar(
  mapping = NULL,
  data = NULL,
  stat = "identity",
  position = "identity",
  ...,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

Arguments

mapping

Set of aesthetic mappings created by aes(). If specified and inherit.aes = TRUE (the default), it is combined with the default mapping at the top level of the plot. You must supply mapping if there is no plot mapping.
data

The data to be displayed in this layer. There are three options:

If NULL, the default, the data is inherited from the plot data as specified in the call to ggplot().

A data.frame, or other object, will override the plot data. All objects will be fortified to produce a data frame. See fortify() for which variables will be created.

A function will be called with a single argument, the plot data. The return value must be a data.frame, and will be used as the layer data. A function can be created from a formula (e.g. ~ head(.x, 10)).
stat

The statistical transformation to use on the data for this layer. When using a ⁠geom_*()⁠ function to construct a layer, the stat argument can be used to override the default coupling between geoms and stats. The stat argument accepts the following:

  • A Stat ggproto subclass, for example StatCount.

  • A string naming the stat. To give the stat as a string, strip the function name of the stat_ prefix. For example, to use stat_count(), give the stat as "count".

  • For more information and other ways to specify the stat, see the layer stat documentation.

position

A position adjustment to use on the data for this layer. This can be used in various ways, including to prevent overplotting and improving the display. The position argument accepts the following:

  • The result of calling a position function, such as position_jitter(). This method allows for passing extra arguments to the position.

  • A string naming the position adjustment. To give the position as a string, strip the function name of the position_ prefix. For example, to use position_jitter(), give the position as "jitter".

  • For more information and other ways to specify the position, see the layer position documentation.

...

Other parameters passed to ggplot2::geom_errorbar().
na.rm

If FALSE, the default, missing values are removed with a warning. If TRUE, missing values are silently removed.
show.legend

logical. Should this layer be included in the legends? NA, the default, includes if any aesthetics are mapped. FALSE never includes, and TRUE always includes. It can also be a named logical vector to finely select the aesthetics to display. To include legend keys for all levels, even when no data exists, use TRUE. If NA, all levels are shown in legend, but unobserved levels are omitted.
inherit.aes

If FALSE, overrides the default aesthetics, rather than combining with them. This is most useful for helper functions that define both data and aesthetics and shouldn't inherit behaviour from the default plot specification, e.g. annotation_borders().

Examples

library(doestyle)
library(ggplot2)

df <- data.frame(
  observation = c("A", "B", "C"),
  lower = c(1, 2, 3),
  estimate = c(2, 4, 4),
  upper = c(3, 6, 5)
)

ggplot(df, aes(x = observation,
               y = estimate,
               ymin = lower,
               ymax = upper)) +
  geom_col() +
  geom_uperrorbar(width = 1/10) +
  geom_downerrorbar(width = 1/10,
                    colour = "white")

Add an up errorbar to a ggplot2 plot

Description

Add the upper portion of an errorbar to a ggplot plot. This allows the halves of the errorbars to be different colours.

Usage

geom_uperrorbar(
  mapping = NULL,
  data = NULL,
  stat = "identity",
  position = "identity",
  ...,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

Arguments

mapping

Set of aesthetic mappings created by aes(). If specified and inherit.aes = TRUE (the default), it is combined with the default mapping at the top level of the plot. You must supply mapping if there is no plot mapping.
data

The data to be displayed in this layer. There are three options:

If NULL, the default, the data is inherited from the plot data as specified in the call to ggplot().

A data.frame, or other object, will override the plot data. All objects will be fortified to produce a data frame. See fortify() for which variables will be created.

A function will be called with a single argument, the plot data. The return value must be a data.frame, and will be used as the layer data. A function can be created from a formula (e.g. ~ head(.x, 10)).
stat

The statistical transformation to use on the data for this layer. When using a ⁠geom_*()⁠ function to construct a layer, the stat argument can be used to override the default coupling between geoms and stats. The stat argument accepts the following:

  • A Stat ggproto subclass, for example StatCount.

  • A string naming the stat. To give the stat as a string, strip the function name of the stat_ prefix. For example, to use stat_count(), give the stat as "count".

  • For more information and other ways to specify the stat, see the layer stat documentation.

position

A position adjustment to use on the data for this layer. This can be used in various ways, including to prevent overplotting and improving the display. The position argument accepts the following:

  • The result of calling a position function, such as position_jitter(). This method allows for passing extra arguments to the position.

  • A string naming the position adjustment. To give the position as a string, strip the function name of the position_ prefix. For example, to use position_jitter(), give the position as "jitter".

  • For more information and other ways to specify the position, see the layer position documentation.

...

Other parameters passed to ggplot2::geom_errorbar().
na.rm

If FALSE, the default, missing values are removed with a warning. If TRUE, missing values are silently removed.
show.legend

logical. Should this layer be included in the legends? NA, the default, includes if any aesthetics are mapped. FALSE never includes, and TRUE always includes. It can also be a named logical vector to finely select the aesthetics to display. To include legend keys for all levels, even when no data exists, use TRUE. If NA, all levels are shown in legend, but unobserved levels are omitted.
inherit.aes

If FALSE, overrides the default aesthetics, rather than combining with them. This is most useful for helper functions that define both data and aesthetics and shouldn't inherit behaviour from the default plot specification, e.g. annotation_borders().

Examples

library(doestyle)
library(ggplot2)

df <- data.frame(
  observation = c("A", "B", "C"),
  lower = c(1, 2, 3),
  estimate = c(2, 4, 4),
  upper = c(3, 6, 5)
)

ggplot(df, aes(x = observation,
               y = estimate,
               ymin = lower,
               ymax = upper)) +
  geom_col() +
  geom_uperrorbar(width = 1/10) +
  geom_downerrorbar(width = 1/10,
                    colour = "white")

Get brand colours by name

Description

Get brand colours by name

Usage

get_colours(...)

doe_colours(...)

doe_cols(...)

Arguments

...

Colour name(s). May be supplied as a character vector or as individual arguments.

Details

get_colours() will only return hex values for valid NSW and Department of Education colour names. To list available colours, use list_doestyle_colours(). To plot available colours, use show_colours().

Value

get_colours() returns a character vector containing the hex values for each requested brand colour. If the input contained named arguments, their names will be used for the outputs.

Examples

get_colours("blue-01", "red-02", "blue-04")
get_colours(c("red-01", "red-02", "red-03", "red-04"))

List valid NSW or DoE colours and their hex values

Description

List valid NSW or DoE colours and their hex values

Usage

list_doestyle_colours()

Value

A tibble containing the names of valid colours and their hex values.

Examples

list_doestyle_colours()
list_doestyle_colours() |> print(n = 50)

The New South Wales Education Public Schools Master Dataset

Description

The master dataset contains comprehensive information for all government schools in NSW. Data items include school locations, latitude and longitude coordinates, school type, student enrolment numbers, electorate information, contact details and more. This dataset is publicly available through the Data NSW website.

Usage

public_schools

Format

An object of class spec_tbl_df (inherits from tbl_df, tbl, data.frame) with 2219 rows and 45 columns.

Source

https://data.nsw.gov.au/data/dataset/nsw-education-nsw-public-schools-master-dataset

Compute the relative luminance of an sRGB colour

Description

Compute the relative luminance of sRGB colour(s). See WCAG 2.1 definition: relative luminance.

Usage

relative_luminance(hex_values)

Arguments

hex_values

A character vector of hex value(s).

Value

relative_luminance() returns a numeric vector of luminance values.

Examples

relative_luminance(c("#ffffff", "#000000", "#002664", "#d7153a"))
relative_luminance(doe_cols("white", "black", "blue-01", "red-02"))

Apply a DoE palette to the colour aesthetic

Description

Apply a DoE palette to the colour aesthetic

Usage

scale_colour_doe(
  palette = doe_palettes$default,
  discrete = TRUE,
  direction = 1,
  ...
)

Arguments

palette

An object of class palettes_palette. Several useful palettes are ready to use in the list doe_palettes, which is included with the doestyle package. The default is doe_palettes$qualitative$default, which uses all of the on-brand colours defined in the NSW Department of Education Brand Guidelines.
discrete

Logical indicating whether the desired scale should be discrete. The default is TRUE. If FALSE, a continuous scale with interpolated colours will be constructed, instead.
direction

Sets the order of colours in the scale. If 1, the default, colours are ordered from first to last as they appear in the palette. If -1, the order of colours is reversed.
...

Additional arguments passed to ggplot2::discrete_scale() or ggplot2::continuous_scale().

Value

A scale function that can be added to a ggplot2 plot.

See Also

Examples

library(dplyr)
library(ggplot2)
library(doestyle)

# Plot growth in primary and secondary schools over time
public_schools |>
 filter(Level_of_schooling %in% c("Primary School", "Secondary School")) |>
 arrange(Date_1st_teacher) |>
 mutate(
   count = 1,
   cumulative_schools = cumsum(count),
   .by = Level_of_schooling) |>
 ggplot(aes(x = Date_1st_teacher,
            y = cumulative_schools,
            colour = Level_of_schooling)) +
 geom_step() +
 # Add a default DoE colour scale
 scale_colour_doe()

Apply a DoE palette to the fill aesthetic

Description

Apply a DoE palette to the fill aesthetic

Usage

scale_fill_doe(
  palette = doe_palettes$default,
  discrete = TRUE,
  direction = 1,
  ...
)

Arguments

palette

An object of class palettes_palette. Several useful palettes are ready to use in the list doe_palettes, which is included with the doestyle package. The default is doe_palettes$qualitative$default, which uses all of the on-brand colours defined in the NSW Department of Education Brand Guidelines.
discrete

Logical indicating whether the desired scale should be discrete. The default is TRUE. If FALSE, a continuous scale with interpolated colours will be constructed, instead.
direction

Sets the order of colours in the scale. If 1, the default, colours are ordered from first to last as they appear in the palette. If -1, the order of colours is reversed.
...

Additional arguments passed to ggplot2::discrete_scale() or ggplot2::continuous_scale().

Value

A scale function that can be added to a ggplot2 plot.

See Also

Examples

library(doestyle)
library(dplyr)
library(ggplot2)

public_schools |>
  filter(grepl("Connected Communities", Principal_network)) |>
  ggplot(aes(x = Principal_network, fill = Level_of_schooling)) +
  geom_bar(colour = "black", position = position_dodge(preserve = "single")) +
  theme(legend.position = "bottom") +
  labs(y = "Schools") +
  # Add a default department scale to the `fill` aesthetic.
  scale_fill_doe()

Get secondary colours for named brand colours

Description

Secondary colours are on-brand colours that can be used for pattern fills or other visual elements that need contrast against an on-brand fill colour. Each NSW Design System colour has a corresponding secondary colour available via secondary_colours().

Usage

secondary_colours(...)

Arguments

...

Colour name(s). May be supplied as a character vector or as individual arguments.

Value

secondary_colours() returns the hex value of an appropriate secondary colour for each on-brand colour name supplied in its arguments.

Examples

secondary_colours("red-02", "blue-01", "blue-04")

Show swatches for doestyle colours

Description

show_colours() produces a plot that shows and names the colours available in doestyle.

Usage

show_colours(swatches = c("brand", "primary", "nsw", "all"), linewidth = 1)

Arguments

swatches

The name of a set of colours to display. "brand" displays the department's brand colours only; "primary" shows the department's primary brand colours only; "nsw" shows all NSW Government brand colours; and "all" shows every colour included in doestyle, including additional off-brand colours for UX element specified in the department's Brand guidelines document.
linewidth

The thickness of each swatch's coloured border.

Value

show_colours() returns a ggplot2 gg object, which can be further manipulated with user-specified themes etc.

Examples

show_colours()

Get text colours for named brand colours

Description

Text colours are designed for plotting text over an on-brand fill colour. Each NSW Design System colour has a corresponding text colour available via text_colours().

Usage

text_colours(...)

Arguments

...

Colour name(s). May be supplied as a character vector or as individual arguments.

Value

secondary_colours() returns the hex value of an appropriate text colour for each on-brand colour name supplied in its arguments.

Examples

text_colours("red-02", "blue-01", "blue-04")

Apply the DoE theme to a ggplot2 plot

Description

Apply a minimalist DoE theme. By default, sets the font family to Public Sans and enables showtext::showtext_auto() to allow easy font display in plots.

Usage

theme_doe(base_size = 16, base_family = "Public Sans", ...)

Arguments

base_size

Base font size, given in pts.
base_family

Base font family. Defaults to the NSW Government on-brand font family, Public Sans.
...

Other parameters passed to ggplot2::theme().

Examples

library(doestyle)
library(ggplot2)

public_schools |>
 ggplot(aes(y = Operational_directorate)) +
 geom_bar() +
 # Apply theme_doe(): minimal decoration and Public Sans typeface
 theme_doe()

The DoE flextable theme

Description

Apply a DoE brand-compliant theme to a flextable object.

Usage

theme_doe_flextable(x)

apply_DoE_zebra_format(x)

Arguments

x

a flextable object

Examples

head(mtcars) |>
  flextable::flextable() |>
  theme_doe_flextable()