# Supported Models

#### Shixiang Wang

#### 2025-12-17

    library(bregr)

## Default Supported Models

By default, the bregr package supports regression models defined in R’s builtin packages, including stats and survival. This encompasses numerous common regression methodologies, such as generalized linear regressions (linear, logistic) and Cox proportional hazards regression. A comprehensive list of all supported model methods can be retrieved using the `br_avail_methods()` function:

    br_avail_methods()
    #>  [1] "lm"               "coxph"            "survreg"          "clogit"
    #>  [5] "cch"              "binomial"         "gaussian"         "Gamma"
    #>  [9] "inverse.gaussian" "poisson"          "quasi"            "quasibinomial"
    #> [13] "quasipoisson"     "nls"              "aov"

For illustrative purposes, we will utilize the pipeline function instead of a piped workflow to maintain simplicity.

### Linear Models

    rv <- br_pipeline(
      data = mtcars,
      y = "mpg", x = c("cyl", "disp", "hp"), x2 = "am",
      method = "lm"
    )

    br_get_results(rv, tidy = TRUE)
    #> # A tibble: 6 × 8
    #>   Focal_variable term  estimate std.error statistic   p.value conf.low conf.high
    #>   <chr>          <chr>    <dbl>     <dbl>     <dbl>     <dbl>    <dbl>     <dbl>
    #> 1 cyl            cyl    -2.50     0.361       -6.93   1.28e-7  -3.24     -1.76
    #> 2 cyl            am      2.57     1.29         1.99   5.64e-2  -0.0742    5.21
    #> 3 disp           disp   -0.0369   0.00578     -6.37   5.75e-7  -0.0487   -0.0250
    #> 4 disp           am      1.83     1.44         1.28   2.12e-1  -1.10      4.77
    #> 5 hp             hp     -0.0589   0.00786     -7.50   2.92e-8  -0.0750   -0.0428
    #> 6 hp             am      5.28     1.08         4.89   3.46e-5   3.07      7.48

To focus on the results of focal variables:

    br_get_results(rv, tidy = TRUE) |>
      dplyr::filter(Focal_variable == term)
    #> # A tibble: 3 × 8
    #>   Focal_variable term  estimate std.error statistic   p.value conf.low conf.high
    #>   <chr>          <chr>    <dbl>     <dbl>     <dbl>     <dbl>    <dbl>     <dbl>
    #> 1 cyl            cyl    -2.50     0.361       -6.93   1.28e-7  -3.24     -1.76
    #> 2 disp           disp   -0.0369   0.00578     -6.37   5.75e-7  -0.0487   -0.0250
    #> 3 hp             hp     -0.0589   0.00786     -7.50   2.92e-8  -0.0750   -0.0428

This corresponds to the “gaussian” family defined within generalized linear models.

    br_pipeline(
      data = mtcars,
      y = "mpg", x = c("cyl", "disp", "hp"), x2 = "am",
      method = "gaussian"
    ) |>
      br_get_results(tidy = TRUE) |>
      dplyr::filter(Focal_variable == term)
    #> # A tibble: 3 × 8
    #>   Focal_variable term  estimate std.error statistic   p.value conf.low conf.high
    #>   <chr>          <chr>    <dbl>     <dbl>     <dbl>     <dbl>    <dbl>     <dbl>
    #> 1 cyl            cyl    -2.50     0.361       -6.93   1.28e-7  -3.21     -1.79
    #> 2 disp           disp   -0.0369   0.00578     -6.37   5.75e-7  -0.0482   -0.0255
    #> 3 hp             hp     -0.0589   0.00786     -7.50   2.92e-8  -0.0743   -0.0435

### Logistic Models

By modifying the variables (or terms) and method, the presented workflow can be readily adapted to any other supported method with appropriate data.

For a logistic regression model:

    br_pipeline(
      data = mtcars,
      y = "vs", x = c("cyl", "disp", "hp"), x2 = "am",
      method = "binomial"
    ) |>
      suppressWarnings() |>
      br_get_results(tidy = TRUE) |>
      dplyr::filter(Focal_variable == term)
    #> exponentiate estimates of model(s) constructed from binomial method at default
    #> # A tibble: 3 × 8
    #>   Focal_variable term  estimate std.error statistic p.value conf.low conf.high
    #>   <chr>          <chr>    <dbl>     <dbl>     <dbl>   <dbl>    <dbl>     <dbl>
    #> 1 cyl            cyl   7.97e-10 5771.      -0.00363  0.997    NA     1.60e+143
    #> 2 disp           disp  6.07e- 1    0.535   -0.933    0.351    NA     8.31e-  1
    #> 3 hp             hp    8.88e- 1    0.0524  -2.28     0.0229    0.764 9.53e-  1

