Package 'ggconsulting'

Brazilian macroeconomic indicators (monthly)

Description

Monthly observations of five headline Brazilian macro series from 2012-03 through 2024-12. Wide format: one row per month, one column per indicator. Snapshot frozen at 2024-12-31. Suitable for theme_editorial() demos and ct_locale("pt-BR") formatting.

Usage

br_macro

Format

A data frame with 154 rows and 6 columns:

date

First day of the month (Date).

selic

Selic accumulated in the month, annualized using base 252, % a.a. (numeric).

ipca_12m

IPCA accumulated over the trailing 12 months, % (numeric).

ibc_br

IBC-Br activity index, seasonally adjusted, 2002=100 (numeric).

usd_brl

USD/BRL exchange rate (sale), BRL per USD, end-of-month (numeric).

unemployment

PNADC unemployment rate, % (numeric).

Details

All source series are monthly. The usd_brl series is the BCB sale rate at the end of the period; dates are normalized to the first day of each month in this snapshot.

Source

Banco Central do Brasil, Sistema Gerenciador de Séries Temporais (SGS), series 4189, 13522, 24364, 3696, and 24369. Series 24369 is PNADC data from IBGE redistributed through SGS. Fetched via the rbcb package. The snapshot ends on 2024-12-31; values are rounded and transformed in this repository, and this is not an official current BCB or IBGE release. See data-raw/br_macro.R and https://www3.bcb.gov.br/sgspub/.

Examples

head(br_macro)

---

Quarterly P&L for a fictional Brazilian conglomerate

Description

Simulated quarterly revenue, COGS, EBITDA, and headcount for five business units of a mid-cap Brazilian conglomerate, spanning 16 quarters (2021-Q1 through 2024-Q4). Suitable for demos of theme_strategy(), stacked-bar ct_finish() value labels, and fmt_brl(). All monetary values are in millions of Brazilian Real (R$ MM).

Usage

bu_quarterly

Format

A data frame with 80 rows and 6 columns:

quarter

First day of the calendar quarter (Date).

business_unit

Factor with 5 levels: Industrial, Consumer, Health, Logistics, Digital.

revenue_brl

Net revenue, R$ MM (numeric).

cogs_brl

Cost of goods sold, R$ MM (numeric).

ebitda_brl

EBITDA, R$ MM (numeric); can be negative.

headcount

Period-end full-time-equivalent employees (integer).

Source

Synthetic data generated by the ggconsulting authors. It does not describe a real company, financial result, or employee population. See data-raw/bu_quarterly.R.

Examples

head(bu_quarterly)

---

Quarterly NPS by client segment

Description

Simulated quarterly Net Promoter Score for three client segments (Enterprise, Mid-Market, SMB) across 12 quarters (2022-Q1 through 2024-Q4). Suitable for line-chart demos with last-point labels and fmt_delta() / fmt_pct().

Usage

client_nps

Format

A data frame with 36 rows and 4 columns:

quarter

First day of the calendar quarter (Date).

segment

Factor with 3 levels: Enterprise, Mid-Market, SMB.

nps

Net Promoter Score, integer in [-100, 100].

responses

Number of survey responses in the period (integer).

Source

Synthetic data generated by the ggconsulting authors. It does not describe real clients, survey respondents, or survey results. See data-raw/client_nps.R.

Examples

head(client_nps)

---

Set or restore ggconsulting aesthetic defaults

Description

ct_set_defaults() overrides ggplot2 aesthetic defaults via ggplot2::update_geom_defaults(). v0.1 sets a single override: geom_point size = 2.5. ct_unset_defaults() restores whatever values were active the first time ct_set_defaults() ran — not ggplot2's untouched baseline.

Originals are captured once into a package-private environment, so repeated ct_set_defaults() calls are idempotent. Column width and linewidth are handled elsewhere — see ct_col() / ct_line() for explicit formal overrides, or apply ct_theme() / theme_strategy() for linewidth via from_theme().

Usage

ct_set_defaults()

ct_unset_defaults()

Value

Both functions return invisible(NULL).

Examples

ct_set_defaults()
ct_unset_defaults()

---

Apply data-aware finishing touches to a plot

Description

