Convert a Mapping to Gantt tasks — as

Produces the task table rtemis.draw::draw_gantt() expects – label, start, end – for the course-to-session direction: one row per course objective, one bar per session that addresses it, laid out along the term.

Usage

as_gantt(
  x,
  threshold = 0.5,
  node_labels = c("text", "id"),
  uncovered_label = "<uncovered>",
  uncovered_width = 0.35,
  gap = 0.08,
  n_bands = 3L
)

Arguments

x: Mapping object, from map_course_to_sessions().
threshold: Numeric [0, 1]: Minimum strength for a session to count as addressing an objective.
node_labels: Character {"text", "id"}: What to label rows with.
uncovered_label: Character: Group name for the marker bars given to course objectives with no session above threshold.
uncovered_width: Numeric (0, Inf): Width of those marker bars, in sessions.
gap: Numeric [0, 0.5): Space left between one session's bar and the next, in sessions. Without it consecutive sessions abut and a term of separate bars reads as one continuous block.
n_bands: Integer [2, Inf): Number of strength bands to cut the surviving edges into, for the band column.

Value

data.frame of label, start, end, session, n_aligned, strength, band, crit_index, label_band, alignment, covered and tooltip, carrying a sessions attribute: the session keys in axis order. One row per (course objective, session) pair that survives threshold, plus one marker row per uncovered objective.

band is an ordered factor cutting strength into n_bands equal intervals between threshold and 1, with uncovered_label as its first level. It is what carries the weight: a Gantt bar has one length and one row, so the only channel left for how strongly a session serves an objective is its color, and a categorical group is what rtemis.draw::draw_gantt() colors by.

crit_index is the course objective's position among the criteria, which is what picks its hue in sankey_palette(). label_band pairs it with the band, so one group column can carry both: hue for which objective, lightness for how strongly that session serves it. A Gantt and a Sankey of the same mapping then give an objective the same color.

Details

This is the question a Sankey cannot answer. A Sankey says how much of each course objective is served and by what; a Gantt says when. An objective met only in week 1, one taught in three separated bursts, and one carried evenly across the term all have the same ribbon and different bars.

Sessions are positioned by the order they appear in the mapping, so start = 0 is the first session and one unit is one session. The session's own key travels in session for the tooltip, which keeps the axis numeric and the label readable.

Uncovered objectives stay on the chart

draw_gantt() derives its rows from the label values present in the tasks, so a course objective with no bars has no row – and an uncovered objective is the finding a reader most needs. Each one is given a marker bar uncovered_width wide at the start of the term, in a group of its own. Those bars are markers rather than measurements: their width says nothing, and their group name is what to read.

Author

EDG

Examples

if (FALSE) { # \dontrun{
  tasks <- as_gantt(cm@mapping, threshold = 0.5)
  rtemis.draw::draw_gantt(
    tasks,
    group = "alignment",
    xlab = "Session",
    filename = "epi207_gantt.svg"
  )
} # }