Package {hairline}

Title:	Clean, Predictable Figures for Medical and Data Science
Version:	0.1.0
Description:	A design system for 'ggplot2' figures: one frame for titles, legends, panels and captions, a fixed spacing and type scale, colour-vision checked palettes, brand files in the 'brand.yml' format, and print-ready export. Produces output matching the 'hairline' Python package.
License:	MIT + file LICENSE
URL:	https://github.com/schradern/hairline
BugReports:	https://github.com/schradern/hairline/issues
Copyright:	The bundled 'Hairline Sans' font is a modified Public Sans, Copyright 2015 The Public Sans Project Authors, under the SIL Open Font License 1.1; see inst/COPYRIGHTS.
Encoding:	UTF-8
Depends:	R (≥ 4.3)
Imports:	S7, ggplot2 (≥ 4.0.0), grid, grDevices, jsonlite, ragg, rlang, systemfonts, textshaping, tools, utils, yaml
Suggests:	cowplot, metafor, patchwork, png, rsvg, survival, svglite, testthat (≥ 3.0.0), withr
Config/testthat/edition:	3
Config/roxygen2/version:	8.1.1
NeedsCompilation:	no
Packaged:	2026-10-19 05:17:30 UTC; nschrader
Author:	Nikolas Schrader [aut, cre, cph]
Maintainer:	Nikolas Schrader <hi@nikolasschrader.com>
Repository:	CRAN
Date/Publication:	2026-10-28 11:50:08 UTC

hairline: Clean, Predictable Figures for Medical and Data Science

Description

A design system for 'ggplot2' figures: one frame for titles, legends, panels and captions, a fixed spacing and type scale, colour-vision checked palettes, brand files in the 'brand.yml' format, and print-ready export. Produces output matching the 'hairline' Python package.

Author(s)

Maintainer: Nikolas Schrader hi@nikolasschrader.com (ORCID) [copyright holder]

Authors:

• Nikolas Schrader hi@nikolasschrader.com (ORCID) [copyright holder]

See Also

Useful links:

• https://github.com/schradern/hairline

• Report bugs at https://github.com/schradern/hairline/issues

Colours in hairline

Description

hairline picks colours for you: every chart function colours its groups, amounts and highlights on its own. This page shows which colour sets there are, how to choose another one, and how to keep a group's colour the same across a report.

Which colours for which job

• Groups (arms, units, diagnoses): a categorical palette, e.g. hl_use(palette = "calm").

• Two groups (intervention, control): a pair, hl_use(palette = "pair").

• A printout in grey: "ink", or the palette "deep".

• Amounts (counts, rates, densities): a sequential ramp, e.g. scale_fill_hairline_c("blues").

• Values above and below a midpoint: a diverging ramp, scale_fill_hairline_c("blue-coral").

• One group against the rest: + hl_highlight("Unit B"), or ⁠highlight =⁠ in hl_timeseries().

• A single series: the accent, hl_use(accent = "#0b6e4f").

• Risk of bias: the "judgement" set, applied by hl_risk_of_bias().

See what there is

hl_palettes() lists every colour set with its kind, number of colours, use, and which one is active; hl_swatches() draws them. The six categorical palettes have eight colours each. Every set opens with its own blue, then its own red, so two groups always read blue against red: "daylight" (vivid; the default), "calm" (softer and lighter, for long reports), "deep" (stays apart when printed in grey), "lagoon" (cool), "citrus" (warm) and "bold" (saturated, for slides). The purpose sets are "pair", "pair-teal" and "pair-print" for two groups, "ink" for greyscale print and "judgement" for low, some concerns and high. The ramps are "blues", "teals", "oranges", "berries" and "greys" (sequential) and "blue-coral" and "teal-berry" (diverging).

Colour by count

The number of groups decides the colours, the same in every chart: two groups take the first two colours, three groups the first three. The first two, three and four colours of each palette are its most readable sets of that size, for colour-blind readers too, and because the sets are nested a group keeps its colour when more groups are shown. A ninth group is an error, not a repeated colour: fold small groups into "Other" or split the figure into panels.

Colour follows the name

Within a session a group keeps the colour it got first, in every later chart. Pin colours to names with hl_use(colors = c("Unit B" = "#e79d01")) and read them back with hl_color() and hl_colors(). For colours that stay the same across a report whatever order the charts are drawn in, put them in the brand file under ⁠defaults: hairline: colors:⁠; ⁠groups:⁠ gives the units of a section tints of the section's colour.

Brand and your own colours

A ⁠_brand.yml⁠ file holds an institution's palette (⁠defaults: hairline: categorical:⁠), found from the working directory upwards or given with hl_use(brand = ); several files layer from institution to project, and hl_brand_report() shows what was taken and which layer each colour came from. While a brand is active, its ramps "brand-sequential" and "brand-diverging" (from its ⁠sequential:⁠ and ⁠diverging:⁠ colours, else its first one and two colours) are the default for hl_ramp(), the continuous scales and the correlation heatmap. Any vector of hex colours can be a palette; hl_check_palette() measures how far apart the colours are for colour-blind readers and everyone else, and their contrast with the background (pairs = "all" for scatter plots and small multiples).

Light colours and dark backgrounds

