28  Interactivity

Plotje produces SVG hiccup, and offers interaction in two ways:

The static Markdown render of this notebook shows the SVGs as flat images. Open the HTML rendering to see the interactions live.

Both kinds of interaction run in a browser reading the figure, so SVG is the only format that carries them – see Formats that draw interaction at the end of the chapter.

(ns plotje-book.interactivity
  (:require
   ;; Tablecloth -- dataset manipulation
   [tablecloth.api :as tc]
   ;; rdatasets -- bundled R datasets
   [scicloj.metamorph.ml.rdatasets :as rdatasets]
   ;; Kindly -- notebook rendering protocol
   [scicloj.kindly.v4.kind :as kind]
   ;; Plotje -- composable plotting
   [scicloj.plotje.api :as pj]))

Tooltips

Pass :tooltip true to pj/options and every point gets a data-tooltip attribute holding its column values. A small embedded script renders the tooltip on hover – no extra setup. pj/lay-point and pj/lay-interval-h are the two marks that carry a tooltip, whether the text is the built-in one or a mapped column; a tooltip written on any other layer type is accepted and draws none, which Known Limitations records.

(-> (rdatasets/datasets-iris)
    (pj/lay-point :sepal-length :sepal-width {:color :species})
    (pj/options {:title "Hover over a point for column values"
                 :tooltip true
                 :height 320}))
Hover over a point for column valuessepal widthsepal lengthspeciessetosaversicolorvirginica4.55.05.56.06.57.07.58.02.02.53.03.54.04.5

Writing the tooltip yourself

The built-in text names the columns the layer drew and their values, which is right for exploring and wrong as soon as the numbers need presenting – a currency sign, a thousands separator, a percentage, 1,653,346 read as 1.7M, or a column the plot does not draw at all.

Rather than a formatting option per case, :tooltip is an aesthetic like any other, mapped to a column whose values are the text each point shows. Building that column is ordinary data work, with the whole language available.

(def sales
  (tc/dataset {:month   ["Jan" "Feb" "Mar" "Apr"]
               :revenue [1653346 2410880 987654 3120500]
               :margin  [0.184 0.223 0.161 0.207]}))
sales

_unnamed [4 3]:

:month :revenue :margin
Jan 1653346 0.184
Feb 2410880 0.223
Mar 987654 0.161
Apr 3120500 0.207

The tooltip column is built with the same tools any other column is. A newline in the string breaks the line on the page.

(def sales-labelled
  (tc/add-column sales :hover
                 #(map (fn [month revenue margin]
                         (str month "\n"
                              (format "%.1fM" (/ (double revenue) 1e6))
                              " at " (format "%.1f%%" (* 100.0 margin))))
                       (:month %) (:revenue %) (:margin %))))
sales-labelled

_unnamed [4 4]:

:month :revenue :margin :hover
Jan 1653346 0.184 Jan
1.7M at 18.4%
Feb 2410880 0.223 Feb
2.4M at 22.3%
Mar 987654 0.161 Mar
1.0M at 16.1%
Apr 3120500 0.207 Apr
3.1M at 20.7%

Map that column to :tooltip:

(-> sales-labelled
    (pj/lay-point :margin :revenue {:tooltip :hover})
    (pj/options {:title "Hover for the month, revenue and margin"
                 :height 320}))
Hover for the month, revenue and marginrevenuemargin0.160.170.180.190.20.210.2210000001500000200000025000003000000

Three things follow from :tooltip being an aesthetic rather than a plot option.

  • The month is in the tooltip and on neither axis. A tooltip column is built from whatever the dataset holds.

  • Writing it turns tooltips on. {:tooltip true} in pj/options is the switch for the built-in text, and is not needed beside a mapping.

  • It scopes like every mapping. On the pose it covers each layer; on one layer it covers that layer, and the nearer one wins.

A written string rather than a column gives every mark of the layer the same tooltip: {:tooltip "one reading per bar"}.

Tooltips with markup

