README.Rmd

---
output: github_document
---

<!-- README.md is generated from README.Rmd. Please edit that file -->

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%"
)
```

# SGDr

<!-- badges: start -->
[![Lifecycle: experimental](https://img.shields.io/badge/lifecycle-experimental-orange.svg)](https://lifecycle.r-lib.org/articles/stages.html#experimental)
<!-- badges: end -->

Submarine fresh groundwater discharge (SFGD) is a critical pathway for nutrient transport to marine ecosystems, yet its quantification is often hindered by sparse and infrequent data in coastal zones. `SGDr` presents a parsimonious methodology for estimating SFGD in data-sparse settings by integrating simple modelling techniques to characterize coastal aquifer water fluxes. It combines a soil water balance model with a lumped-parameter representation of the aquifer, incorporating the freshwater-seawater interface. Its simplicity enables rapid calibration and uncertainty analysis, supporting land-use decisions and field investigations.

## Installation

You can install the development version of SGDr from [GitHub](https://github.com/) with:

``` {r, eval = F}
# install.packages("devtools")
devtools::install_github("hxfan1227/SGDr")
```

```{r, echo=FALSE, message=FALSE, warning=FALSE}
library(SGDr)
```


## Example

To calculate the SFGD using `estimate_sgd()`, the input data required includes:

* Daily precipitation (R [mm])
* Evapotranspiration (E0 [mm])
* Pumping rate (q1 [m3/d])
* Initial groundwater table (hf [mm]) 
* Initial water table in the two soil *buckets*. (phi1, phi2 [mm])

Below is an example of the input file:

```{r, echo=TRUE}
library(SGDr)
test_data <- read.csv(SGDr_example('test_data.csv'))
head(test_data)
```

The parameters are stored using [JSON](https://www.json.org/json-en.html) format (`.json`). Two types of parameter JSON files are required:

* Calibratable Parameters JSON File: Contains parameters that are adjustable or subject to calibration during model optimization.
* Constant Parameters JSON File: Contains fixed parameters that remain unchanged throughout the model run.

Use `json_to_parameter_list` to convert JSON files into list:

```{r}

cali_pars <- json_to_parameter_list(SGDr_example('preferred.json'))
cnst_pars <- json_to_parameter_list(SGDr_example('consts.json'))
```

The SFGD can then be calculated as:
```{r}
results <- estimate_sgd(test_data, cali_pars, cnst_pars, 120, 1500)
results
# use summary
summary(results, base_date = '19670101')
# use print 
print(results, base_date = '19670101')
```

The estimated results can be visualized with `plot`:

```{r, fig.align='default', fig.dpi=300}
# visualize the prediction results
plot(results, base_date = '19670101')
# visualize the input data
plot(results, base_date = '19670101', type = 'input')
# compare with the observed groundwater table
library(data.table)
obs_data <- data.table::fread(SGDr_example('obs_data.csv'))
plot(results, y = obs_data, base_date = '19670101', type = 'comp')
```

A GUI made in shiny is also available:

```{r, echo=FALSE}
knitr::include_graphics('man/figures/gui.gif')
```