---
title: "Getting Started"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Getting Started}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

The package is simple to use. 
First, lets load the basic packages. 

```{r setup}
library(rmdl)
```

The `mtcars` dataset will serve as the example, and we will use linear regressions as the primary test.
Next, we will evaluate a toy dataset and evaluate how a `fmls` object is generated.

```{r}
# Look at potential data from the `mtcars` dataset
head(mtcars)

baseFormula <- mpg ~ wt + hp
rFormula <- fmls(mpg ~ wt + hp)

# Similar to the base formula
rFormula
```

Now we can fit the hypothesis to its data - in this case, a simple linear regression.
The option to return the model as raw or not is given. 
If `TRUE`, the default, then the expected result from the modeling fit will be returned in the form of a list of models, based on the fitting function provided.

```{r}
# Uses a custom fit function to return linear models
listModels <-
  rFormula |>
  fit(.fn = lm, data = mtcars, raw = TRUE)
```

For our purposes though, we want to use the custom fit method, which retains more key information.
This creates a `mdl` object, which is simply a wrapper around base or package-specific models.

```{r}
# Uses a custom fit function 
rModel <-
  rFormula |>
  fit(.fn = lm, data = mtcars, raw = FALSE)

rModel
```

The model wrapper is helpful in that it can be unpacked into a table of elements, which then stores our model for later usage in a research workflow.
For this purpose, we introduce the `mdl_tbl` class, which another core class with specific and generic dispatch methods.

```{r}
# An additional model to work with
r2Model <-
  fmls(am ~ cyl + hp, pattern = "sequential") |>
  fit(.fn = glm, family = "binomial", data = mtcars, raw = FALSE)

# Displays the two additional logistic regressions performed
r2Model

# Creation of a table of models
rTable <- model_table(mileage = rModel, automatic = r2Model)
rTable
```

The `mdl_tbl` class is a useful way to store and manage multiple models, and can be used to generate tables for publication or for internal use.
To quickly access the content (e.g. estimates, standard errors, etc.), there is an experimental function called `flatten_models()` that can be used.
Note that we are also exponentiating the coefficients for the logistic regression models (called by name).

```{r}
fTable <-
  rTable |>
  flatten_models(exponentiate = TRUE, which = "automatic") 

# Display contents
fTable

# Filter down to relevant models
fTable |>
  dplyr::select(name, number, outcome, term, estimate, conf_low, conf_high, p_value, nobs)
```