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

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

Joinpoint regression is commonly used in epidemiology to identify changes in temporal trends. The joinpointR package provides tools to fit joinpoint regression models, estimate annual percentage changes, and present results.

## Joinpoint regression models by group
The function `model_jp()`allows to fit joinpoint regression models with a log-response by levels of one or more categorical variable(s).
For the examples, we are going to use a simulated dataset with the HIV rates by sex in five regions

```{r}
#| message: false
#| id: example-data
# Load required packages
library(dplyr)
library(tidyr)
library(ggplot2)
library(joinpointR)

# Load example data
data(hiv_data)
```

### Stepwise joinpoint regression by sex
```{r}
#| id: model-1
mod1 <- model_jp(
  data = hiv_data,
  value = hiv_rate,
  time = year,
  group = "sex",
  k = 3,
  step = TRUE,
  test = TRUE
)

# Show the model output
mod1
```

### Fixed number of joinpoints by sex
```{r}
#| id: model-2
mod2 <- model_jp(
  data = hiv_data,
  value = hiv_rate,
  time = year,
  group = "sex",
  k = 1,
  step = FALSE,
  test = FALSE
)

# Show the model output
mod2
```

### Stepwise joinpoint regression models by sex and region
```{r}
#| id: model-3
mod3 <- model_jp(
  data = hiv_data,
  value = hiv_rate,
  time = year,
  group = c("region", "sex"),
  step = TRUE
)
```

## Annual percentage change (APC)
The function `get_apc()` provides the annual percentage change and its 95% confidence interval for models with significant joinpoints (`class: "segmented" "lm"`)

```{r}
#| id: APC-1
get_apc(mod2)
```

The function returns empty rows when no significant joinpoints are detected (`class = "lm"`).

```{r}
#| id: APC-2
get_apc(mod1, digits = 1)
```


## Average annual percent change (AAPC)
The function `get_aapc()` allows users to estimate the global trend even when no significant joinpoints were detected.

```{r}
#| id: AAPC-1
get_aapc(mod1, digits = 1, show_ci = TRUE)
```

You can choose to show significance stars instead of CI:
```{r}
#| id: AAPC-2
get_aapc(mod1, digits = 1, show_ci = FALSE)
```

## Summary tables
### Results as a data frame
```{r}
#| id: tab-1
summary_jp(mod1)
```

### HTML Tables
```{r}
# id: tab-2
mod2 |>
  summary_jp(digits = 1) |>
  jp_to_ft()
```

### HTML Tables by two grouping variables
```{r}
#| id: tab-3
mod3 |>
  summary_jp(digits = 1) |>
  jp_to_ft()
```

Change the table language to Spanish
```{r}
#| id: tab-4
mod3 |>
  summary_jp(digits = 1) |>
  jp_to_ft(lan = "es")
```

## Regression plots
Default plot
```{r}
#| id: plot-1
gg_jpoint(mod1)
```

Stack plots
```{r}
#| id: plot-2
gg_jpoint(mod1, facets = "none")
```

Two grouping variables

```{r}
#| id: plot-3
gg_jpoint(mod3)
```

Split by region and sex
```{r}
#| id: plot-4
gg_jpoint(mod3, facets = "grid")
```

Modify the size of data points
```{r}
#| id: plot-5
gg_jpoint(mod3, facets = "grid", psize = 5)
```

Modify the transparency of data points
```{r}
#| id: plot-6
gg_jpoint(mod3, facets = "grid", ptr = 1)
```

Hide data points
```{r}
#| id: plot-7
gg_jpoint(mod3, facets = "grid", obs = FALSE)
```

Hide joinpoint(s) marker(s)
```{r}
#| id: plot-8
gg_jpoint(mod3, facets = "grid", jp = FALSE)
```

Change the default colorblind-friendly palette
```{r}
#| id: plot-9
gg_jpoint(mod3, facets = "grid", jp = FALSE, cbpal = "blue_fluoride")
```

Disable colorblind-friendly palettes
```{r}
#| id: plot- 10
gg_jpoint(mod3, facets = "grid", cb = FALSE)
```