When to use offsetreg"

In offsetreg: An Extension of 'Tidymodels' Supporting Offset Terms

knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>"
)

This vignette describes the motivation for offsetreg and when its usage becomes necessary.

When offsetreg is not necessary

For certain use cases, offsets are supported in tidymodels. Generally speaking, for models that allow for offsets to be specified in a model formula, tidymodels works fine out of the box and offsetreg is not needed. The glm() function from the stats package is a good example of this.

Offsets supported in model formulas: glm()

Below, a Poisson model is fit using the us_deaths data set with an offset equal to the log of population.

library(parsnip)
library(offsetreg)
library(broom)
library(recipes)
library(workflows)
library(rsample)
library(tune)

us_deaths$log_pop <- log(us_deaths$population)

poisson_reg() |>
  set_engine("glm") |>
  fit(deaths ~ gender + age_group + year + offset(log_pop), 
      data = us_deaths)

The code above works for a few reasons:

• fit() captures the formula expression passed to it, and that formula is allowed to contain calls to other functions, like offset().
• Since there is no additional pre-processing of the data required, that formula is passed to the glm() function as-is, as shown in the call printed above.

Let's assume we want to use a recipe to pre-process our data. In the example below, a bare bones recipe is used to verify that we can reproduce the same coefficients as the original example. Unfortunately, this creates a problem because recipe() doesn't allow in-line functions like offset().

mod <- poisson_reg() |> set_engine("glm")
rec <- recipe(deaths ~ gender + age_group + year + offset(log_pop), 
              data = us_deaths)

As the hint above explains, this error can be avoided by removing the call to offset() in the recipe and passing a second formula to add_model() as part of a workflow. Note that the variable passed to offset() must still be included in the recipe.

rec <- recipe(deaths ~ gender + age_group + year + log_pop, 
              data = us_deaths)

workflow() |> 
  add_model(mod, 
            formula = deaths ~ gender + age_group + year + offset(log_pop)) |> 
  add_recipe(rec) |> 
  fit(us_deaths)

These coefficients match the first example without a recipe, so we know this model was set up correctly.

Offsets not supported in model formulas: glmnet()

Not all modeling engines allow for offsets to be passed via the formula interface. For example, the glmnet() function does not not accept formulas; it requires model matrices. Instead, offsets are passed as a numeric vector using an optional engine-specific offset argument.

poisson_reg(penalty = 1E-5) |>
  set_engine("glmnet", offset = us_deaths$log_pop) |>
  fit(deaths ~ year + gender + age_group, 
      data = us_deaths) |> 
  tidy()

This code works because the argument offset = us_deaths$log_pop is captured and passed directly into glmnet().

If we try to use a recipe with an offset passed to the formula argument of add_model(), a difficult-to-spot problem emerges. The model runs without errors, but a completely different set of coefficients is returned.

mod_glmnet <- poisson_reg(penalty = 1E-5) |> set_engine("glmnet")
rec <- recipe(deaths ~ year + gender + age_group + log_pop, 
              data = us_deaths)

workflow() |> 
  add_model(mod_glmnet, 
            formula = deaths ~ year + gender + age_group + offset(log_pop)) |> 
  add_recipe(rec) |> 
  fit(us_deaths) |> 
  tidy()

What happened here? Since glmnet() doesn't natively support the formula interface, it doesn't know what to do with the offset() term passed to the formula. Under the hood, the offset() term is quietly dropped in a call to model.matrix() that is used to convert the formula to a matrix format acceptable to glmnet().

model.matrix(deaths ~ year + gender + age_group + offset(log_pop),
             us_deaths) |> 
  head()

As a result, the model is exactly what we would see if there were no offset terms to begin with. This is a situation when offsetreg is required.

When offsetreg is necessary

offsetreg becomes necessary when the underlying modeling engine does not support offsets in formulas and either of these tasks are performed:

• A pre-processing recipe is applied to the data
• Resampling is performed, often in conjunction with hyperparameter tuning

Using recipe() when offsets cannot be specified in a formula

Let's continue with the last example. The problem can be addressed using offsetreg as follows:

• Replace poisson_reg() with poisson_reg_offset()
• Replace the "glmnet" engine with "glmnet_offset" and provide the name of the offset column
• Remove the formula argument in add_model()
• Add a call to step_dummy(). This step was previously not necessary when formula was passed to add_model().

mod_offset <- poisson_reg_offset(penalty = 1E-5) |> 
  set_engine("glmnet_offset", offset_col = "log_pop")
rec <- recipe(deaths ~ year + gender + age_group + log_pop, 
              data = us_deaths) |> 
  step_dummy(all_nominal_predictors())

workflow() |> 
  add_model(mod_offset) |> 
  add_recipe(rec) |> 
  fit(us_deaths) |> 
  tidy()

Resampling when offsets cannot be specified in a formula

For models like glmnet() where offsets can only be specified as a numeric vector in engine-specific arguments, resampling presents a few challenges:

• tidymodels is only aware of the numeric vector of offsets that has been passed and there is no defined relationship between individual observations and their associated offsets. As a result, when resampling occurs, offsets aren't carried over to resampled data sets.
• Related, and pertinent to glmnet(), if the predict() function requires offset terms, there is no mechanism to pass those along, which will result in an error.

Below is what happens if we attempt to fit 5 bootstrap resamples of the us_deaths data set without offsetreg.

resamples <- bootstraps(us_deaths, times = 5)

mod_glmnet <- poisson_reg(penalty = 1E-5) |> 
  set_engine("glmnet", offset = us_deaths$log_pop)

workflow() |>
  add_recipe(rec) |>
  add_model(mod_glmnet) |>
  fit_resamples(resamples) |>
  collect_metrics()

All models failed to fit, and we receive a specific error message about no offsets being available for predictions.

show_notes(.Last.tune.result)

With offsetreg, this code performs as expected. offsetreg works because behind the scenes it ensures that offset terms are attached to the data at all times, which enables resampling and predictions to function without error.

workflow() |>
    add_recipe(rec) |>
    add_model(mod_offset) |>
    fit_resamples(resamples) |>
    collect_metrics()

offsetreg documentation built on April 4, 2025, 1:35 a.m.