Package {ggkodom}

ggkodom: Visualize Individual Longitudinal Trajectories

Description

A 'ggplot2'-based toolkit for visualizing individual-level longitudinal trajectories. Creates linear kodom plots, circular kodom plots, heatmaps, and state-ribbon charts for repeated-measures data. Each subject gets its own visual lane with measurements colored by value, revealing patterns across subjects and time. The circular variant resembles the Kodom flower.

Author(s)

Maintainer: Subhrajyoty Roy subhrajyotyroy@gmail.com

Authors:

• Ayoushman Bhattacharya

• Sayan Das

• Subrata Pal

References

Geom for geom_kodom_branch

Description

Extends ggplot2::GeomPath to draw branching trajectory plots. In addition to the interpolated colour-gradient path (via .kodom_build_segments()), draws a short vertical fork connector at each subject's branch point — the first x that appears in a predicted arm — connecting the observed lane to the topmost prediction arm. Toggle with show_fork.

Usage

GeomKodomBranch

Format

A ggproto object.

Geom for geom_kodom_circular

Description

Extends ggplot2::GeomPath with kodom defaults for the circular layout. Drops the id column in setup_data() so ggplot2 does not warn about an unknown aesthetic. Draws interpolated colour-gradient segments via ggplot2::GeomSegment and optional observation-point markers via ggplot2::GeomPoint.

Usage

GeomKodomCircular

Format

A ggproto object.

Details

size and linewidth are routed to separate graphical elements: size → points only, linewidth → path segments only.

Geom for geom_kodom_heatmap

Description

Extends ggplot2::GeomTile with kodom defaults. Drops id in setup_data() to avoid an unknown-aesthetic warning from ggplot2.

Usage

GeomKodomHeatmap

Format

A ggproto object.

Geom for geom_kodom_line

Description

Extends ggplot2::GeomPath with kodom defaults. Drops the id column in setup_data() so ggplot2 does not warn about an unknown aesthetic at draw time. Draws interpolated colour-gradient segments via ggplot2::GeomSegment and optional observation-point markers via ggplot2::GeomPoint.

Usage

GeomKodomLine

Format

A ggproto object.

Details

size and linewidth are intentionally routed to separate graphical elements: size → points only, linewidth → path segments only.

Geom for geom_kodom_periodic

Description

Extends ggplot2::GeomPath to draw concentric "star trail" arcs. Interpolates colours/alpha in the (angle, radius) space that the stat already produces, then delegates the polar projection to coord_polar(theta = "x"). This means standard ggplot2 scales and coordinates work as expected: use ggplot2::scale_x_continuous() for time-axis labels, ggplot2::coord_polar() for direction, and theme_kodom_periodic() for a clean panel.

Usage

GeomKodomPeriodic

Format

A ggproto object.

Base stat shared by all kodom geoms

Description

Declares the x and id required aesthetics. Concrete stats inherit from this and override compute_panel().

Usage

StatKodomBase

Format

A ggproto object.

Stat for geom_kodom_branch

Description

Assigns integer base lanes (one per subject) then stacks prediction arms as fractional sub-lanes above the observed path within each subject's lane.

Usage

StatKodomBranch

Format

A ggproto object.

Details

Rows where medication is NA are the observed path; rows with a non-NA medication value are prediction arms. The stat replaces NA in data$medication with "observed" so that the linetype scale can be driven directly from the medication column:

scale_linetype_manual(
  values = c("observed" = "solid", "DrugA" = "dashed", "DrugB" = "dotted")
)

Two internal columns — kodom_lane (integer lane rank) and kodom_track (cleaned medication value) — are passed through to draw_panel so that fork connectors can be placed at each subject's branch point.

Stat for geom_kodom_circular

Description

Assigns lane positions, maps each lane to an angular position and the time variable to a radial position, then converts to Cartesian coordinates for rendering in ordinary Cartesian space (no coord_polar). Called automatically by geom_kodom_circular(); rarely needed directly.

Usage

StatKodomCircular

Format

A ggproto object.

Stat for geom_kodom_heatmap

Description

Bins time into equal-width intervals, aggregates the fill aesthetic within each (subject × bin) cell, and returns a data frame suitable for ggplot2::GeomTile. Called automatically by geom_kodom_heatmap(); rarely needed directly.