Colours below 3:1 contrast on white stay as they are for bars and areas; lines in them are drawn a little wider and points are filled with a darker shade of the same hue. With hl_use(scheme = "dark") the background, text and grid greys turn dark; data colours stay, and thin marks are shaded lighter where needed. Text never takes a data colour.

See Also

hl_palettes(), hl_swatches(), hl_palette(), hl_ramp(), hl_use(), hl_check_palette().

Examples

hl_palettes("categorical")
hl_palette("pair")
hl_swatches(c("daylight", "calm", "pair", "blues"))

Arc diagram

Description

Nodes on a baseline and an arc above for each pair that exchanges something, its width following the value; without value each row counts once. Labels turn upright when they would collide.

Usage

hl_arcs(
  data,
  source,
  target,
  value = NULL,
  title = NULL,
  subtitle = NULL,
  caption = NULL,
  order = NULL
)

Arguments

Value

A ggplot with the hairline frame.

Examples

moves <- data.frame(origin = c("ICU", "ICU", "Ward", "Theatre", "ICU", "Ward"),
                    destination = c("Ward", "Ward", "Home", "ICU", "Home", "ICU"))
hl_arcs(moves, "origin", "destination", order = c("Theatre", "ICU", "Ward", "Home"))

Bar chart

Description

Bars per category; without value the rows are counted. Long or many labels turn the bars horizontal; a single series is sorted by value unless order or sort = "given" says otherwise. Values sit at the bar ends.

Usage

hl_bars(
  data,
  category,
  value = NULL,
  by = NULL,
  title = NULL,
  subtitle = NULL,
  caption = NULL,
  stacked = FALSE,
  percent = FALSE,
  horizontal = NULL,
  sort = NULL,
  order = NULL,
  labels = TRUE,
  colors = NULL
)

Arguments

Value

A ggplot with the hairline frame.

Examples

admissions <- data.frame(
  diagnosis = c("Sepsis", "Sepsis", "Trauma", "Cardiac", "Cardiac", "Cardiac"),
  sex = c("Female", "Male", "Male", "Female", "Male", "Male"))
hl_bars(admissions, "diagnosis")
hl_bars(admissions, "diagnosis", by = "sex", stacked = TRUE)

Brand report

Description

Brand report

Usage

hl_brand_report(brand = NULL)

Arguments

Value

A character string: the layers by number with their paths, then per slot the name, colour as given and as used, light slot and the layer that set it, the checks, and the pinned or grouped colours with their layers.

Examples

path <- file.path(tempdir(), "_brand.yml")
writeLines(c("meta:", "  name: Example Hospital", "color:", "  palette:",
             "    harbor: \"#0b3d6e\"", "    poppy: \"#f2545b\"", "defaults:", "  hairline:",
             "    categorical: [harbor, poppy]"), path)
hl_brand_report(hl_load_brand(path))

Check a palette for readability

Description

Runs hairline's palette checks: lightness band, chroma floor, separation under simulated protanopia and deuteranopia, normal-vision separation, and contrast against the surface.

Usage

hl_check_palette(colors, surface = "#ffffff", pairs = c("adjacent", "all"))

Arguments

Value

A list with passed, worst_cvd, worst_normal, head_all_pairs, light_slots, warnings, failures.

Examples

hl_check_palette(hl_palette(n = 4))
hl_check_palette(c("#1f77b4", "#2b83c4"), pairs = "all")

Chord diagram

Description

Groups as arcs on a ring, each sized by its total, and ribbons through the centre joining each pair (both directions combined), as wide as the pair's value at both ends; without value each row counts once.

Usage

hl_chord(
  data,
  source,
  target,
  value = NULL,
  title = NULL,
  subtitle = NULL,
  caption = NULL,
  order = NULL,
  colors = NULL
)

Arguments

Value

A ggplot with the hairline frame.

Examples

transfers <- data.frame(origin = c("ICU", "Ward", "ICU", "Step-down", "Ward"),
                        destination = c("Ward", "ICU", "Step-down", "Ward", "Step-down"))
hl_chord(transfers, "origin", "destination")

Entity colours

Description

hl_color() returns an entity's colour, assigning the first free palette slot the first time an entity is seen; the colour stays for the session. hl_colors() returns every colour fixed or assigned so far.

Usage

hl_color(name)

hl_colors()

Arguments

Value

A hex colour, or a named character vector.

Examples

hl_use(colors = c("Unit A" = "#0a6ddd", "Unit B" = "#e79d01"))
hl_color("Unit B")
hl_colors()
hl_use()

Compare one variable between groups

Description

Numeric variables: median (IQR) per group with the Wilcoxon rank-sum test (two groups) or Kruskal–Wallis (more), shown as a raincloud. Categorical variables: n (%) per group with the chi-squared test, shown as 100 % bars.

Usage

hl_compare(study, variable)

Arguments

Value

A hairline_result.

Examples

set.seed(1)
cohort <- data.frame(arm = rep(c("Standard care", "Early mobilisation"), each = 40),
                     age = round(stats::rnorm(80, 64, 12)),
                     sex = sample(c("Female", "Male"), 80, TRUE),
                     months = round(stats::rexp(80, 0.05), 1), died = stats::rbinom(80, 1, 0.4))
study <- hl_study(cohort, group = "arm", time = "months", event = "died",
                  units = c(age = "years", months = "months"))
hl_compare(study, "age")$text
hl_compare(study, "sex")$table

Correlation heatmap

Description

