Deprecate adjust_infection_to_report(), report_cases(), and sample_approx_dist()

[jamesmbaazam]

Description

This PR closes #520.

The functions sample_approx_dist(), report_cases(), and adjust_infection_reports() have been deprecated as the functionality they provide can now be achieved with simulate_secondary().

Initial submission checklist

• My PR is based on a package issue and I have explicitly linked it.
• I have tested my changes locally (using devtools::test() and devtools::check()).
• I have added or updated unit tests where necessary.
• I have updated the documentation if required and rebuilt docs if yes (using devtools::document()).
• I have followed the established coding standards (and checked using lintr::lint_package()).
• I have added a news item linked to this PR.

After the initial Pull Request

• I have reviewed Checks for this PR and addressed any issues as far as I am able.

[sbfnk]

Good stuff.

I think it would be good to point the user to how they would simulate_secondary to reproduce the functionality of the deprecated functions - but that should wait until #504 is merged as otherwise the syntax will have to be updated again.

I'd suggest to address the comments/issues and then convert to a draft PR to revisit after #504 is merged.

[jamesmbaazam]

Good stuff.

I think it would be good to point the user to how they would simulate_secondary to reproduce the functionality of the deprecated functions - but that should wait until #504 is merged as otherwise the syntax will have to be updated again.

I'd suggest to address the comments/issues and then convert to a draft PR to revisit after #504 is merged.

Thanks for the review. I'll convert the PR to a draft now until #504 is merged.

[sbfnk]

@jamesmbaazam I've now merged main which seems to pass tests. I think once we add some guidance to the user this is good to go.

Not quite sure where this best lives but here is some code for adjust_infection_to_report:

cases <- data.table::copy(example_confirmed)[, cases := as.integer(confirm)]
delay_def <- lognorm_dist_def(
  mean = 5, mean_sd = 1, sd = 3, sd_sd = 1,
  max_value = 30, samples = 1, to_log = TRUE
)
report <- adjust_infection_to_report(
  cases, delay_defs = delay, reporting_model = function(n) rpois(length(n), n)
)
print(report)


cases <- data.table::copy(example_confirmed)[, primary := as.integer(confirm)]
uncertain_delay <- LogNormal(mean = Normal(5, 1), sd = Normal(3, 1), max = 30)
delay <- fix_dist(uncertain_delay, strategy = "sample")
report <- simulate_secondary(
  cases, delays = delay_opts(delay), obs = obs_opts(family = "poisson")
)
print(report)

and report_cases:

cases <- example_confirmed[1:40]
cases <- cases[, cases := as.integer(confirm)]
cases <- cases[, confirm := NULL][, sample := 1]
reported_cases <- report_cases(
  case_estimates = cases,
  delays = delay_opts(example_incubation_period + example_reporting_delay),
  type = "sample"
)
print(reported_cases$samples)

cases <- example_confirmed[1:40]
cases <- cases[, primary := as.integer(confirm)]
report <- simulate_secondary(
  cases,
  delays = delay_opts(
    fix_dist(example_incubation_period + example_reporting_delay)
  ),
  obs = obs_opts(family = "poisson")
)
print(report)

[jamesmbaazam]

@jamesmbaazam I've now merged main which seems to pass tests. I think once we add some guidance to the user this is good to go.

Not quite sure where this best lives but here is some code for adjust_infection_to_report:

cases <- data.table::copy(example_confirmed)[, cases := as.integer(confirm)]
delay_def <- lognorm_dist_def(
  mean = 5, mean_sd = 1, sd = 3, sd_sd = 1,
  max_value = 30, samples = 1, to_log = TRUE
)
report <- adjust_infection_to_report(
  cases, delay_defs = delay, reporting_model = function(n) rpois(length(n), n)
)
print(report)


cases <- data.table::copy(example_confirmed)[, primary := as.integer(confirm)]
uncertain_delay <- LogNormal(mean = Normal(5, 1), sd = Normal(3, 1), max = 30)
delay <- fix_dist(uncertain_delay, strategy = "sample")
report <- simulate_secondary(
  cases, delays = delay_opts(delay), obs = obs_opts(family = "poisson")
)
print(report)

and report_cases:

cases <- example_confirmed[1:40]
cases <- cases[, cases := as.integer(confirm)]
cases <- cases[, confirm := NULL][, sample := 1]
reported_cases <- report_cases(
  case_estimates = cases,
  delays = delay_opts(example_incubation_period + example_reporting_delay),
  type = "sample"
)
print(reported_cases$samples)

cases <- example_confirmed[1:40]
cases <- cases[, primary := as.integer(confirm)]
report <- simulate_secondary(
  cases,
  delays = delay_opts(
    fix_dist(example_incubation_period + example_reporting_delay)
  ),
  obs = obs_opts(family = "poisson")
)
print(report)

We could add these to the example files of the deprecated functions and add a details argument to deprecate_warn() to point users to it., i.e., "Use simulate_secondary() instead. See ?<deprecated_func()> for equivalent usage. Note that this will be removed in v2.0.0." See suggested changes in 9737603 and 0570abc.

[sbfnk]

Great work!