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

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.align = "center",
  fig.width = 7,
  fig.height = 5
)
```

*trending* aims to provides a coherent interface to several modelling tools.
Whilst it is useful in an interactive context, it's main focus is to provide
an intuitive interface on which other packages can be developed
(e.g. [*trendbreaker*](https://github.com/reconhub/trendbreaker)).

# Main features

- **Model specification:** Interfaces to common models through intuitive
  functions; `lm_model()`, `glm_model()`, `glm_nb_model` and `brms_model`*.

- **Model fitting and prediction:** Once specified, models can be fit to data
  and generate confidence and prediction intervals for future data using `fit()`
  and `predict()`.

- **Error and warning catching:** The provided methods for `fit` and `predict`
  catch all warnings and errors, returning the output and these captured values
  in a list.

\*   Requires [brms](https://CRAN.R-project.org/package=brms)

# Example usage

## Setup
```{r message=FALSE}
library(outbreaks)  # for data
library(trending)   # for trend fitting
library(dplyr)      # for data manipulation

# load data
data(covid19_england_nhscalls_2020)

# select 6 weeks of data (from a period when the prevalence was decreasing)
last_date <- as.Date("2020-05-28")
first_date <- last_date - 8*7
pathways_recent <-
  covid19_england_nhscalls_2020 %>%
  filter(date >= first_date, date <= last_date) %>%
  group_by(date, day, weekday) %>%
  summarise(count = sum(count), .groups = "drop")

# split data for fitting and prediction
dat <-
  pathways_recent %>%
  group_by(date <= first_date + 6*7) %>%
  group_split()

fitting_data <- dat[[2]]
pred_data <- select(dat[[1]], date, day, weekday)
```

## A succesful model fit
```{r}
(model  <- glm_nb_model(count ~ day + weekday))
(fitted_model <- fit(model, fitting_data))
fitted_model %>% get_result()

# default
fitted_model %>% 
  predict(pred_data) %>%
  get_result()

# without uncertainty
fitted_model %>% 
  predict(pred_data, uncertain = FALSE) %>% 
  get_result()

# without prediction intervals
fitted_model %>% 
  predict(pred_data, add_pi = FALSE) %>% 
  get_result()

# bootstraped prediction intervals
fitted_model %>% 
  predict(pred_data, simulate_pi = TRUE) %>% 
  get_result()
```

## Example of failed model fitting
```{r}
(model2  <- glm_nb_model(count ~ day + nonexistent))
(fitted_model2 <- fit(model2, fitting_data))
get_result(fitted_model2)
get_errors(fitted_model2)
```

## Multiple models
The fit function also works with a list input of multiple models.

```{r}
models  <- list(
  simple = lm_model(count ~ day),
  glm_poisson = glm_model(count ~ day, family = "poisson"),
  glm_negbin = glm_nb_model(count ~ day + weekday),
  will_error = glm_nb_model(count ~ day + nonexistant)
)
(fitted_tbl <- fit(models, fitting_data))
get_result(fitted_tbl)
```

This can also then be used with `predict()`
```{r}
(pred <- predict(fitted_tbl, pred_data))
get_result(pred)
```