Companion to ct_theme() that runs after the geom layer is built, so it can inspect the data + active geom to inject value labels, sorting, highlighting, end labels, and scale expansion. Compose with +, after the geoms.

Usage

ct_finish(
  values = FALSE,
  sort = NULL,
  label_fmt = NULL,
  highlight = NULL,
  end_labels = FALSE,
  end_points = FALSE,
  axis_y = NULL,
  mirror_y = FALSE,
  expand = "auto",
  muted_color = "#A8A4A0"
)

Arguments

values	TRUE adds value labels above bars / next to points. "auto" adds them only when the first geom is a column or bar.
sort	One of "asc", "desc", or NULL. When set, reorders the factor levels of the x aesthetic by the y aesthetic.
label_fmt	Either a formatter function (anything that maps a numeric vector to a character vector), or one of the shortcut names "brl", "number", "pct", "delta" resolved to the matching ⁠fmt_*()⁠ helper.
highlight	Value(s) of the x aesthetic to emphasise. Matching bars use the active palette's main colour; non-matching bars use muted_color. Inserted as a ⁠scale_*_manual()⁠.
end_labels	For line plots: TRUE labels the last point of each series with the group identifier. "first_facet" draws those labels only in the first panel, which replaces a legend across small multiples; on an unfaceted plot it behaves like TRUE. The x aesthetic may be numeric, Date, or POSIXct.
end_points	For line plots: when TRUE, draw a filled point at each series' last observation, under the end label.
axis_y	Moves the y axis. "right" or "left"; NULL (default) leaves it where the scale puts it. Applied through ggplot2::guide_axis(), so it does not disturb a ⁠scale_y_*()⁠ call of your own.
mirror_y	When TRUE, repeats the y-axis ticks on the opposite edge without labels, so the eye can track a level across a wide panel. Pairs with a gridline-free theme such as theme_finance(). Applied through ggplot2::guides(), so it leaves a ⁠scale_y_*()⁠ call of your own alone.
expand	"auto" picks geom-aware scale expansion (room above column tops, right-side room for line end labels); FALSE disables. Auto expansion defers to a positional scale you supplied yourself, so a scale_y_continuous(labels = ) keeps its labels; set the expansion in that call when you need both.
muted_color	Fill / colour used for non-highlighted categories.

Value

A ct_finish object, added to a plot via +. The ggplot_add() method composes the requested layers and scales.

Examples

library(ggplot2)
d <- data.frame(g = LETTERS[1:5], v = c(3, 8, 5, 12, 7))
p <- ggplot(d, aes(g, v)) +
  geom_col() +
  ct_finish(values = TRUE, sort = "desc", label_fmt = "brl", highlight = "D") +
  theme_strategy()

---

Locale-aware label formatters

Description

Factory functions: each returns a function compatible with ⁠scales::label_*⁠ (callable on a numeric vector). Marks (thousands, decimals) and currency symbols come from the active ggconsulting locale, set via ct_locale().

• fmt_number() — plain numbers with locale separators.

• fmt_brl() — Brazilian Real. Always renders as ⁠R$⁠ regardless of active locale; the locale argument lets you override marks.

• fmt_currency() — uses the active locale's currency symbol.

• fmt_pct() — percentages. By default interprets input as a fraction (0.5 → "50%"); pass scale = 1 when the input is already in percent units (50 → "50%").

• fmt_delta() — percentage-point-style signed deltas (⁠+1,2pp⁠ / ⁠-0,3pp⁠ / ⁠0,0pp⁠).

• fmt_month() — Date / POSIXct → localised month string.

Negatives default to a minus prefix; currency helpers also support style = "accounting", which wraps negatives in parentheses. Currency rendering uses a non-breaking space (⁠U+00A0⁠) between symbol and number so the pair never wraps across lines.

Usage

fmt_number(decimals = 0, locale = NULL)

fmt_brl(decimals = 2, style = c("minus", "accounting"), locale = NULL)

fmt_currency(decimals = 2, style = c("minus", "accounting"), locale = NULL)

fmt_pct(decimals = 1, scale = 100, locale = NULL, accuracy = NULL)

fmt_delta(decimals = 1, suffix = "pp", locale = NULL)

fmt_month(format = c("abbr", "full"), locale = NULL)

Arguments

