Package 'tooth'

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
)

Arguments

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.

Value

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

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)

Description

Computes Decayed, Missing, and Filled Surfaces per person. Can separate root from coronal surfaces. Accepts long or wide format.

Usage

calc_dmfs(
  data,
  format = c("long", "wide"),
  id = "record_id",
  group = NULL,
  strata = NULL,
  lesion_col = "lesion_code",
  activity_col = "act",
  filling_col = "filling_code",
  tooth_code_col = "code",
  root_lesion_col = NULL,
  root_surfaces = c("rootb", "rootl", "rootm", "rootd"),
  decayed_codes = c(3, 4, 5, 6),
  activity_codes = c(2),
  filled_codes = c(1, 2, 4, 5, 6, 7, 8),
  missing_codes = c(1),
  root_decayed_codes = NULL,
  consider_activity = TRUE,
  consider_activity_coronal = NULL,
  consider_activity_root = NULL
)

Arguments

Value

A tibble with one row per person (and group/strata) containing: DS, FS, MS, DFS, DMFS, plus optional RDS (root decayed surfaces) when root_lesion_col is set, and binary indicators.

Description

Computes Decayed, Missing, and Filled Teeth counts per person. Handles both primary and permanent dentition. Can separate root caries from coronal caries. Accepts long or wide format data.

Usage

calc_dmft(
  data,
  format = c("long", "wide"),
  id = "record_id",
  group = NULL,
  strata = NULL,
  lesion_col = "lesion_code",
  activity_col = "act",
  filling_col = "filling_code",
  tooth_code_col = "code",
  root_lesion_col = NULL,
  root_surfaces = c("rootb", "rootl", "rootm", "rootd"),
  decayed_codes = c(3, 4, 5, 6),
  activity_codes = c(2),
  filled_codes = c(1, 2, 4, 5, 6, 7, 8),
  present_codes = c(2, 3, 4, 5, 6, 7, 8),
  missing_codes = c(1),
  root_decayed_codes = NULL,
  consider_activity = TRUE,
  consider_activity_coronal = NULL,
  consider_activity_root = NULL
)

Arguments

Value

A tibble with one row per person (and group/strata) containing:

DT

Decayed teeth (coronal)

FT

Filled teeth (not decayed)

MT

Missing teeth

DFT

Decayed or filled teeth

DMFT

Decayed + missing + filled teeth

num_teeth

Count of teeth present

RDT

Root-decayed teeth (only when root_lesion_col is set)

DT_yn, DFT_yn

Binary indicators

Diagnostic threshold

The default decayed_codes = c(3, 4, 5, 6) implements the D3 threshold: only ICDAS codes 3–6 (localised enamel breakdown through extensive cavitation) are scored as decayed, while ICDAS 1–2 (non-cavitated initial enamel lesions) are treated as sound. This D(3)MFT convention is the one most commonly reported in caries epidemiology. To use the more sensitive D1 threshold that also counts early enamel lesions, pass decayed_codes = c(1, 2, 3, 4, 5, 6).

Wide format

When format = "wide", each row is one person (and optional group). You must supply columns named like ⁠{tooth}_{surface}_{code_type}⁠ or use the wide_cols parameter. Alternatively, pass a pivot_spec — but the easiest approach is to reshape to long with pivot_to_long() first.

Description

Produces crown surface wedges (B/L/M/D/O) and up to four root surface bars (RB/RL/RM/RD), plus labels, outlines, and diagonals — all as data frames ready for ggplot2. Any surface can be excluded via the surfaces argument.

Usage

draw_tooth(
  tooth_id,
  quadrant,
  tooth_num,
  is_upper,
  surface_values,
  value_col = "prop",
  x_offset = 0,
  y_offset = 0,
  tooth_size = 1,
  show_roots = TRUE,
  surfaces = c("buc", "lin", "mes", "dis", "occ", "rootb", "rootl", "rootm", "rootd"),
  display_label = NULL
)

Arguments

Value

Named list of tibbles: crown, roots, labels, num_label, diags, outline.

Description

