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%"
)
```

# rainOrSnowTools

<!-- badges: start -->

[![R-CMD-check](https://github.com/SnowHydrology/rainOrSnowTools/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/SnowHydrology/rainOrSnowTools/actions/workflows/R-CMD-check.yaml)

<!-- badges: end -->

<img src="https://www.dri.edu/wp-content/uploads/badge.png" align="right" width="150"/>

The goal of the `rainOrSnowTools` R package is to support analysis for the [**Mountain Rain or Snow**](https://www.rainorsnow.org/) **citizen science project**.

:cloud_with_snow::cloud_with_rain::point_right: **The processed data are available on our [public-facing dashboard](https://rainorsnowmaps.com/)** :point_left::cloud_with_rain::cloud_with_snow:

You can learn more about how to use the data on the dashboard's [User Guide tab](https://rainorsnowmaps.com/obs).

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

### `rainOrSnowTools` provides:

1.  Access to meteorological data from the [HADS](https://hads.ncep.noaa.gov/), [LCD](https://www.ncei.noaa.gov/products/land-based-station/local-climatological-data), [WCC](https://www.nrcs.usda.gov/wps/portal/wcc/home/), and [MADIS](https://madis-data.ncep.noaa.gov/) networks.
2.  Modeled meteorological data (air/dew point/wet bulb temperature and relative humidity) for an observation point.
3.  [GPM IMERG probability of liquid precipitation](https://gpm.nasa.gov/data/imerg) (PLP) data for an observation point.
4.  Geographical data (elevation, state, and Ecoregion 3/4) for an observation point.
5.  QC of processed observation data.

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

## Installation and Loading

You can install `rainOrSnowTools` with:

``` r
# install.packages("devtools")
devtools::install_github("LynkerIntel/rainOrSnowTools")
```

Load in the `rainOrSnowTools` library:

```{r load, eval = FALSE, echo = TRUE}
library(rainOrSnowTools)
```

## Package Functions

Each observation is geotagged with a datetime, location (latitude, longitude) and phase observation.

In this example, we will use the following sample: `datetime: 2025-04-10 12:30:00 UTC`,`lat = 40`,`lon = -105`, `phase = "Snow"`

```{r example load, eval = TRUE, echo = FALSE, message = FALSE,warning = FALSE}
library(dplyr)
library(tidyverse)

datetime = as.POSIXct("2026-01-01 12:30:00", tz = "UTC")
lat = 40
lon = -105
phase = 'Snow'

```

#### Tagging an observation with ancillary data:

#### Geography-related:

*Need to provide a lat/lon*

| **Function** | **Description** |
|-------------------------|-----------------------------------------------|
| `get_elev` | Elevation in meters, derived from the USGS 3DEP 10m product |
| `get_eco_level3` | EPA Ecoregion Level 3 |
| `get_eco_level4` | EPA Ecoregion Level 4 |
| `get_state` | U.S. State |

```{r example1, eval = TRUE, echo = TRUE}
# Elevation data in meters:
elev <- rainOrSnowTools::get_elev(lon_obs = lon,
                                  lat_obs = lat)
# [1] 1590.199
```

#### Meteorology-related:

*Need to provide datetime and lat/lon*

| **Function** | **Description** |
|------------------------|------------------------------------------------|
| `get_imerg` | GPM IMERG Probability of Liquid Precipitation value (closer to 0 = likely snow, closer to 100 = likely rain) |
| `model_meteo` | This final function uses data collected from helper functions to model met variables for an observation point. Will only provide modeled data for points with \>= 5 station data. Helper functions = `access_meteo`, `qc_meteo`, `select_meteo`, `gather_meta` |

-   `access_meteo` = Access data (+/- 1 hour) from the met network of choice (`HADS`, `LCD`, `WCC`, `MADIS`, or `ALL`). Required variables include `datetime`, `lat`, `lon`, `deg_filter` (search radius)
    -   *Note that LCD stations are no longer an available network after August 2025*
-   `qc_meteo` = QC the met data collected using standard thresholds
-   `select_meteo` = Final selection of the met data from the network(s) of choice, filtering data to grab the closest in time
-   `gather_meta` = Gathers the metadata associated for each station from `select_meteo`

```{r example2, eval = FALSE, echo = TRUE}
# Get GPM IMERG probability of liquid precipitation:
plp <- rainOrSnowTools::get_imerg(datetime_utc    = datetime,
                                  lon_obs         = lon,
                                  lat_obs         = lat,
                                  product_version = 'GPM_3IMERGHHL.07') # this is the default version

