Skip to contents

Summarizing fitted seroincidence models

Source: R/summary.seroincidence.R
summary.seroincidence.Rd

This function is a summary() method for seroincidence objects.

Usage 

# S3 method for class 'seroincidence'
summary(object, coverage = 0.95, verbose = TRUE, show_full_input = FALSE, ...)

Arguments

object

a list() outputted by stats::nlm() or est_seroincidence()

coverage

desired confidence interval coverage probability

verbose

whether to produce verbose messaging

show_full_input

logical; if TRUE, include metadata columns with noise parameters, observation counts, and input object names. Default is FALSE.

...

unused

Value

a tibble::tibble() containing the following:

  • est.start: the starting guess for incidence rate

  • ageCat: the age category we are analyzing

  • incidence.rate: the estimated incidence rate, per person year

  • CI.lwr: lower limit of confidence interval for incidence rate

  • CI.upr: upper limit of confidence interval for incidence rate

  • coverage: coverage probability

  • log.lik: log-likelihood of the data used in the call to est_seroincidence(), evaluated at the maximum-likelihood estimate of lambda (i.e., at incidence.rate)

  • iterations: the number of iterations used

  • antigen_isos: a list of antigen isotypes used in the analysis

  • nlm.convergence.code: information about convergence of the likelihood maximization procedure performed by nlm() (see "Value" section of stats::nlm(), component code); codes 3-5 indicate issues:

    • 1: relative gradient is close to zero, current iterate is probably solution.

    • 2: successive iterates within tolerance, current iterate is probably solution.

    • 3: Last global step failed to locate a point lower than x. Either x is an approximate local minimum of the function, the function is too non-linear for this algorithm, or stepmin in est_seroincidence() (a.k.a., steptol in stats::nlm()) is too large.

    • 4: iteration limit exceeded; increase iterlim.

    • 5: maximum step size stepmax exceeded five consecutive times. Either the function is unbounded below, becomes asymptotic to a finite value from above in some direction, or stepmax is too small.

If show_full_input = TRUE, the following columns are also included:

  • measurement.noise.<antigen>, measurement.noise.<antigen>, etc.: measurement noise parameters (eps) for each antigen isotype, where <antigen> is the antigen-isotype name

  • biological.noise.<antigen>, biological.noise.<antigen>, etc.: biological noise parameters (nu) for each antigen isotype, where <antigen> is the antigen-isotype name

  • n.seroresponse.params: number of longitudinal seroresponse parameter observations

  • seroresponse.params.stratified: logical indicating whether seroresponse parameters were stratified (FALSE for unstratified)

  • pop_data: name of the population data object passed to est_seroincidence()

  • sr_params: name of the seroresponse parameters object passed to est_seroincidence()

  • noise_params: name of the noise parameters object passed to est_seroincidence()

Examples 


library(dplyr)

xs_data <-
  sees_pop_data_pk_100

curve <-
  typhoid_curves_nostrat_100 |>
  filter(antigen_iso %in% c("HlyE_IgA", "HlyE_IgG"))

noise <-
  example_noise_params_pk

est1 <- est_seroincidence(
  pop_data = xs_data,
  sr_params = curve,
  noise_params = noise,
  antigen_isos = c("HlyE_IgG", "HlyE_IgA")
)

summary(est1)
#> # A tibble: 1 × 10
#>   est.start incidence.rate     SE CI.lwr CI.upr coverage log.lik iterations
#>       <dbl>          <dbl>  <dbl>  <dbl>  <dbl>    <dbl>   <dbl>      <int>
#> 1       0.1          0.166 0.0178  0.135  0.205     0.95   -524.          5
#> # ℹ 2 more variables: antigen.isos <chr>, nlm.convergence.code <ord>