18 Timelines
Where Change Over Time covers marks that trace a numeric quantity evolving along a sequence (line, step, area, smooth), this chapter focuses on placing discrete things on a time axis: events, intervals, schedules. The y-axis here is a lane or a baseline rather than an evolving value – temporal information is where something sits, not how a value moves.
The chapter introduces pj/lay-interval-h for horizontal interval bars (Gantt-style) and shows how existing primitives combine to build calendar-aware visualizations.
Pipeline reminder: every example threads data through one or more pj/lay-* calls, then through pj/options for titles and axis labels. Plotje detects temporal columns automatically and picks calendar-aware tick labels for the date axis.
(ns plotje-book.timelines
(:require
;; Tablecloth -- dataset manipulation
[tablecloth.api :as tc]
;; rdatasets -- bundled R datasets (ggplot2-presidential and others)
[scicloj.metamorph.ml.rdatasets :as rdatasets]
;; Kindly -- notebook rendering protocol
[scicloj.kindly.v4.kind :as kind]
;; Plotje -- composable plotting
[scicloj.plotje.api :as pj]))Historical event timeline
Five milestones in computing history. Each event is a point on a single horizontal line, with a text label shifted above. Every event has the same :y, 1, because the y-axis here carries no meaning – it provides a baseline.
Sources for the milestones:
Turing machine (Alan Turing’s 1936 paper “On Computable Numbers”)
Transistor (Bardeen, Brattain, and Shockley at Bell Labs, December 1947)
ARPANET first link (UCLA-SRI message, October 1969)
World Wide Web (Tim Berners-Lee’s proposal, March 1989)
iPhone (first release, June 2007)
(def computing-milestones
{:date [#inst "1936-01-01" #inst "1947-12-23" #inst "1969-10-29"
#inst "1989-03-12" #inst "2007-06-29"]
:y [1 1 1 1 1]
:event ["Turing machine"
"Transistor"
"ARPANET first link"
"World Wide Web"
"iPhone"]})(-> computing-milestones
(pj/lay-point :date :y {:size 6 :color "#2c3e50"})
(pj/lay-text :date :y {:text :event :dy 0.3 :color "#2c3e50"})
(pj/options {:title "Five milestones in computing"
:height 220
:y-label ""
:x-label "year"}))The text labels read horizontally, which keeps them legible. When several events fall close together on the time axis, giving each event a different y spreads the labels apart vertically. The plot below gives the same five milestones different y values.
(def with-staggered-y
(assoc computing-milestones :y [2 1 1.5 2 1]))(-> with-staggered-y
(pj/lay-point :date :y {:size 6 :color "#2c3e50"})
(pj/lay-text :date :y {:text :event :dy 0.18 :color "#2c3e50"})
(pj/options {:title "Same milestones, staggered y for label clarity"
:height 260
:y-label ""
:x-label "year"}))Annotated time series
A regular line chart gains context when key dates appear as vertical reference lines. Each rule sits at a date passed as a constant to lay-rule-v rather than drawn from a data column, and the x axis reaches that date even where the series does not.
The data is from ggplot2::economics, loaded here via the Rdatasets bundle.
(def unemployment
(-> (rdatasets/ggplot2-economics)
(tc/select-rows #(let [d (:date %)]
(and (>= (.getYear d) 2000)
(<= (.getYear d) 2014))))))(-> unemployment
(pj/lay-line :date :unemploy {:color "#34495e"})
(pj/lay-rule-v {:x-intercept (java.time.LocalDate/parse "2008-09-15")
:color "#c0392b"})
(pj/lay-rule-v {:x-intercept (java.time.LocalDate/parse "2001-03-01")
:color "#7f8c8d"})
(pj/options {:title "US unemployment with recession markers"
:y-label "thousands unemployed"
:x-label "date"
:height 320}))The two rules mark the start of the dot-com recession (March 2001) and the Lehman Brothers collapse (September 2008).
Gantt chart with lay-interval-h
The Gantt chart (Henry Gantt, around 1910) is the canonical “tasks-and-dates” picture: each row is a task, each bar’s left edge is the start, the right edge is the end.
pj/lay-interval-h draws one horizontal bar per row, from x to :x-end, sitting at the lane named by the categorical y column. The classic project Gantt:
(def project
{:start [#inst "2024-01-01" #inst "2024-02-15" #inst "2024-04-01"
#inst "2024-05-10" #inst "2024-06-20"]
:end [#inst "2024-03-15" #inst "2024-04-20" #inst "2024-06-30"
#inst "2024-07-10" #inst "2024-08-30"]
:task ["Design" "Build" "Test" "Deploy" "Document"]
:team ["UX" "Eng" "QA" "Eng" "UX"]})(-> project
(pj/lay-interval-h :start :task {:x-end :end :color :team})
(pj/options {:title "Project plan -- bars colored by team"
:y-label "task"
:x-label ""
:height 320}))A real-world Gantt: every US president’s term since 1953, from ggplot2::presidential. Color encodes party.
(-> (rdatasets/ggplot2-presidential)
(pj/lay-interval-h :start :name {:x-end :end :color :party})
(pj/options {:title "US presidential terms since 1953"
:y-label ""
:x-label "year"
:height 420
:color-values ["#3498db" "#e74c3c"]}))The blue-and-red palette mirrors the conventional US party colors (Democratic / Republican). Each bar’s length is the literal duration of the term – tight bars (Kennedy, Ford) stand out next to long ones (Reagan, Obama).
Adjusting bar thickness
The :interval-thickness option controls how much of each row’s band the bar fills. The default is 0.7; smaller values leave more whitespace between rows, larger values approach overlap.
(-> project
(pj/lay-interval-h :start :task
{:x-end :end :color :team :interval-thickness 0.4})
(pj/options {:title "interval-thickness = 0.4 -- thin bars"
:y-label "task"
:x-label ""
:height 320}))Numeric color
Pass a numeric column to :color and Plotje grades each bar along a continuous gradient instead of a categorical palette. A continuous-color legend appears on the side, showing the domain of the mapped column. The gradient uses the configured color scale (default linear; (pj/scale :color :log) on the pose for log-spaced ticks).
(-> {:start [#inst "2024-01-01" #inst "2024-02-15" #inst "2024-04-01"
#inst "2024-05-10" #inst "2024-06-20"]
:end [#inst "2024-03-15" #inst "2024-04-20" #inst "2024-06-30"
#inst "2024-07-10" #inst "2024-08-30"]
:task ["Design" "Build" "Test" "Deploy" "Document"]
:cost [10 35 22 8 18]}
(pj/lay-interval-h :start :task {:x-end :end :color :cost})
(pj/options {:title "Project plan -- bars colored by cost"
:y-label "task"
:x-label ""
:height 320}))Vertical bars via coord :flip
lay-interval-h always draws the lane on the y axis. To render visually vertical bars (lanes on the horizontal axis, time running upward), apply pj/coord :flip to the pose – the renderer detects which axis carries the band and lays out the rectangles accordingly.
(-> project
(pj/lay-interval-h :start :task {:x-end :end :color :team})
(pj/coord :flip)
(pj/options {:title "Same project, vertical via coord :flip"
:height 360}))Marey train schedule
Etienne-Jules Marey’s classic 1885 diagram of Paris-Lyon trains (context and image, popularized in Edward Tufte’s Visual Display of Quantitative Information) has a categorical y-axis (stations, in the order of the line, Paris at the top) and a temporal x-axis. Each train is a polyline; the segments between stations slope down because time moves forward as the train moves south.
Plotje builds this with pj/lay-line. The station names are text, so the y axis is categorical, and it lists the stations from the bottom up in the order each first appears in the data. Every train starts in Paris, so with no other setting Paris would be at the bottom. The y scale’s :domain lists the stations from the bottom up, Marseille first, to put Paris at the top as Marey drew it.
(def trains
;; Four trains, each visiting five stations in order. Express trains
;; (A, C) take ~7 hours total; locals (B, D) ~9 hours -- visible as a
;; shallower slope on the plot.
(let [stations ["Paris" "Dijon" "Lyon" "Avignon" "Marseille"]
express [6.0 8.0 9.5 11.5 13.0]
local [7.0 9.5 11.5 14.0 16.0]
train-shifts [["Express A" 0.0 express]
["Local B" 1.0 local]
["Express C" 2.5 express]
["Local D" 4.0 local]]]
(vec
(for [[name shift schedule] train-shifts
[station hour] (map vector stations schedule)
:let [h (+ hour shift)
hh (int h)
mm (int (* 60 (- h hh)))]]
{:station station
:time (java.time.LocalDateTime/of 2024 6 1 hh mm)
:train name}))))(-> trains
(pj/lay-line :time :station {:color :train :size 1.5})
(pj/lay-point :time :station {:color :train :size 5})
(pj/scale :y {:domain ["Marseille" "Avignon" "Lyon" "Dijon" "Paris"]})
(pj/options {:title "Marey schedule -- Paris to Marseille"
:y-label ""
:x-label "time of day"
:height 320}))The slope of each line carries information: a shallower segment means a slower stretch, with more time between two stations. The point layer marks the actual stops; remove lay-point and the schedule reads as continuous travel.
Multi-track activity timeline
Two ways to look at “what happened when” across multiple days. The data shape is identical – start, end, day, activity kind – only the interpretation of the time axis differs. The right choice depends on what you want the reader to compare.
Absolute time
The literal approach: :start and :end are real datetimes, each bar covers its actual interval. Useful when absolute time matters (logs, scheduling tools) or when bars may cross day boundaries.
(def activity-datetime
;; A developer's week: meetings and deep-work blocks, with
;; absolute timestamps.
{:start [#inst "2024-06-03T09:00" #inst "2024-06-03T10:30" #inst "2024-06-03T13:00"
#inst "2024-06-04T09:00" #inst "2024-06-04T11:00" #inst "2024-06-04T14:30"
#inst "2024-06-05T09:30" #inst "2024-06-05T13:00" #inst "2024-06-05T15:00"
#inst "2024-06-06T09:00" #inst "2024-06-06T10:00" #inst "2024-06-06T13:30"
#inst "2024-06-07T09:00" #inst "2024-06-07T11:00" #inst "2024-06-07T15:00"]
:end [#inst "2024-06-03T10:30" #inst "2024-06-03T12:00" #inst "2024-06-03T17:00"
#inst "2024-06-04T11:00" #inst "2024-06-04T12:30" #inst "2024-06-04T17:00"
#inst "2024-06-05T13:00" #inst "2024-06-05T15:00" #inst "2024-06-05T17:00"
#inst "2024-06-06T10:00" #inst "2024-06-06T12:30" #inst "2024-06-06T17:00"
#inst "2024-06-07T11:00" #inst "2024-06-07T15:00" #inst "2024-06-07T17:00"]
:day ["Mon" "Mon" "Mon" "Tue" "Tue" "Tue" "Wed" "Wed" "Wed"
"Thu" "Thu" "Thu" "Fri" "Fri" "Fri"]
:kind ["meeting" "deep work" "deep work"
"deep work" "meeting" "deep work"
"deep work" "meeting" "deep work"
"meeting" "meeting" "deep work"
"deep work" "meeting" "deep work"]})(-> activity-datetime
(pj/lay-interval-h :start :day {:x-end :end :color :kind})
(pj/options {:title "A week of activity, absolute time"
:y-label ""
:x-label "datetime"
:height 320}))The bars are accurate but visually narrow: each block is only a few hours within a five-day axis, and the overnight gaps consume most of the width. Comparing Monday’s morning to Wednesday’s afternoon takes mental effort.
Hour-of-day numeric
Re-index the x-axis to “hours since midnight” and the within-day shape is what stands out. The data structure is the same – still (start, end, day, kind) – but start and end are now hours-from-midnight numbers, and the x-axis spans the workday rather than the whole week.
(def activity
;; Same week as above, with hours-since-midnight in place of
;; full datetimes.
{:start [9.0 10.5 13.0 ;; Mon
9.0 11.0 14.5 ;; Tue
9.5 13.0 15.0 ;; Wed
9.0 10.0 13.5 ;; Thu
9.0 11.0 15.0] ;; Fri
:end [10.5 12.0 17.0 ;; Mon
11.0 12.5 17.0 ;; Tue
13.0 15.0 17.0 ;; Wed
10.0 12.5 17.0 ;; Thu
11.0 15.0 17.0] ;; Fri
:day ["Mon" "Mon" "Mon"
"Tue" "Tue" "Tue"
"Wed" "Wed" "Wed"
"Thu" "Thu" "Thu"
"Fri" "Fri" "Fri"]
:kind ["meeting" "deep work" "deep work"
"deep work" "meeting" "deep work"
"deep work" "meeting" "deep work"
"meeting" "meeting" "deep work"
"deep work" "meeting" "deep work"]})(-> activity
(pj/lay-interval-h :start :day {:x-end :end :color :kind})
(pj/options {:title "Same week, hour-by-hour"
:y-label ""
:x-label "hour of day"
:height 320}))Wednesday’s afternoon block is the longest uninterrupted deep-work stretch; Mondays start with a meeting, Fridays with deep work. The trade-off is that you lose absolute time – “Monday 10am” no longer reads as a specific point on a calendar.
Faceting by category
Splitting one chart into one-panel-per-category makes overlapping intervals easier to compare. Faceting the activity timeline by :kind on :row stacks two panels, one above the other, on one hour axis – meetings in the top panel, deep work in the panel below.
(-> activity
(pj/lay-interval-h :start :day {:x-end :end :color :kind})
(pj/facet {:row :kind})
(pj/options {:title "Same week, faceted by activity kind"
:x-label "hour of day"
:y-label ""
:height 360}))Every day has both kinds of activity, so the two panels share the day lanes and no lane is empty. The project Gantt is different: each task belongs to one team, so faceting it by :team with the lane axis shared repeats all five task lanes in every panel, most of them empty. {:share-scales #{:x}} in the options map after the facet shares only the time axis, and each panel keeps the lanes of its own tasks – see Faceting:
(-> project
(pj/lay-interval-h :start :task {:x-end :end :color :team})
(pj/facet {:row :team} {:share-scales #{:x}})
(pj/options {:title "Project plan by team"
:y-label "task"
:x-label ""
:height 360}))Interactive timelines
Pass :tooltip true to add hover-text on each interval, or :brush true for drag-to-select highlighting (the same built-in mechanisms that work for points). For more interaction patterns – cross-panel linking, save-as-PNG – see the Interactivity chapter.
(-> (rdatasets/ggplot2-presidential)
(pj/lay-interval-h :start :name {:x-end :end :color :party})
(pj/options {:title "Hover for term details"
:tooltip true
:height 420
:color-values ["#3498db" "#e74c3c"]}))See Also
- Core Concepts – mappings, aesthetics, and the inference rules behind temporal axes
What’s Next
- Relationships – scatter plots, regression, smoothing, density, and heatmaps
- Interactivity – tooltip, brush, cross-panel linking, save-as-PNG
- Change Over Time – line, step, area on a date axis
- Faceting – splitting one chart into many panels
- Customization – titles, palettes, size, scales