Add version crosswalk article to website for v1.3.0 → v1.4.0 migration

.github/copilot-instructions.md

@@ -579,6 +579,8 @@ When refactoring existing code:
 - **Seed tests**: Use `withr::local_seed()` for reproducible tests
 - **Avoid code duplication**: Don't copy-paste substantial code chunks. Instead, decompose reusable logic into well-named helper functions
 - **Quarto vignettes**: Use Quarto-style chunk options with `#|` prefix (e.g., `#| label: my-chunk`, `#| eval: false`)
+- **New articles**: Use `.qmd` format for all new vignettes and articles going forward
+- **Quarto callouts**: Use Quarto callout blocks for notes, warnings, and tips (e.g., `::: {.callout-note}`)
 - **Tidyverse replacements**: Use tidyverse/modern replacements for base R functions where available
 - **Write tidy code**: Keep code clean, readable, and well-organized
 

DESCRIPTION

@@ -1,7 +1,7 @@
 Type: Package
 Package: serocalculator
 Title: Estimating Infection Rates from Serological Data
-Version: 1.4.0.9007
+Version: 1.4.0.9008
 Authors@R: c(
     person("Kristina", "Lai", , "kwlai@ucdavis.edu", role = c("aut", "cre")),
     person("Chris", "Orwa", role = "aut"),

NEWS.md

@@ -1,5 +1,9 @@
 # serocalculator (development version)
 
+* Added Version Crosswalk article to pkgdown website to help users migrate code from v1.3.0 to v1.4.0
+  - Provides clear tables comparing old and new function names
+  - Includes code examples showing how to update existing code
+  - Accessible as a prominent tab in the website navigation
 ## New features
 
 * Added `cluster_var` and `stratum_var` parameters to `est_seroincidence()` and 

inst/WORDLIST

@@ -42,6 +42,7 @@ bioassays
 biomarker
 biomarkers
 boldsymbol
+callout
 cdot
 codecov
 colour
@@ -100,6 +101,8 @@ providecommand
 qmd
 qquad
 recombinant
+remotes
+renamings
 renewcommand
 se
 sectionally
@@ -111,6 +114,7 @@ seroepidemiology
 seroincidence
 seroincidences
 serologic
+Serological
 seronegative
 seroresponse
 seroresponses

pkgdown/_pkgdown.yml

@@ -73,6 +73,11 @@ articles:
   contents:
   - articles/serocalculator
 
+- title: Version Crosswalk
+  navbar: Version Crosswalk
+  contents:
+  - articles/version-crosswalk-1.3-to-1.4
+
 - title: Methodology
   navbar: Methodology
   contents:

vignettes/articles/version-crosswalk-1.3-to-1.4.qmd

@@ -0,0 +1,244 @@
+---
+title: "Version Crosswalk: v1.3.0 to v1.4.0"
+format: html
+---
+
+```{r}
+#| include: false
+knitr::opts_chunk$set(
+  collapse = TRUE,
+  comment = "#>"
+)
+```
+
+## Overview
+
+This guide helps users migrate code from **serocalculator v1.3.0** to **v1.4.0**. 
+The main changes are function renamings for improved clarity and consistency.
+
+**If you have existing code using v1.3.0, use this guide to update your function calls.**
+
+## Quick Reference Table
+
+### Main Estimation Functions
+
+| v1.3.0 Function | v1.4.0 Function | What it does |
+|----------------|-----------------|--------------|
+| `est.incidence()` | `est_seroincidence()` | Estimate seroincidence for entire dataset |
+| `est.incidence.by()` | `est_seroincidence_by()` | Estimate seroincidence stratified by groups |
+
+::: {.callout-note}
+The intermediate names `estimate_scr()` and `estimate_scr_by()` were used briefly in early v1.4.0 development but replaced with the final names shown above.
+:::
+
+### Data Preparation Functions
+
+| v1.3.0 Function | v1.4.0 Function | What it does |
+|----------------|-----------------|--------------|
+| `load_curve_params()` | `load_sr_params()` | Load seroresponse curve parameters |
+| `as_curve_params()` | `as_sr_params()` | Convert data to seroresponse parameters |
+| `sim.cs()` | `sim_pop_data()` | Simulate cross-sectional population data |
+| `sim.cs.multi()` | `sim_pop_data_multi()` | Simulate multiple cross-sectional datasets |
+
+### Function Arguments
+
+| v1.3.0 Argument | v1.4.0 Argument | Used in functions |
+|-----------------|-----------------|-------------------|
+| `curve_params` | `sr_params` | `est_seroincidence()`, `est_seroincidence_by()` |
+
+## Code Examples
+
+### Example 1: Basic Seroincidence Estimation
+
+**Old code (v1.3.0):**
+```r
+# Load curve parameters (v1.3.0 - DEPRECATED)
+curve_params <- load_curve_params("parameters.rds")
+
+# Estimate seroincidence
+results <- est.incidence(
+  pop_data = my_data,
+  curve_params = curve_params
+)
+```
+
+**New code (v1.4.0):**
+```{r}
+#| label: example-1-v1.4.0
+library(serocalculator)
+
+# Load seroresponse parameters from RDS file
+sr_params <- load_sr_params(
+  serocalculator_example("example_curve_params.rds")
+)
+
+# Load example population data from CSV
+pop_data <- readr::read_csv(
+  serocalculator_example("example_pop_data.csv"),
+  show_col_types = FALSE
+) |>
+  as_pop_data()
+
+# Load noise parameters
+noise_params_full <- load_noise_params(
+  serocalculator_example("example_noise_params.rds")
+)
+
+# Use only the antigen-isotypes present in pop_data
+antigen_isos <- unique(get_biomarker_names(pop_data))
+noise_params <- noise_params_full |>
+  dplyr::filter(antigen_iso %in% antigen_isos) |>
+  dplyr::select(-Country, -X)
+
+# Estimate seroincidence
+results <- est_seroincidence(
+  pop_data = pop_data,
+  sr_params = sr_params,
+  noise_params = noise_params,
+  antigen_isos = antigen_isos
+)
+
+summary(results)
+```
+
+### Example 2: Stratified Analysis
+
+**Old code (v1.3.0):**
+```r
+# Stratified estimation (v1.3.0 - DEPRECATED)
+results_by_group <- est.incidence.by(
+  pop_data = my_data,
+  curve_params = curve_params,
+  strata = c("age_group", "location")
+)
+```
+
+**New code (v1.4.0):**
+```{r}
+#| label: example-2-v1.4.0
+# Stratified estimation by Country
+results_by_group <- est_seroincidence_by(
+  pop_data = pop_data,
+  sr_params = sr_params,
+  noise_params = noise_params,
+  strata = "Country",
+  antigen_isos = antigen_isos
+)
+
+summary(results_by_group)
+```
+
+### Example 3: Simulating Data
+
+**Old code (v1.3.0):**
+```r
+# Simulate cross-sectional data (v1.3.0 - DEPRECATED)
+simulated_data <- sim.cs(
+  curve_params = curve_params,
+  n = 100
+)
+
+# Simulate multiple datasets
+multiple_sims <- sim.cs.multi(
+  curve_params = curve_params,
+  n = 100,
+  n_reps = 10
+)
+```
+
+**New code (v1.4.0):**
+```{r}
+#| label: example-3-v1.4.0
+# Biologic noise distribution for simulation
+noise_limits <- matrix(
+  c(0, 0.5),
+  nrow = length(antigen_isos),
+  ncol = 2,
+  byrow = TRUE,
+  dimnames = list(antigen_isos, c("min", "max"))
+)
+
+# Simulate cross-sectional data
+simulated_data <- sim_pop_data(
+  curve_params = sr_params,
+  noise_limits = noise_limits,
+  antigen_isos = antigen_isos,
+  n_samples = 100,
+  add_noise = TRUE,
+  format = "long"
+)
+
+head(simulated_data)
+
+# Simulate multiple datasets
+multiple_sims <- sim_pop_data_multi(
+  curve_params = sr_params,
+  noise_limits = noise_limits,
+  antigen_isos = antigen_isos,
+  sample_sizes = 100,
+  nclus = 3,
+  lambdas = 0.1,
+  num_cores = 1,
+  add_noise = TRUE,
+  format = "long"
+)
+
+nrow(multiple_sims)
+```
+
+## New Features in v1.4.0
+
+In addition to the renamed functions, v1.4.0 includes several new features:
+
+- **`compare_seroincidence()`**: New function for statistical comparison of seroincidence rates between groups
+- **Enhanced plotting**: Additional options for `autoplot.curve_params()` including `log_x`, `log_y`, and `chain_color`
+- **Extended simulation analysis**: New `analyze_sims()` and `autoplot.sim_results()` functions
+- **Improved documentation**: Multi-version pkgdown documentation with version dropdown
+
+## Other Notable Changes
+
+- Main estimation functions (`est_seroincidence()`, `est_seroincidence_by()`) now use `sr_params` argument instead of `curve_params`
+- Function names now use snake_case instead of dots (e.g., `est.incidence()` → `est_seroincidence()`)
+- Many internal improvements to error messages and warnings
+
+::: {.callout-warning}
+**Important**: Not all functions changed their parameter names. Functions like `sim_pop_data()` and `graph_loglik()` still use `curve_params` as the parameter name. Only the main estimation functions use `sr_params`.
+:::
+
+## Need More Help?
+
+- See the [NEWS file](https://ucd-serg.github.io/serocalculator/news/index.html) for complete details
+- Check the [main tutorial](https://ucd-serg.github.io/serocalculator/articles/serocalculator.html) for comprehensive examples using v1.4.0 syntax
+- Visit the [function reference](https://ucd-serg.github.io/serocalculator/reference/index.html) for detailed documentation
+
+## Summary
+
+The transition from v1.3.0 to v1.4.0 primarily involves:
+
+1. Replace dots in function names with underscores (e.g., `est.incidence()` → `est_seroincidence()`)
+2. Update `curve_params` arguments to `sr_params` **for estimation functions only**
+3. Use the new `load_sr_params()` and `as_sr_params()` instead of the `_curve_params` versions
+4. Use `.rds` files with `load_sr_params()` (not `.csv` files)
+
+**Quick search-and-replace tips:**
+
+::: {.callout-tip}
+## Function name changes (safe for all code)
+
+- `est.incidence.by(` → `est_seroincidence_by(`
+- `est.incidence(` → `est_seroincidence(`
+- `load_curve_params(` → `load_sr_params(`
+- `as_curve_params(` → `as_sr_params(`
+- `sim.cs.multi(` → `sim_pop_data_multi(`
+- `sim.cs(` → `sim_pop_data(`
+:::
+
+::: {.callout-tip}
+## Argument name changes (only for estimation functions)
+
+Within calls to `est_seroincidence()` and `est_seroincidence_by()`:
+
+- `curve_params = ` → `sr_params = `
+
+**Do not** change `curve_params` to `sr_params` in other functions like `sim_pop_data()`.
+:::