decimals	Number of decimal places.
locale	Optional locale name. Defaults to the active locale.
style	"minus" (default) or "accounting" for currency.
scale	Multiplier applied to the input before rendering, for fmt_pct() only. Defaults to 100 (input is a fraction). Use scale = 1 when the input is already in percent units.
accuracy	Optional explicit accuracy passed to scales::percent(); overrides decimals if set.
suffix	Suffix for fmt_delta(). Defaults to "pp".
format	"abbr" (default) or "full" for fmt_month().

Value

A formatter function: function(x) character.

Examples

fmt_number(decimals = 1)(1234.5)
fmt_brl()(c(1000, -500))
fmt_pct(decimals = 0)(0.5)
fmt_pct(decimals = 1, scale = 1)(50)
fmt_delta()(c(1.2, -0.3, 0))
fmt_month()(as.Date("2026-08-15"))

---

Drop-in replacements for geom_col(), geom_line(), and geom_point()

Description

Three-line pass-throughs that ship consulting-grade defaults for ggplot2::geom_col() width, ggplot2::geom_line() linewidth, and ggplot2::geom_point() size. Use them when you want the defaults baked into the call site; plain geom_line() will also pick up linewidth from ct_theme() / theme_strategy() via from_theme(), and geom_point() size is autoloaded by ct_set_defaults().

Usage

ct_col(..., width = 0.8)

ct_line(..., linewidth = 0.7)

ct_point(..., size = 2.5)

Arguments

