quick_start.Rmd

---
title: "reslr: quick start guide"
author: "Maeve Upton, Andrew Parnell and Niamh Cahill"
date: "`r Sys.Date()`"
output: 
  rmarkdown::html_vignette:
       toc: true
vignette: >
  %\VignetteIndexEntry{reslr: quick start guide}
  %\VignetteEncoding{UTF-8}
  %\VignetteEngine{knitr::rmarkdown}
editor_options: 
  chunk_output_type: console
---
```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"#,
  #fig.path = "qs_vig/"
)
options(rmarkdown.html_vignette.check_title = FALSE)
```
## Step 1: install `reslr`

Use:
```{r, eval = FALSE, results='hide',message=FALSE}
# Not on CRAN yet
#install.packages("reslr")
#devtools::install_github("maeveupton/reslr")
install_github("maeveupton/reslr")
```
then,
```{r, start, message=FALSE}
library(reslr)
```

Note: The JAGS software is a requirement for this instruction sheet and refer back to main vignettes for more information.

## Step 2: load in the data into `reslr`

There is a large example dataset included in the `reslr` package called `NAACproxydata`. In this example, we demonstrate how to include proxy record data which is stored in a csv file. This csv file of data can be found in the package and the `readr` function reads the csv file:

```{r, run_data_qs, eval = TRUE}
path_to_data <- system.file("extdata", "one_data_site_ex.csv", package = "reslr")
example_one_datasite <- read.csv(path_to_data)
```

Using the `reslr_load` function to read in the data into the `reslr` package:
```{r, loadslr_qs, eval = TRUE, message=FALSE, results='hide'}
example_one_site_input <- reslr_load(
  data = example_one_datasite)
```


## Step 3: plot the data

```{r, plotdata_qs,fig.align = 'center',fig.width = 7,fig.height = 5,eval = TRUE}
plot(
  x = example_one_site_input,
  title = "Plot of the raw data",
  xlab = "Year (CE)",
  ylab = "Relative Sea Level (m)",
  plot_tide_gauges = FALSE,
  plot_caption = TRUE
)
```

## Step 4:  Run your statistical model and check convergence

Select your modelling technique from the modelling options available:

| Statistical Model | Model Information | `model_type` code | 
| ---- | ------- | -- |
| Errors in variables simple linear regression | A straight line of best fit taking account of any age and measurement errors in the RSL values using the method of Cahill et al (2015). Use for single proxy site. | **"eiv_slr_t"** |
| Errors in variables change point model | An extension of the linear regression modelling process. It uses piece-wise linear sections and estimates where/when trend changes occur in the data (Cahill et al. 2015). | **"eiv_cp_t"** |
| Errors in variables integrated Gaussian Process | A non linear fit that utilities a Gaussian process prior on the rate of sea-level change that is then integrated (Cahill et al. 2015). | **"eiv_igp_t"** |
| Noisy Input spline in time | A non-linear fit using regression splines using the method of Upton et al (2023). | **"ni_spline_t"** |
| Noisy Input spline in space and time | A non-linear fit for a set of sites across a region using the method of Upton et al (2023). | **"ni_spline_st"**|
| Noisy Input Generalised Additive model for the decomposition of the RSL signal | A non-linear fit for a set of sites across a region and provides a decomposition of the signal into regional, local-linear (commonly GIA) and local non-linear components. Again this full model is as described in Upton et al (2023). | **"ni_gam_decomp"** |


For this example, it is a single site and we are interested in how it varies over time select the Noisy Input spline in time. If it was multiple sites, we recommend using a spatial temporal model, i.e. Noisy Input spline in space and time, or for decomposing the signal, i.e. Noisy Input Generalised Additive model. 

Once the model is chosen use the `reslr_mcmc` function to run it:

```{r, runslr_qs,eval = TRUE,message=FALSE, results='hide'}
res_one_site_example <- reslr_mcmc(
  input_data = example_one_site_input,
  model_type = "ni_spline_t",
  CI = 0.95
)
```

The convergence of the algorithm is examined and he parameter estimates from the model can be investigated using the following:
```{r, summaryslr_qs, eval = TRUE}
summary(res_one_site_example)
```

## Step 5: Plot the results
The model fit results can be visualised using the following function:
```{r, plotres_qs, fig.align = 'center',fig.width = 7,fig.height = 5,eval = TRUE}
plot(res_one_site_example,
  xlab = "Year (CE)",
  ylab = "Relative Sea Level (m)",
  plot_type = "model_fit_plot"
)
```
For the rate of change plot use:

```{r, plotresrate_qs, fig.align = 'center',fig.width = 7,fig.height = 5,eval = TRUE}
plot(res_one_site_example,
  plot_type = "rate_plot"
)
```

To examine the data creating these plots the user types the following:
```{r, dataframeslrres_qs, eval = TRUE}
output_dataframes <- res_one_site_example$output_dataframes
head(output_dataframes)
```


To examine the additional options in the `reslr` package, see the main vignette.