### Cox-PH Models

    br_pipeline(
      data = survival::lung,
      y = c("time", "status"),
      x = c("ph.ecog", "ph.karno", "pat.karno", "meal.cal"), x2 = c("age", "sex"),
      method = "coxph"
    ) |>
      suppressWarnings() |>
      br_get_results(tidy = TRUE) |>
      dplyr::filter(Focal_variable == term)
    #> exponentiate estimates of model(s) constructed from coxph method at default
    #> # A tibble: 4 × 8
    #>   Focal_variable term    estimate std.error statistic p.value conf.low conf.high
    #>   <chr>          <chr>      <dbl>     <dbl>     <dbl>   <dbl>    <dbl>     <dbl>
    #> 1 ph.ecog        ph.ecog    1.59   0.114        4.08  4.45e-5    1.27      1.99
    #> 2 ph.karno       ph.kar…    0.987  0.00588     -2.27  2.35e-2    0.975     0.998
    #> 3 pat.karno      pat.ka…    0.981  0.00564     -3.38  7.22e-4    0.970     0.992
    #> 4 meal.cal       meal.c…    1.000  0.000238    -0.563 5.74e-1    0.999     1.00

## Extended Supported Models

Fundamentally, bregr leverages `broom.helpers:::tidy_plus_plus()` for model result processing. Consequently, any model supported by broom.helpers should be compatible with bregr, provided the corresponding dependent packages are installed.

    knitr::kable(
      broom.helpers::supported_models
    )

model | notes
--- | ---
`betareg::betareg()` | Use `tidy_parameters()` as `tidy_fun` with `component` argument to control with coefficients to return. `broom::tidy()` does not support the `exponentiate` argument for betareg models, use `tidy_parameters()` instead.
`biglm::bigglm()` |
`brms::brm()` | `broom.mixed` package required
`cmprsk::crr()` | Limited support. It is recommended to use `tidycmprsk::crr()` instead.
`fixest::feglm()` | May fail with R <= 4.0.
`fixest::femlm()` | May fail with R <= 4.0.
`fixest::feNmlm()` | May fail with R <= 4.0.
`fixest::feols()` | May fail with R <= 4.0.
`gam::gam()` |
`geepack::geeglm()` |
`glmmTMB::glmmTMB()` | `broom.mixed` package required
`glmtoolbox::glmgee()` |
`lavaan::lavaan()` | Limited support for categorical variables
`lfe::felm()` |
`lme4::glmer.nb()` | `broom.mixed` package required
`lme4::glmer()` | `broom.mixed` package required
`lme4::lmer()` | `broom.mixed` package required
`logitr::logitr()` | Requires logitr >= 0.8.0
`MASS::glm.nb()` |
`MASS::polr()` |
`mgcv::gam()` | Use default tidier `broom::tidy()` for smooth terms only, or `gtsummary::tidy_gam()` to include parametric terms
`mice::mira` | Limited support. If `mod` is a `mira` object, use `tidy_fun = function(x, ...) {mice::pool(x) &#124;> mice::tidy(...)}`
`mmrm::mmrm()` |
`multgee::nomLORgee()` | Use `tidy_multgee()` as `tidy_fun`.
`multgee::ordLORgee()` | Use `tidy_multgee()` as `tidy_fun`.
`nnet::multinom()` |
`ordinal::clm()` | Limited support for models with nominal predictors.
`ordinal::clmm()` | Limited support for models with nominal predictors.
`parsnip::model_fit` | Supported as long as the type of model and the engine is supported.
`plm::plm()` |
`pscl::hurdle()` | Use `tidy_zeroinfl()` as `tidy_fun`.
`pscl::zeroinfl()` | Use `tidy_zeroinfl()` as `tidy_fun`.
`quantreg::rq()` | If several quantiles are estimated, use `tidy_with_broom_or_parameters()` tidier, the default tidier used by `tidy_plus_plus()`.
`rstanarm::stan_glm()` | `broom.mixed` package required
`stats::aov()` | Reference rows are not relevant for such models.
`stats::glm()` |
`stats::lm()` |
`stats::nls()` | Limited support
`survey::svycoxph()` |
`survey::svyglm()` |
`survey::svyolr()` |
`survival::cch()` | Experimental support.
`survival::clogit()` |
`survival::coxph()` |
`survival::survreg()` |
`svyVGAM::svy_vglm()` | Experimental support. It is recommended to use `tidy_svy_vglm()` as `tidy_fun`.
`tidycmprsk::crr()` |
`VGAM::vgam()` | Experimental support. It is recommended to use `tidy_vgam()` as `tidy_fun`.
`VGAM::vglm()` | Experimental support. It is recommended to use `tidy_vgam()` as `tidy_fun`.

In such instances, model methods must be configured using a list comprising four elements.

For default supported model methods, configurations are prebuilt within the package and can be inspected using:

    br_avail_method_config("coxph")
    #> $f_call
    #> survival::coxph
    #>
    #> $f_cnst_y
    #> function (y)
    #> {
    #>     glue::glue("survival::Surv({paste(y, collapse = ', ')})")
    #> }
    #> <bytecode: 0x11c3c8e10>
    #> <environment: 0x1388670e8>
    #>
    #> $args_method
    #> NULL
    #>
    #> $args_data
    #> data = data

    br_avail_method_config("binomial")
    #> $f_call
    #> stats::glm
    #>
    #> $f_cnst_y
    #> NULL
    #>
    #> $args_method
    #> family = stats::binomial
    #>
    #> $args_data
    #> data = data