Usage

StatKodomHeatmap

Format

A ggproto object.

Stat for geom_kodom_line

Description

Computes integer lane positions (y) from the id aesthetic and applies optional sorting and subject sampling. Called automatically by geom_kodom_line(); rarely needed directly.

Usage

StatKodomLine

Format

A ggproto object.

Stat for geom_kodom_periodic

Description

Assigns lane positions and converts lane rank to an Archimedean spiral radius (y = inner_radius + lane * lane_width + spiral_fraction * total_time / period). Time x is left continuous, and relies on coord_polar(theta = "x") to natively wrap the data in a 360 degree space for values extending past the period.

Usage

StatKodomPeriodic

Format

A ggproto object.

Polar coordinate system for periodic Kodom plots

Description

A convenience wrapper around ggplot2::coord_polar() with defaults appropriate for geom_kodom_periodic(): theta = "x" (time maps to angle), start = pi/2 (x = 0 at 12 o'clock), and direction = -1 (clockwise). Pass clockwise = FALSE for a counter-clockwise layout.

Usage

coord_kodom_periodic(clockwise = TRUE)

Arguments

Value

A ggplot2::coord_polar() coordinate object.

Examples

library(ggplot2)
df <- data.frame(
  subject_id = rep(1:5, each = 4),
  time = rep(1:4, 5),
  visit_month = rep(1:4, 5),
  value = rep(1:4, 5),
  hba1c = rep(1:4, 5),
  arm = rep(c("Treatment", "Control"), c(12, 8))
)
ggplot(df, aes(x = visit_month, id = subject_id, colour = hba1c)) +
  geom_kodom_periodic(period = 12) +
  scale_x_continuous(breaks = 1:12, labels = month.abb, limits = c(0, 12)) +
  scale_colour_kodom() +
  coord_kodom_periodic() +
  theme_kodom_periodic()

Branching swimlane plot for observed paths and counterfactual predictions

Description

Draws one horizontal path per subject for the observed trajectory, then fans out into sub-lanes — one per medication or intervention arm — for predicted (counterfactual) trajectories. The branching time may differ across subjects.

Usage

geom_kodom_branch(
  mapping = NULL,
  data = NULL,
  stat = StatKodomBranch,
  position = "identity",
  ...,
  sort_by = "none",
  n_max = Inf,
  lane_width = 1,
  branch_fraction = 0.7,
  show_points = TRUE,
  show_fork = TRUE,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

Arguments

Details

Data format. Supply NA in the medication column for all observed rows (pre- and post-branch). Supply a non-NA arm label (e.g. "DrugA") for every predicted row. The stat replaces NA with "observed" in its output so that the linetype scale receives a clean string for every row.

Linetype. Map ⁠linetype = <arm_column>⁠ in aes() and supply a scale_linetype_manual() so that the legend appears and the linetypes are exactly what you want. The stat converts NA (observed rows) to the string "observed" before the scale is applied, so target that key explicitly:

aes(linetype = arm, medication = arm)   # both point to the same column
scale_linetype_manual(
  values = c("observed" = "solid", "DrugA" = "dashed", "DrugB" = "dotted")
)

Fork connector. A short vertical segment is drawn at each subject's branch point (the first x that appears in a predicted arm), connecting the observed lane to the topmost arm. Suppress with show_fork = FALSE.

Lane layout. Each subject occupies a primary band of width lane_width. Within that band the observed path is at the base; each prediction arm sits at an equal sub-lane fraction above it controlled by branch_fraction. With two arms and branch_fraction = 0.7, arm 1 is at 0.35 * lane_width above the base and arm 2 is at 0.70 * lane_width, leaving 30% clearance before the next subject.

Y-axis labels. Subject IDs can be added by setting custom breaks:

scale_y_continuous(
  breaks = seq_len(n_subjects) * lane_width,
  labels = subject_ids
)

Value

A ggplot2 layer object.

Aesthetics

• x — time (numeric or Date)

• id — subject identifier; determines the primary lane position

• colour — measured value mapped to colour (interpolated along path)

• medication — NA for observed rows; a character/factor arm label for predicted rows. Each unique non-NA value becomes one sub-lane.

• size, linewidth, alpha, shape, stroke — standard path/point aesthetics. linetype is set by the stat (medication name / "observed").

Examples

library(ggplot2)
df <- data.frame(
  subject_id = rep(1:5, each = 4),
  time = rep(1:4, 5),
  visit_month = rep(1:4, 5),
  value = rep(1:4, 5),
  hba1c = rep(1:4, 5),
  arm = rep(c("Treatment", "Control"), c(12, 8))
)
ggplot(df, aes(
  x = time, id = subject_id,
  colour = hba1c, linetype = arm, medication = arm
)) +
  geom_kodom_branch(sort_by = "mean", lane_width = 2) +
  scale_linetype_manual(
    values = c("observed" = "solid", "DrugA" = "dashed", "DrugB" = "dotted")
  ) +
  scale_colour_kodom() +
  theme_kodom()

Circular ("Kodom") swimlane plot for longitudinal trajectories

Description

Draws a radial plot where each subject occupies an angular spoke and time increases outward from the center. Measurements are encoded as a colour gradient along each radial path, interpolated between consecutive observations. The layout resembles a Kadam flower (Neolamarckia cadamba), giving the package its name.

Usage

geom_kodom_circular(
  mapping = NULL,
  data = NULL,
  stat = StatKodomCircular,
  position = "identity",
  ...,
  sort_by = "none",
  n_max = Inf,
  gap_fraction = 0.15,
  inner_fraction = 0.3,
  direction = 1L,
  show_points = TRUE,
  reference_rings = c(0),
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

Arguments

Details

Unlike the original coord_polar() variant in the archive package, this geom performs the polar-to-Cartesian transform inside the stat and renders in ordinary Cartesian space, so all ggplot2 scales, themes, and facets work normally. Use coord_fixed() to preserve the circular shape.

Value

A ggplot2 layer object.

Aesthetics

Required aesthetics are shown in bold. size and linewidth are intentionally independent: each controls a different graphical element.

• x — time variable (numeric); mapped to radial distance

• id — subject identifier; mapped to angular position

• colour — color of both the connecting path and the point border

• fill — point interior color for filled shapes (21–25)

• size — point size only; set to NA or 0 to suppress points

• linewidth — path width only

• alpha — transparency applied to both path and points

• shape — point shape (default 19). Set to NA to suppress points.

• stroke, linetype — point border width / path line type

Examples

library(ggplot2)
df <- data.frame(
  subject_id = rep(1:5, each = 4),
  time = rep(1:4, 5),
  visit_month = rep(1:4, 5),
  value = rep(1:4, 5),
  hba1c = rep(1:4, 5),
  arm = rep(c("Treatment", "Control"), c(12, 8))
)
ggplot(df, aes(x = time, id = subject_id, colour = hba1c)) +
  geom_kodom_circular(sort_by = "mean", gap_fraction = 0.1) +
  scale_colour_kodom() +
  coord_fixed() +
  theme_kodom_circular()

Swimlane heatmap for longitudinal trajectories

Description

Divides the time axis into equal-width bins and fills each (subject × bin) cell with an aggregate of the measured value. Each subject occupies one horizontal lane. Use this layout when the cohort is large or when you prefer a compact, aligned grid over individual paths.

Usage

geom_kodom_heatmap(
  mapping = NULL,
  data = NULL,
  stat = StatKodomHeatmap,
  position = "identity",
  ...,
  sort_by = "mean",
  n_max = Inf,
  bins = 10L,
  breaks = NULL,
  fun = "mean",
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

Arguments

Details

Lane ordering is controlled by sort_by (defaults to "mean", which places the highest-mean subjects at the top). Time bins can be customised via bins (number of equal-width intervals) or breaks (explicit boundaries).

Value

A ggplot2 layer object.

Aesthetics

Required aesthetics are shown in bold.

• x — time variable (numeric or Date)

• id — subject identifier; determines lane position on the y axis

• fill — measurement value used for cell color and sorting

• colour — tile border color (default "white")

• linewidth — tile border width (default 0.25)

• alpha — transparency

Examples

library(ggplot2)
df <- data.frame(
  subject_id = rep(1:5, each = 4),
  time = rep(1:4, 5),
  visit_month = rep(1:4, 5),
  value = rep(1:4, 5),
  hba1c = rep(1:4, 5),
  arm = rep(c("Treatment", "Control"), c(12, 8))
)
ggplot(df, aes(x = time, id = subject_id, fill = hba1c)) +
  geom_kodom_heatmap(sort_by = "mean", bins = 12) +
  scale_fill_kodom() +
  theme_kodom()

Swimlane line plot for longitudinal trajectories

Description

Draws one horizontal colored path per subject. Time maps to x, subject identity maps to id (which the stat converts to integer lane positions on the y axis), and a measured value maps to colour. The colour transitions smoothly between consecutive observations via interpolated sub-segments.

Usage

geom_kodom_line(
  mapping = NULL,
  data = NULL,
  stat = StatKodomLine,
  position = "identity",
  ...,
  sort_by = "none",
  n_max = Inf,
  show_points = TRUE,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

Arguments

Details

Lane ordering is controlled by sort_by. With many subjects, consider suppressing y-axis labels via theme(axis.text.y = element_blank()).

Value

A ggplot2 layer object.

Aesthetics

Required aesthetics are shown in bold. size and linewidth are intentionally independent: each controls a different graphical element.

• x — time variable (numeric or Date)

• id — subject identifier; determines lane position on the y axis

• colour — color of both the connecting path and the point border

• fill — point interior color for filled shapes (21–25); no effect on path

• size — point size only; set to NA or 0 to suppress points

• linewidth — path width only; does not affect observation points

• alpha — transparency applied to both path and points

• shape — point shape (default 19). Set to NA to suppress points.

• stroke, linetype — point border width / path line type

Examples

library(ggplot2)
df <- data.frame(
  subject_id = rep(1:5, each = 4),
  time = rep(1:4, 5),
  visit_month = rep(1:4, 5),
  value = rep(1:4, 5),
  hba1c = rep(1:4, 5),
  arm = rep(c("Treatment", "Control"), c(12, 8))
)
ggplot(df, aes(x = time, id = subject_id, colour = hba1c)) +
  geom_kodom_line(sort_by = "mean", n_max = 50) +
  scale_colour_kodom() +
  theme_kodom()

Periodic "Star Trail" swimlane plot for longitudinal trajectories

Description

Draws concentric arcs representing cyclical longitudinal data. Time maps to angle (one full revolution equals one period), and each subject's base radius is determined by its lane rank. To separate successive cycles of the same subject the radius drifts outward slightly as total time increases, forming a star trail or Archimedean spiral.

Usage

geom_kodom_periodic(
  mapping = NULL,
  data = NULL,
  stat = StatKodomPeriodic,
  position = "identity",
  ...,
  period = 12,
  spiral_fraction = 0.1,
  inner_fraction = 0.3,
  lane_width = 1,
  sort_by = "none",
  n_max = Inf,
  show_points = TRUE,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

Arguments

Details

Coordinate system. This geom is designed for use with coord_polar(theta = "x"). Use coord_kodom_periodic() as a convenient wrapper that sets start = pi/2 (12 o'clock at x = 0) and direction = -1 (clockwise) by default.

Axis labels. Because x is continuous time, ggplot2 will automatically expand the limits to cover the entire time range if you use standard scales, which alters the length of a full 360-degree rotation. To make one rotation exactly equal one period, use the included wrapper scale_x_kodom_periodic():

scale_x_kodom_periodic(period = 12, breaks = 1:12, labels = month.abb)

Value

A ggplot2 layer object.

Kodom color palette

Description

Returns colors inspired by the Kadam flower (Neolamarckia cadamba): teal (low), gold (mid), red (high). Passing n > 3 interpolates between the three anchors via grDevices::colorRampPalette().

Usage

kodom_colors(n = 3L)

Arguments

Value

Character vector of hex color codes.

Examples

kodom_colors()
kodom_colors(7)

Kodom color scale for the color aesthetic

Description

A ggplot2 color scale using the Kadam flower palette (teal -> gold -> red). Designed to compose with geom_kodom_line(), geom_kodom_heatmap(), and geom_kodom_circular().

Usage

scale_color_kodom(
  colors = kodom_colors(),
  color_breaks = NULL,
  name = ggplot2::waiver(),
  discretize = FALSE,
  ...
)

scale_colour_kodom(
  colors = kodom_colors(),
  color_breaks = NULL,
  name = ggplot2::waiver(),
  discretize = FALSE,
  ...
)

Arguments

Details

Set discretize = TRUE to switch from a smooth gradient to solid color bands separated at color_breaks — useful when values change slowly and a continuous gradient washes out into a single hue.

Value

A ggplot2 scale object.

Examples

library(ggplot2)
df <- data.frame(
  subject_id = rep(1:5, each = 4),
  time = rep(1:4, 5),
  visit_month = rep(1:4, 5),
  value = rep(1:4, 5),
  hba1c = rep(1:4, 5),
  arm = rep(c("Treatment", "Control"), c(12, 8))
)
ggplot(df, aes(x = time, id = subject_id, color = value)) +
  geom_kodom_line() +
  scale_color_kodom()

# Discrete bands at clinical thresholds
ggplot(df, aes(x = time, id = subject_id, color = hba1c)) +
  geom_kodom_line() +
  scale_color_kodom(discretize = TRUE, color_breaks = c(5.7, 6.5))

Kodom fill scale for the fill aesthetic

Description

Identical behavior to scale_color_kodom() but targets the fill aesthetic. Intended for use with geom_kodom_heatmap().

Usage

scale_fill_kodom(
  colors = kodom_colors(),
  color_breaks = NULL,
  name = ggplot2::waiver(),
  discretize = FALSE,
  ...
)

Arguments

Value

A ggplot2 scale object.

Examples

library(ggplot2)
df <- data.frame(
  subject_id = rep(1:5, each = 4),
  time = rep(1:4, 5),
  visit_month = rep(1:4, 5),
  value = rep(1:4, 5),
  hba1c = rep(1:4, 5),
  arm = rep(c("Treatment", "Control"), c(12, 8))
)
ggplot(df, aes(x = time, id = subject_id, fill = value)) +
  geom_kodom_heatmap() +
  scale_fill_kodom()

X-scale for periodic longitudinal plots

Description

This is a convenience wrapper around ggplot2::scale_x_continuous() that enforces limits = c(0, period) and uses oob = scales::oob_keep.

Usage

scale_x_kodom_periodic(period = 12, breaks = 1:period, ...)

Arguments

Details

Why is this necessary? To make exactly one cycle span exactly one 360-degree rotation in coord_polar, the scale limits must be set to the period length (e.g., c(0, 12)). However, standard ggplot2 scale_x_continuous will drop any data outside those limits. By setting oob = scales::oob_keep, we instruct ggplot2 to keep the data that exceeds the period. coord_polar then natively wraps those out-of-bounds values around the circle, creating beautiful, continuous Archimedean spirals!

Value

A ggplot2::scale_x_continuous() object.

Examples

library(ggplot2)
df <- data.frame(
  subject_id = rep(1:5, each = 4),
  time = rep(1:4, 5),
  visit_month = rep(1:4, 5),
  value = rep(1:4, 5),
  hba1c = rep(1:4, 5),
  arm = rep(c("Treatment", "Control"), c(12, 8))
)
ggplot(df, aes(x = visit_month, id = subject_id, colour = hba1c)) +
  geom_kodom_periodic(period = 12) +
  scale_x_kodom_periodic(period = 12, labels = month.abb) +
  scale_y_kodom_periodic() +
  coord_kodom_periodic() +
  theme_kodom_periodic()

Radial scale for periodic Kodom plots

Description

In coord_polar(theta = "x"), ggplot2 sets the center of the plot to the minimum data y value, not to zero. Because geom_kodom_periodic() stores the hollow-center gap as an offset above zero (inner_fraction * n_lanes), the gap is invisible without this scale: the auto-range simply absorbs it.

Usage

scale_y_kodom_periodic(expand = ggplot2::expansion(mult = c(0, 0.05)))

Arguments

Details

This function pins y = 0 at the center by setting limits = c(0, NA), so the offset computed by inner_fraction becomes a visible donut hole. It should be added to every plot that uses geom_kodom_periodic().

Value

A ggplot2::scale_y_continuous() object.

Examples

library(ggplot2)
df <- data.frame(
  subject_id = rep(1:5, each = 4),
  time = rep(1:4, 5),
  visit_month = rep(1:4, 5),
  value = rep(1:4, 5),
  hba1c = rep(1:4, 5),
  arm = rep(c("Treatment", "Control"), c(12, 8))
)
ggplot(df, aes(x = visit_month, id = subject_id, colour = hba1c)) +
  geom_kodom_periodic(period = 12, inner_fraction = 0.3) +
  scale_x_continuous(breaks = 0:11, labels = month.abb) +
  scale_y_kodom_periodic() +
  scale_colour_kodom() +
  coord_kodom_periodic() +
  theme_kodom_periodic()

Clean theme for ggkodom linear and heatmap plots

Description

Based on ggplot2::theme_minimal(): vertical x-axis grid lines mark time positions, horizontal y-axis grid lines are suppressed (they would bisect subject lanes and add clutter). Restrained axis text, wide horizontal color-bar legend. Suitable for geom_kodom_line() and geom_kodom_heatmap().

Usage

theme_kodom(base_size = 12, legend_position = "top")

Arguments

Details

The vertical grid lines can be suppressed or restyled via the usual ggplot2 theme() override:

+ theme(panel.grid.major.x = element_blank())

Value

A ggplot2::theme() object.

Examples

library(ggplot2)
df <- data.frame(
  subject_id = rep(1:5, each = 4),
  time = rep(1:4, 5),
  visit_month = rep(1:4, 5),
  value = rep(1:4, 5),
  hba1c = rep(1:4, 5),
  arm = rep(c("Treatment", "Control"), c(12, 8))
)
ggplot(df, aes(x = time, id = subject_id, colour = value)) +
  geom_kodom_line() +
  scale_colour_kodom() +
  theme_kodom()

Theme for circular ggkodom plots

Description

Fully minimal Cartesian theme for geom_kodom_circular(): no axis text, ticks, or grid lines. Reference rings are drawn by the geom itself as annotation layers, so this theme suppresses all panel grid elements.

Usage

theme_kodom_circular(base_size = 12)

Arguments

Details

Unlike the original coord_polar()-based approach, geom_kodom_circular() performs its coordinate transformation inside the stat and renders in ordinary Cartesian space. This means panel.grid.major.y lines would appear as horizontal rules, not concentric circles — so both major axes are suppressed here.

Value

A ggplot2::theme() object.

Examples

library(ggplot2)
df <- data.frame(
  subject_id = rep(1:5, each = 4),
  time = rep(1:4, 5),
  visit_month = rep(1:4, 5),
  value = rep(1:4, 5),
  hba1c = rep(1:4, 5),
  arm = rep(c("Treatment", "Control"), c(12, 8))
)
ggplot(df, aes(x = time, id = subject_id, colour = value)) +
  geom_kodom_circular() +
  scale_colour_kodom() +
  coord_fixed() +
  theme_kodom_circular()

Theme for periodic Kodom plots

Description

Designed for use with geom_kodom_periodic() and coord_kodom_periodic(). Suppresses the radial (y) axis — which shows lane numbers that are not meaningful to readers — while keeping the angular (x) axis so that time labels added via ggplot2::scale_x_continuous() are visible around the ring.

Usage

theme_kodom_periodic(base_size = 12)

Arguments

Value

A ggplot2::theme() object.

Examples

library(ggplot2)
df <- data.frame(
  subject_id = rep(1:5, each = 4),
  time = rep(1:4, 5),
  visit_month = rep(1:4, 5),
  value = rep(1:4, 5),
  hba1c = rep(1:4, 5),
  arm = rep(c("Treatment", "Control"), c(12, 8))
)
ggplot(df, aes(x = visit_month, id = subject_id, colour = hba1c)) +
  geom_kodom_periodic(period = 12) +
  scale_x_continuous(breaks = 1:12, labels = month.abb, limits = c(0, 12)) +
  scale_colour_kodom() +
  coord_kodom_periodic() +
  theme_kodom_periodic()