Draw a bipartite flow diagram with straight radial labels and an optional outer grouping ring. Duplicate links are summed. Zero-weight rows are omitted. A target must belong to exactly one group. Missing, negative or non-finite weights are rejected rather than silently changed.
Usage
grouped_chord(
data,
source = "source",
target = "target",
value = "value",
group = NULL,
view = c("targets", "groups"),
source_colours = NULL,
group_colours = NULL,
group_labels = NULL,
labels = list(source = "Sources", target = "Destinations", group = "Groupes"),
title = NULL,
unit = "poids",
footnote = character(),
locale = "fr-CA",
show_table = TRUE,
show_controls = TRUE,
source_label_width = 22,
context = list(),
width = NULL,
height = NULL,
elementId = NULL
)Arguments
- data
A data frame containing the links.
- source, target, value
Names of the source, target and numeric weight columns.
- group
Optional name of a column grouping the targets.
- view
Either `"targets"` for individual targets or `"groups"` for totals by group. The latter requires a grouping column.
- source_colours, group_colours
Optional named colour vectors. Names must cover all visible source or group labels. Extra names are allowed, so the same palette can be used for every filtered subset.
- group_labels
Optional named character vector of short group labels, used on narrow screens. Full labels remain in the key and accessible names.
- labels
Named list with `source`, `target` and `group` headings.
- title
Optional title included in the widget and its SVG export.
- unit
Label for the weight unit, for example `"fictional objects"`.
- footnote
Character vector describing sources or interpretation limits.
- locale
Locale used for numeric labels, default `"fr-CA"`.
- show_table
Show a collapsible table of the underlying links.
- show_controls
Show the widget's SVG download link. Shiny applications may instead use a download handler and `input$<outputId>_svg$xml`.
- source_label_width
Approximate maximum characters per source label line. Targets keep straight, unwrapped names.
- context
Named list of application metadata included with SVG exports, for example the selected year. Do not put credentials in this metadata.
- width, height
Widget dimensions. Its content height adapts to the labels.
- elementId
Optional HTML element identifier.
Details
The same angular unit is used at both ends of every ribbon. The scale is recalculated for each selection. Lengths in different widgets cannot be compared directly; use the numeric weights. The outer ring is a classification track: its length includes space for group labels and does not encode a weight.
Each widget has independent SVG identifiers, selections and exports. In Shiny, a click emits `input$<outputId>_click`, a list with a `type` (`source`, `target`, `group` or `link`) and the corresponding labels. The SVG snapshot is in `input$<outputId>_svg`, with `xml`, `total`, `view` and `context`. Non-Shiny pages receive a `groupedchord:select` DOM event.
Examples
library(groupedChord)
d <- example_workshops()
d <- d[d$year == 2025, ]
grouped_chord(d, "workshop", "item", "quantity", group = "family",
title = "Ateliers et objets inventes", unit = "objets fictifs")