---
title: "Generalized Additive Models"
output:
  html_document:
    theme: flatly
    highlight: tango
    toc: TRUE
    toc_depth: 4            # Define the depth of the TOC (increase as needed)
    toc_float:
      collapsed: TRUE      # Whether the TOC starts collapsed
      smooth_scroll: TRUE   # Smooth scrolling when a TOC entry is clicked
fontsize: 12pt              # Set font size
linkcolor: blue             # Hyperlink color (for PDF output)



vignette: >
  %\VignetteIndexEntry{Generalized Additive Models}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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



```{r setup_lib, include=FALSE}
if (!requireNamespace("htmltools", quietly = TRUE)) {
  stop("Package 'htmltools' is required to run this function. Please install it.")
}
library(growthTrendR)
library(data.table)
library(ggplot2)
library(sf)


```


GAMs/GAMMs handle nonlinear relationships and can include random effects (e.g., site or tree identity) to account for hierarchical structures and temporal or spatial dependencies, making them well-suited for modeling complex dendrochronological data. in growthTrendR package, a suite of GAM/GAMM models has been implemented to accommodate different types of datasets. Here, we use a single model, gamm_spatial, to demonstrate how to generate a fitting and diagnostic model report from raw data.


### **prepare data for model:**
```{r mod_data,  message = FALSE, warning = FALSE, results = 'hide'}


# loading processed ring measurement
dt.samples_trt <- readRDS(system.file("extdata", "dt.samples_trt.rds", package = "growthTrendR"))

# climate
dt.clim <- fread(system.file("extdata", "dt.clim.csv", package = "growthTrendR"))

# merge data
dt.samples_clim <- merge(dt.samples_trt$tr_all_wide[, c("uid_site", "site_id","latitude", "longitude",  "species", "uid_tree", "uid_radius")], dt.samples_trt$tr_all_long$tr_7_ring_widths, by = "uid_radius")

# # Calculate BAI
dt.samples_clim <- calc_bai(dt.samples_clim)

dt.samples_clim <- merge(dt.samples_clim, dt.clim, by = c("site_id", "year"))
```

<br>

### **fitting model**

This example uses gamm_spatial; other functions with the same arguments (gamm_radius, gamm_site, bam_spatial, gam_mod) may be used depending on the data and analysis goals.

```{r mod_fitting,  message = FALSE, warning = FALSE, results = 'hide'}
setorder(dt.samples_clim, uid_tree, year)

# Remove ageC == 1 prior to fitting log-scale models.
dt.samples_clim <- dt.samples_clim[ageC > 1]
m.sp <- gamm_spatial(data = dt.samples_clim, resp_scale = "resp_log",
                     m.candidates =c( "bai_cm2 ~ log(ba_cm2_t_1) + s(ageC) + s(FFD)",
                                      "bai_cm2 ~ log(ba_cm2_t_1) + s(ageC) + FFD")
)
```


#### **arguments**

**resp_scale**
The function provides three options for specifying the response variable, and the user must choose the one that best suits their modelling purpose:

"resp_gaussian": the response variable is used on its original scale and is modelled under a Gaussian distribution with an identity link (no transformation applied).

"resp_log": the response variable is log-transformed prior to modelling. The transformed response is then assumed to follow a Gaussian distribution and is fitted using an identity link.

"resp_gamma": the response variable is kept on its original scale, and the model is fitted under a Gamma distribution with a log link, appropriate for strictly positive and right-skewed data.


**m.candidates**

The list of all candidate equations.
Note that the response variable is kept on its original scale in all cases, even when using the option "resp_log".



<br>

### **model summary and diagnostic**


```{r mod_report_demo, message = FALSE, warning = FALSE}
# generate_report(robj = m.sp)
gam_model <- m.sp$model$gam

# summary of the model
  summary(gam_model)
# smooth term importance
 term_important <- sterm_imp( gam_model)
 print(term_important)
# 

```


------------------------------------------------------------------------