Correlations between numeric columns (all of them by default) as the lower triangle on a diverging ramp, values printed in the cells, each variable named on the empty diagonal; rows with gaps are left out.

Usage

hl_correlation(
  data,
  columns = NULL,
  method = "pearson",
  title = NULL,
  subtitle = NULL,
  caption = NULL
)

Arguments

Value

A ggplot with the hairline frame.

Examples

hl_correlation(datasets::mtcars, c("mpg", "disp", "hp", "wt"))

Table 1: the cohort by group

Description

One row per statistic or category, one column per group plus Overall, with an overview figure of the numeric variables (median and IQR).

Usage

hl_describe(study, stats = "median_iqr")

Arguments

Value

A hairline_result: figure, table, values and text.

Examples

set.seed(1)
cohort <- data.frame(arm = rep(c("Standard care", "Early mobilisation"), each = 40),
                     age = round(stats::rnorm(80, 64, 12)),
                     sex = sample(c("Female", "Male"), 80, TRUE),
                     months = round(stats::rexp(80, 0.05), 1), died = stats::rbinom(80, 1, 0.4))
study <- hl_study(cohort, group = "arm", time = "months", event = "died",
                  units = c(age = "years", months = "months"))
table_one <- hl_describe(study)
table_one$table
table_one$figure

Distribution of one numeric variable by group

Description

Distribution of one numeric variable by group

Usage

hl_distribution(study, variable, stats = "median_iqr")

Arguments

Value

A hairline_result; the figure is a raincloud, or a ridgeline from five groups.

Examples

set.seed(1)
cohort <- data.frame(arm = rep(c("Standard care", "Early mobilisation"), each = 40),
                     age = round(stats::rnorm(80, 64, 12)),
                     sex = sample(c("Female", "Male"), 80, TRUE),
                     months = round(stats::rexp(80, 0.05), 1), died = stats::rbinom(80, 1, 0.4))
study <- hl_study(cohort, group = "arm", time = "months", event = "died",
                  units = c(age = "years", months = "months"))
hl_distribution(study, "age", stats = c("median_iqr", "range"))$values

Donut and nested donut

Description

One ring with labels outside and leader lines, or up to three hierarchy levels with a hierarchical key; labels = "ring" labels the arcs instead. More than seven slices of a single ring fold into "Other". Children use tints of their parent's colour.

Usage

hl_donut(
  data,
  label = NULL,
  value = NULL,
  levels = NULL,
  title = NULL,
  subtitle = NULL,
  caption = NULL,
  labels = NULL,
  total = TRUE,
  total_label = NULL,
  colors = NULL,
  order = NULL
)

Arguments

Value

A ggplot with the hairline frame.

Examples

discharge <- data.frame(route = c("Home", "Rehabilitation", "Ward", "Died"),
                        patients = c(412, 168, 97, 23))
hl_donut(discharge, "route", "patients", total_label = "patients")

Dot plot with intervals

Description

One dot per row, largest at the top. With low and high each dot gets its interval and the numbers on the right; reference adds a vertical line.

Usage

hl_dotplot(
  data,
  label,
  estimate,
  low = NULL,
  high = NULL,
  title = NULL,
  subtitle = NULL,
  caption = NULL,
  sort = TRUE,
  ratio = FALSE,
  reference = NULL,
  digits = 2
)

Arguments

Value

A ggplot with the hairline frame.

Examples

rates <- data.frame(unit = c("Medical", "Surgical", "Cardiac"), mortality = c(0.13, 0.08, 0.06),
                    low = c(0.11, 0.07, 0.04), high = c(0.15, 0.10, 0.08))
hl_dotplot(rates, "unit", "mortality", "low", "high")

Effects with 95 % intervals

Description

From a fitted lm, glm or coxph model, or a table with estimate and interval columns; terms that are study columns take their labels.

Usage

hl_effects(
  study,
  model_or_table,
  measure = NULL,
  study_column = "study",
  estimate = "estimate",
  low = "low",
  high = "high",
  exponentiate = NULL,
  digits = 2,
  ...
)

Arguments

Value

A hairline_result.

Examples

set.seed(1)
cohort <- data.frame(arm = rep(c("Standard care", "Early mobilisation"), each = 40),
                     age = round(stats::rnorm(80, 64, 12)),
                     sex = sample(c("Female", "Male"), 80, TRUE),
                     months = round(stats::rexp(80, 0.05), 1), died = stats::rbinom(80, 1, 0.4))
study <- hl_study(cohort, group = "arm", time = "months", event = "died",
                  units = c(age = "years", months = "months"))
model <- stats::glm(died ~ age + sex, family = stats::binomial, data = cohort)
hl_effects(study, model, "OR")$values

Find a brand file

Description

Looks for ⁠_brand.yml⁠ from start upwards and stops at the project root (a folder containing .git, ⁠_quarto.yml⁠, pyproject.toml or DESCRIPTION).

Usage

hl_find_brand(start = getwd())

Arguments

Value

The path, or NULL.

Examples

path <- file.path(tempdir(), "_brand.yml")
writeLines(c("meta:", "  name: Example Hospital", "color:", "  palette:",
             "    harbor: \"#0b3d6e\"", "    poppy: \"#f2545b\"", "defaults:", "  hairline:",
             "    categorical: [harbor, poppy]"), path)
hl_find_brand(tempdir())

Forest plot

