Time-Series Quality Control for Daily Municipal Health Counts

Evaluates the quality of daily health event time series at the municipal level, producing per-municipality flags for:

Usage

sus_data_ts_quality(
  data,
  outcome_col = "n_obitos",
  muni_col = "code_muni",
  date_col = "date",
  min_completeness = 0.9,
  max_gap = 7L,
  break_alpha = 0.05,
  max_outlier_months = 3L,
  lang = "pt",
  verbose = TRUE
)

Arguments

data: A climasus_df at stage "aggregate", or any data.frame with a municipality identifier column, a date column, and a daily count column.
outcome_col: Character. Name of the daily count column. Default: "n_obitos".
muni_col: Character. Name of the municipality identifier column. Default: "code_muni".
date_col: Character. Name of the date column. Default: "date".
min_completeness: Numeric (0-1). Minimum completeness to recommend inclusion. Default: 0.90 (90% of expected days present).
max_gap: Integer. Maximum tolerated consecutive zero/missing days before flagging a temporal gap. Default: 7L.
break_alpha: Numeric. Significance level for structural break test. Default: 0.05. Ignored if strucchange is not installed.
max_outlier_months: Integer. Maximum number of outlier months allowed before exclusion. Default: 3L.
lang: Character. Language for messages: "pt" (default), "en", "es".
verbose: Logical. Print progress messages. Default TRUE.

Value

A climasus_ts_quality list with:

$flags: Tibble (one row per municipality) with columns: muni_col, n_obs, n_expected, completeness, has_break, break_pval, n_outlier_months, n_gaps_gt{max_gap}d, score, include.
$recommend_include: Character vector of municipality codes recommended for inclusion.
$recommend_exclude: Character vector of municipality codes recommended for exclusion, with reason.
$params: List of QC parameters used.

Details

Completeness: fraction of expected days with non-missing records.
Structural breaks: abrupt level shifts detectable by the CUSUM-based Zeileis et al. (2002) test (requires the strucchange package).
Monthly outliers: months with counts > Q3 + 1.5 x IQR (Tukey fence).
Temporal gaps: runs of consecutive days with zero or missing counts longer than max_gap.

A composite inclusion score (0-100) and a binary include recommendation are returned, matching the exclusion criteria used in large Brazilian heat-wave studies (Lowe et al. 2021, Anjos & Targino 2023).

References

Zeileis, A., Leisch, F., Hornik, K., & Kleiber, C. (2002). strucchange: An R Package for Testing for Structural Change in Linear Regression Models. Journal of Statistical Software, 7(2). doi:10.18637/jss.v007.i02

Examples

if (FALSE) { # \dontrun{
qc <- sus_data_ts_quality(
  df_agg,
  outcome_col       = "n_obitos",
  min_completeness  = 0.90,
  max_gap           = 7L
)
print(qc)

# Filter series to include only QC-passing municipalities
df_clean <- df_agg[df_agg$code_muni %in% qc$recommend_include, ]
} # }