Plot a curriculum's alignment as a Sankey — plot

Course objectives on the left, session objectives on the right, and a ribbon between them whose width is the support the pair was scored at. The main figure of a run: it answers how much of each course objective is served and by what, which is the question the mapping was made to ask.

Usage

plot_sankey(
  x,
  direction = c("course_to_session", "session_to_assessment"),
  threshold = NULL,
  node_labels = c("text", "id"),
  candidate_fill = c("mix", "neutral"),
  palette = NULL,
  theme = c("light", "dark"),
  title = NULL,
  card = c("bottomleft", "bottomright", "topleft", "topright", "none"),
  margins = NULL,
  filename = NULL,
  width = 1400,
  height = 900,
  verbosity = 1L,
  ...
)

Arguments

x: CurriculumMapping object, from map_curriculum().
direction: Character {"course_to_session", "session_to_assessment"}: Which mapping to draw. The assessment direction is available only where the course supplied assessments.
threshold: Numeric [0, 1]: Minimum strength for a ribbon to count as aligned. NULL uses the threshold the run was made with.
node_labels: Character {"text", "id"}: What to label nodes with.
candidate_fill: Character {"mix", "neutral"}: Whether session objectives inherit a weighted mix of the course objectives they serve, or one neutral grey.
palette: Character: Hex colors for the course objectives, recycled where there are more objectives than colors. NULL uses the package's hue-spread default.
theme: Character {"light", "dark"}: Which way the neutral grey should lean.
title: Character: Chart title. NULL builds one from the course name and term.
card: Character {"bottomleft", "bottomright", "topleft", "topright", "none"}: Corner for a small card naming the scoring system, what one rating means and where the alignment threshold was drawn. "none" omits it. The card is built from the run's own scoring system, so a figure cannot describe an instrument other than the one that produced it.
margins: Named list: Space around the plotting box, as any of left, right, top, bottom in pixels. NULL derives them from the labels – a node's label is drawn to its right, so the session objectives need room or their text is clipped, and objective text runs long. Set them for a static export, where the canvas is known exactly.
filename: Character: Path to write the drawing to, or NULL to return it without writing. .svg is supported.
width: Numeric: Figure width in pixels. Used when writing, and to size the plotting box against the labels, so a wider export gets wider margins rather than a squeezed diagram.
height: Numeric: Figure height in pixels, used when writing.
verbosity: Integer [0, Inf): Verbosity level.
...: Additional arguments passed to rtemis.draw::draw_sankey(), e.g. node_width, node_gap, orient, label_font_size.

Value

htmlwidget: The drawing, invisibly where filename was written.

Details

Each course objective takes a hue of its own. A session objective is painted with the mix of the course objectives it serves, weighted by support, so a saturated node serves essentially one objective and a washed-out node is spread across several – overlap is legible at a glance rather than by tracing ribbons. Read the wash relatively, against the course-objective colours feeding a node, since the hues are not equal-chroma. See sankey_palette() for the mixing rule and candidate_fill = "neutral" to turn it off.

Weight thresholded away is routed to a gap sentinel rather than dropped, and a course objective nothing reaches keeps a ribbon to it, so an uncovered objective cannot vanish from the diagram. See as_sankey().

The run's own threshold is used unless another is given, so the figure agrees with the verdict print() and report_curriculum() report.

Requires the rtemis.draw package, and filename additionally requires a node binary on the PATH.

Author

EDG

Examples

if (FALSE) { # \dontrun{
  cm <- map_curriculum(course, llmconfig = llmconfig)
  plot_sankey(cm)
  plot_sankey(cm, filename = "epi207_sankey.svg")
  plot_sankey(cm, direction = "session_to_assessment", threshold = 0.65)
} # }