- `f_call`: A string representing the caller used to construct the model.

- `f_cnst_y`: A function to construct the response term in string format within the model. For most models utilizing a single variable, set this to `NULL`; however, for models such as survival models that typically employ `Surv(time, status)` as the response term, the aforementioned function can be utilized to construct the term from user-specified `y`.

- `args_method`: A string indicating additional configuration for method definition. For generalized linear models (GLM), the method should be specified as a family. Generally, this is set to `NULL`.

- `args_data`: A string representing the data argument. If the model function does not use `data` as the data input (e.g., if `data2` is used instead), adjust it accordingly (e.g., set it to “data2 = data”). If not required, set it to “data = data”.

For example, to configure a linear mixed model:

    if (requireNamespace("lme4")) {
      md_config <- list(
        f_call = "lme4::lmer",
        f_cnst_y = NULL,
        args_method = NULL,
        args_data = "data = data"
      )
    }
    #> Loading required namespace: lme4

Subsequently, utilize it in the `method` argument:

    if (requireNamespace("lme4") && requireNamespace("merDeriv") && requireNamespace("broom.mixed")) {
      br_pipeline(
        data = lme4::sleepstudy,
        y = "Reaction",
        x = c("Days", "Subject"), x2 = "(Days | Subject)",
        method = md_config
      ) |>
        # br_get_results(tidy = TRUE)
        br_show_table(export = TRUE, args_table_export = list(format = "html"))
    }
    #> Loading required namespace: merDeriv
    #> Loading required namespace: broom.mixed
    #> Warning in checkConv(attr(opt, "derivs"), opt$par, ctrl = control$checkConv, :
    #> unable to evaluate scaled gradient
    #> Warning in checkConv(attr(opt, "derivs"), opt$par, ctrl = control$checkConv, : Model failed to converge: degenerate  Hessian with 1 negative eigenvalues
    #>   See ?lme4::convergence and ?lme4::troubleshooting.

Focal_variable | effect | group | term | estimate | std.error | statistic | conf.int
--- | --- | --- | --- | --- | --- | --- | ---
Days | fixed |  | Days | 10.47 | 1.55 | 6.77 | [ 7.44, 13.50]
Days | ran_pars | Subject | sd__(Intercept) | 24.74 |  |  |
Days | ran_pars | Subject | cor__(Intercept).Days | 0.07 |  |  |
Days | ran_pars | Subject | sd__Days | 5.92 |  |  |
Days | ran_pars | Residual | sd__Observation | 25.59 |  |  |
Subject | fixed |  | Subject309 | -43.16 | 39.25 | -1.10 | [-120.08, 33.76]
Subject | fixed |  | Subject310 | -43.94 | 39.25 | -1.12 | [-120.86, 32.98]
Subject | fixed |  | Subject330 | 41.62 | 39.25 | 1.06 | [ -35.30, 118.54]
Subject | fixed |  | Subject331 | 38.14 | 39.25 | 0.97 | [ -38.78, 115.06]
Subject | fixed |  | Subject332 | 17.54 | 39.25 | 0.45 | [ -59.38, 94.46]
Subject | fixed |  | Subject333 | 28.22 | 39.25 | 0.72 | [ -48.70, 105.14]
Subject | fixed |  | Subject334 | -5.99 | 39.25 | -0.15 | [ -82.91, 70.93]
Subject | fixed |  | Subject335 | 13.76 | 39.25 | 0.35 | [ -63.16, 90.68]
Subject | fixed |  | Subject337 | 45.35 | 39.25 | 1.16 | [ -31.57, 122.27]
Subject | fixed |  | Subject349 | -30.79 | 39.25 | -0.78 | [-107.71, 46.13]
Subject | fixed |  | Subject350 | -18.82 | 39.25 | -0.48 | [ -95.74, 58.09]
Subject | fixed |  | Subject351 | 13.79 | 39.25 | 0.35 | [ -63.13, 90.71]
Subject | fixed |  | Subject352 | 30.49 | 39.25 | 0.78 | [ -46.43, 107.41]
Subject | fixed |  | Subject369 | 8.63 | 39.25 | 0.22 | [ -68.29, 85.55]
Subject | fixed |  | Subject370 | -34.51 | 39.25 | -0.88 | [-111.43, 42.41]
Subject | fixed |  | Subject371 | 6.85 | 39.25 | 0.17 | [ -70.07, 83.77]
Subject | fixed |  | Subject372 | 20.69 | 39.25 | 0.53 | [ -56.23, 97.61]
Subject | ran_pars | Subject | sd__(Intercept) | 23.46 |  |  |
Subject | ran_pars | Subject | cor__(Intercept).Days | 0.02 |  |  |
Subject | ran_pars | Subject | sd__Days | 11.93 |  |  |
Subject | ran_pars | Residual | sd__Observation | 25.59 |  |  |