---
title: "snotelr functionality"
author: "Koen Hufkens"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{snotelr functionality}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

# load the library
library(snotelr)

# check cran, same routine as skip_on_cran()
# but not dependent on testthat which might
# not be available on user systems (not required
# only suggested)
check_cran <- function() {
  if (identical(tolower(Sys.getenv("NOT_CRAN")), "true")) {
    return(TRUE)
  } else {
    return(FALSE)
  }
}

# do cran check
cran <- check_cran()

# for local render set to true
# mainly important for rendering
# a website using pkgdown
#cran <- TRUE
```

## Introduction

The SNOTEL network is composed of over 800 automated data collection sites located in remote, high-elevation mountain watersheds in the western U.S. They are used to monitor snowpack, precipitation, temperature, and other climatic conditions. The data collected at SNOTEL sites are transmitted to a central database. This package queries this centralized database to provide easy access to these data and additional seasonal metrics of snow accumulation (snow phenology).

## Downloading site meta-data

The SNOTEL network consists of a vast number of observation sites, all of them listed together with their meta-data on the SNOTEL website. The `snotel_info()` function allows you to query this table and import it as a neat table into `R`. Some of the meta-data, in particular the site id (`site_id`), you will need of you want to download the data for a site. You can save this table to disk using the `path` variable to specify a location on your computer where to store the data as a csv. If this parameter is missing the data is returned as an `R` variable.

```{r eval = cran}
# download and list site information
site_meta_data <- snotel_info()
head(site_meta_data)
```

## Downloading site data

If you downloaded the meta-data for all sites you can make a selection using either geographic coordinates, or `state` columns. For the sake of brevity I'll only query data for one site using its `site_id` below. By default the data, reported in imperial values, are converted to metric measurements.

```{r eval = cran}
# downloading data for a random site
snow_data <- snotel_download(
  site_id = 670,
  internal = TRUE
  )

# show the data
head(snow_data)
```

```{r fig.width = 7, fig.height=3, eval = cran}
# A plot of snow accummulation through the years
plot(as.Date(snow_data$date),
     snow_data$snow_water_equivalent,
     type = "l",
     xlab = "Date",
     ylab = "SWE (mm)"
    )
```

## Calculating snow phenology from downloaded data or data frames

Although the main function of the package is to provide easy access to the SNOTEL data a function `snotel_phenology()` is provided to calculate seasonal metrics of snow deposition.

```{r eval = cran}
# calculate snow phenology
phenology <- snotel_phenology(snow_data)
```

```{r fig.width = 7, fig.height=3, eval = cran}
# subset data to the first decade of the century
snow_data_subset <- subset(snow_data, as.Date(date) > as.Date("2000-01-01") &
                             as.Date(date) < as.Date("2010-01-01"))

# plot the snow water equivalent time series
plot(as.Date(snow_data_subset$date),
     snow_data_subset$snow_water_equivalent,
     type = "l",
     xlab = "Date",
     ylab = "SWE (mm)"
  )

# plot the dates of first snow accumulation as a red dot
points(phenology$first_snow_acc,
       rep(1,nrow(phenology)),
       col = "red",
       pch = 19,
       cex = 0.5
      )
```

A list of all provided snow phenology statistics is provided below.


| Value | Description |
| --------- | ------------------ |
| year      | The year in which the an event happened |
| first_snow_melt | day of first full snow melt (in DOY) |
| cont_snow_acc | start of continuous snow accumulation / retention (in DOY) |
| last_snow_melt | day on which all snow melts for the remaining year (in DOY) |
| first_snow_acc | day on which the first snow accumulates (in DOY) |
| max_swe | maximum snow water equivalent value during a given year (in mm) |
| max_swe_doy | day on which the maximum snow water equivalent value is reached (in DOY) |


## Reference

Please use the proper Zenodo DOI when using this software for research purposes.