Package 'insperplot'

Title: Insper Themed 'ggplot2' Extensions
Description: Extends 'ggplot2' with the visual identity of Insper, a Brazilian non-profit institution for teaching and research. Provides themes, brand color palettes, discrete and continuous scales, and high-level plotting functions.
Authors: Vinicius Oike [aut, cre] (ORCID: <https://orcid.org/0009-0005-8015-9189>), Insper - Instituto de Ensino e Pesquisa [cph]
Maintainer: Vinicius Oike <[email protected]>
License: MIT + file LICENSE
Version: 0.3.1
Built: 2026-10-07 08:36:03 UTC
Source: https://github.com/inspercidades/insperplot

Help Index


Format Brazilian Numbers

Description

Formats numbers in Brazilian style, with a decimal comma and a period as the thousands separator. Also formats currency and percentages.

Usage

format_num_br(x, digits = 0, percent = FALSE, currency = FALSE, ...)

Arguments

x

Numeric vector.

digits

Number of decimal places. Default is 0.

percent

Logical. If TRUE, multiplies by 100 and adds a percent sign.

currency

Logical. If TRUE, formats as Brazilian reais (R$).

...

Additional arguments passed to scales::number().

Value

Formatted character vector.

See Also

Other utilities: has_insper_fonts(), save_insper_plot()

Examples

# Basic number formatting
format_num_br(1234.56, digits = 2)

# Currency formatting
format_num_br(1234.56, currency = TRUE, digits = 2)

# Percentage formatting
format_num_br(0.1234, percent = TRUE, digits = 1)
format_num_br(0.1234, percent = TRUE, digits = 2)

Global Fossil Fuel Consumption

Description

Primary energy consumption from fossil fuels (coal, oil, and gas) measured in terawatt-hours (TWh), for the world as a whole, from 1800 to 2023.

Usage

fossil_fuel

Format

A data frame with 228 rows and 5 variables:

entity

Character, name of the country or region (currently "World")

code

Character, country/region code (OWID_WRL for World)

year

Numeric, year of observation (1800-2023)

fuel

Ordered factor with 3 levels: Oil, Gas, Coal. Levels are ordered for logical stacking in plots

consumption

Numeric, primary energy consumption in terawatt-hours (TWh)

Details

Global fossil fuel consumption since the Industrial Revolution, split by fuel. The fuel factor is ordered Oil, Gas, Coal, which fixes the stacking order in area charts.

Source

Our World in Data (OWID) https://ourworldindata.org/grapher/global-fossil-fuel-consumption License: CC BY 4.0

See Also

insper_area for creating area plots with this data


Insper Area Plot

Description

Creates area charts of time series with Insper's visual identity. Supports single, stacked, and overlapping areas.

Usage

insper_area(
  data,
  x,
  y,
  fill = NULL,
  palette = NULL,
  stacked = NULL,
  area_alpha = 0.9,
  fill_color = get_insper_colors("turquesa_3"),
  add_line = TRUE,
  line_color = get_insper_colors("turquesa_2"),
  line_width = 0.8,
  line_alpha = 1,
  zero = FALSE,
  ...
)

Arguments

data

A data frame.

x

<data-masked> Time variable (numeric, Date, or POSIXct).

y

<data-masked> Value variable.

fill

Fill aesthetic. Accepts one of the options below.

  • A quoted color string, used as a static color (e.g., "#3ACC9F", "grey40").

  • A bare discrete column, used for grouping (e.g., category).

  • A bare continuous column, mapped to a gradient (e.g., intensity).

  • NULL (default), which uses Insper turquesa.

The fill color also sets the line color when add_line = TRUE.

palette

Character. Palette for mapped variables. If NULL (default), uses "main".

stacked

Logical or NULL. Whether to stack areas. If NULL (default), stacks only when fill maps a variable. See Details.

area_alpha

Numeric. Area opacity, from 0 to 1. Default is 0.9.

fill_color

Character. Area color, used only when fill is NULL. Default is turquesa_3. Prefer fill = "<color>", which colors both the area and the line.

add_line

Logical. If TRUE (default), draws a line on top of each area.

line_color

Character. Line color, used only when fill is NULL. Default is turquesa_2, a lighter step of the turquesa ramp.

line_width

Numeric. Line width. Default is 0.8.

line_alpha

Numeric. Line opacity, from 0 to 1. Default is 1.

zero

Logical. If TRUE, draws a horizontal line at y = 0. Default is FALSE.

...

Additional arguments passed to ggplot2::geom_area().

Details

Stacking

Under the default stacked = NULL, areas stack when fill maps a variable and overlap when fill is missing or a static color, where stacking would have no effect anyway. Set stacked = TRUE or stacked = FALSE to choose directly. Overlapping areas suit comparing group trajectories; stacked areas suit part-to-whole.

Line overlay

A line is drawn on top of each area by default (add_line = TRUE), in the fill color. Set add_line = FALSE to drop it, which helps when many groups are stacked.

Value

A ggplot object.

See Also

theme_insper, scale_fill_insper_d, insper_timeseries

Other plots: insper_barplot(), insper_boxplot(), insper_density(), insper_heatmap(), insper_histogram(), insper_scatterplot(), insper_timeseries(), insper_violin()

Examples

library(ggplot2)

# Single area: coal consumption since 1900
coal_data <- subset(fossil_fuel, fuel == "Coal" & year >= 1900)
insper_area(coal_data, x = year, y = consumption)

# Mapping fill to a variable stacks the areas
recent_data <- subset(fossil_fuel, year >= 1950)
recent_data$fuel <- factor(recent_data$fuel, levels = c("Oil", "Gas", "Coal"))
insper_area(recent_data, x = year, y = consumption, fill = fuel) +
  labs(
    title = "Global Fossil Fuel Consumption",
    subtitle = "Primary energy consumption by fuel type (1950-present)",
    x = "Year",
    y = "Consumption (TWh)",
    fill = "Fuel Type"
  )

# Overlapping areas, to compare trajectories
insper_area(recent_data, x = year, y = consumption,
            fill = fuel, stacked = FALSE) +
  labs(
    title = "Comparing Fuel Consumption Trends",
    subtitle = "Overlapping areas show individual trajectories",
    x = "Year",
    y = "Consumption (TWh)",
    fill = "Fuel Type"
  )

Insper Bar Plot

Description

Creates bar plots with Insper's visual identity. Supports grouped, stacked, and filled bars, value labels, and horizontal or vertical orientation.

Usage

insper_barplot(
  data,
  x,
  y,
  fill = NULL,
  position = "dodge",
  palette = "main",
  zero = TRUE,
  text = FALSE,
  text_size = 4,
  text_color = "black",
  stack_vjust = 0.5,
  label_formatter = scales::comma,
  ...
)

Arguments

data

A data frame.

x

<data-masked> Variable for the x-axis.

y

<data-masked> Variable for the y-axis.

fill

Fill aesthetic. Accepts one of the options below.

  • A bare column name, mapped to fill (e.g., fill = gear).

  • A quoted color string, used as a static fill (e.g., fill = "blue").

  • NULL (default), which uses Insper red.

A mapped variable produces grouped, stacked, or filled bars, depending on position.

position

Character. Position adjustment for bars: "dodge" (default), "stack", "fill", or "identity".

palette

Character. Palette for mapped variables. Default is "main".

zero

Logical. If TRUE (default), draws a reference line at zero.

text

Logical. If TRUE, adds value labels to the bars. Default is FALSE.

text_size

Numeric. Size of the value labels. Default is 4.

text_color

Character. Color of the value labels. Default is "black". On stacked and filled bars, the default picks white or dark text for each segment based on its fill; any other value is used as is.

stack_vjust

Numeric. Vertical position of labels within stacked and filled segments, from 0 (bottom) to 1 (top). Default is 0.5 (center).

label_formatter

Function used to format value labels. Default is scales::comma(). It must accept an accuracy argument. Filled bars ignore it and always show percentages.

...

Additional arguments passed to ggplot2::geom_col(), such as width or alpha.

Details

Orientation follows the variable types. A categorical x with a numeric y gives vertical bars; a numeric x with a categorical y gives horizontal bars. Value labels and the zero line follow the orientation.

Value

A ggplot object.

See Also

theme_insper, scale_fill_insper_d

Other plots: insper_area(), insper_boxplot(), insper_density(), insper_heatmap(), insper_histogram(), insper_scatterplot(), insper_timeseries(), insper_violin()

Examples

# Simple bar plot with default color
insper_barplot(mtcars, x = factor(cyl), y = mpg)

# With text labels showing values
insper_barplot(mtcars, x = factor(cyl), y = mpg, text = TRUE)

# Stacked bars with centered text labels
data <- data.frame(
  category = rep(c("A", "B", "C"), each = 2),
  group = rep(c("X", "Y"), 3),
  value = c(10, 15, 20, 25, 30, 35)
)
insper_barplot(data, x = category, y = value, fill = group,
               position = "stack", text = TRUE)

# Filled bars with automatic percentage formatting
insper_barplot(data, x = category, y = value, fill = group,
               position = "fill", text = TRUE)

Insper Box Plot

Description

Creates box plots with Insper's visual identity, with optional jittered points and notches.

Usage

insper_boxplot(
  data,
  x,
  y,
  fill = NULL,
  palette = "main",
  add_jitter = NULL,
  add_notch = FALSE,
  box_alpha = 0.8,
  ...
)

Arguments

data

A data frame.

x

<data-masked> Categorical variable for the x-axis.

y

<data-masked> Numeric variable for the y-axis.

fill

Fill aesthetic. Accepts one of the options below.

  • A bare column name, mapped to fill (e.g., fill = Species).

  • A quoted color string, used as a static fill (e.g., fill = "lightblue").

  • NULL (default), which uses Insper turquesa.

palette

Character. Palette for mapped variables. Default is "main".

add_jitter

Logical or NULL. If TRUE, adds jittered points. If NULL (default), adds them only when every group has fewer than 100 observations.

add_notch

Logical. If TRUE, draws notched boxes. Default is FALSE.

box_alpha

Numeric. Box opacity, from 0 to 1. Default is 0.8.

...

Additional arguments passed to ggplot2::geom_boxplot().

Value

A ggplot object.

See Also

theme_insper, scale_fill_insper_d

Other plots: insper_area(), insper_barplot(), insper_density(), insper_heatmap(), insper_histogram(), insper_scatterplot(), insper_timeseries(), insper_violin()

Examples

# Simple boxplot with default fill
insper_boxplot(iris, x = Species, y = Sepal.Length)

# Static fill color
insper_boxplot(iris, x = Species, y = Sepal.Length, fill = "#F89D49")

# Variable fill mapping
insper_boxplot(iris, x = Species, y = Sepal.Length, fill = Species)

# Boxplot without jitter
insper_boxplot(iris, x = Species, y = Sepal.Length, add_jitter = FALSE)

Insper Brand Color Reference Table

Description

A lookup table with one row per official Insper brand color. It covers the primary colors, the six secondary hue families (five steps each), the neutral gray ramp and dark blue used in segment-specific applications, and the four Insper Cidades colors.

Usage

insper_color_reference

Format

A data frame with 43 rows and 8 variables:

hierarquia

Character, color hierarchy: "Principais" (Vermelho, Branco, Preto), "Secundários" (Turquesa, Verde, Amarelo, Laranja, Rosa, Roxo), "Neutros" (Cinza, Azul), or "Cidades" (the Insper Cidades sub-brand: Folhagem, Solar, Asfalto, Tijolo)

familia

Character, hue family (e.g. "Vermelho", "Verde", "Cinza")

nome

Character, lowercase identifier for the specific swatch (e.g. "vermelho", "verde 0"..."verde 4"). Matches the ⁠_N⁠ suffix used internally in data-raw/colors_palettes.R, where ⁠_0⁠ is the family base and ⁠_1⁠/⁠_2⁠ are tints, ⁠_3⁠/⁠_4⁠ are shades

amostra

Character, hex code of the swatch (mirrors hex); in the companion data-raw/insper_color_reference.xlsx this column is rendered as a color-filled cell instead

pantone

Character, Pantone spot color reference, or "-" when the brand guide does not specify one (Branco, Preto, and all four Cidades colors, since the Cidades manual gives CMYK only)

rgb

Character, "R, G, B" digital color values as printed in the brand guide

hex

Character, hexadecimal color code, uppercase with leading "#"

acessibilidade

Character, which text/logo color the brand guide permits on this background: "branco" (white only), "preto" (black only), or "ambos" (both pass). The guide only rules on the family base colors and neutrals; tints/shades are NA, as are the Cidades colors (that manual has no accessibility page). This column records what a brand guide rules, not what the package computes

Details

Values are transcribed from Insper's 2026 brand guide (data-raw/refs/insper-guia-de-marca.pdf) via data-raw/colors_palettes.R, the package's authoritative source for brand hex codes. The "Neutros" rows (Cinza ramp and Azul) come from the guide's segment-specific pages (Pós-Graduação, Educação Executiva) rather than its main "2.1 Cores" section.

The "Cidades" rows come from a second document, the Insper Cidades application manual (⁠data-raw/refs/Manual de Aplicação - Insper Cidades.pdf⁠, June 2026). Those four colors belong to the Centro de Estudos das Cidades / Laboratório Arq.Futuro sub-brand and are close enough to the institutional hues that the two families should not be mixed in one chart. See insper_palette() for details.

The acessibilidade column condenses the guide's accessibility and logo-background pages (white/black text contrast per background). Plot functions that draw labels on colored bars pick the text color from the fill's luminance instead.

This dataset is a reference aid. To use brand colors in plots, call insper_palette() or the ⁠scale_*_insper_*()⁠ functions.

Source

Insper brand guide (2026) and the Insper Cidades application manual (June 2026), via data-raw/create_color_reference_table.R

See Also

insper_palette for programmatic palette access; show_insper_palettes to preview palettes

Examples

head(insper_color_reference)

# All swatches in the "Verde" family
subset(insper_color_reference, familia == "Verde")

Insper Density Plot

Description

Creates density plots with Insper's visual identity. Supports grouped densities, with one color per group.

Usage

insper_density(
  data,
  x,
  fill = NULL,
  palette = NULL,
  fill_color = get_insper_colors("turquesa_3"),
  line_color = get_insper_colors("turquesa_2"),
  alpha = 0.6,
  bw = "nrd0",
  adjust = 1,
  kernel = "gaussian",
  ...
)

Arguments

data

A data frame.

x

<data-masked> Numeric variable for the x-axis.

fill

Fill aesthetic. Accepts one of the options below.

  • A quoted color string, used as a static color (e.g., "purple", "#9148B0").

  • A bare discrete column or factor expression, used for grouping (e.g., Species or factor(gear)).

  • NULL (default), which uses Insper turquesa.

The fill color also sets the density line color.

palette

Character. Palette for mapped variables. If NULL (default), uses "main".

fill_color

Character. Area color, used only when fill is NULL. Default is turquesa_3. Prefer fill = "<color>", which colors both the area and the line.

line_color

Character. Line color, used only when fill is NULL. Default is turquesa_2, a lighter step of the turquesa ramp.

alpha

Numeric. Area opacity, from 0 to 1. Default is 0.6.

bw

Numeric or character. Bandwidth, either a number or the name of a bandwidth selector ("nrd0", "nrd", "ucv", "bcv", "SJ"). Default is "nrd0".

adjust

Numeric. Multiplier applied to the bandwidth. Default is 1.

kernel

Character. Smoothing kernel. Default is "gaussian".

...

Additional arguments passed to ggplot2::geom_density().

Value

A ggplot object.

See Also

theme_insper, insper_histogram

Other plots: insper_area(), insper_barplot(), insper_boxplot(), insper_heatmap(), insper_histogram(), insper_scatterplot(), insper_timeseries(), insper_violin()

Examples

# Simple density plot (default turquesa)
insper_density(macro_series, x = ipca)

# Static color
insper_density(macro_series, x = ipca, fill = "purple")

# Grouped density plot (discrete variable)
insper_density(iris, x = Sepal.Length, fill = Species)

Insper Heatmap

Description

Creates heatmaps, such as correlation matrices, with Insper's visual identity. Accepts either a matrix or a data frame in long format.

Usage

insper_heatmap(
  data,
  show_values = FALSE,
  value_color = "white",
  value_size = 3,
  palette = "vermelho_turquesa",
  ...
)

Arguments

data

A matrix (for example, from cor()) or a long data frame with columns Var1, Var2, and value.

show_values

Logical. If TRUE, prints values on the tiles. Default is FALSE.

value_color

Character. Color of the printed values. Default is "white".

value_size

Numeric. Size of the printed values. Default is 3.

palette

Character. Palette for the continuous fill scale. Default is "vermelho_turquesa".

...

Additional arguments passed to ggplot2::geom_tile().

Value

A ggplot object.

See Also

theme_insper, scale_fill_insper_c

Other plots: insper_area(), insper_barplot(), insper_boxplot(), insper_density(), insper_histogram(), insper_scatterplot(), insper_timeseries(), insper_violin()

Examples

# From a correlation matrix
cor_mat <- cor(mtcars[, 1:4])
insper_heatmap(cor_mat)

# Print values on the tiles
insper_heatmap(cor_mat, show_values = TRUE)

# Another diverging palette
insper_heatmap(cor_mat, palette = "roxo_verde")

Insper Histogram

Description

Creates histograms with Insper's visual identity. The number of bins comes from the Sturges, Freedman-Diaconis, or Scott rule, or from a count you supply.

Usage

insper_histogram(
  data,
  x,
  fill = NULL,
  palette = NULL,
  bins = NULL,
  bin_method = c("sturges", "fd", "scott", "manual"),
  border_color = "white",
  zero = TRUE,
  ...
)

Arguments

data

A data frame.

x

<data-masked> Numeric variable for the x-axis.

fill

Fill aesthetic. Accepts one of the options below.

  • A quoted color string, used as a static fill (e.g., "blue", "#FF0000").

  • A bare discrete column or factor expression, used for grouping (e.g., Species or factor(cyl)).

  • NULL (default), which uses Insper red.

palette

Character. Palette for mapped variables. If NULL (default), uses "main".

bins

Numeric. Number of bins. Used only when bin_method = "manual".

bin_method

Character. Bin selection method: "sturges" (default), "fd" (Freedman-Diaconis), "scott", or "manual".

border_color

Character. Color of the bar borders. Default is "white".

zero

Logical. If TRUE (default), draws a horizontal line at y = 0.

...

Additional arguments passed to ggplot2::geom_histogram().

Details

The four bin selection methods are described below.

  • Sturges: k=⌈log⁡2(n)+1⌉k = \lceil \log_2(n) + 1 \rceil. Assumes roughly normal data and tends to undersmooth large samples.

  • Freedman-Diaconis: Derives bin width from the IQR, so outliers move it less than the other two.

  • Scott: Derives bin width from the standard deviation, assuming roughly normal data.

  • Manual: Uses the bin count given in bins.

Value

A ggplot object.

See Also

theme_insper, insper_density

Other plots: insper_area(), insper_barplot(), insper_boxplot(), insper_density(), insper_heatmap(), insper_scatterplot(), insper_timeseries(), insper_violin()

Examples

# Simple histogram with Sturges method
insper_histogram(mtcars, x = mpg)

# Using Freedman-Diaconis method
insper_histogram(mtcars, x = mpg, bin_method = "fd")

# Manual bin specification
insper_histogram(mtcars, x = mpg, bin_method = "manual", bins = 15)

Get an Insper Color Palette

Description

Returns a named character vector of hex color codes from an Insper palette. When printed interactively, displays a visual color swatch. The result behaves as a plain character vector and can be used directly anywhere colors are accepted.

Usage

insper_palette(palette = "main", n = NULL, reverse = FALSE)

Arguments

palette

Character. Palette name. Use show_insper_palettes to see all options.

n

Integer or NULL. Number of colors to return. If NULL (default), returns all colors in the palette. If n exceeds the palette size, colors are interpolated smoothly using colorRampPalette.

reverse

Logical. If TRUE, reverses the color order. Default FALSE.

Details

Available palettes by type:

  • Qualitative: main, muted, colorblind, cidades

  • Sequential: vermelho, turquesa, verde, amarelo, laranja, rosa, roxo, cinza, azul, cidades_folhagem, cidades_solar, cidades_asfalto, cidades_tijolo

  • Diverging: vermelho_turquesa (default for diverging data), roxo_verde, laranja_roxo, rosa_verde, cidades_folhagem_asfalto, cidades_folhagem_tijolo

Value

An object of class insper_palette (a named character vector of hex codes). Printing displays a visual swatch. Use as.character() to strip the class if needed.

Insper Cidades

Palettes prefixed cidades belong to the Insper Cidades sub-brand (Centro de Estudos das Cidades / Laboratório Arq.Futuro) and are built from its own application manual rather than the institutional brand kit. They are opt-in: nothing in the package defaults to them.

Do not mix them with the institutional palettes in one chart. The two families sit close together in CIELAB: asfalto is only 6.6 dE from roxo, and solar 8.8 dE from laranja. A chart drawing from both reads as a rendering error rather than a design choice, so pick one family per chart.

The Cidades manual ships no tints or shades, so the four cidades_* sequential ramps are derived: seven steps each, with the official color pinned at position 4. For diverging data prefer cidades_folhagem_asfalto, which has the widest colorblind separation of any diverging palette in the package; cidades_folhagem_tijolo is more symmetric in lightness (so it reads better in grayscale) but pairs green against orange-red, which is hard under red-green color vision deficiency.

All palettes are built from the 2026 Insper brand kit except "colorblind", which is the Okabe-Ito set (https://jfly.uni-koeln.de/color/) and contains no Insper tokens. It is bundled as an accessibility fallback for when colorblind readers cannot tell the brand hues in "main" apart. "main" mixes red, green, orange and yellow, a difficult combination under the common forms of color vision deficiency. Use "main" for on-brand work and reach for "colorblind" when distinguishability matters more than brand fidelity.

See Also

show_insper_palettes, scale_color_insper_d, scale_color_insper_c

Other colors: show_insper_palettes()

Examples

# Get all colors from a palette
insper_palette("main")

# Subset to n colors
insper_palette("vermelho", n = 3)

# Reverse order
insper_palette("vermelho_turquesa", reverse = TRUE)

# Use directly in a plot
library(ggplot2)
ggplot(mtcars, aes(wt, mpg)) +
  geom_point(color = insper_palette("vermelho", n = 1))

# Use in manual scales
ggplot(iris, aes(Sepal.Length, Sepal.Width, color = Species)) +
  geom_point() +
  scale_color_manual(values = insper_palette("main", n = 3))

Insper Scatter Plot

Description

Creates scatter plots with Insper's visual identity, with an optional fitted line. Accepts both color and fill aesthetics, so outlined point shapes can carry two mappings.

Usage

insper_scatterplot(
  data,
  x,
  y,
  color = NULL,
  fill = NULL,
  palette = "main",
  add_smooth = FALSE,
  smooth_method = "lm",
  point_size = 2,
  point_alpha = 1,
  ...
)

Arguments

data

A data frame.

x

<data-masked> Variable for the x-axis.

y

<data-masked> Variable for the y-axis.

color

Color aesthetic. Accepts one of the options below.

  • A bare column name, mapped to color (e.g., color = Species).

  • A quoted color string, used as a static color (e.g., color = "blue").

  • NULL (default), which uses Insper turquesa.

A mapped variable gets a discrete or continuous Insper scale to match its type.

fill

Fill aesthetic, for outlined shapes 21 to 25. Accepts one of the options below.

  • A bare column name, mapped to fill (e.g., fill = Species).

  • A quoted color string, used as a static fill (e.g., fill = "lightblue").

  • NULL (default), for no fill.

palette

Character. Palette for mapped variables. Default is "main".

add_smooth

Logical. If TRUE, adds a fitted line with a confidence band. Default is FALSE.

smooth_method

Character. Smoothing method: "lm" (default), "loess", "gam", or "glm".

point_size

Numeric. Point size. Default is 2.

point_alpha

Numeric. Point opacity, from 0 to 1. Default is 1.

...

Additional arguments passed to ggplot2::geom_point(), such as shape or stroke.

Details

Solid shapes (16 to 20) use only color. Outlined shapes (21 to 25) use color for the outline and fill for the interior, so you can map a different variable, or a static color, to each.

Value

A ggplot object.

See Also

theme_insper, scale_color_insper_d, scale_fill_insper_d

Other plots: insper_area(), insper_barplot(), insper_boxplot(), insper_density(), insper_heatmap(), insper_histogram(), insper_timeseries(), insper_violin()

Examples

# Simple scatter plot with default color
insper_scatterplot(mtcars, x = wt, y = mpg)

# Discrete variable mapping
insper_scatterplot(mtcars, x = wt, y = mpg, color = factor(cyl))

# With smooth line
insper_scatterplot(mtcars, x = wt, y = mpg, add_smooth = TRUE)

# Extra arguments go to geom_point()
insper_scatterplot(mtcars, x = wt, y = mpg, size = 3, alpha = 0.5)

# Shape 21 with static color and mapped fill
insper_scatterplot(mtcars, x = wt, y = mpg,
                   color = "white",
                   fill = factor(cyl),
                   shape = 21)

Insper Time Series Plot

Description

Creates line plots of time series with Insper's visual identity. Handles Date and POSIXct x-axes and both discrete and continuous color mappings.

Usage

insper_timeseries(
  data,
  x,
  y,
  color = NULL,
  palette = "main",
  line_width = 0.8,
  add_points = FALSE,
  ...
)

Arguments

data

A data frame.

x

<data-masked> Time variable (numeric, Date, or POSIXct).

y

<data-masked> Value variable.

color

Color aesthetic. Accepts one of the options below.

  • A bare column name, mapped to color, one line per group (e.g., color = category).

  • A quoted color string, used as a static color (e.g., color = "blue").

  • NULL (default), which uses Insper turquesa.

A mapped variable gets a discrete or continuous Insper scale to match its type.

palette

Character. Palette for mapped variables. Default is "main".

line_width

Numeric. Line width. Default is 0.8.

add_points

Logical. If TRUE, adds points on the lines. Default is FALSE.

...

Additional arguments passed to ggplot2::geom_line(), such as linetype or alpha.

Value

A ggplot object.

See Also

theme_insper, scale_color_insper_d

Other plots: insper_area(), insper_barplot(), insper_boxplot(), insper_density(), insper_heatmap(), insper_histogram(), insper_scatterplot(), insper_violin()

Examples

library(ggplot2)

# Plot inflation over time
insper_timeseries(macro_series, x = date, y = ipca)

# A quoted color string sets a static line color
insper_timeseries(macro_series, x = date, y = ipca, color = "#3ACC9F")

# Grouped time series (discrete variable)
recent_data <- subset(fossil_fuel, year >= 1920)
insper_timeseries(recent_data, x = year, y = consumption, color = fuel)

Insper Violin Plot

Description

Creates violin plots with Insper's visual identity, with optional boxplot and jittered-point overlays.

Usage

insper_violin(
  data,
  x,
  y,
  fill = NULL,
  palette = "main",
  show_boxplot = FALSE,
  show_points = FALSE,
  violin_alpha = 0.7,
  ...
)

Arguments

data

A data frame.

x

<data-masked> Categorical variable for the x-axis.

y

<data-masked> Numeric variable for the y-axis.

fill

Fill aesthetic. Accepts one of the options below.

  • A bare column name, mapped to fill (e.g., fill = Species).

  • A quoted color string, used as a static fill (e.g., fill = "purple").

  • NULL (default), which uses Insper turquesa.

palette

Character. Palette for mapped variables. Default is "main".

show_boxplot

Logical. If TRUE, overlays a boxplot. Default is FALSE.

show_points

Logical. If TRUE, adds jittered points. Default is FALSE.

violin_alpha

Numeric. Violin opacity, from 0 to 1. Default is 0.7.

...

Additional arguments passed to ggplot2::geom_violin().

Value

A ggplot object.

See Also

theme_insper, scale_fill_insper_d, insper_boxplot

Other plots: insper_area(), insper_barplot(), insper_boxplot(), insper_density(), insper_heatmap(), insper_histogram(), insper_scatterplot(), insper_timeseries()

Examples

# Simple violin plot with default fill
insper_violin(iris, x = Species, y = Sepal.Length)

# Static fill color
insper_violin(iris, x = Species, y = Sepal.Length, fill = "#E50505")

# Variable fill mapping
insper_violin(iris, x = Species, y = Sepal.Length, fill = Species)

# Another palette
insper_violin(iris, x = Species, y = Sepal.Length, fill = Species, palette = "muted")

# With boxplot overlay and points
insper_violin(iris, x = Species, y = Sepal.Length,
              show_boxplot = TRUE, show_points = TRUE)

Brazilian Macroeconomic Time Series

Description

Monthly macroeconomic indicators from the Brazilian Central Bank (Banco Central do Brasil), covering economic activity, inflation, industrial production, and oil production from January 2003 onward.

Usage

macro_series

Format

A data frame with 279 rows and 5 variables:

date

Date, first day of the month (YYYY-MM-DD)

ibcbr_dessaz

IBC-Br dessazonalizado (Seasonally adjusted Central Bank Economic Activity Index). Monthly economic activity indicator that serves as a proxy for GDP, base 2002 = 100

ipca

IPCA - Índice de Preços ao Consumidor Amplo (Broad Consumer Price Index). Monthly inflation rate in percent, official inflation measure used for monetary policy targeting

ipi

IPI - Índice de Produção Industrial (Industrial Production Index). Measures monthly industrial production, base 2012 = 100

oil

Produção de petróleo bruto (Crude oil production). Monthly crude oil production in thousands of barrels per day

Details

The Brazilian Central Bank publishes these indicators through its Time Series Management System (SGS), under the codes below.

  • IPCA: 433

  • IPI: 21859

  • Oil production: 1389

  • IBC-Br (seasonally adjusted): 24364

Source

Brazilian Central Bank (Banco Central do Brasil) https://www3.bcb.gov.br/sgspub/

Examples

library(ggplot2)

# Plot inflation over time using insper_timeseries
recent_data <- subset(macro_series, date >= as.Date("2020-01-01"))
insper_timeseries(recent_data, x = date, y = ipca) +
  labs(
    title = "Brazilian Inflation (IPCA)",
    subtitle = "Monthly rate in percent (2020-present)",
    y = "IPCA (%)"
  )

Brazilian Macroeconomic Time Series (Long Format)

Description

Long-format version of the macro_series dataset, with one row per indicator per date. Faceted and grouped plots take this shape directly.

Usage

macro_series_long

Format

A data frame with 1,116 rows and 3 variables:

date

Date, first day of the month (YYYY-MM-DD)

name_series

Character, name of the macroeconomic indicator. Values: "ibcbr_dessaz", "ipca", "ipi", "oil"

value

Numeric, value of the indicator on that date

Details

Pivoting macro_series from wide to long produces this table. The values are the same. See macro_series for what each indicator measures and where it comes from.

Source

Brazilian Central Bank (Banco Central do Brasil) https://www3.bcb.gov.br/sgspub/

See Also

macro_series for the wide-format version


Recife Bus Lines Data

Description

Data on bus lines in the Greater Recife metropolitan region from Insper's Observatório Nacional de Mobilidade Sustentável (National Observatory of Sustainable Mobility).

Usage

rec_buslines

Format

A data frame with 694 rows and 4 variables:

abbrev_company

Character, abbreviated name of the bus company (e.g., "BOA" for Borborema Imperial Transportes)

code_line

Character, unique code identifier for the bus line

name_company

Character, full name of the bus company operating the line

name_line

Character, name and route description of the bus line, typically showing origin and destination points

Details

Reference table of bus lines and their operating companies. It shares the code_line column with rec_passengers. Note that code_line repeats across rows here, since a line can appear under more than one company.

Source

Insper - Observatório Nacional de Mobilidade Sustentável https://dataverse.datascience.insper.edu.br DOI: 10.60873/FK2/TLFP8L

See Also

rec_passengers for related passenger transport data


Recife Bus Passengers Data

Description

Daily passenger count data for buses in the Greater Recife metropolitan region from Insper's Observatório Nacional de Mobilidade Sustentável (National Observatory of Sustainable Mobility).

Usage

rec_passengers

Format

A data frame with 237,852 rows and 6 variables:

abbrev_company

Character, abbreviated name of the bus company

name_company

Character, full name of the bus company

code_line

Character, unique code identifier for the bus line

name_line

Character, name and route description of the bus line

date

Date, daily observation date (YYYY-MM-DD), from January 2024 to March 2025

passengers

Numeric, total number of passengers transported on that date for the specific line

Details

One row per bus line per day, running from January 2024 to March 2025. The company and route columns repeat the values in rec_buslines, which shares the code_line column.

Source

Insper - Observatório Nacional de Mobilidade Sustentável https://dataverse.datascience.insper.edu.br DOI: 10.60873/FK2/JEYM0J

See Also

rec_buslines for bus line reference data


Save Insper Plot

Description

Wraps ggplot2::ggsave() with defaults for Insper-branded output: dimensions in centimeters, a golden-ratio aspect, and the ragg device for PNG files.

Usage

save_insper_plot(
  plot,
  filename,
  asp_ratio = 1.618,
  width = height * asp_ratio,
  height = 8,
  dpi = 300,
  device = NULL,
  unit = "cm",
  ...
)

Arguments

plot

A ggplot object.

filename

File name.

asp_ratio

Aspect ratio (width / height). Default is the golden ratio (1.618). Used only when width is not supplied.

width

Plot width, in unit. Derived from height and asp_ratio when not supplied.

height

Plot height, in unit. Default is 8.

dpi

Resolution in dots per inch. Default is 300.

device

Graphics device. If NULL (default), uses ragg::agg_png() for PNG files when ragg is installed, and the ggplot2 default otherwise. Pass a device function to override.

unit

Units for width and height, passed to ggplot2::ggsave(). Default is "cm".

...

Additional arguments passed to ggplot2::ggsave().

Value

The file path of the saved plot (invisibly), as returned by ggplot2::ggsave().

See Also

ggplot2::ggsave()

Other utilities: format_num_br(), has_insper_fonts()

Examples

## Not run: 
p <- ggplot2::ggplot(mtcars, ggplot2::aes(wt, mpg)) +
  ggplot2::geom_point() +
  theme_insper()
save_insper_plot(p, tempfile(fileext = ".png"))

## End(Not run)

Insper Continuous Color and Fill Scales

Description

Continuous ggplot2 scales that map numeric values to a gradient built from an Insper palette. Use them for numeric variables; for categorical variables, see scale_color_insper_d().

Usage

scale_color_insper_c(palette = "turquesa", reverse = FALSE, ...)

scale_colour_insper_c(palette = "turquesa", reverse = FALSE, ...)

scale_fill_insper_c(palette = "turquesa", reverse = FALSE, ...)

Arguments

palette

Character. Palette name. Default is "turquesa". Sequential palettes suit ordered magnitudes, and diverging palettes (such as "vermelho_turquesa") suit data with a meaningful midpoint. See show_insper_palettes() for all options.

reverse

Logical. If TRUE, reverses the gradient. Default is FALSE.

...

Additional arguments passed to ggplot2::scale_color_gradientn() or ggplot2::scale_fill_gradientn(), such as name, limits, or labels.

Value

A ggplot2 scale object.

See Also

insper_palette(), theme_insper(), scale_color_insper_d()

Other scales: scale_color_insper_d()

Examples

library(ggplot2)
ggplot(mtcars, aes(x = wt, y = mpg, color = hp)) +
  geom_point() +
  scale_color_insper_c(palette = "turquesa")

# Diverging palette for values around a midpoint
ggplot(faithfuld, aes(waiting, eruptions, fill = density)) +
  geom_raster() +
  scale_fill_insper_c(palette = "vermelho_turquesa")

Insper Discrete Color and Fill Scales

Description

Discrete ggplot2 scales that map categories to colors from an Insper palette. Levels take colors in palette order, so the brand colors appear exactly as defined. Use them for categorical variables; for numeric variables, see scale_color_insper_c().

Usage

scale_color_insper_d(palette = "main", reverse = FALSE, ...)

scale_colour_insper_d(palette = "main", reverse = FALSE, ...)

scale_fill_insper_d(palette = "main", reverse = FALSE, ...)

Arguments

palette

Character. Palette name. Default is "main". Qualitative palettes ("main", "muted", "colorblind", "cidades") suit most categorical data. See show_insper_palettes() for all options.

reverse

Logical. If TRUE, reverses the palette order. Default is FALSE.

...

Additional arguments passed to ggplot2::discrete_scale(), such as name or labels.

Value

A ggplot2 scale object.

See Also

insper_palette(), theme_insper(), scale_color_insper_c()

Other scales: scale_color_insper_c()

Examples

library(ggplot2)
ggplot(mtcars, aes(x = wt, y = mpg, color = factor(cyl))) +
  geom_point() +
  scale_color_insper_d()

ggplot(mtcars, aes(x = factor(cyl), fill = factor(gear))) +
  geom_bar() +
  scale_fill_insper_d(palette = "muted", name = "Gears")

Show All Insper Color Palettes

Description

Displays all Insper palettes as a stacked swatch grid, optionally filtered by type. Invisibly returns a data frame of palette metadata.

Usage

show_insper_palettes(type = c("all", "sequential", "diverging", "qualitative"))

Arguments

type

Character. Filter by palette type. One of "all", "sequential", "diverging", or "qualitative". Default "all".

Value

Invisibly returns a data frame with columns name, type, n_colors, and recommended_use.

See Also

insper_palette, scale_color_insper_d

Other colors: insper_palette()

Examples

# Show all palettes
show_insper_palettes()

# Show only sequential palettes
show_insper_palettes("sequential")

# Capture metadata
meta <- show_insper_palettes()

São Paulo Metro Line 4 Station Data

Description

Monthly passenger entry data for stations on Line 4 (Yellow Line) of the São Paulo Metro system.

Usage

spo_metro

Format

A data frame with 817 rows and 4 variables:

date

Date, monthly observations (YYYY-MM-DD)

year

Year as numeric

name_station

Character, name of the metro station. Covers the eleven stations on Line 4, from São Paulo - Morumbi to Luz

value

Numeric, number of passenger entries at the station on that date

Details

Line 4 (Yellow Line) runs from the western neighborhoods of São Paulo to the city center, passing Paulista Avenue. Monthly entries run from January 2018 to July 2024, a window that covers the pandemic drop and the recovery after it.

Source

São Paulo Metro Company (Companhia do Metropolitano de São Paulo)


Insper Custom ggplot2 Theme

Description

A ggplot2 theme built on Insper's brand colors and typography, with arguments for grid lines, borders, and title alignment.

Usage

theme_insper(
  base_size = 12,
  font_title = "Georgia",
  font_text = "Inter",
  grid = TRUE,
  border = "none",
  align = "panel",
  ...
)

Arguments

base_size

Numeric. Base font size in points. Default is 12. All other text sizes are relative to this value.

font_title

Character. Font family for the plot title. Default is "Georgia", the substitute for Insper's proprietary GT Ultra. Falls back to the system "serif" family if Georgia is unavailable.

font_text

Character. Font family for all other text (subtitle, axis labels, legend, caption). Default is "Inter", which ships with the package. Falls back to "Arial", then to the system "sans" family.

grid

Logical. If TRUE (default), draws light gray major grid lines. If FALSE, removes all grid lines. Minor grid lines are always removed.

border

Character. Plot border style, one of the options below.

  • "none" (default): no border or axis lines.

  • "half": axis lines with ticks, but no full border.

  • "closed": a full rectangle around the panel.

align

Character. Alignment of the title, subtitle, and caption, one of the options below.

  • "panel" (default): align to the plot panel.

  • "plot": align to the whole plot, including margins.

...

Additional arguments passed to ggplot2::theme_minimal().

Details

The theme sets a white plot background, places a horizontal legend at the top with a bold title, removes minor grid lines, and draws remaining elements in Insper brand grays.

Fonts

Titles use Georgia and all other text uses Inter. Inter is bundled with the package and registered automatically on load. Georgia is a system font that stands in for Insper's proprietary GT Ultra. If Georgia is missing, titles fall back to the system "serif" family; if Inter is missing, text falls back to Arial and then to the system "sans" family.

Value

A ggplot2 theme object, added to a plot with +.

See Also

ggplot2::theme_minimal(), ggplot2::theme()

Other themes: theme_insper_doc()

Examples

library(ggplot2)

# Default
ggplot(mtcars, aes(x = wt, y = mpg)) +
  geom_point() +
  theme_insper()

# No grid lines
ggplot(mtcars, aes(x = wt, y = mpg)) +
  geom_point() +
  theme_insper(grid = FALSE)

# Larger text for slides
ggplot(mtcars, aes(x = wt, y = mpg)) +
  geom_point() +
  theme_insper(base_size = 16, grid = FALSE)

# Closed border and smaller text for print
ggplot(mtcars, aes(x = wt, y = mpg)) +
  geom_point() +
  theme_insper(base_size = 11, border = "closed")

Insper Theme for Word and Print Documents

Description

A variant of theme_insper() with smaller text, sized for figures inserted into Word documents and other print reports. A typical document figure is about 15 cm (6 in) wide. At that size, the default 12 pt base of theme_insper() renders larger than the surrounding body text, so this variant lowers the base to 10 pt.

Usage

theme_insper_doc(base_size = 10, ...)

Arguments

base_size

Numeric. Base font size in points. Default is 10. All other text sizes are relative to this value.

...

Additional arguments passed to theme_insper(), such as grid, border, or align.

Value

A ggplot2 theme object, added to a plot with +.

See Also

theme_insper()

Other themes: theme_insper()

Examples

library(ggplot2)

p <- ggplot(mtcars, aes(x = wt, y = mpg)) +
  geom_point() +
  labs(title = "Fuel efficiency", x = "Weight (1000 lbs)", y = "MPG")

# Smaller text for a figure destined for a Word document
p + theme_insper_doc()

## Not run: 
# Save at document width and insert into Word without rescaling
save_insper_plot(p + theme_insper_doc(), "figure.png", width = 15)

## End(Not run)