# [1] 2
# This values agrees with the Snow phase report
```

*Note that the GPM IMERG algorithm has deprecated the version 6 as of late 2024, [see here](https://gpm.nasa.gov/resources/documents/imerg-v07-release-notes)*

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

##### Example workflow:

Get modeled meteorological variables, harnessing data from the HADS, WCC, and MADIS met networks.

```{r example3, eval = TRUE, echo = TRUE}
# Define the static vars
met_networks = "ALL" # Call the HADS, WCC, and MADIS stations
degree_filter = 1 # 1º radius

meteo <- rainOrSnowTools::access_meteo(networks         = met_networks,
                                       datetime_utc_obs = datetime,
                                       lon_obs          = lon,
                                       lat_obs          = lat,
                                       deg_filter       = degree_filter)

# List of Observations ("met") and Metadata ("metadata")

met <- meteo[["met"]]

# QC the meteo data
meteo_qc <- rainOrSnowTools::qc_meteo(met)
## All data pass QC

# Subset the data to select data points closest in time, and average the measured value
meteo_subset <- rainOrSnowTools:::select_meteo(meteo_qc, datetime)

# Get metadata for each station ID
metadata <- meteo$metadata %>%
          dplyr::filter(id %in% meteo_subset$id)
```

```{r station, eval = TRUE, echo = FALSE}
station_counts <- cbind(
      "hads_counts" =
          metadata %>%
          dplyr::filter(network == "hads") %>%
          dplyr::tally() %>%
          as.numeric(),
      # "lcd_counts" =
      #     metadata %>%
      #     dplyr::filter(network == "lcd") %>%
      #     dplyr::tally() %>%
      #     as.numeric(),
      "wcc_counts" =
          metadata %>%
          dplyr::filter(network %in% c("snotel", "scan", "snotelt")) %>%
          dplyr::tally() %>%
          as.numeric(),
      "madis_counts" =
          metadata %>%
          dplyr::filter(network %in% c("madis")) %>%
          dplyr::tally() %>%
          as.numeric()
      )

var_counts <- meteo_subset %>% 
  pivot_longer(cols = rh:temp_wet,
               names_to = "var", 
               values_to = "val") %>% 
  dplyr::group_by(var) %>% 
  dplyr::summarise(counts = sum(!is.na(val))) %>% 
  pivot_wider(names_from = 'var', values_from = 'counts')


```

```{r stationout, eval = TRUE, echo = TRUE}
# `metadata` can get the number of data points from each network

#>      hads_counts wcc_counts madis_counts
#>       43         22          357

# `meteo_subset` can get the number of data points for each met variable

#>    rh temp_air temp_dew temp_wet
#>   360      404      333        0

```

```{r met, eval = TRUE, echo = TRUE}
# Finally, get modeled meteorological variables
met_vars <- rainOrSnowTools::model_meteo(id           = "example",
                                         lon_obs      = lon,
                                         lat_obs      = lat,
                                         elevation    = elev,
                                         datetime_utc = datetime,
                                         meteo_df     = meteo_subset,
                                         meta_df      = metadata)
```

```{r metout, eval = TRUE, echo = TRUE}
# Output of 37 variables, does not include the QC flags

# Temperature units = ºC and RH unit = %
dplyr::tibble(met_vars)
```

*Data Citations:*

Kantor, Diana; Casey, Nancy W.; Menne, Matthew J.; Buddenberg, Andrew. 2023. Local Climatological Data (LCD), Version 1. NOAA National Centers for Environmental Information. <https://www.ncei.noaa.gov/access/metadata/landing-page/bin/iso?id=gov.noaa.ncdc:C01689>. [before 29 Aug 2025]

NOAA National Centers for Environmental Prediction. 2006. Hydrometeorological Automated Data System (HADS). NOAA National Centers for Environmental Information.

NOAA. (n.d.). MADIS Meteorological Surface Dataset. Meteorological Assimilation Data Ingest System (MADIS). <https://madis.ncep.noaa.gov/>

NRCS. (n.d.). Snow and Climate Monitoring rRports and Maps. U.S. Department of Agriculture. <https://www.nrcs.usda.gov/wps/portal/wcc/home/>