A tooltip may hold hiccup instead of a string, for a label that carries a heading, an emphasis or a table rather than a line of text. A column of hiccup gives each mark its own markup, and a written hiccup vector gives every mark of the layer the same markup, exactly as a column of strings and a written string do.

(def sales-rich
  (tc/add-column sales :hover
                 #(map (fn [month revenue margin]
                         [:div
                          [:b month]
                          [:br]
                          "revenue " [:code (format "%.1fM" (/ (double revenue) 1e6))]
                          [:br]
                          "margin " [:code (format "%.1f%%" (* 100.0 margin))]])
                       (:month %) (:revenue %) (:margin %))))
sales-rich

_unnamed [4 4]:

:month :revenue :margin :hover
Jan 1653346 0.184 [:div [:b Jan] [:br] revenue [:code 1.7M] [:br] margin [:code 18.4%]]
Feb 2410880 0.223 [:div [:b Feb] [:br] revenue [:code 2.4M] [:br] margin [:code 22.3%]]
Mar 987654 0.161 [:div [:b Mar] [:br] revenue [:code 1.0M] [:br] margin [:code 16.1%]]
Apr 3120500 0.207 [:div [:b Apr] [:br] revenue [:code 3.1M] [:br] margin [:code 20.7%]]

The column holds hiccup vectors, one per row.

(-> sales-rich
    (pj/lay-point :margin :revenue {:tooltip :hover})
    (pj/options {:title "Hover for a formatted label"
                 :height 320}))
Hover for a formatted labelrevenuemargin0.160.170.180.190.20.210.2210000001500000200000025000003000000

A written hiccup vector covers the layer, the way a written string does:

(-> sales
    (pj/lay-point :margin :revenue {:tooltip [:b "one reading per point"]})
    (pj/options {:height 240}))
revenuemargin0.160.170.180.190.20.210.2210000001500000200000025000003000000

A string tooltip stays text, so a string that happens to spell out a tag is shown as that text rather than rendered:

(-> sales
    (pj/lay-point :margin :revenue {:tooltip "<b>not bold</b>"})
    (pj/options {:height 240}))
revenuemargin0.160.170.180.190.20.210.2210000001500000200000025000003000000

Brush selection

:brush true enables drag-to-select. While dragging, a shaded rectangle follows the cursor; on release, points inside keep full opacity and points outside dim to 0.15. A short drag (less than 3 CSS pixels each side – the unit a mouse event reports, not a drawing unit) clears the selection. Selection is keyed by row index, so it tracks the same rows across every panel in the pose.

(-> (rdatasets/datasets-iris)
    (pj/lay-point :sepal-length :sepal-width {:color :species})
    (pj/options {:title "Drag a rectangle to highlight a region"
                 :brush true
                 :height 320}))
Drag a rectangle to highlight a regionsepal widthsepal lengthspeciessetosaversicolorvirginica4.55.05.56.06.57.07.58.02.02.53.03.54.04.5

Cross-panel linked highlighting

Brush selection is keyed by data-row-idx, the row of the pose’s dataset a mark was drawn from. A facet keeps that number when it splits the data, so a row drawn in several panels carries one number in all of them, and selecting it in one panel highlights it in the others. Below, each flower is drawn twice, once against its sepal width and once against its petal width. Drag over the setosa cluster in the top panel, and the same flowers light up in the bottom one.

(-> (rdatasets/datasets-iris)
    (pj/pose {:x :sepal-length})
    pj/lay-point
    (pj/facet {:y [:sepal-width :petal-width]})
    (pj/options {:title "Brush on one panel, see linked points in the other"
                 :brush true
                 :tooltip true
                 :height 420}))
sepal width234petal width4.55.05.56.06.57.07.58.0012sepal lengthBrush on one panel, see linked points in the other

A series links its columns the same way: both points drawn from one row carry that row’s number. The cells of an arrangement drawn from one dataset link the same way, and so do the panels of a scatter plot matrix, which is a facet over columns. A facet over the categories of a column draws each row in one panel only, so there a selection stays in the panel it was made in.