Description

A results table (study, extra columns, effect with 95 % interval, weight) beside the intervals: squares sized by weight, a pooled diamond, a solid null line, a dashed pooled line, a log axis for ratios and "favours" labels under it. Heterogeneity goes into the caption.

Usage

hl_forest(
  data,
  study = "study",
  estimate = "estimate",
  low = "low",
  high = "high",
  weight = NULL,
  columns = character(),
  pooled = NULL,
  ratio = TRUE,
  favours = NULL,
  heterogeneity = NULL,
  title = NULL,
  subtitle = NULL,
  caption = NULL,
  exponentiate = NULL,
  ...
)

Arguments

Value

A ggplot with the hairline frame.

Examples

trials <- data.frame(study = c("Trial A", "Trial B", "Trial C"), or = c(0.62, 0.81, 0.47),
                     low = c(0.41, 0.55, 0.25), high = c(0.94, 1.19, 0.88), weight = c(40, 35, 25))
hl_forest(trials, "study", "or", "low", "high", weight = "weight",
          pooled = list(estimate = 0.66, low = 0.52, high = 0.84, label = "Pooled"))

Format numbers, percentages and intervals

Description

Fixed decimals, locale separators ("en" or "de") and a true minus sign.

Usage

hl_format_number(value, digits = 1, locale = NULL)

hl_format_percent(share, digits = 1, locale = NULL)

hl_format_interval(estimate, low, high, digits = 2, locale = NULL)

Arguments

Value

A character string.

Examples

hl_format_number(1234.5, 1)
hl_format_number(-0.25, 2, locale = "de")
hl_format_percent(0.125, 1)
hl_format_interval(0.62, 0.41, 0.94)

Funnel plot

Description

Effect against standard error (running down from 0) with pseudo 95 % limits around the pooled estimate, a dashed pooled line and a solid null line; the pooled estimate and Egger's test become the key numbers.

Usage

hl_funnel(
  data,
  estimate,
  se,
  title = NULL,
  subtitle = NULL,
  caption = NULL,
  ratio = TRUE,
  pooled = NULL,
  x_title = NULL
)

Arguments

Value

A ggplot with the hairline frame.

Examples

trials <- data.frame(odds_ratio = c(0.84, 0.67, 0.91, 0.72, 0.55),
                     se = c(0.12, 0.27, 0.09, 0.2, 0.35))
hl_funnel(trials, "odds_ratio", "se")

Highlight series or panels

Description

Keeps the named series (legend labels of the colour or fill mapping) or panels (facet label or 1-based index) in their colours and draws every other data series in the context grey.

Usage

hl_highlight(series = NULL, panels = NULL)

Arguments

Value

An object to add to a ggplot with +.

Examples

data <- data.frame(day = rep(1:10, 3),
                   share = c(seq(0.6, 0.9, length.out = 10), rep(0.7, 10), rep(0.8, 10)),
                   unit = rep(c("Unit A", "Unit B", "Unit C"), each = 10))
ggplot2::ggplot(data, ggplot2::aes(day, share, colour = unit)) + ggplot2::geom_line() +
  ggplot2::labs(title = "Occupancy") + theme_hairline() + hl_highlight("Unit A")

Install the bundled font for PDF output

Description

Copies the bundled 'Hairline Sans' files into your user font folder so that every PDF route (cairo, rsvg, Quartz) can embed it. Nothing is installed unless you call this function.

Usage

hl_install_font(confirm = interactive())

Arguments

Value

The installed file paths, invisibly.

Examples

if (interactive()) hl_install_font()

Kaplan–Meier curves

Description

Step curves per group with 95 % bands (Greenwood, log scale) and censor ticks, a dotted 50 % line, medians and your statistics in the panel header, and the number at risk under the x-axis aligned to its ticks.

Usage

hl_kaplan_meier(
  data,
  time = NULL,
  event = NULL,
  by = NULL,
  title = NULL,
  subtitle = NULL,
  caption = NULL,
  x_title = "Time",
  endpoint = "Survival",
  median_line = TRUE,
  stats = character(),
  at_risk = TRUE,
  times = NULL,
  order = NULL,
  test = TRUE,
  colors = NULL
)

Arguments

Value

A ggplot with the hairline frame.

Examples

set.seed(1)
trial <- data.frame(months = round(stats::rexp(60, 0.06), 1), died = stats::rbinom(60, 1, 0.6),
                    arm = rep(c("Standard care", "Early mobilisation"), 30))
hl_kaplan_meier(trial, "months", "died", by = "arm", x_title = "Months since discharge")

Frame positions of a hairline plot

Description

Lays out the plot at the given size and returns the positions hairline computes (pt from the top-left corner); the same keys as the Python package's layout_report(), used for cross-language parity checks.

Usage

hl_layout_report(plot, width_mm = NULL, height_mm = NULL, size = "onehalf")

Arguments

Value

A named list.

Examples

plot <- ggplot2::ggplot(datasets::mtcars, ggplot2::aes(wt, mpg)) + ggplot2::geom_point() +
  ggplot2::labs(title = "Fuel use by weight") + theme_hairline()
str(hl_layout_report(plot, size = "single")$panels)

Explicit legend items

Description

Replaces the legend row collected from the plot's colour and fill scales with these items, e.g. to explain line kinds instead of groups.

Usage

hl_legend(items)

