calc_dmfs: Calculate DMFS / dmfs index from surface-level data

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
)

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.

Arguments

data: Data frame. In long format: one row per tooth-surface with columns for id, tooth_num, tooth_surface, and clinical codes. In wide format: one row per person-tooth with surface codes in separate columns.
format: "long" (default) or "wide". See Details.
id: Person-identifier column (default "record_id").
group: Optional grouping column(s) for repeated measures, e.g. "redcap_event_name". Character vector.
strata: Optional stratification column(s), e.g. "treatment". The output will include these columns for downstream group summaries.
lesion_col, activity_col, filling_col, tooth_code_col: Column names for ICDAS codes (long format).
root_lesion_col: Optional column for root surface lesion codes. When provided, root caries (RDT) is calculated separately from coronal (DT). Set to NULL to ignore root caries (default).
root_surfaces: Character vector of surface names considered root surfaces. Default c("rootb","rootl","rootm","rootd").
decayed_codes: Numeric vector of lesion codes considered decayed (default c(3,4,5,6) for ICDAS).
activity_codes: Numeric vector of activity codes indicating active caries (default c(2)).
filled_codes: Numeric vector of filling codes indicating a restoration is present (default c(1,2,4,5,6,7,8)).
missing_codes: Numeric vector of tooth-level codes indicating the tooth is missing (default c(1)).
root_decayed_codes: Numeric vector for root caries codes (default same as decayed_codes).
consider_activity: Logical; overall default for whether a lesion must also carry an active-caries code (activity_codes) to be counted as decayed. TRUE (default) requires activity; FALSE counts any lesion in decayed_codes regardless of activity. Standard epidemiological D(3)MFT counts all cavitated lesions irrespective of activity, so set FALSE to match that convention. When FALSE, the activity column is not referenced and need not be present.
consider_activity_coronal, consider_activity_root: Optional logical overrides for the coronal and root components. NULL (default) inherits consider_activity. Use these to treat crown and root caries differently (e.g. require activity coronally but not for roots, where activity is often not assessed): consider_activity_root = FALSE.