Skip to contents

Getting Started

Source: vignettes/articles/erglm.Rmd
erglm.Rmd

erglm provides estimation tools for exposure-response models based on glm(). It’s mostly a convenience package: the core tools are thin wrappers around glm() and its usual machinery, tested and supported for binomial, poisson, gaussian, and Gamma families. This article is a quick tour of the main pieces; the other articles go into more depth on each.

Example data

The package ships with a synthetic dataset, erglm_data, used throughout the documentation. It has an exposure metric (aucss), several covariates (sex, age, weight, dose, …), and response columns for each supported family: binary (ae1, ae2), count (ae_count), continuous (biomarker_change), and positive right-skewed continuous (ae_duration):

erglm_data
#> # A tibble: 300 × 13
#>       id sex      age weight  dose treatment aucss cmaxss   ae1   ae2 ae_count
#>    <int> <fct>  <int>  <dbl> <dbl> <fct>     <dbl>  <dbl> <dbl> <dbl>    <int>
#>  1     1 Male      35     79   200 Drug       673.   97.3     0     1        1
#>  2     2 Female    22     58   200 Drug      2806.  301.      1     1        6
#>  3     3 Female    28     58     0 Placebo      0     0       0     0        1
#>  4     4 Female    18     57   100 Drug      1169.  198.      1     1        0
#>  5     5 Male      28     77   100 Drug       377.   51.4     0     0        0
#>  6     6 Female    19     76   200 Drug       327.   25.4     1     0        0
#>  7     7 Male      30     70     0 Placebo      0     0       0     0        0
#>  8     8 Female    34     60   100 Drug      1208.  133.      1     1        1
#>  9     9 Male      21     89     0 Placebo      0     0       0     0        0
#> 10    10 Female    34     56   200 Drug       254.   31.0     0     0        1
#> # ℹ 290 more rows
#> # ℹ 2 more variables: biomarker_change <dbl>, ae_duration <dbl>

Fitting a model

erglm_model() fits the model – it takes the same formula/data arguments as glm(), plus a family argument (defaulting to gaussian(), matching glm()’s own default):

mod <- erglm_model(ae1 ~ aucss + sex, erglm_data, family = binomial())
mod
#> 
#> Call:  stats::glm(formula = formula, family = family, data = data)
#> 
#> Coefficients:
#> (Intercept)        aucss      sexMale  
#>   -1.648112     0.005508    -0.312232  
#> 
#> Degrees of Freedom: 299 Total (i.e. Null);  297 Residual
#> Null Deviance:       402.1 
#> Residual Deviance: 192.7     AIC: 198.7

Prediction

erglm_predict() produces predictions with confidence intervals, on both the link and response scales, as a tidy data frame:

mod |>
  erglm_predict(newdata = tibble(aucss = seq(0, 3000, by = 500), sex = "Female"))
#> # A tibble: 7 × 7
#>   aucss sex    fit_link se_link fit_resp ci_lower ci_upper
#>   <dbl> <chr>     <dbl>   <dbl>    <dbl>    <dbl>    <dbl>
#> 1     0 Female    -1.65   0.301    0.161   0.0964    0.258
#> 2   500 Female     1.11   0.297    0.751   0.628     0.844
#> 3  1000 Female     3.86   0.558    0.979   0.941     0.993
#> 4  1500 Female     6.61   0.871    0.999   0.993     1.000
#> 5  2000 Female     9.37   1.20     1.000   0.999     1.000
#> 6  2500 Female    12.1    1.53     1.000   1.000     1.000
#> 7  3000 Female    14.9    1.86     1.000   1.000     1.000

Choosing covariates

When there are several candidate covariates, erglm_scm_forward() and erglm_scm_backward() automate the process of deciding which belong in the model, via stepwise addition/elimination based on significance testing:

erglm_scm_forward(mod, candidates = c("dose", "weight", "age"), seed = 1024)
#> 
#> Call:  stats::glm(formula = formula, family = family, data = data)
#> 
#> Coefficients:
#> (Intercept)        aucss      sexMale  
#>   -1.648112     0.005508    -0.312232  
#> 
#> Degrees of Freedom: 299 Total (i.e. Null);  297 Residual
#> Null Deviance:       402.1 
#> Residual Deviance: 192.7     AIC: 198.7

See the “Stepwise covariate modelling” article for a full treatment, including the forward/backward workflow and the audit log (erglm_scm_history()).

Simulation

simulate() generates replicate datasets from a fitted model, and erglm_vpc_sim() reshapes those replicates into a data set ready for a visual predictive check:

erglm_vpc_sim(mod, nsim = 5, seed = 2048)
#> # A tibble: 1,500 × 5
#>      ae1 aucss sex    row_id sim_id
#>    <int> <dbl> <fct>   <int>  <int>
#>  1     0  673. Male        1      1
#>  2     1 2806. Female      2      1
#>  3     0    0  Female      3      1
#>  4     1 1169. Female      4      1
#>  5     1  377. Male        5      1
#>  6     1  327. Female      6      1
#>  7     0    0  Male        7      1
#>  8     1 1208. Female      8      1
#>  9     0    0  Male        9      1
#> 10     1  254. Female     10      1
#> # ℹ 1,490 more rows

See the “Simulation” article for details, including the lower-level erglm_fun() building block.

Working with fitted models

An object returned by erglm_model() is a genuine glm object – it has class c("erglm_model", "glm", "lm") – so all of the standard glm/lm methods (summary(), predict(), confint(), AIC(), anova(), and so on) work on it directly, with no erglm-specific replacement needed. See the “Using base R model methods” article for a worked-through tour of these.

Where to next