Arguments

Value

An object to add to a ggplot with +.

Examples

ggplot2::ggplot(datasets::mtcars, ggplot2::aes(wt, mpg)) + ggplot2::geom_point() +
  ggplot2::labs(title = "Fuel use by weight") + theme_hairline() +
  hl_legend(list(list(kind = "dot", colour = hl_palette(n = 1), label = "Car")))

Read a brand file

Description

Parses a ⁠_brand.yml⁠ file in the brand.yml format. Errors name the file, the key path and the offending value.

Usage

hl_load_brand(path, output = NULL)

Arguments

Value

A list with name, path, names, colors_given, colors_used, adapt, font, heading_font, heading_weight, neutral, base_size, sizes, locale, entity_colors, entity_failures, output, sequential_hue, diverging_hues, layers (the file paths), slot_origins and entity_origins (the layer that set each colour).

Examples

path <- file.path(tempdir(), "_brand.yml")
writeLines(c("meta:", "  name: Example Hospital", "color:", "  palette:",
             "    harbor: \"#0b3d6e\"", "    poppy: \"#f2545b\"", "defaults:", "  hairline:",
             "    categorical: [harbor, poppy]"), path)
brand <- hl_load_brand(path, output = "pdf")
brand$name

One measure over time by group

Description

Small multiples per group with the raw values and a trailing mean; the table gives n, mean (SD) and median (IQR) over the whole period. ISO date text (2025-01-31) is read as dates.

Usage

hl_over_time(study, date, value, window = 7)

Arguments

Value

A hairline_result.

Examples

set.seed(1)
visits <- data.frame(day = 1:60, lactate = round(2 + sin(1:60 / 8) + stats::rnorm(60, 0, 0.3), 1))
study <- hl_study(visits, units = c(day = "days", lactate = "mmol/l"))
hl_over_time(study, "day", "lactate", window = 7)$text

Palette colours in slot order

Description

Colours for groups, in the order hairline assigns them: two groups take slots 1-2, three groups slots 1-3, and a group keeps its colour when more are shown. There are six categorical palettes of eight slots, each opening blue then red so two groups always read blue against red ("daylight", the default, "calm", "deep", "lagoon", "citrus" and "bold"), and purpose sets for common cases: "pair", "pair-teal" and "pair-print" for two groups, "ink" for greyscale print and "judgement" for low, some concerns and high. hl_palettes() lists them all with their uses and hl_swatches() draws them; make one the default with hl_use(palette = ). For amounts, use a ramp (hl_ramp()) instead.

Usage

hl_palette(name = NULL, n = NULL)

Arguments

Value

Character vector of hex colours.

See Also

hl_palettes(), hl_swatches(), hl_check_palette(), hl_use().

Examples

hl_palette()
hl_palette(n = 3)
hl_palette("pair")
hl_palette("calm", n = 4)

Every colour set, with its use

Description

The catalogue of hairline's colours: categorical palettes and purpose sets for groups, sequential and diverging ramps for amounts. active marks the palette in use; a palette from a brand or hl_use(palette = c(...)) comes first. Use a name with hl_palette(), hl_use(palette = ) or hl_ramp().

Usage

hl_palettes(kind = NULL)

Arguments

Value

A data frame with name, kind, slots, active, use and colors (hex codes separated by spaces).

See Also

hl_swatches() draws them.

Examples

hl_palettes()
hl_palettes("purpose")

Panel header with key numbers

Description

Adds a header line above a panel: the name, an optional qualifier, and key numbers right-aligned. When the numbers do not fit they move to a second line; numbers that still do not fit are dropped with a warning.

Usage

hl_panel_header(
  name = NULL,
  qualifier = NULL,
  stats = NULL,
  panel = NULL,
  key = NULL,
  x_title = NULL
)

Arguments

Value

An object to add to a ggplot with +.

Examples

data <- data.frame(day = rep(1:10, 2), share = c(seq(0.6, 0.9, length.out = 10), rep(0.7, 10)),
                   unit = rep(c("Unit A", "Unit B"), each = 10))
ggplot2::ggplot(data, ggplot2::aes(day, share)) + ggplot2::geom_line() +
  ggplot2::facet_wrap(~unit) +
  ggplot2::labs(title = "Occupancy") + theme_hairline() +
  hl_panel_header(panel = "Unit A", qualifier = "12 beds", stats = c(Mean = "75 %")) +
  hl_panel_header(panel = "Unit B", qualifier = "8 beds", stats = c(Mean = "70 %"))

Partition bars

Description

A hierarchy as stacked rows, one per level, children directly under their parent; the documented alternative to a nested donut. Labels sit inside the bars (name and share, else the share, else none); a legend row names the top level.

Usage

hl_partition(
  data,
  levels,
  value = NULL,
  title = NULL,
  subtitle = NULL,
  caption = NULL,
  level_names = NULL,
  colors = NULL,
  order = NULL
)

Arguments

Value

A ggplot with the hairline frame.

Examples

discharge <- data.frame(route = c("Home", "Home", "Rehabilitation", "Ward"),
                        support = c("Alone", "With support", "Inpatient", "Ward"),
                        patients = c(250, 162, 168, 97))
hl_partition(discharge, c("route", "support"), "patients",
             level_names = c("Destination", "Support"))

PRISMA 2020 flow diagram

Description

