Designing ggtime: a grammar of temporal graphics

[mitchelloharawild]

Thanks for joining my extenders presentation about ggtime design! I hope sharing my development-stage design process and hearing from others was insightful, and not too chaotic!

There's clearly a lot of work ahead for implementation, so I really appreciate everyone's design contributions.
I'm hoping for 'measure twice, cut once' for the implementation of this package. 🪚 🤞

I've created response comment threads for each of the presentation's design discussion questions. If you have any thoughts after the talk, we can continue the discussion here 💬

[mitchelloharawild]

Discussion topic 1: grammar design for temporal alignment

A core design element of ggtime is temporal alignment, which can be used to more clearly show seasonal and cyclical patterns.

There are three types of alignment in the package design:

• timezone alignment (local time)

  Timezones are make global temporal analysis hard.

  When comparing human behaviour around the world (e.g. when people eat dinner), it is far more informative to compare the local time of all countries.

  This is also critically important when working with hourly data (or sub-hourly), because daylight savings shifts will mis-align seasonal patterns when computed with absolute modular arithmetic (e.g. 24 hours, when there can be 23 or 25 hours in a day).

• granularity alignment (mixed precision)

  A key feature of {mixtime} is mixing time calendars.

  {mixtime} offers other Gregorian 'calendars' including weekly, monthly, quarterly, and annual data (all in the same vector). This is a more precise solution to the otherwise standard option of using the first moment of each granularity (e.g. 2025-01-01 to represent Jan 2025, or 2025-01-01 01:00:00 to represent hour 1 of 2025.

  This left alignment of data for higher granularities carries through to most time-series plots.

  Instead of left alignment, {ggtime} uses center alignment (centered by temporal mass) by default. An option is planned to change this alignment to left, center, right, or any percentage in-between.

• cycle alignment (warping)

  This is more novel alignment option planned for ggtime which does not (yet) correspond to a commonly used plot, however warping (or 'dynamic time warping') is commonly used in modelling for speech, gesture, and other time series classification/clustering problems.

  The idea here is to regularise irregular temporal durations to have the same length. At its simplest, this would be a linear rescaling of time/period_duration. The result would be converting something irregular (e.g. days in each month) to something regular (e.g. percentage through month) to better align cyclical patterns.

The broad question is, where do each of these alignment options belong within ggplot2's layered grammar of graphics? I can justify each of these existing in different places, ranging from geom, stat, position, and scale.

Relevant slides: https://slides.mitchelloharawild.com/ggextenders-ggtime/#/section-19

[mitchelloharawild]

Related notes from discussions

• @mjskay expressed some concerns about ggtime/ggdist interoperability if some of these alignment tools are implemented as a stat.
• It seems many of these operations can belong in scale, which primarily would be beneficial for keeping temporal dimension manipulation independent of others (e.g. distributions)
• I'm still unsure about the role of position for any of these alignment problems. I'll do more searching into different uses of position, but my impression is that position is rarely used outside of dodged/stacked bar charts by end-users.

[teunbrand]

w.r.t. warping; wouldn't a helper function suffice so that you can directly do aes(x = warp(time), ...)? If it is just a univariate, one-way transformation that cannot (easily) be reversed, I'd argue that casting this as a grammar component might become an overengineered solution perhaps.

[mitchelloharawild]

I think directly warping time as suggested is reasonable. I see it as equivalent to treating it as a data pre-processing step, so this would put it in the data layer in the grammar. I do think there is some value in keeping the original temporal nature of the data input, but I haven't thought too deeply about it for warping yet.

[mitchelloharawild]

Discussion topic 2: calendar coordinate systems

I expect this design idea to be the most technically challenging, but the best payoff as an elegant and general solution to the problem.

Creating calendars in ggplot2 has been a long-standing challenge that many have taken on to varying extents. @cynthiahqy featured many monolithic calendar plot helpers in this blog https://www.cynthiahqy.com/posts/ggplot-helper-design, and was inspired to try creating one herself https://cynthiahqy.github.io/ggtilecal/.

The scope of my calendar ambitions go beyond just plotting tile-based calendars. Instead I want to support arbitrary plot types within a calendar layout, the closest attempt to this is facet_calendar() and frame_calendar() from https://github.com/earowang/sugrrants.

• facet_calendar() is excellent as a facet, however producing a facet for each day can be slow and visually bulky.
• The alternative frame_calendar() uses data pre-processing and plot post-processing to produce a calendar layout within a single panel. This allows for far greater customisation (at least for the package author), to produce a dense calendar layout with lower computational cost. The downside is that it is limited to simple line or point geometries due to the data pre-processing implementation.

The proposed coord_calendar() aims to generalise the approach of frame_calendar(), and integrate the calendar layout transformations into a coordinate system. Since the calendar coordinate system is essentially cartesian with extra layout, the coord_calendar() design nests an inner (default cartesian) coordinate system to do most of the drawing. This (as a stretch goal) allows other coordinate systems to be nested, such as polar and sf to produce some wacky calendars.

I'd appreciate some guidance on gtable and manipulating grobs, because I expect to run into many problems when creating coord_calendar(). Some early testing has revealed some odd inconsistencies in data handling between coord_cartesian() and coord_polar(), and I expect more difficulty with data handling and grob modification.

Data handling

To arrange the layout of the calendar coordinates, I will need the corresponding classed {mixtime} data for the plot -- however I'm not yet sure how/where to restore it. Since all sorts of transformations can be applied by other stats/scales/etc., I believe it is best to access the data as late as possible (likely after it has been transformed to plot coordinates).

Perhaps the scale's inverse transformation is suitable here? Since it will necessarily use scale_x/y_mixtime() I should have full design access to this.

Grob manipulation

To properly cut lines from one row into the next, I think it is safest / best to directly cut and manipulate the grobs during coordinate rendering.

One approach to implementing this is to use (or implement) a grob intersection tool, which would allow grobs to be cut arbitrarily based on intersection with a bounding box.

Is anyone aware of existing work in set manipulation with grobs, or can suggest alternative methods?

Relevant slides: https://slides.mitchelloharawild.com/ggextenders-ggtime/#/section-28

[EvaMaeRey]

fwiw, the ggcalendar project currently proposes using faceting by month, w/ calculated a day-of-week (x) week (y), and date (label - default_aes only) by StatCalendar. But it never felt satisfactory - while you could aes(date = date_var) and have positions within month taken care of with geom_text(stat = StatCalendar), but then had to do the additional step of facet_wrap(~month(date_var)). It felt like an facet_wrap(~after_stat(year_month) move -- looking at the stat-transformed data -- would be super convenient, but I don't think there's an avenue for that. (right?)

To push the project a little further (which is like the easy space of discrete dates and not continuous time), I think writing a position (position_wrap_months) to offset by month, or just further developing StatCalendar (to do the month spatial offset as a second computation) is probably nicer (even though, facet_* does such nice things with axis labels, strips, etc)...

[teunbrand]

I don't think there's an avenue for that

No, panels are assigned even before undelayed aesthetics are evaluated.

[EvaMaeRey]

Right. Makes sense.

[EvaMaeRey]

geom_sf and stat_sf are interesting in their use of assumed variable geometry. Using assumed variable date, and bundling facet and Stat could be a way forward for ggcalendar. But I don't really like sf's assumed variables that much. In case of sf at least you can declare `aes(geometry = my_geometry_col) in the case that var assumption isn't true.

But aes(date = my_date_col) alone wouldn't be the, at least with a simple facet-stat bundle.

[mitchelloharawild]

I think you don't necessarily need to do grob manipulation if you can do the data handling in a smart way. I think it should be possible in Coord$transform to cut groups into separate days to break lines.

The reason why I've looked toward grob manipulation is because I don't want to cut the groups into separate days/weeks/months in the calendar. If a line crosses between weeks, it is best if it is partially drawn up until the end of the week and continued into the next week. This is more a problem for other geometries such as rectangles (e.g. multi-day event boxes) aren't necessarily neatly contained within days/weeks.

I think nested layouts might be a little bit ambitious for your first coord extension. There is nothing wrong with a little ambition, but I'd recommend to play around with a more tractable coord extension first to get a feel of how data flows in and out the class.

It's definitely ambitious, and this is why I wanted to bring it up with this discussion group to gauge feasibility and appropriateness of nested coordinate layouts.

A simpler coord extension which I'll start grob manipulation with would be wrapping time (topic 3) implemented as a coord. In this case the layout simply matches the original data, and only the grobs are repositioned for overplotting.

Another thing that you could consider is to package coord/facets together (like a geom_sf()/coord_sf() situation) to achieve a calendar layout. I imagine the coord system would do the per-month layout and the facet system might just cut the time data into monthly bins.

Yes, I've considered this. The idea is that coord_calendar() and facet_*() could be mixed to offer different layout options. In particular, I think coord_calendar() should produce an extremely dense layout (with no margins between days/weeks/months) - then combined with facet_*() can introduce these gaps.

[mitchelloharawild]

Discussion topic 3: wrapping time

Wrapping time to produce seasonal plots can be accomplished in many ways.

Consider producing polar seasonal plots with this neat hack from @teunbrand: #36 (reply in thread)

library(ggplot2)
tsibble::as_tsibble(USAccDeaths) |> 
  ggplot(aes(
    x = lubridate::month(index) + lubridate::year(index) * 12,
    y = value,
    colour = lubridate::year(index),
    group = 1)
  ) + 
  geom_line() + 
  scale_x_continuous(
    breaks = scales::breaks_width(1),
    limits = c(0, 12), oob = scales::oob_keep
  ) +
  labs(x = "Month", y = "United States accidental deaths", colour = "Year") +
  coord_polar()
#> Registered S3 method overwritten by 'tsibble':
#>   method               from 
#>   as_tibble.grouped_df dplyr

^{Created on 2024-12-12 with reprex v2.1.1}

This works (I think at least) by creating a plot only of the first year, and allowing the rest of the line to be plotted outside of the plot window. However in polar coordinates, the lines wrap around themselves and are overplotted over the previous years. Very tricky, but efficient and would have solved many challenges similar to ggperiodic 😍.

Ideally, a similar trick (or less hacky implementation) could be applied to produce season plots in cartesian coordinates. Where instead of running off the end of the plot, it wraps around to the start (or teleports).

There are many ways I can imagine this being achieved, including:

• data pre-processing, much like ggperiodic. This is how I currently do it in the implementation monstrosity of gg_feasts() - there are so many issues with this that I don't want to repeat!

  Pre-processing the data would also introduce limitations for interactivity with other graphical elements. For example, without an origin you cannot (reliably) adjust for daylight savings time and leap years.

• position might be usable to reposition/add a few time points that can create a line between years, however this doesn't seem robust to other types of geometries

• coordinate to me feels like the best way forward, as it is essentially the same issue as coord_calendar() but without the calendar layout. The same grob manipulation can be used to cut and overplot arbitrary grobs.

Relevant slides: https://slides.mitchelloharawild.com/ggextenders-ggtime/#/section-32

[mitchelloharawild]

Related notes from discussions

While we didn't get to this discussion (and I didn't plan to!), some earlier conversation was relevant.

• Some implementation concerns were raised for interoperability with other geoms (e.g. cutting between wraps). Using a similar implementation to coord_calendar() seems to be the safest approach.

[mjskay]

Re: interoperability with ggdist: some things that come to mind:

1. If some of what you have ends up in stats, there may be difficulties with interoperability with {ggdist} unless some version of "chained stats" ends up existing (which I would like to exist, so maybe that's a good reason to push that forward).
2. Currently ggdist's approach to xdist / ydist is very hacky in that it sometimes requires manually training the x/y scale at the layer level, which {ggdist} almost certainly should not be doing (sorry @teunbrand). I would love for there to be a properly sanctioned way to do this. See here.

[teunbrand]

Re: chained stats: tidyverse/ggplot2#6326

[EvaMaeRey]

Another easy-to-understand use-case might be rank -> bump... So StatBump only does the smoothing out for you, as you move across x and ranks should be computed prior to plotting, 'prep'. https://github.com/davidsjoberg/ggbump?tab=readme-ov-file#prep But chaining StatRank (though it doesn't yet exists, though maybe) and StatBump would give you the classic bump chart in a layer w/ ggbuilder or 6326?

[teunbrand]

I'm also secretly plotting to absorb {ggbump}-like functionality into ggplot2. But yeah that sounds sensible to me, I like it! I had also contemplated a position_rank() at some point that would work kinda like position_jitter() but instead of giving points a small jitter, you sort points around a central location from high to low (or vice versa).

[mjskay]

Re: chained stats: tidyverse/ggplot2#6326

Oh sweet, thanks @teunbrand!

[EvaMaeRey]

{ggbump}-like functionality

connecting points in a smooth way is pretty useful functionality.

position_rank()

so then you need to declare x, y, and rank aes? I don't think I've come across such a graph (is it an idiom? or more novel!?) - fun to think about!