Add cluster-robust standard errors and multi-level clustering support for clustered sampling designs

DESCRIPTION

@@ -1,7 +1,7 @@
 Type: Package
 Package: serocalculator
 Title: Estimating Infection Rates from Serological Data
-Version: 1.4.0.9003
+Version: 1.4.0.9004
 Authors@R: c(
     person("Kristina", "Lai", , "kwlai@ucdavis.edu", role = c("aut", "cre")),
     person("Chris", "Orwa", role = "aut"),
@@ -77,7 +77,7 @@ Encoding: UTF-8
 Language: en-US
 LazyData: true
 NeedsCompilation: no
-Roxygen: list(markdown = TRUE, roclets = c("collate", "rd", "namespace", "devtag::dev_roclet"))
+Roxygen: list(markdown = TRUE, roclets = c("collate", "rd", "namespace"))
 RoxygenNote: 7.3.3
 Remotes: 
     d-morrison/snapr

NAMESPACE

@@ -7,6 +7,8 @@ S3method(autoplot,seroincidence)
 S3method(autoplot,seroincidence.by)
 S3method(autoplot,sim_results)
 S3method(autoplot,summary.seroincidence.by)
+S3method(print,icc_seroincidence)
+S3method(print,icc_seroincidence.by)
 S3method(compare_seroincidence,default)
 S3method(compare_seroincidence,seroincidence)
 S3method(compare_seroincidence,seroincidence.by)
@@ -25,6 +27,7 @@ export(as_pop_data)
 export(as_sr_params)
 export(autoplot)
 export(check_pop_data)
+export(compute_icc)
 export(compare_seroincidence)
 export(count_strata)
 export(est.incidence)

NEWS.md

@@ -1,9 +1,43 @@
 # serocalculator (development version)
 
+## New features
+
+* Added `compute_icc()` function to calculate the Intraclass Correlation Coefficient
+  (ICC) for seroincidence estimates from clustered sampling designs. The ICC measures
+  the proportion of variance due to between-cluster variation. Now works with both
+  `seroincidence` and `seroincidence.by` objects, calculating ICC for each stratum
+  when used with stratified analyses.
+* Added `cluster_var` and `stratum_var` parameters to `est_seroincidence_by()` to
+  support cluster-robust standard error estimation in stratified analyses.
+* `compute_icc()` output now includes antigen isotypes information to clarify which
+  antibodies were used in the analysis.
+* `compute_icc()` output now includes minimum and maximum cluster sizes in addition
+  to the average, providing more complete information about cluster size distribution.
+  The print method now clarifies that cluster size refers to "observations per cluster".
+* `cluster_var` parameter now accepts multiple variables (e.g., `c("school", "classroom")`)
+  for multi-level clustered sampling designs. Cluster-robust standard errors will account
+  for all specified clustering levels. Note: ICC calculation only supports single-level
+  clustering and will produce an error if multiple cluster variables are provided.
+
+## Bug fixes
+
+* Fixed column naming issue in `summary.seroincidence()` where cluster-robust standard
+  errors caused `[]` notation in column names (`SE[,1]` instead of `SE`).
+* Added `se_type` column to `summary.seroincidence()` output to clearly indicate whether
+  "standard" or "cluster-robust" standard errors are being used.
+* Fixed `est_seroincidence_by()` to properly pass cluster and stratum variables through
+  to stratified analyses. Previously, these variables were dropped during data stratification,
+  causing errors when trying to use clustering with `est_seroincidence_by()`.
+
 # serocalculator 1.4.0
 
 ## New features
 
+* Added support for cluster-robust standard errors in `est_seroincidence()` through
+  new `cluster_var` and `stratum_var` parameters. When `cluster_var` is specified,
+  `summary.seroincidence()` automatically computes cluster-robust (sandwich) variance
+  estimates to account for within-cluster correlation in clustered sampling designs
+  such as household or school-based surveys.
 * Added `compare_seroincidence()` function for statistical comparison of seroincidence rates
   - Performs two-sample z-tests to compare seroincidence estimates
   - Returns `htest` format when comparing two single estimates