Helper to reshape wide-format data (one row per person-tooth, surfaces as separate columns) into the long format expected by calc_dmft().

Usage

pivot_to_long(
  data,
  id = "record_id",
  group = NULL,
  strata = NULL,
  lesion_suffix = "_les",
  filling_suffix = "_fil",
  activity_suffix = "_act",
  code_suffix = "_code"
)

Arguments

Details

Expects columns following the naming convention: ⁠{tooth}_{surface}_les⁠, ⁠{tooth}_{surface}_fil⁠, ⁠{tooth}_{surface}_act⁠, and ⁠{tooth}_code⁠ for tooth-level status.

Value

A long-format tibble.

Description

A simulated surface-level dental examination dataset for 20 patients, each with 7 teeth per quadrant (28 teeth) and 5 coronal surfaces plus 2 root surfaces per tooth. Designed for demonstrating and testing calc_dmft(), calc_dmfs(), and build_odontogram().

Usage

sim_exam

Format

A data frame with 3,920 rows and 7 columns:

record_id

Patient identifier (character, "P01" to "P20").

tooth_num

Tooth identifier in quadrant notation (e.g. "ur1", "ll7").

tooth_surface

Surface name: buc, lin, mes, dis, occ, rootb, or rootl.

lesion_code

ICDAS lesion code (integer 0-6). 0 = sound, 3-6 = caries.

filling_code

Filling/restoration code (integer). 0 = none, 1-8 = restored.

act

Lesion activity code (integer). 1 = inactive, 2 = active.

code

Tooth-level status code (integer). 1 = missing, 2-8 = present.

Examples

data(sim_exam)
head(sim_exam)
calc_dmft(sim_exam)

Description

Takes the output of calc_dmft() and produces a summary table with n, mean number of teeth, mean DT, mean DMFT, and optionally other columns — ready to pass directly to build_odontogram() via stats and stats_raw.

Usage

summarise_dmft(dmft_data, group_col, digits = 1)

Arguments

Value

A list with two elements:

stats

Summary data frame with one row per group, containing n, mean_teeth, mean_DT, mean_DMFT. Column names match what build_odontogram() expects for stats.

raw

The input data frame, for passing to stats_raw in build_odontogram().

Examples

data(sim_exam)
dmft <- calc_dmft(sim_exam)
dmft$treatment <- ifelse(
  as.numeric(gsub("P", "", dmft$record_id)) <= 10, "SDF", "ART"
)
result <- summarise_dmft(dmft, "treatment")
result$stats
# Pass directly to build_odontogram:
# build_odontogram(d, strata = "treatment",
#   stats = result$stats, stats_raw = result$raw,
#   stats_test = "wilcox", stats_var = "DMFT")

Description

Creates a tibble of tooth IDs for primary or permanent dentition with a configurable number of teeth per quadrant (5-8).

Usage

tooth_config(dentition = c("permanent", "primary"), teeth_per_quadrant = NULL)

Arguments

Value

A tibble with columns: quadrant, num, tooth_id, is_upper.

Description

Converts between FDI (ISO 3950), Universal (ADA), and the internal quadrant format used by this package ("ur1", "ll5", etc.).

Usage

tooth_convert(x, from = "fdi", to = "quadrant", dentition = "permanent")

Arguments

Details

The "universal" system follows the standard ADA conventions: permanent teeth are numbered 1–32 (1 = upper-right third molar, 32 = lower-right third molar), while primary teeth use the letters A–T (A = upper-right second primary molar, T = lower-right second primary molar). FDI two-digit codes are 11–48 for permanent and 51–85 for primary dentition.

Value

Character vector in the target system.

Examples

tooth_convert("11", from = "fdi", to = "quadrant")
tooth_convert("ur1", from = "quadrant", to = "fdi")
tooth_convert(c("1", "16", "17", "32"), from = "universal", to = "fdi")
# Primary dentition uses ADA letters A-T for the universal system:
tooth_convert("ur1", from = "quadrant", to = "universal",
              dentition = "primary")   # "E"
tooth_convert("K", from = "universal", to = "fdi", dentition = "primary")