Visualization on Posit Open Source

Recreating Septa Transit Timetables in Python

Michael Chow — Thu, 12 Mar 2026 00:00:00 +0000

Recently, Rich and I were poking around transit data, and we were struck by the amount of structuring that goes into transit timetables.

For example, consider this weekend rail schedule table from SEPTA, Philadelphia’s transit agency.

Notice these big pieces:

The vertical text on the left indicating trains are traveling “TO CENTER CITY”.
The blue header, and spanner columns (“Services” and “Train Number”) grouping related columns.
The striped background for easier reading. Also the black background indicating stations in Center City (the urban core).

Tables like this often have to be created in tools like Illustrator, and updated by hand. At the same time, when agencies automate table creation, they often sacrifice a lot of the assistive features and helpful affordances of the table.

We set out to recreate this table in Great Tables (and by we I mean 99% Rich). In this post, I’ll walk quickly through how we recreated it, and share some other examples of transit timetables in the wild. For the theory behind why tables like this are useful, see The Design Philosophy of Great Tables .

The final result

Here’s a look at our quick version in Great Tables. In this post we’ll walk through quickly how we created it, but wanted to treat you to the final result up front! Note that the table is fully in HTML for accessibility.

Code

ggplot2 styling

Teun Van den Brand — Wed, 01 Oct 2025 00:00:00 +0000