Interval (Gantt) tooltips

lay-interval-h participates in the same tooltip/brush system. Each rectangle’s tooltip names the lane, the start, the end, and the color label; on temporal axes the start and end are formatted as date strings rather than raw epoch-milliseconds.

(-> {: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"]}
    (pj/lay-interval-h :start :task {:x-end :end :color :team})
    (pj/options {:title "Hover for task: start -> end, team"
                 :tooltip true
                 :height 320}))
Hover for task: start -> end, teamtaskstartteamUXEngQAJanMarMayJulDesignBuildTestDeployDocument

Custom wrapper: save as PNG

Browsers can serialize an SVG element to a PNG via a <canvas> round-trip. The wrapper below adds a β€œSave PNG” button that renders the current SVG into a canvas and triggers a download.

(let [plot-svg (pj/plot
                (-> (rdatasets/datasets-iris)
                    (pj/lay-point :sepal-length :sepal-width {:color :species})
                    (pj/options {:title "Click 'Save PNG' to download the rendering"
                                 :height 320})))
      attrs (second plot-svg)
      body (drop 2 plot-svg)
      plot-id (str "pj-png-" (System/nanoTime))
      btn-id (str plot-id "-save")
      script (str "document.getElementById('" btn-id "').addEventListener('click',function(){"
                  "var svg=document.getElementById('" plot-id "');"
                  "var w=svg.clientWidth||" (or (:width attrs) 600) ","
                  "h=svg.clientHeight||" (or (:height attrs) 400) ";"
                  "var data=new XMLSerializer().serializeToString(svg);"
                  "var img=new Image();"
                  "img.onload=function(){"
                  "var c=document.createElement('canvas');c.width=w;c.height=h;"
                  "c.getContext('2d').drawImage(img,0,0,w,h);"
                  "var a=document.createElement('a');"
                  "a.href=c.toDataURL('image/png');a.download='plotje.png';"
                  "document.body.appendChild(a);a.click();a.remove();};"
                  "img.src='data:image/svg+xml;base64,'+btoa(unescape(encodeURIComponent(data)));"
                  "});")]
  (kind/hiccup
   [:div
    [:button {:id btn-id
              :style "margin-bottom:6px; padding:4px 12px;"}
     "Save PNG"]
    (into [:svg (assoc attrs :id plot-id)] body)
    [:script script]]))
Click 'Save PNG' to download the renderingsepal widthsepal lengthspeciessetosaversicolorvirginica4.55.05.56.06.57.07.58.02.02.53.03.54.04.5

Formats that draw interaction

A tooltip and a brush are behaviours a browser runs over the figure, so they reach a reader only where the figure is SVG. A plot rendered to :bufimg, or saved as a PNG, carries neither: a raster image is finished before anyone hovers over it, and has no elements for a script to attach to.

A tooltip or a brush requested on such a format prints a warning, and the figure still renders without them. One warning covers the plot, naming both requests where both were written, the format, and the formats that draw interaction:

(with-out-str
  (-> (rdatasets/datasets-iris)
      (pj/lay-point :sepal-length :sepal-width {:color :species})
      (pj/options {:tooltip true :brush true})
      (pj/plot {:format :bufimg})))
"Warning: :tooltip and :brush asked for, and the :bufimg format draws no interaction. The formats that do: :svg. The request is accepted and draws nothing.\n"

pj/save to a PNG prints the same warning, since a PNG file is that format written to disk. Saving the SVG keeps the attributes on the marks, and a browser opening the file runs the script that reads them.

See Also

  • Options and Scopes – where :tooltip, :brush, and other plot options live in the pose

What’s Next

  • Troubleshooting – common issues and how to fix them
  • Timelines – interval charts, whose tooltips are shown above
  • Customization – titles, labels, palettes, themes and legend placement
  • Architecture – how the pipeline produces the SVG
source: notebooks/plotje_book/interactivity.clj