...	Forwarded to the underlying ggplot2 constructor.
width	Column width. Defaults to 0.8 (vs ggplot2's 0.9).
linewidth	Line width. Defaults to 0.7 (vs ggplot2's 0.5).
size	Point size. Defaults to 2.5 (vs ggplot2's 1.5).

Value

A ggplot2 ggplot2::layer() object.

Bar charts with Date x

ct_col()'s default width = 0.8 is in x-axis units. On a Date x-axis that is 0.8 days, which renders bars as slivers when the data is spaced quarterly or monthly. For bar charts, convert the x variable to either an ordered factor (e.g. "21Q1", "21Q2", ...) or a numeric index before plotting; line charts on Date are fine.

Examples

library(ggplot2)
d <- data.frame(g = c("A", "B", "C"), v = c(3, 5, 2))
p_col   <- ggplot(d, aes(g, v)) + ct_col()
p_line  <- ggplot(economics, aes(date, unemploy)) + ct_line()
p_point <- ggplot(mtcars, aes(wt, mpg)) + ct_point()

---

Set the active ggconsulting locale

Description

Stores the choice in options(ggconsulting.locale = ...). The active locale is read by the formatter helpers (fmt_number(), fmt_currency(), fmt_month(), etc.) when their locale argument is NULL. Defaults to "pt-BR"; "en-US" is always available.

Usage

ct_locale(locale = c("pt-BR", "en-US"))

Arguments

locale

One of "pt-BR" or "en-US".

Details

Does not touch Sys.setlocale() — that's OS-dependent and breaks on Windows CI. ggconsulting ships its own month tables and formatting marks instead.

Value

The previous locale, invisibly. Use it to round-trip: ⁠old <- ct_locale("en-US"); ...; ct_locale(old)⁠.

Examples

old <- ct_locale("en-US")
ct_locale(old)

---

Get palette colours

Description

Returns the hex colour vector for a named palette, optionally subsetting or interpolating to n colours. Called with no arguments, returns the names of all available palettes.

Usage

ct_palette(palette = NULL, n = NULL, reverse = FALSE)

Arguments

palette	Palette name (e.g. "strategy_navy") or NULL (default) to list available palette names.
n	Number of colours to return. When n is smaller than the palette, the first n colours are returned. When n is larger, colours are interpolated via grDevices::colorRampPalette() (with a warning). Defaults to NULL (return the full palette).
reverse	Reverse palette order before subsetting. Defaults to FALSE.

Value

A character vector of hex colours, or (when palette is NULL) a character vector of palette names.

Examples

# List available palettes
ct_palette()

# Full palette
ct_palette("strategy_navy")

# First 3 colours
ct_palette("strategy_navy", n = 3)

# Interpolate to 9 colours
ct_palette("strategy_navy", n = 9)

---

Preview ggconsulting palettes as a swatch

Description

Returns a ggplot showing palettes as colour tiles with the hex value overlaid in monospace. With palette = NULL, every palette shipped in .ct_palettes is shown faceted.

Usage

ct_palette_show(palette = NULL)

Arguments

palette

Palette name (e.g. "strategy_emerald"), character vector of colours, or NULL (default) to show every shipped palette.

Value

A ggplot object.

Examples

p_all  <- ct_palette_show()
p_one  <- ct_palette_show("strategy_emerald")
p_vec  <- ct_palette_show(c("#0F4D38", "#177B57", "#3DA876"))

---

Consulting colour and fill scales

Description

Discrete and continuous scales backed by ggconsulting palettes. Discrete variants interpolate (with a warning) when the data has more levels than the palette can hold. Continuous variants gradient across all palette colours via ggplot2::scale_color_gradientn() / ggplot2::scale_fill_gradientn().

British spellings (scale_colour_ct(), scale_colour_ct_c()) are provided as aliases.

Usage

scale_color_ct(palette = "strategy_navy", reverse = FALSE, ...)

scale_colour_ct(palette = "strategy_navy", reverse = FALSE, ...)

scale_fill_ct(palette = "strategy_navy", reverse = FALSE, ...)

scale_color_ct_c(palette = "strategy_navy", direction = 1, ...)

scale_colour_ct_c(palette = "strategy_navy", direction = 1, ...)

scale_fill_ct_c(palette = "strategy_navy", direction = 1, ...)

Arguments

palette	Palette name (e.g. "strategy_navy") or character vector of colours.
reverse	Reverse palette order before mapping. Defaults to FALSE.
...	Forwarded to the underlying ggplot2 scale constructor.
direction	1 (default) or -1 to reverse the continuous gradient.

Value

A ggplot2 scale.

Examples

library(ggplot2)
p_d <- ggplot(mtcars, aes(wt, mpg, colour = factor(cyl))) +
  geom_point() +
  scale_color_ct("strategy_azure")
p_c <- ggplot(faithfuld, aes(waiting, eruptions, fill = density)) +
  geom_raster() +
  scale_fill_ct_c("strategy_emerald")

---

Build a consulting-grade ggplot2 theme

Description

Flexible builder behind the archetype presets (theme_strategy() and friends). Composes ggplot2::theme_minimal() with executive-output overrides via ⁠theme_sub_*()⁠ helpers, sets the theme geom element so from_theme()-aware layers (e.g. ggplot2::geom_line()) inherit the resolved linewidth and main colour, and applies the resolved font with a fallback chain.

Usage

ct_theme(
  palette = "strategy_navy",
  font = "Inter",
  font_fallback = c("Helvetica Neue", "Arial", "sans"),
  density = c("normal", "tight", "loose"),
  context = c("presentation", "report", "screen"),
  base_size = NULL,
  main_color = NULL,
  paper = NULL
)

Arguments

palette	Palette name (e.g. "strategy_navy") or character vector of colours.
font	Preferred font family.
font_fallback	Character vector of fallback families to try if font is unavailable. The generic R families "sans", "serif", and "mono" are always recognised as terminal fallbacks.
density	One of "normal", "tight", "loose". Controls panel.spacing and axis-text margins.
context	One of "presentation", "report", "screen". Drives default base_size and plot.margin.
base_size	Base font size. If NULL, derived from context.
main_color	Routed into the theme geom element's ink slot, so unmapped geoms pick it up via from_theme(). NULL falls back to the palette's first colour. Title colour is a fixed neutral near-black (⁠#1A1A1A⁠); override with a follow-on theme() call if you want it palette-tinted.
paper	Figure ground colour. NULL (default) leaves ggplot2::theme_minimal()'s white background untouched. Otherwise one of the shortcuts "cream", "warm_grey", "white", or any colour grDevices::col2rgb() accepts. Because theme_minimal() leaves the panel background blank, filling the plot background alone gives a uniform ground with no panel-versus-plot seam. Setting paper also warms the major gridline to match it.

Value

A ggplot2::theme() object.

Examples

library(ggplot2)
p <- ggplot(mtcars, aes(wt, mpg)) +
  geom_point() +
  ct_theme()

---

FY23 to FY24 EBITDA bridge

Description

Eight-row ordered breakdown decomposing the year-over-year EBITDA change for the fictional conglomerate behind bu_quarterly into volume, price, cost, mix, FX, and one-off effects. The first and last rows are absolute levels; the six intermediate rows are signed deltas that reconcile the endpoints. Designed for waterfall charts.

Usage

ebitda_bridge

Format

A data frame with 8 rows and 3 columns:

component

Ordered factor naming the bridge step.

value_brl

R$ MM (numeric). Absolute level for endpoint rows; signed delta for intermediate rows.

type

Factor with 3 levels: "total" for endpoint rows, "increase" or "decrease" for deltas.

Source

Synthetic data generated by the ggconsulting authors. It does not describe a real company or financial result. See data-raw/ebitda_bridge.R.

Examples

ebitda_bridge

---

Test whether a font family is available

Description

Used to gate font-dependent code paths and tests, and by ct_theme() to walk its font_fallback chain.

Usage

has_font(name)

Arguments

name	Font family name, as it appears in the family column of systemfonts::system_fonts() or systemfonts::registry_fonts().

Details

Checks both font tables systemfonts maintains: families installed on the operating system (systemfonts::system_fonts()) and families registered for the current session with systemfonts::register_font() (systemfonts::registry_fonts()). Registered fonts do not appear in the system table, so checking only that one would silently reject a corporate font a user had registered from a file rather than installed.

Value

TRUE if name matches an available family, FALSE otherwise. Vectorised over name.

Examples

has_font("Arial")

# Registered fonts count as available, so a client brand font you
# register from a file can be used by name:
## Not run: 
systemfonts::register_font("ClientSans", plain = "~/fonts/ClientSans.ttf")
has_font("ClientSans")
ct_theme(font = "ClientSans")

## End(Not run)

---

Monthly B3 sector indices

Description

Monthly closing values and total monthly return for the Ibovespa (IBOV) and six B3 sector indices, covering 2020-01 through 2024-12. Snapshot frozen at 2024-12-31. Long format: one row per (sector_index, month). Suitable for theme_finance() demos and small-multiples.

Usage

ibov_sectors

Format

A data frame with ~420 rows and 4 columns:

date

First day of the month (Date).

sector_index

Factor with 7 levels: IBOV, IFNC, INDX, IMAT, IEEX, ICON, IMOB.

close

End-of-month index level (numeric).

return_m

Monthly arithmetic return, fraction (numeric); NA for the first month of each series.

Source

B3 S.A. – Brasil, Bolsa, Balcão, historical index series for the Ibovespa and B3 sector indices, fetched via the rb3 package. The snapshot ends on 2024-12-31; close and return_m are transformed or derived in this repository. B3 does not endorse this package. See data-raw/ibov_sectors.R and https://www.b3.com.br/pt_br/market-data-e-indices/indices/indices-de-segmentos-e-setoriais/.

Examples

head(ibov_sectors)

---

Install consulting fonts from Google Fonts

Description

Downloads and installs the font families used by the three archetype themes (theme_strategy(), theme_finance(), theme_editorial()). All fonts are OFL or Apache-2.0 licensed.

Usage

install_consulting_fonts(fonts = NULL, dest = NULL, quiet = FALSE)

Arguments

fonts	Character vector of family names to install, or NULL (default) for the full set: Inter, Source Sans 3, Lato, Source Serif 4, IBM Plex Sans. Validated against the known catalog.
dest	Destination directory. NULL (default) uses a platform-appropriate user font directory: ⁠~/Library/Fonts⁠ on macOS, ⁠~/.local/share/fonts⁠ on Linux, or ⁠~/AppData/Local/Microsoft/Windows/Fonts⁠ on Windows. On Windows the fonts are also registered for the current R session with systemfonts::register_font(), because files in the per-user folder are not visible to other applications until they are installed (right-click > Install).
quiet	Suppress informational messages. Errors are always emitted. Defaults to FALSE.

Details

Variable-weight families (Inter, Source Sans 3, Source Serif 4, IBM Plex Sans) are downloaded as variable .ttf files containing all weights (Light through Bold and beyond). Lato is downloaded as four static .ttf files (Regular, Bold, Italic, Light).

Value

Invisibly, a character vector of installed file paths.

Consent

Installing to the default destination writes font files into your home directory and downloads roughly 9 MB from the network. Because that is outside the R session, this function never does it silently: in an interactive session it asks for confirmation first, and in a non-interactive one it aborts. To install unattended, either pass an explicit dest or set options(ggconsulting.font_consent = TRUE). No confirmation is asked when dest is supplied, since the caller has then named the directory themselves.

Examples

## Not run: 
install_consulting_fonts()
install_consulting_fonts("Inter")

# Unattended, into a directory you choose:
install_consulting_fonts("Inter", dest = tempdir())

## End(Not run)

---

Annual market share for a fictional sector

Description

Simulated annual market share for six players (five named + Others) over ten years (2015 through 2024). Shares sum to 1 within each year. Story arc: incumbent erodes, challenger gains. Designed for slope and bump-chart demos.

Usage

market_share

Format

A data frame with 60 rows and 3 columns:

year

Calendar year (integer).

company

Factor with 6 levels: Player A, Player B, Player C, Player D, Player E, Others.

share

Market share, fraction in [0, 1] (numeric).

Source

Synthetic data generated by the ggconsulting authors. The players, sector, and shares are fictional and do not represent real market research. See data-raw/market_share.R.

Examples

head(market_share)

---

Editorial archetype theme

Description

Preset path through ct_theme() tuned for analyst notes and market commentary: serif typography ("Source Serif 4" with a Georgia / Times / serif fallback chain), a slightly larger title with tighter leading, and italic subtitles for typographic personality.

Usage

theme_editorial(main_color = NULL, ...)

Arguments

main_color	Routed into the theme geom ink slot for from_theme() linkage. NULL (default) falls back to editorial_warm[1]. Title colour is a fixed neutral near-black.
...	Forwarded to ct_theme() — e.g. density, context, base_size, or an explicit palette override.

Value

A ggplot2::theme() object.

Examples

library(ggplot2)
p <- ggplot(economics, aes(date, unemploy)) +
  geom_line() +
  theme_editorial()

---

Finance archetype theme

Description

Preset path through ct_theme() tuned for finance reports and pitch books: humanist sans typography ("Source Sans 3" with an Inter / Helvetica Neue / Arial fallback chain), no gridlines, y-axis ticks to read levels against, and denser defaults (density = "tight", context = "report") so plots read closer to a printed page than a slide.

Usage

theme_finance(main_color = NULL, density = "tight", context = "report", ...)

Arguments

main_color	Routed into the theme geom ink slot for from_theme() linkage. NULL (default) falls back to finance_classic[1]. Title colour is a fixed neutral near-black.
density	Passed to ct_theme(). Defaults to "tight" — finance reports favour denser layouts than presentation slides.
context	Passed to ct_theme(). Defaults to "report" — drives a smaller base_size and tighter plot.margin.
...	Forwarded to ct_theme() — e.g. base_size, or an explicit palette override.

Details

Sans rather than serif follows the institutional chart packs the archetype is drawn from, which set their exhibits in a humanist sans and reserve serif for body text. Pair the bare axis with ct_finish(mirror_y = TRUE) to repeat the ticks on the right edge, which is how those references let the eye track a level across a wide panel without gridlines.

Value

A ggplot2::theme() object.

Examples

library(ggplot2)
p <- ggplot(economics, aes(date, unemploy)) +
  geom_line() +
  theme_finance()

---

Strategy archetype theme

Description

Preset path through ct_theme() tuned for a minimal, generous-whitespace, navy-default look inspired by top-tier global strategy consultancies.

Usage

theme_strategy(main_color = NULL, ...)

Arguments

main_color	Routed into the theme geom ink slot so unmapped geoms pick it up via from_theme(). Defaults to strategy_navy[1]. Pass any value grDevices::col2rgb() accepts to override. Does not affect title colour (a fixed neutral near-black).
...	Forwarded to ct_theme() — e.g. density, context, base_size.

Value

A ggplot2::theme() object.

Examples

library(ggplot2)
p <- ggplot(mtcars, aes(wt, mpg)) +
  geom_point() +
  theme_strategy()

---