Identified, screened, sought, assessed and included records with the exclusions beside them, phases as brackets on the left. Counts that do not add up give a warning.

Usage

hl_prisma(counts, title = NULL, subtitle = NULL, caption = NULL)

Arguments

Value

A ggplot with the hairline frame.

Examples

hl_prisma(list(identified = 1240, duplicates = 260, screened = 980, excluded = 860, sought = 120,
               not_retrieved = 10, assessed = 110, excluded_reasons = c("Wrong population" = 92),
               included = 18))

Raincloud plot

Description

Per group a half density, the box (interquartile range and median) and the points, with "n = …" under the group names. Comparison brackets show your test results and are stacked so they never overlap.

Usage

hl_raincloud(
  data,
  group,
  value = NULL,
  title = NULL,
  subtitle = NULL,
  caption = NULL,
  y_title = NULL,
  order = NULL,
  comparisons = list(),
  colors = NULL
)

Arguments

Value

A ggplot with the hairline frame.

Examples

set.seed(1)
stays <- data.frame(unit = rep(c("Surgical", "Medical"), each = 30),
                    days = round(stats::rexp(60, 0.2), 1))
hl_raincloud(stays, "unit", "days", y_title = "Days")

Sequential or diverging ramp

Description

Colours for amounts. Sequential ramps run light to dark in one hue ("blues", "teals", "oranges", "berries", "greys"); diverging ramps run from one pole through a neutral midpoint to the other ("blue-coral", "teal-berry"), for values below and above a reference. scale_colour_hairline_c() and scale_fill_hairline_c() use them in a plot. While a brand is active, "brand-sequential" and "brand-diverging" follow its colours (its sequential and diverging entries, else its first one and two colours) and become the default.

Usage

hl_ramp(name = NULL, n = NULL)

Arguments

Value

Character vector of hex colours.

See Also

hl_palettes(), hl_swatches().

Examples

hl_ramp("blues")
hl_ramp("blues", n = 3)
hl_ramp("blue-coral", n = 5)

Reference line with a label

Description

A thin dashed line (threshold, target) behind the data in every panel, with an optional label at its end and an optional legend entry.

Usage

hl_reference(y = NULL, x = NULL, label = NULL, legend_label = NULL)

Arguments

Value

An object to add to a ggplot with +.

Examples

ggplot2::ggplot(datasets::airquality, ggplot2::aes(Day, Temp)) + ggplot2::geom_point() +
  ggplot2::labs(title = "Daily temperature") + theme_hairline() +
  hl_reference(y = 80, label = "80 F")

Ridgeline plot

Description

One density ridge per group on a shared x-axis, the first group on top, each overlapping the row above; all ridges share one height scale, and a short line marks each median.

Usage

hl_ridgeline(
  data,
  group,
  value = NULL,
  title = NULL,
  subtitle = NULL,
  caption = NULL,
  order = NULL,
  medians = TRUE,
  colors = NULL
)

Arguments

Value

A ggplot with the hairline frame.

Examples

set.seed(1)
diagnoses <- c("Sepsis", "Trauma", "Cardiac", "Respiratory", "Neuro")
ages <- data.frame(diagnosis = rep(diagnoses, each = 40),
                   age = round(stats::rnorm(200, rep(c(68, 45, 70, 62, 55), each = 40), 10)))
hl_ridgeline(ages, "diagnosis", "age")

Risk-of-bias summary

Description

