---
title: "Supported Models"
author: 
  - name: Shixiang Wang
    affiliation: Central South University
    email: wangshx@csu.edu.cn
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Supported Models}
  %\VignetteEncoding{UTF-8}
  %\VignetteEngine{knitr::rmarkdown}
editor_options: 
  markdown: 
    wrap: 72
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

```{r setup}
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:

```{r}
br_avail_methods()
```

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

### Linear Models

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

```{r}
br_get_results(rv, tidy = TRUE)
```

To focus on the results of focal variables:

```{r}
br_get_results(rv, tidy = TRUE) |>
  dplyr::filter(Focal_variable == term)
```

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

```{r}
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)
```

### 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:

```{r}
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)
```

### Cox-PH Models

```{r}
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)
```

## 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.

```{r}
knitr::kable(
  broom.helpers::supported_models
)
```

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:

```{r}
br_avail_method_config("coxph")
```

```{r}
br_avail_method_config("binomial")
```

-   `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:

```{r}
if (requireNamespace("lme4")) {
  md_config <- list(
    f_call = "lme4::lmer",
    f_cnst_y = NULL,
    args_method = NULL,
    args_data = "data = data"
  )
}
```

Subsequently, utilize it in the `method` argument:

```{r}
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"))
}
```