Convert a Mapping to Sankey links

Produces the link table rtemis.draw::draw_sankey() expects: source, target and value.

Usage

as_sankey(
  x,
  threshold = 0,
  node_labels = c("text", "id"),
  uncovered_label = "<uncovered>",
  unaligned_label = "<unaligned>",
  min_width = 0.05
)

Arguments

x

Mapping object.

threshold

Numeric [0, 1]: Drop edges with strength below this.

node_labels

Character {"text", "id"}: What to label nodes with.

uncovered_label

Character: Sentinel node for criteria left with no surviving edge.

unaligned_label

Character: Sentinel node for candidates left with no surviving edge.

min_width

Numeric (0, Inf): Width given to a sentinel link that has no residual to scale, so that it renders at all. Such ribbons are markers, not measurements.

Value

data.frame of source, target, value, carrying a nodes attribute: a data.frame of label, id and role ("criterion", "candidate" or "sentinel") for every node in the diagram. sankey_palette() uses it so that a palette cannot drift from the labels these links actually use.

Details

draw_sankey() derives its node list from the links, so a node with no surviving link cannot be drawn at all. That matters here because an entirely uncovered course objective is exactly the finding a reader most needs to see, and it is the node most likely to lose all its edges. Two devices keep gaps visible rather than absent:

• Thresholded-away weight is routed to uncovered_label instead of being dropped, so a criterion's unmet support stays on the diagram at its true size. This is accounted on the criterion side only; the same mass is not emitted again on the candidate side, which would double-count it.

• A criterion with no surviving edge gets a link to uncovered_label, and a candidate with none gets a link from unaligned_label, so neither can disappear.

Sentinel links are drawn at min_width when their true residual is zero, so those ribbons are markers, not measurements.

Author

EDG