One 100 % bar per domain with the number of studies judged low, some concerns or high inside, and an overall row (each study's worst judgement) below a rule. Reads a long table (study, domain, judgement) or a wide one with one column per domain.

Usage

hl_risk_of_bias(
  data,
  study,
  domain = NULL,
  judgement = NULL,
  domains = NULL,
  overall = "Overall",
  title = NULL,
  subtitle = NULL,
  caption = NULL
)

Arguments

Value

A ggplot with the hairline frame.

Examples

trials <- data.frame(study = c("Trial 1", "Trial 2"), Randomisation = c("Low", "Some concerns"),
                     Reporting = c("Low", "High"), check.names = FALSE)
hl_risk_of_bias(trials, "study", domains = c("Randomisation", "Reporting"))

Sankey diagram

Description

Flows from left to right through two or more columns. Nodes share one scale; later columns are ordered to reduce crossings and links are ordered at both ends, so they never cross inside a node. Links take the colour of their group in color_by (default the last column).

Usage

hl_sankey(
  data,
  columns,
  value = NULL,
  title = NULL,
  subtitle = NULL,
  caption = NULL,
  color_by = NULL,
  headings = NULL,
  colors = NULL
)

Arguments

Value

A ggplot with the hairline frame.

Examples

budget <- data.frame(income = c("Salary", "Salary", "Benefit"),
                     account = c("Joint", "Joint", "Savings"),
                     spending = c("Rent", "Food", "Reserve"), euros = c(1200, 420, 150))
hl_sankey(budget, c("income", "account", "spending"), "euros")

Save print-ready files

Description

Writes ⁠name.<format>⁠ for each format: PDF (vector), PNG and TIFF (600 dpi by default, TIFF LZW-compressed) and SVG (text kept as text). PDF, PNG and SVG files are named by the plot's title, with the title and subtitle as their description; none shows a timestamp or producer banner. PDF uses cairo where it is available; otherwise svglite + rsvg. Both embed the bundled font once it can be found: cairo finds it on its own outside Windows, otherwise run hl_install_font() once. PDFs are byte-identical across runs with cairo before 1.17.6; later versions keep a creation date inside a compressed stream that no PDF reader shows.

Usage

hl_save(
  plot,
  name,
  formats = c("pdf", "png"),
  size = "onehalf",
  width_mm = NULL,
  height_mm = NULL,
  dpi = 600,
  background = NULL
)

Arguments

Value

The written paths, invisibly.

Examples

plot <- ggplot2::ggplot(datasets::mtcars, ggplot2::aes(wt, mpg)) + ggplot2::geom_point() +
  ggplot2::labs(title = "Fuel use by weight") + theme_hairline()
hl_save(plot, file.path(tempdir(), "fuel"), formats = "png", size = "single", dpi = 150)

Scatter plot with fit

Description

Points per group in their entity colours and, with fit = "linear", a linear fit over all points with its 95 % band; n, r and slope become the key numbers.

Usage

hl_scatter(
  data,
  x,
  y,
  by = NULL,
  title = NULL,
  subtitle = NULL,
  caption = NULL,
  fit = "linear",
  order = NULL,
  colors = NULL
)

Arguments

Value

A ggplot with the hairline frame.

Examples

hl_scatter(datasets::mtcars, "wt", "mpg", title = "Fuel use by weight")

Active hairline settings

Description

Active hairline settings

Usage

hl_settings()

Value

The settings list set by the last hl_use(), or the defaults.

Examples

hl_settings()$font

Spread rows: distributions per group on one axis

Description

Per group, first on top: the range as a thin line, the interquartile range as a band in the group's colour, the median as a dot, an optional reference tick, and the key numbers right-aligned.

Usage

hl_spread(
  data,
  group,
  value,
  title = NULL,
  subtitle = NULL,
  caption = NULL,
  order = NULL,
  marks = NULL,
  mark_label = NULL,
  stats = c("median", "iqr", "mean"),
  percent = FALSE,
  digits = NULL,
  zero = FALSE,
  axis_title = NULL,
  colors = NULL
)

Arguments

Value

A ggplot with the hairline frame.

Examples

set.seed(1)
beds <- data.frame(unit = rep(c("Unit A", "Unit B", "Unit C"), each = 50),
                   occupied = c(stats::rpois(50, 10), stats::rpois(50, 7), stats::rpois(50, 12)))
hl_spread(beds, "unit", "occupied", marks = c("Unit A" = 12, "Unit B" = 8, "Unit C" = 14),
          mark_label = "Beds",
          zero = TRUE, axis_title = "Occupied beds")

Describe a dataset once for the study endpoints

Description

Names the column that plays each role, runs the checks and returns a study for hl_describe(), hl_distribution(), hl_compare(), hl_survival() and hl_effects(). Checks report problems (print the study) and never change the data; errors block only the endpoints that need the column.

Usage

hl_study(
  data,
  group = NULL,
  time = NULL,
  event = NULL,
  id = NULL,
  variables = NULL,
  labels = NULL,
  types = NULL,
  order = NULL,
  unit = NULL,
  units = NULL
)

Arguments

Value

A hairline_study.

Examples

set.seed(1)
cohort <- data.frame(arm = rep(c("Standard care", "Early mobilisation"), each = 40),
                     age = round(stats::rnorm(80, 64, 12)),
                     sex = sample(c("Female", "Male"), 80, TRUE),
                     months = round(stats::rexp(80, 0.05), 1), died = stats::rbinom(80, 1, 0.4))
study <- hl_study(cohort, group = "arm", time = "months", event = "died",
                  units = c(age = "years", months = "months"))
study

Survival by group

Description

Kaplan–Meier curves with the log-rank test; the table gives n, events and the median per group. A fit already made (survival::survfit) can be passed as fit; it keeps its own intervals, and the log-rank test comes from the study's own time, event and group columns when they are set.

Usage

hl_survival(study, fit = NULL)

Arguments

Value

A hairline_result.

Examples

set.seed(1)
cohort <- data.frame(arm = rep(c("Standard care", "Early mobilisation"), each = 40),
                     age = round(stats::rnorm(80, 64, 12)),
                     sex = sample(c("Female", "Male"), 80, TRUE),
                     months = round(stats::rexp(80, 0.05), 1), died = stats::rbinom(80, 1, 0.4))
study <- hl_study(cohort, group = "arm", time = "months", event = "died",
                  units = c(age = "years", months = "months"))
hl_survival(study)$values

Colour sets as swatches

Description

Draws palettes, purpose sets and ramps as rows of squares under their headings, each with its use, to choose colours by eye. In HTML output each square shows its slot and hex code on hover.

Usage

hl_swatches(names = NULL, title = NULL, subtitle = NULL, caption = NULL)

Arguments

Value

A ggplot with the hairline frame.

See Also

hl_palettes(), hl_palette(), hl_ramp().

Examples

hl_swatches()
hl_swatches(c("daylight", "calm", "pair", "blues"), title = "Colours for this report")

Small-multiple time series with two levels of detail

Description

One panel per group: raw values as a thin line under a trailing rolling mean in the group's entity colour, with key numbers in the panel headers, and optional period mean, threshold, highlighted periods and events.

Usage

hl_timeseries(
  data,
  x,
  y,
  by = NULL,
  title = NULL,
  subtitle = NULL,
  caption = NULL,
  window = 7,
  raw = TRUE,
  period_mean = FALSE,
  percent = FALSE,
  threshold = NULL,
  threshold_label = NULL,
  threshold_legend = NULL,
  stats = c("mean", "median"),
  share_label = NULL,
  key = NULL,
  key_panels = NULL,
  highlight = NULL,
  qualifiers = list(),
  bands = list(),
  events = list(),
  order = NULL,
  raw_label = "Raw values",
  mean_label = NULL,
  colors = NULL
)

Arguments

Value

A ggplot with the hairline frame.

Examples

set.seed(1)
occupancy <- data.frame(date = rep(as.Date("2025-01-01") + 0:89, 2),
                        unit = rep(c("Unit A", "Unit B"), each = 90),
                        share = pmin(1, c(0.8 + stats::rnorm(90, 0, 0.05),
                                          0.7 + stats::rnorm(90, 0, 0.05))))
hl_timeseries(occupancy, "date", "share", by = "unit", percent = TRUE, threshold = 0.9,
              threshold_label = "90 %")

Shared design tokens

Description

Returns the design tokens shared by the R and Python packages (type and spacing scales, line widths, neutral colours, palettes, size presets).

Usage

hl_tokens()

Value

A named list.

Set hairline's style for this session

Description

Precedence: these arguments > the brand (⁠brand =⁠ path, or a ⁠_brand.yml⁠ found from the working directory up to the project root; brand = FALSE disables the lookup) > hairline's defaults.

Usage

hl_use(
  font = NULL,
  base_size = NULL,
  sizes = NULL,
  palette = NULL,
  locale = NULL,
  background = NULL,
  brand = NULL,
  colors = NULL,
  output = NULL,
  accent = NULL,
  scheme = NULL
)

Arguments

Value

The active settings, invisibly.

Examples

hl_use(base_size = 10, locale = "de", accent = "#0b6e4f")
hl_settings()$locale
hl_use()

Venn diagram

Description

The overlap of two or three sets with the count of every region inside it and each set's name and size outside. Circles are schematic (equal sizes); with proportional = TRUE, two circles get areas proportional to their sizes and overlap by the shared count. Four or more sets are refused: show the intersections as bars instead.

Usage

hl_venn(
  data,
  columns = NULL,
  title = NULL,
  subtitle = NULL,
  caption = NULL,
  colors = NULL,
  proportional = FALSE
)

Arguments

Value

A ggplot with the hairline frame.

Examples

hl_venn(list(Diabetes = c(1, 2, 3, 5, 8), Hypertension = c(2, 3, 4, 8, 9, 10),
             Obesity = c(3, 5, 9, 11)))

Colour and fill scales from hairline palettes and ramps

Description

Discrete scales give every level its entity colour (see hl_color()) when palette is NULL, or the palette's slots in order otherwise, and refuse more categories than slots; continuous scales use a sequential or diverging ramp. Charts made with hairline's own functions pick their colours already; these scales are for plots built with ggplot2 directly.

Usage

scale_colour_hairline(palette = NULL, ...)

scale_fill_hairline(palette = NULL, ...)

scale_colour_hairline_c(ramp = NULL, ...)

scale_fill_hairline_c(ramp = NULL, ...)

Arguments

Value

A ggplot2 scale.

See Also

hl_palettes(), hl_swatches().

Examples

ggplot2::ggplot(datasets::iris, ggplot2::aes(Sepal.Length, Petal.Length, colour = Species)) +
  ggplot2::geom_point() + ggplot2::labs(title = "Petal by sepal length") + theme_hairline() +
  scale_colour_hairline()
ggplot2::ggplot(ggplot2::faithfuld, ggplot2::aes(waiting, eruptions, fill = density)) +
  ggplot2::geom_raster() + ggplot2::labs(title = "Old Faithful eruptions") + theme_hairline() +
  scale_fill_hairline_c("teals")

Position scales with nice breaks

Description

Continuous position scales using hairline's 3–6 'nice' breaks, locale number formatting and limits that end on a break. Applied automatically to hairline plots; add explicitly to change percent or target.

Usage

scale_y_hairline(percent = FALSE, target = NULL, ...)

scale_x_hairline(percent = FALSE, target = NULL, ...)

Arguments

Value

A ggplot2 scale.

Examples

shares <- data.frame(unit = c("A", "B", "C"), share = c(0.42, 0.65, 0.81))
ggplot2::ggplot(shares, ggplot2::aes(unit, share)) + ggplot2::geom_col() +
  ggplot2::labs(title = "Share of beds occupied") + theme_hairline() +
  scale_y_hairline(percent = TRUE)

hairline theme and frame

Description

Adds hairline's theme and frame to a ggplot: title, subtitle, legend row, panel headers and caption on one left edge, with the spacing scale applied wherever the plot is printed or saved.

Usage

theme_hairline(base_size = NULL, font = NULL, axes = TRUE)

Arguments

Value

An object to add to a ggplot with +.

Examples

ggplot2::ggplot(datasets::mtcars, ggplot2::aes(wt, mpg)) + ggplot2::geom_point() +
  ggplot2::labs(title = "Fuel use by weight", subtitle = "32 cars, 1974", caption = "Motor Trend.",
                x = "Weight (1000 lb)", y = "Miles per gallon") + theme_hairline()