5x height * [ ] [`hugodown::use_tidy_thumbnails()`](https://rdrr.io/pkg/hugodown/man/use_tidy_post.html) * [ ] Add intro sentence, e.g. the standard tagline for the package * [ ] [`usethis::use_tidy_thanks()`](https://usethis.r-lib.org/reference/use_tidy_thanks.html) -->

So you want to style your plot?

Diligently, you have read, cleaned and modelled your data. You have carefully crafted a plot that lets your data speak its story. Now it is time to polish. Now it is time to let your visualisation shine.

We will set out to illuminate how to set the stylistic finishing touches on your visualisations made with the ggplot2 package. The ggplot2 package has had a recent release that included some relevant changes to styling plots. In ggplot2, the theme system is responsible for many non-data aspects of how your plot looks. It covers anything from panels, to axes, titles and legends. Here, we’ll get started with digesting important parts of the theme system. We’ll start with complete themes, get into theme elements followed by how these elements are used in various parts of the plot and finish off with some tips, including how to write your own theme functions. Before we begin discussing themes, let’s make an example plot that can showcase many aspects.

library(ggplot2)

p <- ggplot(mpg, aes(displ, hwy, colour = cty, shape = drv)) +
  geom_point() +
  facet_grid(~ year) +
  labs(
    title = "Fuel efficiency",
    subtitle = paste0("Described for ", nrow(mpg), " cars from 1999 and 2008"),
    caption = "Source: U.S. Environmental Protection Agency",
    x = "Engine Displacement",
    y = "Highway miles per gallon",
    colour = "City miles\nper gallon",
    shape = "Drive train"
  )

p

If you haven’t already accidentally triggered it, feel free to hover your mouse over the plot above. Hovering will tell you what theme element you are pointing at.

What is a theme?

In ggplot, a theme is a list of descriptions for various parts of the plot. It is where you can set the size of your titles, the colours of your panels, the thickness of your grid lines and placement of your legends.

Themes are declared using the theme() function, which populates these descriptions called ’theme elements’. Some of these elements have a predefined set of properties and can be set using the element functions, like element_text() . Other theme elements can take simpler values like strings, numbers or units.

Some pre-arranged collections of elements can be found in complete themes, like the iconic theme_gray() . These are convenient ways to quickly swap out the complete look of a plot.

Complete themes

Let’s start big and work our way through the more nitty-gritty aspects of theming plots. The most thorough way to change the styling of a single plot is to swap out the complete theme. You can do this simply by adding one of the theme_*() functions, like theme_minimal() .

p + theme_minimal()

Built-in themes

The base ggplot2 package already comes with a series of 9 built-in complete themes. For the sake of completeness about complete themes, they are displayed in the fold-out sections below. You can peruse them at your leisure to help you pick one you might like.

theme_grey() (default)

ggplot2 4.0.0

Teun Van den Brand — Thu, 11 Sep 2025 00:00:00 +0000

We’re tickled pink to announce the release of ggplot2 4.0.0. ggplot2 is a system for declaratively creating graphics, based on The Grammar of Graphics. You provide the data, tell ggplot2 how to map variables to aesthetics, what graphical primitives to use, and it takes care of the details.

The new version can be installed from CRAN using:

install.packages("ggplot2")

This is a substantial release meriting a new major version, and contains a series of changes from a rewrite of the object oriented system from S3 to S7, large new features to smaller quality of life improvements and bugfixes. It is also the 18th anniversary of ggplot2 which is cause for celebration! In this blog post, we will highlight the most salient new features that come with this release. You can see a full list of changes in the release notes

library(ggplot2)
library(patchwork)

Adopting S7

In ggplot2, we use major version increments to indicate that something at the core of the package has changed. In this release, we have replaced many of ggplot2’s S3 objects with S7 objects. Like S3 and S4, S7 is also an object oriented system that uses classes, generics and methods. S7 is a newer system that aims to strike a good balance between the flexibility of S3 and formality of S4.

Mostly, this change shouldn’t be very noticeable when you’re just using ggplot2 for building regular plots. At best, you may notice that we’re more strictly enforcing types for certain arguments. For example, most ludicrous input is now rejected right away. This is due to how properties in S7 work, which get validated when a new object is instantiated.

element_text(hjust = "foo")
#> Error:  object properties are invalid:
#> - @hjust must be , , or , not

However, it may require some adaptation on your end if you use ggplot2’s innards in unusual ways. For extension builders, a major benefit of using S7 is that one can now use double dispatch. This is most important for the update_ggplot() function (the successor of ggplot_add() ), which determines what happens when you + an object to a plot. Now with S7, you can control what happens not only for right-hand side objects (which is how it used to work in S3), but also for the left-hand side objects.

We have put various pieces of backwards compatibility in to not break many packages that assumed the S3 structures of ggplot2. For example, we still return the data property with ggplot()$data, whereas the S7 way of accessing this should be ggplot()@data. Expect these to be phased out over time in favour of S7. We are preparing another blog post to help migrating from S3 to S7 for ggplot2 related packages.

Theme improvements

Themes in ggplot2 have long served the role of capturing any non-data aspects of styling plots. We have come to realise that the default look of layers, from what the default shape of points is to what the default colour palette is, are also not truly data-driven choices. The idea to put these defaults into themes has been around for a while and Dana Page Seidel did pioneering work implementing this as early as 2018. Now, years of waiting have come to fruition and we’re proud to announce this new functionality.

Ink and paper

The way layer defaults are now implemented differs slightly from typical aesthetics you know and love. Whereas layers aesthetics distinguish colour and fill, the theme defaults distinguish ink (foreground) and paper (background). A boxplot is unreadable without colour, but is perfectly interpretable without fill. In the boxplot case, the ink is thus clearly the colour whereas paper is the fill. In bar charts or histograms, the proportional ink principle prescribes that the fill aesthetic is considered foreground, and thus count as ink. To accommodate special cases, like lines in geom_smooth() or geom_contour() , we also added a third accent option. In short, the theme defaults have role-oriented settings that differ from the property-oriented settings in layers.

We’ve added these three options to all built-in complete themes. Not only propagate these automatically to the layer defaults, they are also used to style additional theme components. You may notice that the panel background colour is a blend between paper and ink, which is now how many elements are parametrised in complete themes.

ggplot(mpg, aes(displ, hwy)) +
  geom_point() +
  geom_smooth(method = "lm", formula = y ~ x) +
  theme_gray(paper = "cornsilk", ink = "navy", accent = "tomato")

If you’re customising a theme, you can use the theme(geom) argument to set a collection of defaults. The new function element_geom() can be used to set these properties. Additionally, if you want a layer to read the property from this theme element, you can use the from_theme() function in the mapping to access these variables¹.

ggplot(mpg, aes(class, displ)) +
  geom_boxplot(aes(colour = from_theme(accent))) +
  theme(
    geom = element_geom(accent = "tomato", paper = "cornsilk")
  )

A second conceptual difference in element_geom() pertains the the use of lines. In one role, like in a line graph, the line represents the data directly. In a second role, a line serves as separation between two units. For example, you can display countries as polygons and the line connecting the vertices separate out places that are inside a country versus places that are outside that country. These two roles are captured in a linewidth and linetype pair and a borderwidth and bordertype pair.

ggplot(faithful, aes(waiting)) +
  geom_histogram(bins = 30, colour = "black") +
  geom_freqpoly(bins = 30) +
  theme(geom = element_geom(
    bordertype = "dashed",
    borderwidth = 0.2,
    linewidth = 2,
    linetype = "solid"
  ))

Scales and palettes

In addition to the defaults for layers, default palettes are now also encapsulated in the theme. The relevant theme settings have the pattern palette.{aesthetic}.{type}, where type can be either discrete or continuous. This allows you to coordinate your colour palettes with the rest of the theme.

ggplot(mpg, aes(displ, hwy, shape = drv, colour = cty)) +
  geom_point() +
  theme(
    palette.colour.continuous = c("chartreuse", "forestgreen"),
    palette.shape.discrete = c("triangle", "triangle open", "triangle down open")
  )

The way this works is that all defaults scales now have palette = NULL as their default. During plot building, any NULL palettes are replaced by those declared in the theme.

Shortcuts

We like to introduce a new family of short cuts. Looking at code in the wild, we’ve come to realise that theme declarations are very often chaotic. The theme() functions has lots of arguments, long argument names (hello there, axis.minor.ticks.length.x.bottom!) and very little structure. To make themes a little bit more digestible, we’ve created the following helper functions:

These helper functions pass on their arguments to theme() after they’ve prepended a relevant prefix. For example, using theme_sub_legend(justification) will translate to theme(legend.justification). When you have >1 theme element to change in a cluster of settings, it quickly becomes less typing to enlist the relevant shortcut. As a bonus, your theme code will tend to self-organise and become somewhat more readable.

# Tired, verbose, chaotic
theme(
  panel.widths = unit(5, "cm"),
  axis.ticks.x = element_line(colour = "red"),
  axis.ticks.length.x = unit(5, "mm"),
  panel.background = element_rect(fill = NA),
  panel.spacing.x = unit(5, "mm")
)

# Wired, terse, orderly
theme_sub_axis_x(
  ticks = element_line(colour = "red"),
  ticks.length = unit(5, "mm")
) +
theme_sub_panel(
  widths = unit(5, "cm"),
  spacing.x = unit(5, "mm"),
  background = element_rect(fill = NA)
)

In addition to shortcuts for clusters of theme elements, we’ve also added a few variants to declare margins.

margin_auto() sets the margins in a CSS-like fashion similar to the margin and padding property.
- margin_auto(1) sets all four sides at once. It expands to margin(t = 1, r = 1, b = 1, l = 1).
- margin_auto(1, 2) sets horizontal and vertical sides. It expands to margin(t = 1, r = 2, b = 1, l = 2).
- margin_auto(1, 2, 3) expands to margin(t = 1, r = 2, b = 3, l = 2).
margin_part() has NA units as default, which will get replaced when the theme gets resolved. It roughly equates to ‘set some of the sides, keep others as they are’.

merge_element(
  margin_part(r = 20), # child
  margin_auto(10) # parent
)
#> [1] 10points 20points 10points 10points

New settings

To coordinate (non-text) margins and spacings in a theme, we’ve introduced spacing and margins as new root elements in the theme. Other spacings and margins at the leaf elements inherit from (scale with) these root elements. To facilitate the different spacings in ggplot2, unit elements can now use rel() to modify the inherited value. For example the default axis.ticks.length is now rel(0.5), making the y-axis ticks 0.5 cm in the plot below. If we set the axis.ticks.length.x to rel(2), it will double the value coming from axis.ticks.length, not double the value of spacing.

p <- ggplot(penguins, aes(bill_dep, bill_len, colour = species)) +
  geom_point(na.rm = TRUE)

p + theme(
  spacing = unit(1, "cm"), 
  margins = margin_auto(1, unit = "cm"),
  axis.ticks.length.x = rel(2)
)

We also made it easier to set plot sizes. Using the panel.widths and panel.heights arguments, you can control the sizes of the panels. This mechanism is distinct from using ggsave(width, height), where the whole plot, including annotations such as axes and titles is included. There are two ways to use these arguments:

Give a vector of units: each one will be applied to a panel separately and the vector will be recycled to fit the number of panels.
Give a single unit: which sets the total panel area (including panel spacings and inner axes) to that size.

Naturally, if you only have a single panel, these approaches are identical. If you have multiple panels and you want to set individual panels all to the same size (as opposed to the total size), you can take advantage of the recycling and use a length 2 unit vector.

In the plots below, you can notice that the panels span a different width despite the units adding up to the same amount (9 cm). This is because the ‘single unit’ approach also includes the panel spacings, but not the ‘separate units’ approach.

p1 <- p + facet_grid(~ island) +
  labs(title = "Separate units (per panel)") +
  # Using the new shortcut for panels
  theme_sub_panel(
    widths = unit(c(2, 3, 4), "cm"),
    heights = unit(3, "cm")
  )

p2 <- p + facet_grid(~ island) +
  labs(title = "Single unit (all panels)") +
  theme_sub_panel(
    widths = unit(9, "cm"),
    heights = unit(3, "cm")
  )

p1 / p2

Labels

We have added new ways that a plot retrieves labels for your variables. It is an informal convention in several packages including gt, Hmisc, labelled and others to use the ’label’ attribute to store human readable labels for vectors. Now ggplot2 joins this convention and uses the ’label’ attribute as the default label for a variable if present.

# The penguins dataset was incorporated into base R 4.5
df <- penguins

# Manually set label attributes.
# Other packages may offer better tooling than this.
attr(df$species, "label") <- "Penguin Species"
attr(df$bill_dep, "label") <- "Bill depth (mm)"
attr(df$bill_len, "label") <- "Bill length (mm)"
attr(df$body_mass, "label") <- "Body mass (g)"

ggplot(df, aes(bill_dep, bill_len, colour = sqrt(body_mass))) +
  geom_point(na.rm = TRUE)

It has also been entrenched in some workflows to use a ‘data dictionary’ or codebook. For labelling purposes these dictionaries often contain column metadata that include labels or descriptions for variables (columns) in the dataset. To make it easier to work with column labels, we added the labs(dictionary) argument. It takes a named vector of labels, that can easily be generated from a data dictionary by setNames() or dplyr::pull() .

dict <- tibble::tribble(
  ~var,    ~label,
  "species",  "Penguin Species",
  "bill_dep", "Bill depth (mm)",
  "bill_len", "Bill length (mm)",
  "body_mass", "Body mass (g)"
)

ggplot(penguins, aes(bill_dep, bill_len, colour = body_mass)) +
  geom_point(na.rm = TRUE) +
  # Or:
  # labs(dictionary = dplyr::pull(dict, label, name = var))
  labs(dictionary = setNames(dict$label, dict$var))

One benefit to the label attributes or data dictionary approaches is that it is linked to your variables, not aesthetics. This means you can easily rearrange your aesthetics for a different plot, without having to painstakingly reorient the labels towards the correct aesthetics.

last_plot() +
  aes(body_mass, bill_len, colour = species)

There are a few caveats to these label attributes and data dictionary approaches though:

If the aesthetic is not a pure variable name the label is not used. You can see this in the sqrt(body_mass) in the first example, which does not use the ‘Body mass (g)’ label. We assume when a variable is adjusted in this way, this would need to be reflected in the label itself. It would therefore be inappropriate to use the label of the unadjusted variable. Use of the .data-pronoun counts as a pure variable name for labelling purposes.
Some attributes are more stable than others, and it is not ggplot2’s responsibility to babysit attributes. For example using head() will typically drop attributes from atomic columns, whereas head() will not.

In addition, we’re also allowing to use functions in all the places you can declare labels. The labs() function, scale names and guide titles now accept functions that take in the labels generated by the lower hierarchies and return amended labels. It should be spelled out that the hierarchy from lowest priority to highest priority is the following:

The expression given in aes() .
The entry in labs(dictionary).
The label attribute of the column.
The entry in labs( = ).
The scale_*(name) argument.
The guide_*(title) argument.

We can see this hierarchy in action in the plot below: the function in the axis guide transforms the input from the labs() function.

ggplot(penguins, aes(bill_dep, bill_len, colour = species)) +
  geom_point(na.rm = TRUE) +
  scale_colour_discrete(name = toupper) +
  guides(x = guide_axis(title = tools::toTitleCase)) +
  labs(
    y = \(x) paste0(x, " variable"),
    x = "the label for the x variable"
  )

In addition to the labs() -labels, we also made labelling the levels of discrete scales easier. When the scale’s breaks are named, the scale’s labels will adopt the break’s names by default. This already was the case in continuous scales but now discrete scales have parity. A nice benefit of specifying labels this way is that they are directly linked to the breaks, which prevents the common mistake of specifying the labels argument without also setting the breaks argument, which may accidentally mismatch labels.

ggplot(penguins, aes(bill_dep, bill_len, colour = species)) +
  geom_point(na.rm = TRUE) +
  scale_colour_discrete(
    breaks = c(
      "Pygoscelis adeliae"     = "Adelie",
      "Pygoscelis papua"       = "Gentoo",
      "Pygoscelis antarcticus" = "Chinstrap"
    )
  )

Discrete scales

In this release we have tried to improve the ‘freedom’ afforded by discrete position scales. Previously, discrete values were always mapped to an integer sequence starting at 1 going up to the number of levels. Instead, we wanted to allow for different mappings that deviated from that pattern. While it is a bit foreign for position scales, ggplot2 already had a mechanism to assign alternate values to the levels of a scale: palettes! You can now use the palette argument like you would for non-position scales. It makes it easier to indicate any grouping structure along the axis, like separating the orange juice (OJ) groups from the vitamin C (VC) groups in the plot below.

ggplot(ToothGrowth, aes(interaction(dose, supp, sep = "\n"), len)) +
  geom_boxplot() +
  scale_x_discrete(
    palette = scales::pal_manual(c(1:3, 5:7))
  )

A second improvement we made to the placement of discrete levels is that we give greater control over the continuous limits. The continuous limits of a discrete scale used to be an implementation detail that kept track of any ‘additional space’ layers were taking up, for example because they use a width parameter. Now, these can be declared directly, making it easier to synchronise limits across plots or even facets. In the plot below, we’re using the continuous.limits argument to ensure that all the bars have the same width; regardless of how many levels the x scale has to accommodate.

p1 <- ggplot(mpg, aes(class)) +
  geom_bar() +
  facet_wrap(~ drv, ncol = 1, scales = "free_x")

p2 <- p1 + scale_x_discrete(continuous.limits = c(1, 5))

(p1 + labs(title = "Free limits")) | 
(p2 + labs(title = "Fixed limits"))

Also absent from discrete scales was the ability to set minor breaks. Admittedly, they are less useful than minor breaks in continuous scales. In contrast to discrete (major) breaks, minor_breaks uses numeric input instead, allowing you to fine-tune placement without being bound by the scale’s levels. With a few tweaks of the theme, you can conceivably use minor breaks to visually separate levels as an alternative to the centre-lines for major breaks.

p1 <- ggplot(mpg, aes(drv, hwy, colour = factor(year))) +
  geom_point(position = "jitterdodge") +
  guides(colour = "none") +
  scale_x_discrete(
    minor_breaks = scales::breaks_width(1, offset = 0.5),
    # To show that the minor axis ticks take on these values
    guide = guide_axis(minor.ticks = TRUE)
  )

p2 <- p1 + 
  theme(panel.grid.major.x = element_blank()) +
  theme_sub_axis_bottom(ticks = element_blank(), minor.ticks = element_line())

p1 | p2

Discrete position scales now also have access to secondary axes. In contrast to continuous scales, discrete scales don’t support transformations. So instead of sec_axis() , it is recommended to use dup_axis() . To allow for arbitrary positions for dup_axis(breaks), these can take numeric values or one of the discrete levels. They are not truly useful to for showing two aligned datasets of different scales, but they can serve as annotations. For example, they can display some summary statistics about the groups.

ggplot(mpg, aes(class, cty)) +
  geom_boxplot() +
  scale_x_discrete(
    sec.axis = dup_axis(
      name = "Counts",
      # You can use numeric input for breaks
      breaks = seq_len(length(unique(mpg$class))),
      # Watch out for the order of `table()` and your levels!
      labels = paste0("n = ", table(mpg$class))
    )
  )

Position aesthetics

Layers consist of three components: stats, geoms and positions. While stats and geoms have their own aesthetics, like weight or linewidth, the position adjustments did not. In this release, positions can also declare their own aesthetics. You can map data to these aesthetics like you would for geom or stat aesthetics.

In position_nudge() for example, we now have the nudge_x and nudge_y parameters as aesthetics. ² Two benefits are that we can now use expressions in aes() to declare these and they are vectorised. We use that advantage in the plot below where we use sign() in a divergent bar chart to determine the left-right direction of the nudge.

# Taken from:
# https://ourworldindata.org/grapher/share-electricity-coal?tab=table&tableFilter=continents
coal <- tibble::tribble(
  ~continent,  ~pct_1985, ~pct_2024,
  "Africa",        53.87, 24.68,
  "Asia",          32.60, 51.19,
  "Europe",        32.84, 12.91,
  "North America", 48.93, 13.79,
  "South America",  2.91,  3.31,
  "Oceania",       58.75, 39.26
) |>
  dplyr::mutate(pp_difference = pct_2024 - pct_1985)

ggplot(coal, aes(pp_difference, continent)) +
  geom_col() +
  geom_text(
    aes(nudge_x = sign(pp_difference) * 3, 
        label = pp_difference)
  ) +
  labs(x = "Change in electricity generated by coal (pp)")

A second position adjustment that has gotten its own aesthetic is position_dodge() . In the plot below, we see for sports where we do not have records for both ‘sex = “f”’ and ‘sex = “m”’ only one box is drawn just beneath the centre line. This is true for ‘water polo’ where we have no records for ‘f’, but also netball and gymnastics where there are no records for ’m’. For sports where there are records for both sexes, the “f” is depicted beneath the centre line and “m” is depicted above the centre line. Depending on your aesthetic sensibilities, this inconsistency can be a major pain.

sports <- c("water polo", "swimming", "gymnastics", "field", "netball")
p <- ggridges::Aus_athletes |>
  dplyr::filter(sport %in% sports) |>
  ggplot(aes(height, sport, fill = sex)) +
  geom_boxplot(position = position_dodge(preserve = "single"))

p

The origin of this inconsistency is that ggplot2 doesn’t have an understanding of groups other than that they exist. It doesn’t know that groups are formed by fill and what levels populate this aesthetic. To break ggplot2’s ignorance, we now have the order aesthetic for position_dodge() .

p + aes(order = sex)

Using that aesthetic to the position adjustment soothes the soul by putting all the right groups in the right places.

Wrapping directions

The facet_wrap() function has had two arguments controlling the layout: dir which can be "h" or "v", and as.table with can be TRUE or FALSE. Together, these gave a total of 4 layout options. Arguably there are 8 sensible options in total though, so we were missing out on the layout. To simplify having to juggle two arguments for 4 options, we’re now just using one argument (dir) for 8 options. The new options are all two letter codes using combinations of t (top), r (right), b (bottom) and l (left). The combination will tell you where the first facet level will be. Both br and rb will start in the bottom-right with the first facet. Then the order will tell you about the filling direction, where starting with b will fill bottom-to-top and starting with r will fill right-to-left.

p <- ggplot(mpg, aes(displ, hwy)) +
  geom_point()

p1 <- p + 
  facet_wrap(~ vctrs::vec_group_id(class), dir = "br") +
  labs(title = "dir = 'br'")

p2 <- p +
  facet_wrap(~ vctrs::vec_group_id(class), dir = "rb") +
  labs(title = "dir = 'rb'")

p1 | p2

To cover all 8 options, we list them here:

"lt": start in the top-left, start filling left-to-right.
"tl": start in the top-left, start filling top-to-bottom.
"lb": start in the bottom-left, start filling left-to-right.
"bl": start in the bottom-left, start filling bottom-to-top.
"rt": start in the top-right, start filling right-to-left.
"tr": start in the top-right, start filling top-to-bottom.
"rb": start in the bottom-right, start filling right-to-left.
"br" start in the bottom-right, start filling bottom-to-top.

Free space in wrapping

The facet_grid(space) argument can ensure that panels are allocated space in proportion to their data range. This works because all data within a row share a y-axis, and data within a column share an x-axis. Historically, this argument did not have an equivalent in facet_wrap() because axes aren’t shared. We realised that there is a narrow circumstance in which each column has a consistent axis, and this is when there is only one row. The inverse also holds true for rows when there is only one column. In this release, we’ve added facet_wrap(space) that sets the panel sizes in these circumstances.

ggplot(penguins, aes(bill_dep, bill_len, colour = species)) +
  geom_point(na.rm = TRUE) +
  facet_wrap(~ island, scales = "free_x", space = "free_x")

We can note that the Dream and Torgersen islands have narrower panels because they don’t have the Gentoo penguin with low bill depths.

Layer layout

We’ve added the argument layer(layout), which instructs facets on how to handle the data. Generally speaking, facets or custom layouts are free to interpret instructions as they see fit, so it is not set in stone. Nonetheless, we’ve come up with the following interpretations for facet_wrap() and facet_grid() .

layout = NULL (the default) uses the faceting variables to assign data to a panel.
layout = "fixed" repeats the data for every panel and ignores faceting variables.
layout = assigns to data to a specific panel.

In addition, specifically for facet_grid() the following options also apply:

layout = "fixed_cols" pools data for every column and repeats it within the column’s panels.
layout = "fixed_rows" pools data for every row and repeats it within the row’s panels.

ggplot(penguins, aes(bill_dep, bill_len)) +
  # Repeat within every row
  geom_point(na.rm = TRUE, colour = "grey", layout = "fixed_rows") +
  # Use facetting variables (default)
  geom_point(na.rm = TRUE, layout = NULL) +
  # Pick particular panel
  annotate(
    "text", x = I(0.5), y = I(0.5),
    label = "Panel 6", layout = 6
  ) +
  facet_grid(island ~ species)

In previous incarnations of ggplot2, people went through some acrobatics to get data to repeat across panels. With these new options, this should be a walk in the park.

Styling updates

Boxplots

In geom_boxplot() , you may have become accustomed to all the different options for styling outliers like outlier.colour or outlier.shape. Now, we’re also enabling styling the different parts of the boxplot: the median line, the box, the whiskers and the staples. You can assign different colours, line type or line width to these parts of the boxplot.

ggplot(mpg, aes(class, hwy, colour = class)) +
  geom_boxplot(
    whisker.linetype = "dashed",
    box.colour = "black",
    median.linewidth = 2,
    staplewidth = 0.5, # show staple
    staple.colour = "grey50"
  ) +
  guides(colour = "none")

For consistency, geom_crossbar() has been given the same treatment, but uses the middle.* prefix where geom_boxplot() uses the median.* prefix. Because middle.linewidth and median.linewidth have taken over the role of fatten and are aligned with other graphical properties, the fatten argument is now deprecated.

Violin & quantiles

It has been an inconvenience for some time that the quantile computation in violin layers was computed on the density data rather than the input data. To make the quantile computation more faithful to the real data, we had to properly delegate the responsibilities to the correct parts of the layer. The stat part of the layer is now in charge of calculating quantiles of the input data via the stat_ydensity(quantiles) arguments. By default, the quantiles are the 25th, 50th and 75th percentiles and are always computed. Whether these quantiles are also displayed, is under the purview of the geom part of the layer. We’ve taken a similar approach as boxplots shown above, in that we now have quantile.colour, quantile.linetype and quantile.linewidth arguments to style the quantile lines. Previously, quantiles were not displayed by default. To mirror that behaviour, we’ve set quantile.linetype = 0 (blank, no line) by default. This means that to turn on the display of quantiles, you have to set a non-blank line type.

ggplot(mpg, aes(class, hwy, fill = class)) +
  geom_violin(
    quantiles = c(0.1, 0.9),
    quantile.linetype = 1
  ) +
  guides(fill = "none")

Labels

geom_label() also has new styling options. It now has a linetype and linewidth aesthetic, which can be mapped from the data. The linewidth aesthetic replaces the label.size argument, which used to determine the line width of the label border. In addition to the new aesthetics, geom_label() has two new arguments: border.colour and text.colour which set the colour for the border and text respectively. When these are set, it overrules the colour aesthetic for a part of the label. In the plot below, we fix the text.colour to black, so the colour aesthetic applies to the border, not the text.

ggplot(mtcars) +
  aes(
    wt, mpg,
    label = rownames(mtcars),
    colour = factor(cyl),
    linetype = factor(vs),
    linewidth = factor(am)
  ) +
  geom_label(text.colour = "black") +
  scale_linewidth_manual(values = c(0.3, 0.6))

Area and ribbons

Both geom_area() and geom_ribbon() now allow a varying fill aesthetic within a group. Such a fill is displayed as a gradient, and therefore requires R 4.1.0+ and a compatible graphics device.

ggplot(economics, aes(date, unemploy)) +
  geom_area(aes(fill = uempmed))

New stats

Manual

Many ggplot extensions are based on stats, which allows you to perform arbitrary computations on data before handing it off the drawing functions. The new stat_manual() aims to give you the same extension powers, but without doing the formal ritual of defining a class and constructor. You can provide it any function that both ingests and returns a data frame. It can create new aesthetics or modify pre-existing aesthetics as long as eventually the geom part of the layer has their required aesthetics. In the example below, we use stat_manual() with a geom and a function, but also show you how to use a geom with stat = "manual".

make_centroids <- function(df) {
  transform(
    df,
    xend = mean(x, na.rm = TRUE),
    yend = mean(y, na.rm = TRUE)
  )
}

make_hull <- function(df) {
  df <- df[complete.cases(df), , drop = FALSE]
  hull <- chull(df$x, df$y)
  df[hull, , drop = FALSE]
}

ggplot(penguins, aes(bill_len, bill_dep, colour = species)) + 
  geom_point(na.rm = TRUE) + 
  # As a stat, provide a geom
  stat_manual(
    geom = "segment", # function creates new xend/yend for segment
    fun = make_centroids,
    linewidth = 0.2,
    na.rm = TRUE
  ) +
  # As a geom, provide the stat
  geom_polygon(
    stat = "manual",
    fun = make_hull,
    fill = NA,
    linetype = "dotted"
  )

Connection

It has come to our attention that generalisations of geom_step() have become commonplace in several extensions. Stairstep ribbons are used in Kaplan-Meier curves to indicate uncertainty. Stairstep area plots make for some great histograms. To this end, we’re introducing stat_connect() , which can connect observations in a stairstep fashion without constraining a geom choice. In the plot, you can see it work on the y, ymin and ymax aesthetics indiscriminately with distinct geoms.

eco <- economics |>
  dplyr::mutate(year = lubridate::year(date)) |>
  dplyr::summarise(
    min = min(unemploy),
    max = max(unemploy),
    mid = median(unemploy),
    .by = year
  )

ggplot(eco, aes(year, y = mid, ymin = min, ymax = max)) +
  geom_line(stat = "connect") +
  geom_ribbon(stat = "connect", alpha = 0.4)

However, we aren’t necessarily limited to stairstep connections. We can use a 2-column numeric matrix to sketch out other types of connections. For example if we use plogis() to create a logistic transition, we can make ‘bump chart’-like connections. Or you can use a zigzag pattern if silliness is your cup of tea.

x <- seq(0, 1, length.out = 20)[-1]
smooth <- cbind(x, scales::rescale(plogis(x, location = 0.5, scale = 0.1)))
zigzag <- cbind(c(0.4, 0.6, 1), c(0.75, 0.25, 1))

ggplot(head(eco, 10), aes(year, y = mid)) +
  geom_point() +
  stat_connect(aes(colour = "smooth"), connection = smooth) +
  stat_connect(aes(colour = "zigzag"), connection = zigzag)

Coord reversal

It has been possible to use reverse transformations for scales to flip a plot direction. You could even use scales::transform_compose() to do, for example, a reversed log₁₀ transformation to highlight the smallest p-values. However, the transformation approach has a few limitations, notably that discrete scales do not support transformations and not all coords obeyed transformed scales. You can’t really combine coord_sf() + scale_x_log10() for example. To remedy this limitation, coords now have a reverse argument that can typically be "none", "x", "y" or "xy" that reverse some directions. If you are from the lands down under, you can now plot a map in your native orientation.

world <- sf::st_as_sf(maps::map('world', plot = FALSE, fill = TRUE))

ggplot(world) +
  geom_sf() +
  coord_sf(reverse = "y")

In coord_radial() , the reverse argument replaces the direction argument that only worked for the theta-direction. Contrary to many coords, coord_radial(reverse) takes "none", "theta", "r" and "thetar" instead of the x/y directions.

Goodies for extensions

Layers

If you’ve ever written a Geom class, chances are that you’ve danced with grid::gpar() and frowned at the use of .pt and .stroke and whatnot. We’ve made a wrapper for grid::gpar() that applies the ggplot2 interpretation of settings and translates them to grid settings. For example, linewidth (or the lwd grid setting) is interpreted in millimetres in ggplot2, whereas grid expects them in points. The gg_par() function helps these translations, protects against NAs in line types and strokes, removes 0-length vectors, and has additional logic for point strokes.

gg_par(lwd = 5)
#> $lwd
#> [1] 14.22638
grid::convertUnit(unit(5, "mm"), "pt")
#> [1] 14.2263779527559points

For geom and stat extensions, the magic usually happens in the Geom* or Stat* classes and the constructor is simply boilerplate code used to populate a layer. To reduce the amount of boilerplate code, you can now use make_constructor() on Geom* and Stat* classes. It produces a typical constructor function that adheres to several conventions, like exposing arguments to compute/drawing methods. To illustrate, notice how the following constructor for GeomPath includes arguments for lineend and linejoin automatically because they are arguments to the GeomPath$draw_panel() method.

geom_foo <- make_constructor(GeomPath, position = "stack")
print(geom_foo)
#> function (mapping = NULL, data = NULL, stat = "identity", position = "stack", 
#>     ..., arrow = NULL, arrow.fill = NULL, lineend = "butt", linejoin = "round", 
#>     linemitre = 10, na.rm = FALSE, show.legend = NA, inherit.aes = TRUE) 
#> {
#>     layer(mapping = mapping, data = data, geom = "path", stat = stat, 
#>         position = position, show.legend = show.legend, inherit.aes = inherit.aes, 
#>         params = list2(na.rm = na.rm, arrow = arrow, arrow.fill = arrow.fill, 
#>             lineend = lineend, linejoin = linejoin, linemitre = linemitre, 
#>             ...))
#> }
#>

In addition, you can now also use the #' @aesthetics roxygen tag to automatically populate an ‘Aesthetics’ section of your documentation. The code below;

GeomDummy <- ggproto("GeomDummy", Geom, default_aes = aes(foo = "bar"))

#' 
#' @aesthetics GeomDummy
geom_foo <- make_constructor(GeomDummy)

will generate the following .Rd code:

\section{Aesthetics}{

\code{geom_dummy()} understands the following aesthetics. Required aesthetics are displayed in bold and defaults are displayed for optional aesthetics:
\tabular{rll}{
 • \tab \code{foo} \tab → \code{"bar"} \cr
 • \tab \code{\link[ggplot2:aes_group_order]{group}} \tab → inferred \cr
}

Learn more about setting these aesthetics in \code{vignette("ggplot2-specs")}.
}

Themes

To replicate how themes are handled internally, you can now use complete_theme() . It fills in all missing elements and performs typical checks.

my_theme <- theme(plot.background = element_rect(fill = NA))
length(my_theme)
#> [1] 1

completed <- complete_theme(my_theme)
length(completed)
#> [1] 144

# You should give rect elements to text settings
completed <- theme(legend.text = element_rect()) |>
  complete_theme()
#> Error in `plot_theme()`:
#> ! Can't merge the `legend.text` theme element.
#> Caused by error in `method(merge_element, list(ggplot2::element, class_any))`:
#> ! Only elements of the same class can be merged.

# Unknown elements
completed <- theme(foobar = 12) |>
  complete_theme()
#> Warning in plot_theme(list(theme = theme), default = default): The `foobar` theme element is not defined in the element hierarchy.

We’re also introducing point and polygon theme elements. These aren’t used in any of the base ggplot2 theme settings, but you can use them in extensions. The example below demonstrates registering new theme settings and that points and polygons follow inheritance and can be rendered.

# Let's say your package 'my_pkg' registers custom point/polygon elements
register_theme_elements(
  my_pkg_point = element_point(colour = "red"),
  my_pkg_polygon = element_polygon(fill = NA),
  element_tree = list(
    my_pkg_point = el_def(element_point, inherit = "point"),
    my_pkg_polygon = el_def(element_polygon, inherit = "polygon")
  )
)

# Which should inherit from the root point/polygon theme elements
my_theme <- theme(
  point = element_point(shape = 17),
  polygon = element_polygon(linetype = "dotted")
) |>
  complete_theme()

# Rendering your elements
pts <- calc_element("my_pkg_point", my_theme) |>
  element_grob(
    x = c(0.2, 0.5, 0.8),
    y = c(0.8, 0.2, 0.5)
  )
poly <- calc_element("my_pkg_polygon", my_theme) |>
  element_grob(
    x = c(0.1, 0.5, 0.9),
    y = c(0.9, 0.1, 0.5)
  )

# Drawing the elements
grid::grid.newpage()
grid::grid.draw(pts)
grid::grid.draw(poly)

Acknowledgements

Thank you to all the people who contributed their issues, code and comments to this release: @83221n4ndr34 , @Abiologist , @acebulsk , @adisarid , @agila5 , @agmurray , @agneeshbarua , @aijordan , @amarjitsinghchandhial , @amkilpatrick , @amongoodtx , @Andtise , @andybeet , @antoine4ucsd , @aphalo , @aravind-j , @arcresu , @arnaudgallou , @assaron , @baderstine , @BajczA475 , @bakaburg1 , @BegoniaCampos , @benjaminhlina , @billdenney , @binkleym , @bkohrn , @bnprks , @botanize , @Breeze-Hu , @brianmsm , @brunomioto , @btupper , @bwu62 , @carljpearson , @catalamarti , @cbrnr , @ccani007 , @ccsarapas , @cgoo4 , @clauswilke , @Close-your-eyes , @collinberke , @const-ae , @dafxy , @DanChaltiel , @danli349 , @dansmith01 , @daorui , @david-romano , @davidhodge931 , @dinosquash , @dominicroye , @dsconnell , @EA-Ammar , @EBukin , @elgabbas , @eliocamp , @elipousson , @erinnacland , @etiennebacher , @EvaMaeRey , @evanmascitti , @eyayaw , @fabian-s , @fkohrt , @FloLecorvaisier , @fmarotta , @Fugwaaaa , @fwunschel , @g-pacheco , @gaborcsardi , @gregorp , @guqicun , @hadley , @heinonmatti , @heor-robyoung , @herry23xet , @HMU-WH , @HRodenhizer , @hsiaoyi0504 , @Hy4m , @IndrajeetPatil , @jack-davison , @JacobBumgarner , @JakubKomarek , @jansim , @japhir , @jbengler , @jdonland , @jeraldnoble , @Jigyasu4indp , @jiw181 , @jmbuhr , @JMeyer31 , @jmgirard , @jnolis , @joaopedrosusselbertogna , @johow , @jonocarroll , @jpquast , @JStorey42 , @JThomasWatson , @julianbarg , @julou , @junjunlab , @JWiley , @kauedesousa , @kdarras , @kevinushey , @kevinwolz , @kieran-mace , @kkellysci , @kobetst , @koheiw , @krlmlr , @KryeKuzhinieri , @kylebutts , @laurabrianna , @lbenz730 , @lcpmgh , @lgaborini , @lgibson7 , @LGraz , @llrs , @louis-heraut , @ltierney , @Lucielclr , @luhann , @m-muecke , @marcelglueck , @margaret-colville , @markus-schaffer , @Maschette , @MathiasAmbuehl , @MathieuYeche , @mattansb , @MauricioCely , @MaxAtoms , @mcol , @mfoos , @MichaelChirico , @MichelineCampbell , @mikmart , @misea , @mjskay , @mkoohafkan , @mlaparie , @MLopez-Ibanez , @mluerig , @mohammad-numan , @MoREpro , @mtrsl , @muschellij2 , @mzavattaro , @nicholasdavies , @njspix , @nmercadeb , @noejn2 , @npearlmu , @Olivia-Box-Power , @olivroy , @oracle5th , @oskard95 , @palderman , @PanfengZhang , @paulfajour , @PCEBrunaLab , @petrbouchal , @pgmj , @phispu , @PietrH , @pn317 , @ppoyk , @pradosj , @psoldath , @py9mrg , @qli84 , @randyzwitch , @raphaludwig , @RaynorJim , @rdboyes , @reechawong , @rempsyc , @rfgoldberg , @rikivillalba , @rishabh-mp3 , @RodDalBen , @rogerssam , @rsh52 , @rwilson8 , @salim-b , @sambtalcott , @samuel-marsh , @schloerke , @schmittrjp , @sierrajohnson , @smouksassi , @stitam , @stragu , @strengejacke , @sunta3iouxos , @szkabel , @taozhou2020 , @tdhock , @telenskyt , @teunbrand , @the-Hull , @thgsponer , @thomasp85 , @ThomasSoeiro , @Tiggax , @tikkss , @TimTaylor , @tombishop1 , @tommmmi , @totajuliusd , @trafficfan , @tungttnguyen , @tvatter , @twest820 , @ujtwr , @venpopov , @vgregoire1 , @victorcat4 , @victorfeagins , @vivekJax , @wbvguo , @willgearty , @williamlai2 , @withr , @wvictor14 , @XdahaX , @yjunechoe , @yoshidk6 , @YUCHENG-ZHAO , @Yunuuuu , @yutannihilation , @yzz32 , @zhengxiaoUVic , and @zjwinn .

Normally, aes() is strictly used to map data instead of setting a fixed property. We diverge from this API for pragmatic reasons, not theoretical ones. ↩︎
Aesthetics of the position adjustment are not be confused with position aesthetics. Position aesthetics like x and y are transformed by a scale, whereas aesthetics of the position adjustment like nudge_x and nudge_y are not (akin to width and height). ↩︎

Great Tables `v0.18.0`: Easy Column Spanners and More!

Rich Iannone — Fri, 18 Jul 2025 00:00:00 +0000

The development of Great Tables continues! We’re excited to announce the release of v0.18.0, which brings several powerful new features. These features make it even easier to create beautiful, informative tables. The key additions in this release include new methods (and a tweak to an existing one):

~~.GT.tab_spanner_delim(): quick spanner creation
~~.GT.fmt_tf(): easy boolean value formatting
~~.GT.cols_label_rotate(): enables column label rotation
~~.GT.fmt_datetime(): added format_str= parameter for extra customization

Let’s explore each of these interesting new features!

Quick spanner creation with `tab_spanner_delim()`

Working with data that has hierarchical column names can be tedious when manually creating spanners. The new ~~.GT.tab_spanner_delim() method automates this process by intelligently splitting column names based on a delimiter and creating the appropriate spanner structure.

Here’s a practical example using the towny dataset, which contains population data for a collection of municipalities across multiple census years. Let’s start by looking at the most populated cities and examining their column structure:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


from great_tables import GT
from great_tables.data import towny
import polars as pl
import polars.selectors as cs

# Create a smaller version of the `towny` dataset
towny_mini = (
    pl.from_pandas(towny)
    .filter(pl.col("csd_type") == "city")
    .sort("population_2021", descending=True)
    .select(
        "name",
        cs.starts_with("population_"),
        cs.starts_with("density_")
    )
    .head(5)
)

# Let's look at the column names
print(towny_mini.columns)

['name', 'population_1996', 'population_2001', 'population_2006', 'population_2011', 'population_2016', 'population_2021', 'density_1996', 'density_2001', 'density_2006', 'density_2011', 'density_2016', 'density_2021']

Notice how the column names have a clear hierarchical structure with underscores as delimiters. Let’s now create a table that takes advantage of this structure:

1
2
3
4
5
6
7
8


(
    GT(towny_mini, rowname_col="name")
    .tab_spanner_delim(delim="_")
    .fmt_integer(columns=cs.contains("population"))
    .fmt_number(columns=cs.contains("density"), decimals=1)
    .tab_header(title="Population and Density Trends from Census Data")
    .opt_align_table_header(align="left")
)

Population and Density Trends from Census Data
	population						density
	1996	2001	2006	2011	2016	2021	1996	2001	2006	2011	2016	2021
Toronto	2,385,421	2,481,494	2,503,281	2,615,060	2,731,571	2,794,356	3,779.8	3,932.0	3,966.5	4,143.6	4,328.3	4,427.8
Ottawa	721,136	774,072	812,129	883,391	934,243	1,017,449	258.6	277.6	291.3	316.8	335.1	364.9
Mississauga	544,382	612,925	668,599	713,443	721,599	717,961	1,859.6	2,093.8	2,283.9	2,437.1	2,465.0	2,452.6
Brampton	268,251	325,428	433,806	523,906	593,638	656,480	1,008.9	1,223.9	1,631.5	1,970.4	2,232.7	2,469.0
Hamilton	467,799	490,268	504,559	519,949	536,917	569,353	418.3	438.4	451.2	464.9	480.1	509.1

The ~~.GT.tab_spanner_delim() method recognizes the underscore delimiter and creates a hierarchical structure: "population" and "density" become top-level spanners, with the years (1996, 2001, 2021) as the final column labels. This creates a clean, organized appearance that clearly groups related metrics together. And, this one method can be used instead of a combination of ~~.GT.cols_label() and ~~.GT.tab_spanner() (which requires a separate invocation per spanner added).

Beautiful boolean formatting with `fmt_tf()`

Boolean data is common in analytical tables, but raw True/False values can look unprofessional. The new ~~.GT.fmt_tf() method provides elegant ways to display boolean data using symbols, words, or custom formatting.

Here’s a simple example showing different tf_style= options:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


from great_tables import GT
import polars as pl

# Create a simple DF with boolean data
bool_df = pl.DataFrame({
    "feature": ["Premium Sound", "Leather Seats", "Sunroof", "Navigation"],
    "model_a": [True, False, True, True],
    "model_b": [True, True, False, True],
    "model_c": [False, True, True, False]
})

(
    GT(bool_df, rowname_col="feature")
    .fmt_tf(tf_style="check-mark", colors=["green", "red"])
    .tab_header(title="Car Features Comparison", subtitle="Using check-mark style")
)

Car Features Comparison
Using check-mark style
	model_a	model_b	model_c
Premium Sound	✔	✔	✘
Leather Seats	✘	✔	✔
Sunroof	✔	✘	✔
Navigation	✔	✔	✘

You can also use different symbols and colors for a more distinctive look:

1
2
3
4
5


(
    GT(bool_df, rowname_col="feature")
    .fmt_tf(tf_style="circles", colors=["#4CAF50", "#F44336"])
    .tab_header(title="Car Features Comparison", subtitle="Using circles style")
)

Car Features Comparison
Using circles style
	model_a	model_b	model_c
Premium Sound	●	●	⭘
Leather Seats	⭘	●	●
Sunroof	●	⭘	●
Navigation	●	●	⭘

The ~~.GT.fmt_tf() method transforms boolean values into visually appealing symbols that make it easy to quickly scan and compare data across rows and columns.

Rotating column labels with `cols_label_rotate()`

When dealing with many columns or long column names, horizontal space becomes precious. The ~~.GT.cols_label_rotate() method solves this by rotating column labels vertically, allowing for more compact table layouts.

Here’s an example where we use the gtcars dataset to create a table which communicates a feature matrix:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49


from great_tables import GT, style, loc
from great_tables.data import gtcars
import polars as pl
import polars.selectors as cs

# Manipulate dataset to create a feature comparison table
gtcars_mini = (
    pl.from_pandas(gtcars)
    .filter(pl.col("year") == 2017)
    .filter(pl.col("ctry_origin").is_in(["Germany", "Italy", "United Kingdom"]))
    .with_columns([
        (pl.col("hp") > 500).alias("High Power"),
        (pl.col("mpg_h") > 25).alias("Fuel Efficient"),
        (pl.col("drivetrain") == "awd").alias("All Wheel Drive"),
        (pl.col("msrp") > 100000).alias("Premium Price"),
        (pl.col("trsmn").str.contains("manual")).alias("Manual Transmission")
    ])
    .select([
        "mfr", "model", "trim",
        "High Power",
        "Fuel Efficient",
        "All Wheel Drive",
        "Premium Price",
        "Manual Transmission"
    ])
    .head(10)
)

(
    GT(gtcars_mini)
    .fmt_tf(
        columns=cs.by_dtype(pl.Boolean),
        tf_style="check-mark",
        colors=["#2E8B57", "#DC143C"]
    )
    .cols_label_rotate(
        columns=cs.by_dtype(pl.Boolean),
        dir="sideways-lr"
    )
    .tab_header(
        title="European Luxury Cars Feature Matrix",
        subtitle="2017 Models with Performance & Luxury Features"
    )
    .opt_stylize(style=1)
    .tab_style(
        style=style.text(size="11px"),
        locations=loc.body()
    )
)

European Luxury Cars Feature Matrix
2017 Models with Performance & Luxury Features
mfr	model	trim	High Power	Fuel Efficient	All Wheel Drive	Premium Price	Manual Transmission
Ferrari	GTC4Lusso	Base Coupe	✔	✘	✔	✔	✘
Aston Martin	DB11	Base Coupe	✔	✘	✘	✔	✘
Lotus	Evora	2+2 Coupe	✘	✘	✘	✘	✘
Porsche	718 Boxster	Base Convertible	✘	✔	✘	✘	✘
Porsche	718 Cayman	Base Coupe	✘	✔	✘	✘	✘

This example demonstrates how both the ~~.GT.fmt_tf() and ~~.GT.cols_label_rotate() methods can work well together. The boolean columns use checkmarks (✓/✗) with custom colors=, while the rotated labels save horizontal space in this dense feature matrix. The combination allows you to put more information into a compact and still readable format.

Enhanced datetime formatting with `fmt_datetime()`

The ~~.GT.fmt_datetime() method now supports custom format strings through the new format_str= parameter, giving you complete control over how datetime values appear in your tables.

Here’s an example using the included gibraltar weather dataset:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40


from great_tables import GT
from great_tables.data import gibraltar
import polars as pl

# Prepare the meteorological data
gibraltar_mini = (
    pl.from_pandas(gibraltar)
    .with_columns(
        [
            pl.concat_str([pl.col("date"), pl.lit(" "), pl.col("time")])
            .str.strptime(pl.Datetime, format="%Y-%m-%d %H:%M")
            .alias("datetime")
        ]
    )
    .filter(pl.col("datetime").dt.hour().is_in([6, 12, 18]))
    .select(["datetime", "temp", "humidity", "condition"])
    .sort("datetime")
    .head(10)
)

(
    GT(gibraltar_mini)
    .fmt_datetime(
        columns="datetime",
        format_str="%b %d %Y (%a) - %I:%M %p",
    )
    .fmt_number(columns="temp", decimals=1, pattern="{x}°C")
    .fmt_percent(columns="humidity", scale_values=False, decimals=0)
    .cols_label(
        datetime="Time",
        temp="Temperature",
        humidity="Humidity",
        condition="Conditions",
    )
    .tab_header(
        title="Gibraltar Temperature and Humidity Conditions",
        subtitle="Morning, Noon, and Evening Readings"
    )
    .opt_stylize(style=1, color="cyan")
)

Gibraltar Temperature and Humidity Conditions
Morning, Noon, and Evening Readings
Time	Temperature	Humidity	Conditions
May 01 2023 (Mon) - 06:50 AM	17.2°C	1%	Fair
May 01 2023 (Mon) - 12:20 PM	22.2°C	1%	Fair
May 01 2023 (Mon) - 12:50 PM	22.2°C	1%	Fair
May 01 2023 (Mon) - 06:20 PM	20.0°C	1%	Fair
May 01 2023 (Mon) - 06:50 PM	20.0°C	1%	Fair
May 02 2023 (Tue) - 06:50 AM	17.8°C	1%	Mostly Cloudy
May 02 2023 (Tue) - 12:20 PM	18.9°C	1%	Mostly Cloudy
May 02 2023 (Tue) - 12:50 PM	20.0°C	1%	Mostly Cloudy
May 02 2023 (Tue) - 06:20 PM	22.2°C	1%	Fair
May 02 2023 (Tue) - 06:50 PM	22.2°C	1%	Fair

The custom datetime formatting string in format_str="%b %d %Y (%a) - %I:%M %p" creates a readable datetime format that’s perfect for weather reporting, showing the day of week, month, day, year, and the time in 12-hour format.

Acknowledgements and what’s next

We’re grateful to all the contributors who made this release possible. These new features represent significant improvements for creating space-efficient tables while also maximizing visual appeal.

The combination of these features lets you now create complex, professional tables with hierarchical column structures, boolean indicators, space-saving labels, and nicely formatted datetime displays.

We’re always happy to get feedback and hear about how you’re using Great Tables:

Keep building those beautiful tables!

Adding Plots to Great Tables

Jules Walzer-Goldfeld — Thu, 03 Jul 2025 00:00:00 +0000

While working on gt-extras , I’ve been exploring how to add small plots to Great Tables. These can go by many names, like spark lines, nanoplots, and so on. In this post, I’ll look at three approaches I tried: adding plots with plotnine , svg.py , or adding HTML directly. In the first two cases, the plots are SVGs, while the latter entails a collection of composed HTML div elements.

Here are the pieces I’ll cover:

svg.py: creating your own tiny chart directly for a row.
direct HTML: adding HTML divs directly.
plotnine: adding a full, stripped-down chart to a row.

In the end, it’s often simplest to use svg.py, since you can create basic charts with minimal overhead. Building elements with HTML has even less overhead, but it is also slightly less user-friendly. At the other end of the spectrum, as your charts become more complex, using existing packages like the more exhaustive plotnine is a good alternative.

Animal	Legs	Plot
Ostrich	2	2
Spider	8	8
Lion	4	4

Here is the final result:

Code

Great Tables + marimo = Interactive Tables

Rich Iannone — Tue, 24 Jun 2025 00:00:00 +0000

Jerry Wu’s recent post demonstrates how Great Tables can be made reactive in a marimo notebook. The post showcases a really nice integration where marimo’s reactive widgets can be embedded directly into Great Tables using the html() helper function. This effectively creates an interactive table that updates in real-time whenever users interact with the controls.

Interactive Table Demo

Here’s a screencast (based on the aforementioned post ) showing Jerry’s GT table in marimo. It demonstrates how the embedded marimo widgets create reactive effects, allowing you to directly modify the table in real-time.

The marimo reactive widgets can be embedded into a GT table through the html() helper function. In Jerry’s example, the table responds to widget changes in the opt_stylize() method call, where the .value attributes for all of the widgets are passed in as arguments.

1
2
3
4
5


gt.opt_stylize(
    style=style_widget.value,
    color=color_widget.value,
    add_row_striping=row_striping_widget.value,
)

marimo Showcases the Integration

The marimo team must have seen that post and liked what they saw! They recently released a video showcasing how marimo widgets work with Great Tables to create reactive tables.

For more details on marimo’s widget system, check out their UI elements documentation and reactivity guide .

marimo + Quarto Integration

For those interested in embedding marimo notebooks directly in Quarto documents, the marimo team has also created a quarto-marimo plugin . This extension allows you to run marimo code blocks natively within Quarto documents, making it easy to create interactive content that combines the best of both tools. It’s a very exciting development since we use Quarto extensively (our docs and this very blog post were authored through Quarto!). And naturally there’s a video for this as well.

Wrapping Up

We’re excited by how the marimo team is committed to creating seamless integrations with popular tools like Great Tables and Quarto. We’re also excited to see what new features and integrations they’ll develop next!

Be sure to check out the marimo YouTube channel as they consistently produce high-quality videos that demonstrate the power of reactive notebooks in action.

svglite 2.2.0

Thomas Lin Pedersen — Wed, 07 May 2025 00:00:00 +0000

We’re pleased to announce the release of svglite 2.2.0. svglite is a graphic device that is capable of creating SVG files from R graphics. SVG is a vector graphic format which means that it encodes the instructions for recreating a graphic in a scale-independent way. This is in contrast with raster graphics, such as PNG (as can be produced with the graphic devices in ragg ), which encode actual pixel values and will get pixelated as you zoom in.

You can install it from CRAN with:

1

install.packages("svglite")

This blog post will describe the news features available the release, with a special focus on text rendering and font handling.

You can see a full list of changes in the release notes

1
2


library(svglite)
library(grid)

Graphics engine support

With this release svglite now supports all the latest features offered by the R graphics engine. The graphics engine is the part of R that communicate plotting instructions from the user to the graphics device, and the last couple of years Paul Murrell has made a huge amount of working adding to what is possible with R graphics. svglite already supported a bunch of these with the 2.0.0 release, but with 2.2.0 the support is complete (for now).

Stroking and filling complex paths

In 4.2.0 R gained the ability to create complex path objects out of (almost) any grob or collection of grobs. Now, svglite supports this, even allowing text to be used. First, let’s see how a compound grob looks when it is rendered normally:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


circle <- circleGrob(
  r = .25,
  gp = gpar(col = "black", lwd = 5, fill = "goldenrod")
)
text <- textGrob(
  "svglite",
  gp = gpar(col = "forestgreen", fontsize = 110, fontface = "bold")
)
gt <- gTree(
  children = gList(
    circle,
    text
  )
)

grid.draw(gt)

Instead, if we render it as a compound path (using the even-odd filling rule) we get this:

1
2
3


grid.draw(
  fillGrob(gt, rule = "evenodd", gp = gpar(fill = "steelblue"))
)

Observe how everything is now part of the same graphic object, and that the even-odd filling rule makes it so that the overlap is empty. Another point is that the graphic parameters of the composite grob doesn’t have an effect on the compound path as only the path information is used.

If you open up the two SVGs in a vector image editor like Inkscape or Affinity Designer, you can see another difference. In the first SVG the text is still editable, while in the second it is not. This is because that in order to support compound paths the glyphs have to be converted to paths, destroying the notion of “text” they might have had.

Groups

Another novelty in R 4.2.0 was the ability to define “groups” that could be reused, composed, and transformed. This is now also possible in svglite, though with a slight limitation in the number of composition operators possible. Inexplicably, the SVG standard has mode Porter-Duff composition way more complicated than colour blending to the extent that it doesn’t really work with how the graphics engine is set up. Still, most of what makes groups great works:

1

grid.group(text, "difference", circle)

1
2
3
4
5
6
7


grid.define(gt, name = "gt")
grid.use(
  "gt",
  transform = \(...) {
    viewportTransform(..., shear = groupShear(sx = 2))
  }
)

Glyphs

A slightly newer feature that came with R 4.3.0 is the glyph interface for rendering rich text. Despite the fact that this is what allows complex text layouting to work in e.g. marquee , at the device side it is actually really simple. It gets a font file, an index for the glyph in that file, and a location for the glyph and is then tasked with rendering it. This is in contrast with the standard text support where you get a string, a font family name, etc. and have to figure out on your own the location of the font file, how glyphs should be placed to look correct etc.

Still, the glyph interface presents a problem for svglite because it tries very hard to create output that can be edited in post-production, and in order to support the glyph interface we have to (like with the compound paths above) render the glyphs as elements instead of elements. There is simply no way in SVG to place glyphs individually based on a font file and a glyph index. However, some support is better than none, so until I find a way to render marquee text in an editable way with svglite, you have at least support for rendering of the text:

1
2
3
4
5
6
7


grid.draw(
  marquee::marquee_grob(
    "This *is* now working with `{svglite}` 🎉",
    style = marquee::classic_style(base_size = 28),
    y = 0.5
  )
)

Again, opening up the SVG in a text editor you’ll see no trace of the input text there as it has all been converted to elements (and an element in the case of the emoji)

Font embedding

If you have followed my work over the last years you know that I’ve grown to care deeply about text rendering, and it’s cousin: font handling. SVG files (as well as PDF files) are special in that regard because the text is not rendered directly in the file (except for the glyph implementation discussed above), but rather postponed until the file is opened. This poses the problem of the font potentially not being available on the machine(s) that is eventually going to open the file.

You can avoid all of these by only using fonts that are considered “web-safe”, such as Arial, Times New Roman, Courier, etc. but what a poor world to live in if those fonts were the only ones used in data visualization. Instead, you can use whatever font you like and embed the font specification in the file so it travels along and is available wherever the file is opened.

svglite() has for a while had the web_fonts argument which allow you to specify font imports to add to the SVG file. With the new release, however, this has been tightened up and in unison with new functionality in systemfonts I believe the gordian knot of font handling in SVGs have finally been untied (this statement will come back to hunt me, I’m sure).

systemfonts now provide the function fonts_as_import(), which allows you to get a URL pointing to a stylesheet with the font to be added. Most often, the font will be served by Google Fonts , but the alternative repository Font Library is also supported:

1

fonts_as_import("Open Sans")

## [1] "https://fonts.googleapis.com/css2?family=Open+Sans&display=swap"

1

fonts_as_import("Bedstead")

## [1] "https://fontlibrary.org/face/bedstead"

The output of this function can be used directly in the web_fonts argument making it very easy to embed any font of your liking in an SVG. Even easier, you can also just pass in the font family name and svglite will take care of the rest (though you loose out on the customization offered by fonts_as_import()):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


library(ggplot2)
require_font("Almendra")

p <- ggplot(na.omit(penguins)) +
  geom_point(aes(flipper_len, body_mass, colour = species)) +
  theme_minimal(base_family = "Almendra")

svg <- svgstring(web_fonts = "Almendra", scaling = 2)
plot(p)
invisible(dev.off())
svg()

Hopefully you can see that the svg above renders with the custom font, and hopefully I chose a font so obscure that you didn’t already have it available on your computer so that you can see the font embedding in action.

If you look at the output generated by fonts_as_import() above, you can see they are URLs pointing to an online location as already discussed. This poses the issue that the one opening the SVG needs to be online for it to render correctly. While that is generally true, it is still a major limitation. Another requirement is that the font is available in one of the supported repositories, and that the repository hasn’t changed it’s API or is down or one of another myriad of reasons why the URL stops being valid. Many of these concerns seldom apply, but if you need your SVG file to by fully self-contained, fonts_as_import() also supports embedding the font data directly into the URL, by opting out of the repositories:

1
2
3
4
5


require_font("Quicksand")

full_embed <- fonts_as_import("Quicksand", repositories = NULL)

substr(full_embed, 1, 400)

## [1] "data:text/css,@font-face%20%7B%0A%20%20font-family:%20%22Quicksand%22;%0A%20%20src:%20url(data:font/otf;charset=utf-8;base64,T1RUTwAKAIAAAwAgQ0ZGIIPL1GAAAAtoAABFjUdQT1OvRtmMAABUHAAAGghPUy8ygho88QAAARAAAABgY21hcED/4R8AAAf8AAADSmhlYWT4ztT1AAAArAAAADZoaGVhB/wFfQAAAOQAAAAkaG10eMd0NowAAFD4AAADJG1heHAAyVAAAAABCAAAAAZuYW1lEqs13gAAAXAAAAaJcG9zdP+4ADIAAAtIAAAAIAABAAAAAQCD/Fij2F8PPPUAAwPoAAAAAMq6SGIAAAAAyrp"

1
2
3
4
5
6
7


p <- p +
  theme_minimal(base_family = "Quicksand")

svg <- svgstring(web_fonts = full_embed, scaling = 2)
plot(p)
invisible(dev.off())
svg()

Be aware that embedding font data directly into an SVG will have a negative effect on the file size, so this is something you should reserve for when it is actually needed:

1
2
3
4
5
6
7
8
9


embedded_data <- svgstring(web_fonts = full_embed, scaling = 2)
plot(p)
invisible(dev.off())

embedded_url <- svgstring(web_fonts = "Quicksand", scaling = 2)
plot(p)
invisible(dev.off())

c(data = nchar(embedded_data()), url = nchar(embedded_url()))

##  data   url
## 79300 41519

Acknowledgements

A big thank to everyone who contributed to this release with issues and PRs!

@ca4wa , @davidhodge931 , @gaborcsardi , @hadley , @psoldath , @robert-dodier , @thomasp85 , and @trevorld .

scales 1.4.0

Teun Van den Brand — Wed, 23 Apr 2025 00:00:00 +0000

We’re stoked to announce the release of scales 1.4.0. scales is a package that provides much of the scaling logic that is used in ggplot2 to a general framework, along with utility functions for e.g. formatting labels or creating colour palettes.

You can install it from CRAN with:

install.packages("scales")

This blog post will give an overview of the 1.4.0 release, which has some nifty upgrades for working with colours and labels.

You can see a full list of changes in the release notes

library(scales)

Colour manipulation

The alpha() and muted() functions have been part of scales for a long time. Back in the 1.1.0 release we swapped to farver to power these functions. We felt it was appropriate to use this package for other common colour tasks, and so col_shift() , col_lighter() , col_darker() , col_saturate() and col_mix() were born.

my_colours <- c("red", "green", "blue")

m <- rbind(
  original = my_colours,
  shift    = col_shift(my_colours, 90),
  lighter  = col_lighter(my_colours, 20),
  darker   = col_darker(my_colours, 20),
  duller   = col_saturate(my_colours, -50),
  mixed    = col_mix(my_colours, "orchid")
)

show_col(t(m), ncol = ncol(m))
text(x = ncol(m) + 0.25, y = -(1:nrow(m)) + 0.5, rownames(m), adj = 0)

Palettes

Palettes have also been reworked in this release to include some useful properties. Palettes now come in one of two classes: ‘pal_discrete’ or ‘pal_continuous’.

my_palette <- manual_pal(c("palegreen", "deepskyblue", "magenta"))
class(my_palette)
#> [1] "pal_discrete" "scales_pal"   "function"

Having palettes as a class rather than as plain functions, allows us to store useful metadata about the palette which can be used downstream. In addition, most colour palette functions also allow the aforementioned colour manipulation functions to work on the palette output.

palette_type(my_palette)
#> [1] "colour"

palette_nlevels(my_palette)
#> [1] 3

col_shift(my_palette, 180)(3)
#> [1] "#FFC3FF" "#E4A735" "#00B100"

With the new setup it is now possible to expand discrete palettes to continuous palettes with as_continuous_pal() or vise versa to chop up continuous palettes into discrete palettes with as_discrete_pal() .

plot(as_continuous_pal(my_palette))

Another quality of life improvement for palettes, is that the ‘scales’ package now keeps track of some named palettes. By default, the collection of ‘known’ palettes is pre-populated with colour palettes from the grDevices, RColorBrewer and viridisLite packages.

as_discrete_pal("Okabe-Ito")(8)
#> [1] "#000000" "#E69F00" "#56B4E9" "#009E73" "#F0E442" "#0072B2" "#D55E00"
#> [8] "#CC79A7"

Providing palettes as package

For those that are interested in developing R packages with palettes, there are a few recommendations we make in ?palette-recommendations to smoothly interface with the scales package.

If your palettes are vectors of colour values, we recommend simply exporting the naked vector.

#' @export
aurora <- c("palegreen", "deepskyblue", "magenta")

That way, they can easily be accessed and used in as_discrete_pal() and as_continuous_pal() .

as_continuous_pal(aurora)
as_discrete_pal(aurora)

Alternatively, if you have functions that generate colours that is not predefined, we recommend wrapping the function in new_discrete_palette() and new_continuous_palette() . For predefined palettes, you can also use pal_manual() or pal_gradient_n() .

pal_random <- function() {
  fun <- function(n) {
    sample(colours(distinct = TRUE), size = n, replace = TRUE)
  }
  new_discrete_palette(fun, type = "colour", nlevels = length(colours()))
}

Populating the metadata in new_discrete_palette() /new_continuous_palette() helps to make converting between palette types less painful.

as_continuous_pal(pal_random())
as_discrete_pal(pal_random())

Labels

This release also provides improvements to labelling in the form of two new labelling functions and two new convenience functions for labels. In contrast to most of scales’ label functions, these label functions are great for discrete input. First up is label_glue() , which uses the string interpolation from the glue package to format your labels.

label_glue("The {x} penguin")(c("Gentoo", "Chinstrap", "Adelie"))
#> The Gentoo penguin
#> The Chinstrap penguin
#> The Adelie penguin

The other labelling function, label_dictionary() , is convenient when some variable you use consists of short-codes or abbreviations. You can provide label_dictionary() with a named vector that translates the values to prettier labels. If one or more of your values doesn’t exist in the dictionary, they stay as-is by default.

dict <- c(
  diy = "Do it yourself", eta = "Estimated time of arrival",
  asap = "As soon as possible", tldr = "Too long; didn't read"
)
label_dictionary(dict)(c("diy", "tldr", "bff"))
#> [1] "Do it yourself"        "Too long; didn't read" "bff"

compose_label() is a useful convenience function we’ve added which will help you to create custom labelling behaviour without needing to write a labelling function from scratch. Similar to compose_trans() , it allows you to chain together different labelling functions.

screaming_flowers <- compose_label(label_glue("The {x} flower"), toupper)
screaming_flowers(c("daffodil", "orchid", "tulip"))
#> THE DAFFODIL FLOWER
#> THE ORCHID FLOWER
#> THE TULIP FLOWER

Lastly, we haven’t completely forgotton about numeric labels either. We have introduced the number_options() functions to globally populate defaults for functions such as label_number() and label_currency() . This can be convenient if you produce statistical reports in non-English languages.

number_options(
  decimal.mark = ",",
  big.mark = ".",
  style_negative = "minus",
  currency.prefix = "",
  currency.suffix = "€",
  currency.decimal.mark = ",",
  currency.big.mark = " ",
  ordinal.rules = ordinal_french()
)

label_currency(accuracy = 0.01)(c(0.1, 10, 1000000, -1000))
#> [1] "0,10€"         "10,00€"        "1 000 000,00€" "-1 000,00€"

label_ordinal()(1:4)
#> [1] "1er" "2e"  "3e"  "4e"

Acknowledgements

We’d like to thank all people who have contributed in some way, whether it was filing issues, participating in discussion or contributing to code and documentation:

@Aariq , @Aehmlo , @Ali-Hudson , @cb12991 , @colindouglas , @d-morrison , @davidhodge931 , @EricMarcon , @kellijohnson-NOAA , @kmcd39 , @lz1nwm , @mine-cetinkaya-rundel , @mjskay , @Moohan , @muschellij2 , @ppreshant , @rawktheuniversemon , @rogiersbart , @SchmidtPaul , @teunbrand , and @thomasp85 .

Great Tables: Becoming the Polars `.style` Property

Michael Chow — Wed, 16 Apr 2025 00:00:00 +0000

Roughly a year ago, the DataFrame library Polars made its v1.0.0 release. One neat feature included in the release was a DataFrame.style property—which returns a Great Tables object, so you can add things like titles, column labels, and highlighting for reporting.

When talking about the Polars integration, people are often surprised to hear it happened when Great Tables was only 8 months old. Moreover, the whole process of how open source maintainers chat and discuss teaming up can feel shrouded in mystery.

In this post, I want to take some time to discuss how folks in the Polars and Great Tables communities got to DataFrame.style. There are three big pieces:

How we got there: the magic of the Polars discord.
Making .style work: enabling Great Tables to work as a property.
What’s next?

How we got there

First contact: Polars discord

Roughly a year ago, Rich Iannone and I (Michael Chow) started working together on Great Tables—a Python library for creating display tables. Initially, Great Tables only supported Pandas, but this made a few things difficult. For example, selecting columns and applying conditional styles took a surprising amount of code.

As an experiment, we added support for Polars, and wrote a post called Great Tables: The Polars DataFrame Styler of Your Dreams .

Curious in what folks thought, we dropped it in the Polars discord, and got some Great Feedback:

But Ritchie Vink, the creator of Polars, knew we were harboring a shameful Pandas dependency secret:

It’s true, we had baked Pandas in as a dependency. We were just kids back then when starting Great Tables. We didn’t realize that the world was moving to DataFrame agnostic support 😓.

But the more we used Polars with Great Tables, the happier we were. So we made some architectural tweaks to make Great Tables BYODF (Bring Your Own DataFrame) . With these changes, Polars users could install and use Great Tables without pulling in an unnecessary dependency on another DataFrame library (Pandas).

These interactions were critical early on for co-designing Great Tables with Polars in mind. But the real magic for us was when Polars users started opening PRs on Great Tables, to make sure we got things right. Chief among them, Jerry Wu!

Jerry Wu: power contributor

Luckily, members of the Polars community, like Jerry Wu (jrycw) , showed up to make sure we wired up to Polars correctly, and to weigh in on how Polars should be used.

For example, Jerry’s first PR was ensuring we handled a Polars deprecation correctly.

I really can’t overstate how much we appreciate his help, and how critical it has been in ensuring we get the details right.

In addition to his PRs, Jerry has done really Great Work sharing about table display. The most interesting example of this to me is that he discovered that Polars, Great Tables, and FastHTML work well together.

Rich and I had no idea that was possible, and the FastHTML folks ended up adapting his example into an entry on their gallery . Jerry is constantly teaching us about what Great Tables can do.

Growing up: making the case for `.style`

With so much joy coming out of the Polars integration, and support from folks in the Polars community, we started to wonder: how could Great Tables make Polars a first-class citizen?

This ultimately boiled down to asking: what would it take for the polars.DataFrame.style property to return a Great Tables object?

After some discussion on discord, the big pieces folks needed were some sense that Great Tables used a reasonable approach to table styling, carried few dependencies, and was engineered such that it could be returned from a DataFrame.style property. Ultimately, the next few months were spent getting Great Tables up to snuff, and the Polars PR merged.

Making `.style` work

The PR to implement .style in Polars went super quick, from advice on discord April to merged by June. A huge force behind the PR was Marco Gorelli , who encouraged us through the process!

In this section I’ll look at how we addressed the 3 big requirements behind making a strong case for .DataFrame.style returning a Great Tables object:

Design Credibility: It’s clear Great Tables is reasonably thought out.
Working with Polars selectors: It integrates well with pieces like Polars selectors.
Technical: Great Tables can be returned from a DataFrame.style property.

Design credibility

Our biggest hurdle was that the Great Tables library was less than a year old. However, this youthful appearance is a bit misleading, because Great Tables builds on decades of table design and tooling. For example, Rich’s version of Great Tables in R, called gt, has been around since 2019 (see his rstudio::conf() talk ).

My favorite aspect of gt is that the community ran table contests every year. The contests don’t even require the use of gt or Great Tables, just a zest for the art of table styling. The 2024 Table Contest had around 60 submissions, and is something we often draw on for inspiration.

For more on the long history of table design, see The Design Philosophy of Great Tables , or this Fred Hutch better tables workshop .

Working with Polars selectors

One important task was sorting out how we use Polars selectors, to ensure they didn’t break down the road.

For example, Great Tables allows Polars selectors to set styles on specific columns data. However, one challenge we ran into was figuring out what Polars considers an expression versus a selector. Essentially, selectors choose columns, but expressions represent operations on the data itself.

The code below shows cases where the .exclude() results in expressions or selectors.

1
2
3
4
5
6
7
8


import polars as pl
import polars.selectors as cs

# selector: all columns except "a"
cs.exclude("a")

# expression: same columns as above ¯\_(ツ)_/¯
cs.all().exclude("a")

After discussing with Polars folks in this Polars issue , we landed on 4 rules for selectors:

rule	description	example
`cs` functions	top-level `cs` selection functions -> selector	`cs.starts_with("a")`
infix selectors	infix operators over all selectors -> selector	`cs.starts_with("a") - cs.by_name("abc")`
infix expressions	infix operators over any non-selectors -> expression	`cs.starts_with("a") - "abc"`
method expressions	method calls off selectors -> expression	`cs.all().exclude("a")`

Clarifying this was critical in Great Tables, because in some place we only accept selectors, so we needed to be able to articulate to users how to produce them.

Technical wiring work

The last hurdle was tweaking the great_tables.GT class to fit the flow of DataFrame.style. For example, here is what creating a GT() object looked like before and after .style:

Before: GT(my_data, id="my-table")
After: my_data.style.with_id("my-table")

Notice that before, the GT(id=...) argument could set the html id for a table. However, DataFrame.style is a property that can’t take arguments, so we needed methods like with_id() to set these kinds of options.

Here’s a full code example, in case you want to see it in action.

1
2
3
4
5
6
7
8
9


import polars as pl
from great_tables import GT
from great_tables import exibble

# create a GT object ----
GT(exibble, id="my-table")

# create GT object via .style property ----
pl.DataFrame(exibble).style

num	char	fctr	date	time	datetime	currency	row	group
0.1111	apricot	one	2015-01-15	13:35	2018-01-01 02:22	49.95	row_1	grp_a
2.222	banana	two	2015-02-15	14:40	2018-02-02 14:33	17.95	row_2	grp_a
33.33	coconut	three	2015-03-15	15:45	2018-03-03 03:44	1.39	row_3	grp_a
444.4	durian	four	2015-04-15	16:50	2018-04-04 15:55	65100.0	row_4	grp_a
5550.0	None	five	2015-05-15	17:55	2018-05-05 04:00	1325.81	row_5	grp_b
None	fig	six	2015-06-15	None	2018-06-06 16:11	13.255	row_6	grp_b
777000.0	grapefruit	seven	None	19:10	2018-07-07 05:22	None	row_7	grp_b
8880000.0	honeydew	eight	2015-08-15	20:20	None	0.44	row_8	grp_b

The DataFrame.style property is special, in that you don’t pass any parameters to it. The motivation for this in Polars is that it matches the Pandas pandas.DataFrame.style approach, so provides a familiar interface for users coming from that package. It also matches the DataFrame.plot flow of both packages.

As it turns out, allowing every options settable in the GT() constructor to be set somewhere else was not something anticipated in the design of Great Tables. But after some light architectural wrestling, we introduced .tab_stub(), .with_id(), and .with_locale() to capture arguments you might pass to GT().

What’s next?

Currently, we’re really excited about using Great Tables in different ways!

Pointblank : validate your DataFrames and database tables. Pointblank is quick to fire up and produces delightfully styled reports (using Great Tables 😎).
reactable : create interactive tables. We want to use reactable to render a Great Tables object interactively.

We’re also focused on keeping bug fixes and features cooking in Great Tables. If there’s anything in particular you’re looking for, definitely reach out on the Great Tables discussion page .

In conclusion

This post looked at how interacting with the Polars community discord shaped Great Tables development early on, and how community members like Jerry ended up ensuring Great Tables and Polars played well together. We ended up putting a ring on it, and ensuring Great Tables design, dependencies, and architecture worked well enough to justify returning via polars.DataFrame.style. (Though this is still marked unstable in Polars!)

We’re excited to look at different use cases for Great Tables (and table styling in general) over the next year!

How We Used Great Tables to Supercharge Reporting in Pointblank

Rich Iannone — Tue, 11 Feb 2025 00:00:00 +0000

The Great Tables package allows you to make tables, and they’re really great when part of a report, a book, or a web page. The API is meant to be easy to work with so DataFrames could be made into publication-quality tables without a lot of hassle. And having nice-looking tables in the mix elevates the quality of the medium you’re working in.

We were inspired by this and decided to explore what it could mean to introduce a package where reporting is largely in the form of beautiful tables. To this end, we started work on a new Python package that generates tables (c/o Great Tables) as reporting objects. This package is called Pointblank , its focus is that of data validation, and the reporting tables it can produce informs users on the results of a data validation workflow. In this post we’ll go through how Pointblank:

enables you to validate many types of DataFrames and SQL databases
provides easy-to-understand validation result tables and thorough drilldowns
gives you nice previews of data tables across a range of backends

Validating data with Pointblank

Just like Great Tables, Pointblank’s primary input is a table and the goal of that library is to perform checks of the tabular data. Other libraries in this domain include Great Expectations , pandera , Soda , and PyDeequ .

Below is the main validation report table that users are likely to see quite often. Each row is a validation step, with columns reporting details about each step and their results.

Show the code

Style Table Body with `mask=` in `loc.body()`

Jerry Wu — Fri, 24 Jan 2025 00:00:00 +0000

In Great Tables 0.16.0, we introduced the mask= parameter in loc.body(), enabling users to apply conditional styling to rows on a per-column basis more efficiently when working with a Polars DataFrame. This post will demonstrate how it works and compare it with the “old-fashioned” approach:

Leveraging the mask= parameter in loc.body(): Use Polars expressions for streamlined styling.
Utilizing the locations= parameter in GT.tab_style(): Pass a list of loc.body() objects.

Let’s dive in.

Preparations

We’ll use the built-in dataset gtcars to create a Polars DataFrame. Next, we’ll select the columns mfr, drivetrain, year, and hp to create a small pivoted table named df_mini. Finally, we’ll pass df_mini to the GT object to create a table named gt, using drivetrain as the rowname_col= and mfr as the groupname_col=, as shown below:

Show the Code

Updates to Text Rendering in R Graphics

Thomas Lin Pedersen — Fri, 17 Jan 2025 00:00:00 +0000

text rendering is one of those disciplines where, if you think you finally got it right, you can be 100% certain that you didn't
— Thomas Lin Pedersen (@thomasp85.com) January 10, 2025 at 10:44 AM

No reason to hide the fact: Text rendering is complicated! When I set out to improve the support for modern text rendering features in R all those years ago, I don’t think I truly appreciated that fact. And probably for the better, since I’m not sure I would have taken on the task had I known.

Taking the quote above as a universal truth (it comes from a reputable source after all), I’m sure I’ll never be fully done, but recent work on the whole stack at least makes me worry less about the correctness. This post will go through the changes that span the systemfonts , textshaping , and marquee packages and let you now how you, as a user or developer, should take advantage of them.

Working with non-installed fonts

The genesis of the systemfonts package was a need to be able to tap into the operating systems font library, so that whatever was installed on the system, would be available to graphics devices (assuming those devices used systemfonts). The scope of the package has gradually increased, and one of the needs that has become obvious over time, is a way to work with fonts, that aren’t installed on the system (E.g. if you want to bundle a font with a package, or if you are deploying a Shiny app that uses a specific font for the graphics).

Until now, the register_font() and register_variant() functions have been the only option for letting systemfonts know about fonts other than those installed on the system. However, both of these functions were designed to circumvent limitations in the R graphics system when it comes to font selection (e.g. no way to use a “thin” font variant as the only weight option in the graphics system is bold yes/no), and as such were clunky to use for introducing new fonts.

With the new version of systemfonts we get a dedicated way to tell systemfonts “please consider these font files as equals to the installed ones”. The function is called add_fonts() and all you need to do is to pass in a vector of paths to font files and these will then be reachable by systemfonts.

1
2


# Add fonts from specific files
systemfonts::add_fonts(c("path/to/font1.ttf", "path/to/font2.ttf"))

In addition to this function, systemfonts also comes with scan_local_fonts() that looks in ./fonts and ~/fonts and adds any fonts located there. The function is called when systemfonts is loaded meaning that you can immediately uses fonts saved in these directories. This is great for deploying projects because all you need to do is to include a fonts folder at the root of you project and these fonts will then always be available wherever you deploy your code.

While it is nice to have good access to the font files on your computer, the files has to come from somewhere. Nowadays that somewhere is usually Google Fonts or some other online font repository. systemfonts is now aware of a few of these repositories (Google Fonts and Font Squirrel for now), and can search and download from these (using search_web_fonts(), get_from_google_fonts(), and get_from_font_squirrel()). The downloaded fonts are automatically added using add_fonts() so they are immediately available, and by default they are placed in ~/fonts so that they persist across R sessions and projects.

1
2
3


# Search and download fonts
systemfonts::get_from_font_squirrel("Quicksand")
systemfonts::get_from_google_fonts("Rubik Moonrocks")

But what if you don’t want to think too much about all these details and just want to ensure that some specific font is available when a piece of code is running? In that case require_font() got you covered. This function allows you to state a dependency on a font in a script. The function scans the available fonts on the system and, if it doesn’t find anything, proceeds to look for the font in the online repositories, downloading it if it finds it. If that also fails the function will either throw an error, or map the required font to a fallback of your choosing:

1
2
3
4
5


library(systemfonts)
require_font("Rubik Moonrocks")

plot.new()
text(0.5, 0.5, "Fancy Font", family = "Rubik Moonrocks", cex = 6)

Remember that all of these niceties only goes into effect if you use a graphics device that uses systemfonts. For now, that more or less means that you should use ragg (you should use ragg anyway so that is not a terrible requirement).

Getting to the Glyphs

Most fonts these days are based on a vector outline. That means that they can be scaled smoothly to any size and doesn’t take up a lot of storage space. It also means that there are polygons inside the font files and that these can be extracted! This is now possible with systemfonts and the new glyph_outline() and glyph_raster() functions.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


# Get the location of the glyph inside the font
moonrocks <- font_info("Rubik Moonrocks")
G <- glyph_info("G", path = moonrocks$path, index = moonrocks$index)

# Extract the outline of the glyph and plot it
outline <- glyph_outline(G$index, moonrocks$path, moonrocks$index, size = 400)
grid::grid.path(
  x = outline$x,
  y = outline$y + 20, # To raise the baseline a bit
  id = outline$contour,
  default.units = "bigpts",
  gp = grid::gpar(fill = "grey", col = "black", lwd = 4)
)

Extracting them as polygons means that we can do all sorts of weird stuff with them if we so pleases:

1
2
3
4
5
6
7
8


# Skew the glyph making it italic
grid::grid.path(
  x = outline$x + outline$y * 0.4,
  y = outline$y + 20, # To raise the baseline a bit
  id = outline$contour,
  default.units = "bigpts",
  gp = grid::gpar(fill = "grey", col = "black", lwd = 4)
)

(real italic glyphs are designed to look good skewed, not just skewed versions of the regular glyphs)

Remember how I said “most fonts” in the beginning of this section. There are still fonts that do not provide an outline, the prime example being most emoji fonts. The glyphs in such fonts are encoded as multiple bitmaps at fixed sizes (Microsofts emoji font going a different way by encoding them as SVGs). Since we can’t get to the data as outlines we can instead extract it as a raster:

1
2
3
4


emoji <- font_info("emoji")
dancer <- glyph_info("💃", path = emoji$path, index = emoji$index)
raster <- glyph_raster(dancer$index, emoji$path, emoji$index, size = 400)
grid::grid.draw(glyph_raster_grob(raster[[1]], 0, 50))

In the above we used the glyph_raster_grob() helper function to create a raster grob with the correct scaling of the resulting raster.

Raster extraction is not only for bitmap encoded fonts since it is easy to go from an outline to a raster (but not the other way around). Freetype (which systemfonts uses) includes a very efficient scanline rasterizer (the same as used in ragg) and we can thus get a raster version of any font:

1
2


raster2 <- glyph_raster(G$index, moonrocks$path, moonrocks$index, size = 400)
grid::grid.draw(glyph_raster_grob(raster2[[1]], 0, 20))

The Way the Text Flows

The thing that provoked me to writing the quote in the beginning of this blog post, was my work on the textshaping package. This package is largely invisible to the user but together with systemfonts it is responsible for laying out strings of text correctly. It figures out the location of every glyph and finds alternative fonts if the selected one doesn’t contain the needed glyph. textshaping powers ragg as well as marquee, doing the heavy lifting of translating a string of text into glyphs and locations.

Part of converting a string into glyphs and coordinates (a process known as text shaping) is to figure out which way the text flows and act accordingly. For many people left-to-right flow is the natural text direction, but this is merely a cultural bias and many scripts with a different flow exists (arabic and hebrew being the two most dominant right-to-left flowing scripts). So, part of shaping requires figuring out what script a specific character belongs to and what direction it flows. This is all fairly simple when a string internally agrees on the direction of flow, but can get much more complicated when scripts are embedded within other scripts that doesn’t have the same flow (not to mention scripts embedded even deeper). Combine all of this with soft wrapping of text inside an embedded script and you got the recipe for a headache. textshaping (through me) already made the claim that it fully supported bi-directional text but it turned out that I severely misjudged the complexity. Because of this, the shaping engine has been rewritten almost from scratch. Based on the starting quote I can’t quite claim that it now works 100% correctly but it does pass all 91.707 test cases for bidirectional text provided by the Unicode consortium so there’s that.

Again, it is unlikely that you will come into contact with textshaping directly so you will mostly experience these improvements in the way text just appears more correct (to the extend that this was ever an issue for you). The place you are most likely to stumble upon these changes is marquee, which uses textshaping under the hood. Styling in marquee has been expanded to include a text_direction setting. It defaults to "auto" which mean “deduce it from the text you get”, but you can also set it to "ltr" or "rtl" to set the direction explicitly. Be aware that this setting doesn’t change how single glyphs flow so you cannot use it to e.g. write arabic in left-to-right flow. Instead it governs the paragraph-level direction and thus how bi-directional text should be assembled. It also governs to which side indentation happen and the placement of bullets in bullet lists. Often, leaving it on the default value will work fine. There are also two new values for the align setting. "auto" picks either "left" or "right" depending on the text direction, while "justified" picks either "justified-left" or "justified-right". This makes it much easier to work natively with right-to-left text as everything just looks as it should. To top it off, classic_style() gains an ltr argument that controls whether the styling in general should cater to left-to-right or right-to-left text. It controls things such as the position of the grey bar in quotation blocks and the indentation of nested lists.

1
2
3
4
5
6
7


library(marquee)
# Create a style specific for rtl text
rtl_style <- classic_style(
  text_direction = "rtl", # Forces bidi text to be assembled from right to left
  align = "auto", # Will convert itself to "right"
  ltr = FALSE # Will move bullet padding and bar along quote blocks to the right
)

A marquee for Everyone

Speaking of marquee, the biggest obstacle it has put in front of its users is that it is build on very new features in R. The ability to write text by placing glyphs one at a time was only added in R 4.2 and not every graphics device supports it yet (worse still, the implementation in the default macOS quartz device caused the session to crash). Again, ragg is your friend, but the Cairo devices also has excellent support.

Text rendering, however, should always work. It is quite frustrating for text to not show up when you expect it to. Because of this it has been a clear plan to expand the support for marquee somehow. With the new version of marquee this is finally a reality. How does it work? Well, remember when we talked about extracting glyph outlines and rasters? If marquee encounters a graphics device that doesn’t provide the necessary features it will take matters into its own hands, by extracting all the necessary polygons and bitmaps and plot them. It is certainly not faster than relying on the optimized routines of the graphics device and it can also lead to visual degradation at smaller font sizes. But it works - everywhere.

To show it off, here is an svg created with svglite which doesn’t have the required new features:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


text <- "_Fancy_ {.red Font}📝"

m_grob <- marquee_grob(
  text,
  classic_style(
    body_font = "Rubik Moonrocks",
    base_size = 72
  )
)

s <- svglite::svgstring(width = 7, height = 1.5)
grid::grid.draw(m_grob)
invisible(dev.off())

s()

If you inspect the SVG above you’ll see that rather than being made up of text elements it is a collection of path and image elements.

Again, it is unlikely that many people will use marquee like this. It is much more likely that they will encounter it through ggplot2 in the form of geom_marquee() and element_marquee(). The takeaway, however, is the same - it is now safe to use marquee even when you don’t know which graphics device will be used to render the text with.

What’s Next?

Circling back to the starting quote. I’m 100% certain I’m not done yet. I believe the next big push will be proper support for vertical text in textshaping (it currently only deals with horizontal text). I also have some plans to get marquee to automatically translate the numbers in ordered lists into their proper representation in the script that is being used, so that e.g. ‘3.’ will be shown as ‘.٣’ when used with Arabic text.

Contributing to Public Transit Data Analysis and Tooling

Michael Chow — Thu, 19 Dec 2024 00:00:00 +0000

Hello! Michael Chow here. In 2025, I’ll be focusing on contributing to open source data standards and tooling for public transit. If you work on analytics at a public transit agency, please reach out on linkedin or bluesky —I would love to hear about your work, and how I could be useful!

(I will also be at the TRB Annual Meeting 2025 in Washington D.C.)

At this point, you might be wondering three things:

why focus on open source in public transit?
why is this on the Great Tables blog?
what are you hoping to contribute?

Why focus on open source in public transit?

People doing analytics in public transit are active in developing open data standards (like GTFS, GTFS-RT, and TIDES). These open data sources are complex—they cover schedules that change from week to week, buses moving in realtime, and passenger events. As people like me work more and more on open source tools, we start to lose touch with data analysis in realistic, complex settings. Working on open source transit data is an opportunity for me to ensure my open source tooling work helps people solve real, complex problems.

An inspiration for this angle is the book R for Data Science , which uses realistic datasets—like NYC flights data—to teach data analysis using an ecosystem of packages called the Tidyverse. The Tidyverse packages have dozens of example datasets, and I think this focus on working through examples is part of what made their design so great.

A few years ago, I worked with the Cal-ITP project to build out a warehouse for their GTFS schedule and realtime data. This left a profound impression on me: transit data is perfect for educating on data analyses in R and Python, as well as analytics engineering with tools like dbt or sqlmesh. Many analysts in public transit are querying warehouses, which opens up interesting use-cases with tools like dbplyr (in R) and ibis (in Python).

(I’m also inspired by tools like tidytransit , and other communities like pharmaverse.org .)

Here are some relevant talks:

Why is this on the Great Tables blog?

It gives me the opportunity to show off a lot of interesting, transit related tables!

Great Tables data: Paris metro lines

If you’ve seen the Great Tables documentation for GT.fmt_image(), then you’ve basked in this beautiful example from our Paris dataset.

Code

Great Tables `v0.15.0`: Flags, Icons, and Other Formatting Goodies

Rich Iannone — Thu, 19 Dec 2024 00:00:00 +0000

The development of Great Tables is really moving along these days. We just released version 0.15.0 and it adds quite a few nice things to the package. The features we’ll highlight in this post are:

adding flag icons with the new fmt_flag() method
peppering your table cells with Font Awesome icons via fmt_icon()
support for displaying accounting notation with four number-based formatting methods

Let’s look at each of these in turn!

Using `fmt_flag()` to incorporate country flag icons

When tables contain country-level data, having a more visual representation for a country can help the reader more quickly parse the table contents. The new fmt_flag() method makes this easy to accomplish. You just need to have either two-letter country codes or three-letter country codes in a column.

Here’s an example where country flags, shown as simplified circular icons, can be added to a table with fmt_flag():

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26


from great_tables import GT
from great_tables.data import peeps
import polars as pl

peeps_mini = (
    pl.from_pandas(peeps)
    .filter(pl.col("dob").str.slice(offset=0, length=4) == "1988")
    .with_columns(name=pl.col("name_given") + " " + pl.col("name_family"))
    .fill_null(value="")
    .select(["country", "name", "address", "city", "state_prov", "postcode"])
)

(
    GT(peeps_mini)
    .tab_header(title="Our Contacts (Born in 1988)")
    .fmt_flag(columns="country")
    .opt_vertical_padding(scale=0.5)
    .cols_label(
        country="",
        name="Name",
        address="Address",
        city="City",
        state_prov="State/Prov.",
        postcode="Zip/Postcode",
    )
)


Name	Address	City	State/Prov.	Zip/Postcode
Martin Bartůněk	1850 Valley Lane	Austin	TX	78744
Feride Šijan	Tavcarjeva 58	Sodražica		1317
Vejsil Crevar	Gosposka ulica 60	Novo mesto		8501
Matilda Bates	582 Islington Ave	Toronto	ON	M8V 3B6

This slice of the peeps dataset has country codes in their 3-letter form (i.e., "USA", "SVN", and "CAN") within the country column. So long as they are correct, fmt_flag() will perform the conversion to flag icons. Also, there’s a little bit of interactivity here: when hovering over a flag, the country name will appear as a tooltip!

We have the power to display multiple flag icons within a single cell. To make this happen, the country codes need to be combined in a single string where each code is separated by a comma (e.g., "US,DE,GB"). Here’s an example that uses a portion of the films dataset:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


from great_tables import GT, google_font
from great_tables.data import films
import polars as pl

films_mini = (
    pl.from_pandas(films)
    .filter(pl.col("director") == "Michael Haneke")
    .with_columns(title=pl.col("title") + " (" + pl.col("year").cast(pl.String) + ")")
    .select(["title", "run_time", "countries_of_origin"])
)

(
    GT(films_mini)
    .fmt_flag(columns="countries_of_origin")
    .tab_header(title="In Competition Films by Michael Haneke")
    .opt_stylize()
    .tab_options(column_labels_hidden=True)
    .opt_table_font(font=google_font("PT Sans"))
)

In Competition Films by Michael Haneke
Funny Games (1997)	1h 48m
Code Unknown (2000)	1h 58m
The Piano Teacher (2001)	2h 11m
Caché (2005)	1h 57m
The White Ribbon (2009)	2h 24m
Amour (2012)	2h 7m
Happy End (2017)	1h 47m

The column countries_of_origin has these combined strings for each of the co-production films, where countries are arranged by decreasing level of contribution (e.g., "FR,AT,RO,DE" in the second row). The fmt_flag() method parses these strings into a sequence of flag icons that are displayed in the order provided. Each of the flags is separated by a space character but you can always change that default separator with the sep= argument.

Using `fmt_icon()` to include Font Awesome icons

The new fmt_icon() method gives you the ability to easily include Font Awesome icons in a table. It uses a similar input/output scheme as with fmt_flag(): provide the short icon name (e.g., "table", "music", "globe", etc.) or a comma-separated list of them, and fmt_icon() will provide the Font Awesome icon in place. Let’s see it in action with an example that uses the metro dataset:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25


from great_tables import GT
from great_tables.data import metro
import polars as pl

metro_mini = (
    pl.from_pandas(metro).tail(10)
    .with_columns(
        services = (
            pl.when(pl.col("connect_tramway").is_not_null())
            .then(pl.lit("train, train-tram"))
            .otherwise(pl.lit("train"))
        )
    )
    .select(["name", "services", "location"])
)

(
    GT(metro_mini)
    .tab_header("Services Available at Select Stations")
    .fmt_icon(columns="services", sep=" / ")
    .tab_options(column_labels_hidden=True)
    .opt_stylize(color="green")
    .opt_horizontal_padding(scale=3)
    .opt_align_table_header(align="left")
)

Services Available at Select Stations
Porte de Vanves	/	Paris 14th
Saint-Denis—Porte de Paris	/	Saint-Denis
Saint-Denis—Université	/	Saint-Denis
Saint-François-Xavier		Paris 7th
Varenne		Paris 7th
Bibliothèque François Mitterrand	/	Paris 13th
Cour Saint-Émilion		Paris 12th
Olympiades		Paris 13th
Pont Cardinet		Paris 17th
Saint-Ouen		Clichy, Saint-Ouen-sur-Seine

In the code, we added in the icon names "train" and "train-tram" to the services column, and there could either be just the train icon or the pair that includes the tramway service. We wanted a little separation between the icons in the latter case, so sep=" / " was used to place a slash with spacing between any pair of icons. The icons appear here with a black fill color, but that can be changed with the fill_color= argument (and there are several other arguments for controlling style attributes).

For a list of available icons, their names, and what they look like, check out this listing on the Font Awesome website . The icons draw from the Font Awesome ‘free’ set (2000+ icons in total) but are not obtained via the web. Rather, we use the faicons library so that this can be done entirely offline (directly using the SVG icons stored within faicons).

Accounting notation in select numeric formatting methods

For certain types of tables, it may be preferable to use accounting notation for numerical figures. This type of notation renders negative values in parentheses while omitting the minus sign. This is often seen for monetary and percentage figures but it’s also sensible for plain numbers in the right context. We’ve added support for accounting notation in four formatting methods:

fmt_number()
fmt_integer()
fmt_currency()
fmt_percent()

Here’s a comprehensive example table that demonstrates how this type of formatting looks.

Show the code

Rendering images anywhere in Great Tables

Jerry Wu — Fri, 13 Dec 2024 00:00:00 +0000

Rendering images in Great Tables is straightforward with GT.fmt_image() and vals.fmt_image(). In this post, we’ll explore three key topics:

Four examples demonstrating how to render images within the body using GT.fmt_image().
How to render images anywhere using vals.fmt_image() and html().
How to manually render images anywhere using html().

Rendering Images in the Body

GT.fmt_image() is the go-to tool for rendering images within the body of a table. Below, we’ll present four examples corresponding to the cases outlined in the documentation:

Case 1: Local file paths.
Case 2: Full HTTP/HTTPS URLs.
Case 3: Image names with the path= argument.
Case 4: Image names using both the path= and file_pattern= arguments.

Finding the Right Case for Your Needs

Case 1 and Case 2 work best for data sourced directly from a database.
Case 3 is ideal for users dealing with image names relative to a base directory or URL (e.g., /path/to/images).
Case 4 is tailored for users working with patterned image names (e.g., metro_{}.svg).

Preparations

For this demonstration, we’ll use the first five rows of the built-in metro dataset, specifically the name and lines columns.

To ensure a smooth walkthrough, we’ll manipulate the data (a Python dictionary) directly. However, in real-world applications, such operations are more likely performed at the DataFrame level to leverage the benefits of vectorized operations.

Show the Code

Great Tables: Generating LaTeX Output for PDF

Rich Iannone — Wed, 13 Nov 2024 00:00:00 +0000

We’ve been doing quite a bit of work on getting Great Tables to produce LaTeX table code and v0.14.0 introduces the as_latex() method to make this possible. For those publishing workflows involving LaTeX documents, it’s useful to have a reproducible solution for generating data tables as native LaTeX tables.

In this post, we will go over the following:

generating LaTeX table code: how we handle the different parts of a table
rendering to PDF with Quarto: integrating LaTeX table code into PDFs
current limitations and roadmap: what has been implemented, and what is left

Generating a LaTeX table with Great Tables

We can use the GT.as_latex() method to generate LaTeX table code. This code includes important structural pieces like titles, spanners, and value formatting. For example, here’s a simple table output as LaTeX code:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37


from great_tables import GT
from great_tables.data import gtcars
import polars as pl

gtcars_pl = (
    pl.from_pandas(gtcars)
    .select(["mfr", "model", "hp", "trq", "mpg_c", "msrp"])
)

gt_tbl = (
    GT(
        gtcars[["mfr", "model", "hp", "trq", "msrp"]].head(5),
    )
    .tab_header(
        title="Some Cars from the gtcars Dataset",
        subtitle="Five Cars are shown here"
    )
    .tab_spanner(
        label="Make and Model",
        columns=["mfr", "model"],
        id="make_model"
    )
    .tab_spanner(
        label="Performance",
        columns=["hp", "trq", "msrp"]
    )
    .tab_spanner(
        label="Everything but the cost",
        columns=["mfr", "model", "hp", "trq"]
    )
    .fmt_integer(columns=["hp", "trq"])
    .fmt_currency(columns="msrp")
    .tab_source_note("Cars are all 2015 models.")
    .tab_source_note("Horsepower and Torque values are estimates.")
)

print(gt_tbl.as_latex())

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28


\begin{table}
\caption*{
{\large Some Cars from the gtcars Dataset} \\
{\small Five Cars are shown here}
}

\fontsize{12.0pt}{14.4pt}\selectfont

\begin{tabular*}{\linewidth}{@{\extracolsep{\fill}}llrrr}
\toprule
\multicolumn{4}{c}{Everything but the cost} &  \\
\cmidrule(lr){1-4}
\multicolumn{2}{c}{Make and Model} & \multicolumn{3}{c}{Performance} \\
\cmidrule(lr){1-2} \cmidrule(lr){3-5}
mfr & model & hp & trq & msrp \\
\midrule\addlinespace[2.5pt]
Ford & GT & 647 & 550 & \$447,000.00 \\
Ferrari & 458 Speciale & 597 & 398 & \$291,744.00 \\
Ferrari & 458 Spider & 562 & 398 & \$263,553.00 \\
Ferrari & 458 Italia & 562 & 398 & \$233,509.00 \\
Ferrari & 488 GTB & 661 & 561 & \$245,400.00 \\
\bottomrule
\end{tabular*}
\begin{minipage}{\linewidth}
Cars are all 2015 models.\\
Horsepower and Torque values are estimates.\\
\end{minipage}
\end{table}

The returned LaTeX table code shows how some of Great Tables’ structural components are represented in LaTeX. Note these three important pieces of LaTeX code:

\caption*{ produces our title and subtitle (line 2)
the \multicolumn{ statements produce spanners (i.e., labels on top of multiple column labels) (line 11)
the values in the data are escaped, using \ (e.g., \$ represents a literal dollar sign) (line 17)

A frequent issue with any programmatic generation of LaTeX table code is LaTeX escaping. Not doing so can lead to LaTeX rendering errors, potentially breaking an entire publishing workflow. Great Tables will automatically escape characters in LaTeX, limiting such errors.

Using LaTeX output from Great Tables in Quarto

Producing LaTeX table code is especially handy when using Quarto to generate PDF documents. Quarto is a tool for publishing documents, websites, books, etc., with an emphasis on running Python code. It uses the .qmd file format, which is a superset of Markdown (.md).

Here’s an example .qmd file with these pieces in place:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


---
format: pdf
---

Using Great Tables in a Quarto PDF document.

```{python}
#| output: asis

from great_tables import GT, exibble

gt_tbl = GT(exibble)

print(gt_tbl.as_latex())
```

Notice that in the .qmd above we needed to have the following pieces to generate a PDF:

set "format: pdf" in YAML header
set "output: asis" in the code cell that’s outputting LaTeX table code
use the as_latex() method on a GT object and print() the text

The example above used a very simple table, but here’s the table from the previous example rendered to PDF in Quarto:

.qmd content

Version 0.14.0

Thu, 07 Nov 2024 00:00:00 +0000

Code - Imports

Great Tables `v0.13.0`: Applying styles to all table locations

Rich Iannone — Thu, 10 Oct 2024 00:00:00 +0000

We did something in Great Tables (0.13.0) that’ll make your tables that much more customizable: super fine-grained ways of setting styles throughout the table. Before you were largely constrained to styling through the following strategies:

use a limited set of styles (e.g., background color, font weight, etc.) to different table locations like the stub, the column labels, etc., through tab_options()
use tab_style() with a larger set of styling options for the table body cells (specified by loc.body())

In v0.13.0, we can target much more than just the table body! Here is the expanded set of loc.*() methods along with the locations that they can target.

This augmentation of the loc module to include all locations in the table means that there won’t be a spot in the table to which you can’t add styling. This is terrific because it gives you free rein to fully customize the look of your table.

Let’s make a table and see how this new feature could be used.

Starting things off with a big GT table

The table we’ll make uses the nuclides dataset (available in the great_tables.data module). Through use of the tab_*() methods, quite a few table components (hence locations) will be added. We have hidden the code here because it is quite lengthy but you’re encouraged to check it out to glean some interesting GT tricks.

Show the code

Great Tables `v0.12.0`: Google Fonts and zebra stripes

Rich Iannone — Mon, 30 Sep 2024 00:00:00 +0000

In Great Tables 0.12.0 we focused on adding options for customizing the appearance of a table. In this post, we’ll present two new features:

using typefaces from Google Fonts via tab_style() and opt_table_font()
adding table striping via tab_options() and opt_row_striping()

Let’s have a look at how these new features can be used!

Using fonts from Google Fonts

Google Fonts is a free service that allows use of hosted typefaces in your own websites. In Great Tables, we added the google_font() helper function to easily incorporate such fonts in your tables. There are two ways to go about this:

use google_font() with opt_table_font() to set a Google Font for the entire table
invoke google_font() within tab_style(styles=style.text(font=...)) to set the font within a location

Let’s start with this small table that uses the default set of fonts for the entire table.

Show the code

patchwork 1.3.0

Thomas Lin Pedersen — Fri, 13 Sep 2024 00:00:00 +0000

I’m excited to present patchwork 1.3.0, our package for creating multifigure plot compositions. This versions adds table support and improves support for “free"ing components to span across multiple grid cells.

You can install patchwork from CRAN with:

install.packages("patchwork")

You can see a full list of changes in the release notes

library(patchwork)
library(ggplot2)
library(gt)

Tables are figures too

The new and shiny feature of the release is that patchwork now has native support for gt objects, making it possible to compose beautifully formatted tables together with your figures. This has been made possible through Teun Van den Brand’s effort to provide grob output to gt. While this means that you can now pass in gt objects to wrap_elements() in the same way as other supported data types, it also goes one step further, using the semantics of the table design to add table specific formatting options through the new wrap_table() function.

But let’s take a step back and see how the simplest support works in reality:

p1 <- ggplot(airquality) +
  geom_line(aes(x = Day, y = Temp, colour = month.name[Month])) +
  labs(colour = "Month")

aq <- airquality[sample(nrow(airquality), 10), ]
p1 + gt(aq) + ggtitle("Sample of the dataset")

A few things can be gathered already from this small example. Tables can have titles (and subtitles, captions, and tags) like regular plots (in that sense they behave like wrap_elements() output). Also, and this is perhaps more interesting, patchwork is aware that the first row is special (a header row), and thus places that on top of the panel area so that the plot region of the left plot is aligned with the body of the table, not the full table.

Lastly, we see that tables often have a fixed size, contrary to plots which can shrink and expand based on how much room they have. Because of this, our table is overflowing it’s region in the plot above creating a not-so-great look.

Let’s see how we can use wrap_table() to control some of these behaviors. First, while we could decrease the font size in the table to make it smaller, we could also allow it some more space instead. We could do this by using plot_layout(widths = ...) but it would require a fair amount of guessing on our side to get it just right. Thankfully, patchwork is smart enough to figure it out for us and we can instruct it to do so using the space argument in wrap_table() . Setting it to "free_y" instructs it to fix the width to the table width but keep the height free:

p1 + wrap_table(aq, space = "free_y")

Setting space to "fixed" would constrain both the width and the height of the area it occupies. Since we only have a single row in our layout this would leave us with some empty horizontal space:

p1 + wrap_table(aq, space = "fixed")

If the space is fixed in the y direction and the table has any source notes or footnotes, these will behave like the column header and be placed outside the panel area depending on the panel setting

aq_footer <- gt(aq) |>
  tab_source_note("This is not part of the table body")
p1 + wrap_table(aq_footer, space = "fixed")

While the space argument is great for making the composition look good and the table well placed in the whole, it can also serve a different purpose of making sure that rows (or columns) are aligned with the axis of a plot. There are no facilities to ensure that the breaks order matches between plots and tables so that is the responsibility of the user, but otherwise this is a great way to use tables to directly augment a plot:

p2 <- ggplot(airquality) +
  geom_boxplot(aes(x = month.name[Month], y = Temp)) +
  theme(axis.text.x = element_blank(), axis.title.x = element_blank()) +
  scale_x_discrete(expand = c(0, 0.5))

# Construct our table
table <- rbind(
  tapply(airquality$Temp, airquality$Month, max),
  tapply(airquality$Temp, airquality$Month, median),
  tapply(airquality$Temp, airquality$Month, min)
)
colnames(table) <- month.name[5:9]
table <- data.frame(
  Measure = c("Max", "Median", "Min"),
  table
)
table <- gt(table, rowname_col = "Measure") |>
  cols_width(contains(month.name) ~ px(100)) |>
  cols_align(align = "center") |>
  cols_align(align = "right", columns = "Measure")

p2 / wrap_table(table, space = "fixed")

Circling back, there was another argument to wrap_table() we didn’t get into yet. In the plot above, we see that the row names are conveniently aligned with the axis rather than the panel of the plot above, in the same way as the headers where placed outside the panel area. This is a nice default and generally makes sense for the semantics of a table, but you might want something different. The panel argument allows you to control this exact behavior. It takes "body", "full", "rows", or "cols" which indicate what portion of the table should be inside the panel area. The default is "body" which places row and column names outside the panel. "full", on the contrary, places everything inside, while "rows" and "cols" are half versions that allows you to keep either column or row names outside the panel respectively.

# Place all rows (including the header row) inside the panel area
p1 + wrap_table(aq, panel = "rows", space = "free_y")

Just like the tables support ggplot2-like titles, they also support tags, meaning that patchworks auto-tagging works as expected. It can be turned off using the ignore_tag argument but often you’d want to treat it as a figure in the figure text:

p1 + wrap_table(aq, panel = "rows", space = "free_y") +
  plot_annotation(tag_levels = "A") &
  theme(plot.tag = element_text(margin = margin(0, 6, 6, 0)))

Accesibility

We truly believe that the features laid out above will be a boon for augmenting your data visualisation with data that can be read precisely at a glance. However, we would be remiss to not note how tables that are part of a patchwork visualisation doesn’t have the same accessibility featurees as a gt table included directly in e.g. an HTML output. This is because graphics are rasterised into a PNG file and thus looses all semantical information that is inherent in a table. This should be kept in mind when providing Alt text for your figures so you ensure they are legible for everyone.

Future

The support on the patchwork end is likely done at this point, but the conversion to grobs that has been added to gt is still somewhat young and will improve over time. It is likely that markdown formatting (through marquee) and other niceties will get added, leading to even more power in composing tables with plots using patchwork as the glue between them. As with the support for gt in typst the support for gt in patchwork is part of our larger effort to bring the power of gt to more environments and create a single unified solution to table styling.

With freedom comes great responsibility

The second leg of this release concerns the free() function which was introduced in the last release. I devoted a whole section of my posit::conf talk this year to talk about free() and how it was a good thing to say no to requests for functionality until you have a solution that fits into your API and doesn’t add clutter. I really like how the API for free() turned out but I also knew it could do more. In this release it delivers on those promises with two additional arguments.

Which side?

As it were, free() could only be used to completely turn off alignment of a plot, e.g. like below:

p1 <- ggplot(mtcars) +
  geom_bar(aes(y = factor(gear), fill = factor(gear))) +
  scale_y_discrete(
    "",
    labels = c("3 gears are often enough",
               "But, you know, 4 is a nice number",
               "I would def go with 5 gears in a modern car")
  )
p2 <- ggplot(mtcars) + geom_point(aes(mpg, disp))

free(p1) / p2

We can see that panel alignment has been turned off both to the left and to the right (and top and bottom if it were visible). But perhaps you are only interested in un-aligning the left side, keeping the legend to the right of both plots. Now you can, thanks to the side argument which takes a string containing one or more of the t, r, b, and l characters to indicate which sides to apply the freeing to (default is "trbl" meaning “target all sides”).

free(p1, side = "l") / p2

Freeing works inside nested patchworks, where you can target various sides at various levels:

p3 <- ggplot(mtcars) +
  geom_boxplot(aes(y = factor(gear), disp)) +
  scale_y_discrete(
    "",
    labels = c("... and 3",
               "4 of them",
               "5 gears")
  )


nested <- p2 / free(p1, side = "l")

free(nested, side = "r") /
  p3

What does “freeing” means anyway?

While being able to target specific sides is pretty great in and off itself, we are not done yet. After being able to not align panels the most requested feature was the possibility of moving the axis title closer to the axis text if alignment had pushed it apart. Consider again our unfreed patchwork:

p1 / p2

While we can “fix” it by letting the top panel stretch, another way to improve upon it would be to move the dangling y-axis title of the bottom plot closer to the axis. Enter the type argument to free() which informs patchwork how to not align the input. The default ("panel") works just as free() always has, but the other two values opens up some new nifty goodies. Setting type = "label" does exactly what we discussed above, freeing the label from alignment so it sticks together with the axis and axis text:

p1 /
  free(p2, type = "label")

The other type is "space" which works slightly different. Using this you tell patchwork to not reserve any space for what the side(s) contain. This is perfect in situation where you already have empty space next to it that can fit the content. Consider this plot:

plot_spacer() + p1 +
  p2 + p2

Ugh, the axis text of the top plot pushes everything apart even though there is ample of space for it in the empty region on the left. This is where type = "space" comes in handy:

plot_spacer() + free(p1, type = "space", side = "l") +
  p2 + p2

Of course, such power comes with the responsibility of you ensuring there is actually space for it — otherwise it will escape out of the figure area:

free(p1, type = "space", side = "l") /
  p2

All the different types of freeing can be stacked on top of each other so you can have a plot that keeps the left axis label together with the axis while also stretches the right side to take up empty space:

p1 /
  free(free(p2, "panel", "r"), "label", "l")

But as always, don’t go overboard. If you find yourself needing to use an elaborate combination of stacked free() calls there is a good chance that something with your core composition needs rethinking.

The rest

The above are the clear highlights of this release. It also contains the standard bug fixes — especially in the area of axis collecting which was introduced in the last release and came with a bunch of edge cases that were unaccounted for. There is also a new utility function: merge() which is an alternative to the - operator that I don’t think many users understood or used. It allows you to merge all plots together into a nested patchwork so that the right hand side is added to a new composition.

Acknowledgements

Thank you to all people who have contributed issues, code and comments to this release:

@BenVolpe94 , @daniellembecker , @dchiu911 , @ericKuo722 , @Fan-iX , @IndrajeetPatil , @jack-davison , @karchern , @laresbernardo , @marchtaylor , @mariadelmarq , @Maschette , @michaeltopper1 , @mkoohafkan , @n-kall , @person-c , @pettyalex , @petzi53 , @phispu , @psychelzh , @rinivarg , @selkamand , @Soham6298 , @svraka , @teng-gao , @teunbrand , @thomasp85 , @timz0605 , @wish1832 , and @Yunuuuu .

Visualization on Posit Open Source

Recreating Septa Transit Timetables in Python

The final result

ggplot2 styling

So you want to style your plot?

What is a theme?

Complete themes

Built-in themes

ggplot2 4.0.0

Adopting S7

Theme improvements

Ink and paper

Scales and palettes

Shortcuts

New settings

Labels

Discrete scales

Position aesthetics

Facets

Wrapping directions

Free space in wrapping

Layer layout

Styling updates

Boxplots

Violin & quantiles

Labels

Area and ribbons

New stats

Manual

Connection

Coord reversal

Goodies for extensions

Layers

Themes

Acknowledgements

Great Tables `v0.18.0`: Easy Column Spanners and More!

Quick spanner creation with tab_spanner_delim()

Beautiful boolean formatting with fmt_tf()

Rotating column labels with cols_label_rotate()

Enhanced datetime formatting with fmt_datetime()

Acknowledgements and what’s next

Adding Plots to Great Tables

Great Tables + marimo = Interactive Tables

Interactive Table Demo

marimo Showcases the Integration

marimo + Quarto Integration

Wrapping Up

svglite 2.2.0

Graphics engine support

Stroking and filling complex paths

Groups

Glyphs

Font embedding

Acknowledgements

scales 1.4.0

Colour manipulation

Palettes

Providing palettes as package

Labels

Acknowledgements

Great Tables: Becoming the Polars `.style` Property

How we got there

First contact: Polars discord

Jerry Wu: power contributor

Growing up: making the case for .style

Making .style work

Design credibility

Working with Polars selectors

Technical wiring work

What’s next?

In conclusion

How We Used Great Tables to Supercharge Reporting in Pointblank

Validating data with Pointblank

Style Table Body with `mask=` in `loc.body()`

Preparations

Updates to Text Rendering in R Graphics

Working with non-installed fonts

Getting to the Glyphs

The Way the Text Flows

A marquee for Everyone

Quick spanner creation with `tab_spanner_delim()`

Beautiful boolean formatting with `fmt_tf()`

Rotating column labels with `cols_label_rotate()`

Enhanced datetime formatting with `fmt_datetime()`

Growing up: making the case for `.style`

Making `.style` work

Using `fmt_flag()` to incorporate country flag icons

Using `fmt_icon()` to include Font Awesome icons