tooth (version 0.5.0)

build_odontogram: Build a surface-level odontogram heatmap

Description

Draws a full-arch odontogram with colour-coded tooth surfaces. Supports primary and permanent dentition (5–8 teeth per quadrant), selective surfaces, stratification, summary statistics with significance testing, and configurable tooth numbering.

Usage

build_odontogram(
  data,
  value_col = "prop",
  dentition = "permanent",
  teeth_per_quadrant = NULL,
  title = "Surface Odontogram",
  subtitle = NULL,
  color_low = "#FFFFFF",
  color_high = "#C62828",
  na_color = "grey90",
  min_val = NULL,
  max_val = NULL,
  legend_title = "Proportion",
  show_roots = TRUE,
  surfaces = c("buc", "lin", "mes", "dis", "occ", "rootb", "rootl", "rootm", "rootd"),
  show_labels = TRUE,
  label_size = 1.8,
  tooth_label_size = 3,
  numbering = c("quadrant", "fdi", "universal"),
  strata = NULL,
  strata_labels = NULL,
  stats = NULL,
  stats_test = NULL,
  stats_var = NULL,
  stats_raw = NULL,
  footnote = NULL,
  combine = TRUE,
  ncol = 1
)

Value

A ggplot object (or list of ggplots if combine = FALSE).

Arguments

data

Data frame with at least tooth_num (e.g. "ur1"), tooth_surface (e.g. "buc", "occ", "rootb"), and a numeric value column. If stratifying, include the column named in strata.

value_col

Name of the numeric column to map to fill colour.

dentition

"permanent" or "primary".

teeth_per_quadrant

Integer 5–8 (default derived from dentition).

title, subtitle

Plot title/subtitle.

color_low, color_high

Gradient endpoints (default "#FFFFFF" to "#C62828").

na_color

Fill for missing surfaces (default "grey90").

min_val, max_val

Lower and upper limits for the colour scale. Both auto-detected when NULL. Set manually to fix the range across multiple plots.

legend_title

Legend title.

show_roots

Logical; draw root caries bars.

surfaces

Character vector of surfaces to draw.

show_labels

Logical; show surface abbreviation labels (B, L, M, D, O, RB, RL, RM, RD) inside each surface polygon.

label_size

Numeric; size of surface labels.

tooth_label_size

Numeric; size of tooth number labels (default 3).

numbering

Tooth numbering system for display: "quadrant" (default), "fdi", or "universal".

strata

Optional column name for stratification.

strata_labels

Optional named character vector to relabel strata in panel titles.

stats

Optional data frame of per-group summary statistics to display below each panel. Must contain a column matching strata and numeric columns to display (e.g. n, mean_DMFT, mean_DT). See Details.

stats_test

Method for comparing stats across strata: "t" for t-test (default), "wilcox" for Wilcoxon rank-sum, or NULL to skip. P-values are shown as significance stars.

stats_var

Column name in stats_raw to test for differences (e.g. "DMFT"). Required when stats_test is not NULL.

stats_raw

Optional data frame of individual-level data used for significance testing. Must contain a column matching strata and a numeric column matching stats_var. Required when stats_test is set.

footnote

Optional character string displayed below the plot as a caption. Use for abbreviation explanations and p-value definitions.

combine

Logical; if strata is set, combine panels into one plot (default TRUE) or return a named list.

ncol

Number of columns when combining stratified panels.

Details

Summary statistics: Pass a data frame to stats with one row per stratum. Example:

stats_df <- data.frame(
  treatment = c("SDF", "ART"),
  n = c(120, 115),
  mean_DT = c(2.3, 2.8),
  mean_DMFT = c(5.1, 5.6)
)
build_odontogram(d, strata = "treatment", stats = stats_df)

Significance stars: When stats_test and stats_var are set and raw data is provided via stats_raw, p-values are computed and appended: *** p < 0.001, ** p < 0.01, * p < 0.05, ns otherwise.

Examples

library(tibble)
d <- expand.grid(
  tooth_num = paste0(rep(c("ur","ul","lr","ll"), each=7), 1:7),
  tooth_surface = c("buc","lin","mes","dis","occ"),
  stringsAsFactors = FALSE
)
d$prop <- runif(nrow(d))
build_odontogram(d, teeth_per_quadrant = 7)