fasstr <img src="man/figures/fasstr.png" align="right" />

<!-- badges: start -->

<!-- badges: end --> </div>

The Flow Analysis Summary Statistics Tool for R (‘fasstr’) is a set of R functions to tidy, summarize, analyze, trend, and visualize streamflow data. This package summarizes continuous daily mean streamflow data into various daily, monthly, annual, and long-term statistics, completes annual trends and frequency analyses, in both table and plot formats.

Reference

fasstr package 📦 home page and reference guide

Features

This package provides functions for streamflow data analysis, including:

• data tidying (to prepare data for analyses; add_* and fill_* functions),
• data screening (to identify data range, outliers and missing data; screen_* functions),
• calculating summary statistics (long-term, annual, monthly and daily statistics; calc_*functions),
• computing analyses (volume frequency analyses and annual trending; compute_* functions), and,
• visualizing (data plotting the various statistics; plot_* functions).

Useful features of functions include:

• the integration of the tidyhydat package to pull streamflow data from a Water Survey of Canada HYDAT database for analyses;
• arguments for filtering of years and months in analyses and plotting;
• choosing the start month of your water year;
• selecting for rolling day averages (e.g. 7-day rolling average); and,
• choosing how missing dates are handled, amongst others.

This package is maintained by the Water Management Branch of the British Columbia Ministry of Water, Land and Resource Stewardship.

Installation

You can install fasstr directly from CRAN:

install.packages("fasstr")

To install the development version from GitHub, use the remotes package then the fasstr package:

if(!requireNamespace("remotes")) install.packages("remotes")
remotes::install_github("bcgov/fasstr")

To use the station_number argument and pull data directly from a Water Survey of Canada HYDAT database into fasstr functions, download a HYDAT file using the following code:

tidyhydat::download_hydat()

Using fasstr

There are several vignettes and a cheatsheet to provide more information on the usage of fasstr functions and how to customize various argument options.

• Getting Started
• Users Guide
• Computing an Annual Trends Analysis
• Computing a Volume frequency Analysis
• Computing a Full fasstr Analysis
• Internal fasstr Workflows

Cheatsheet

<a href="https://github.com/bcgov/fasstr/raw/main/fasstr_cheatsheet.pdf"><img src="man/figures/fasstr_cheatsheet.png" width="630" height="252"/></a>

Data Input

All functions in fasstr require a daily mean streamflow data set from one or more hydrometric stations. Long-term and continuous data sets are preferred for most analyses, but seasonal and partial data can be used. Other daily time series data, like temperature, precipitation or water levels, may also be used, but with certain caution as some calculations/conversions are based on units of streamflow (cubic metres per second). Data is provided to each function using the either the data argument as a data frame of flow values, or the station_number argument as a list of Water Survey of Canada HYDAT station numbers.

When using the data option, a data frame of daily data containing columns of dates (YYYY-MM-DD in date format), values (mean daily discharge in cubic metres per second in numeric format), and, optionally, grouping identifiers (character string of station names or numbers) is called. By default the functions will look for columns identified as ‘Date’, ‘Value’, and ‘STATION_NUMBER’, respectively, to be compatible with the ‘tidyhydat’ defaults, but columns of different names can be identified using the dates, values, groups column arguments (ex. values = Yield_mm). The following is an example of an appropriate data frame (STATION_NUMBER not required):

#>   STATION_NUMBER       Date Value
#> 1        08NM116 1949-04-01  1.13
#> 2        08NM116 1949-04-02  1.53
#> 3        08NM116 1949-04-03  2.07
#> 4        08NM116 1949-04-04  2.07
#> 5        08NM116 1949-04-05  2.21
#> 6        08NM116 1949-04-06  2.21

Alternatively, you can directly pull a flow data set directly from a HYDAT database (if installed) by providing a list of station numbers in the station_number argument (ex. station_number = "08NM116" or station_number = c("08NM116", "08NM242")) while leaving the data arguments blank. A data frame of daily streamflow data for all stations listed will be extracted using tidyhydat and then fasstr calculations will produce results of the functions.

This package allows for multiple stations (or other groupings) to be analyzed in many of the functions provided identifiers are provided using the groups column argument (defaults to STATION_NUMBER). If grouping column doesn’t exist or is improperly named, then all values listed in the values column will be summarized.

Function Types

Tidying

These functions, start with either add_* or fill_*, add columns and rows, respectively, to streamflow data frames to help set up your data for further analysis. Examples include adding rolling means, adding date variables (WaterYear, Month, DayofYear, etc.), adding basin areas, adding columns of volumetric discharge and water yields, and filling dates with missing flow values with NA.

Analysis

The analysis functions summarize your discharge values into various statistics. screen_* functions summarize annual data for outliers and missing dates. calc_* functions calculate daily, monthly, annual, and long-term statistics (e.g. mean, median, maximum, minimum, percentiles, amongst others) of daily, rolling days, and cumulative flow data. compute_* functions also analyze data but produce more in-depth analyses, like frequency and trending analysis, and may produce multiple plots and tables as a result. All tables are in tibble data frame formats. Can use write_flow_data() or write_results() to customize saving tibbles to a local drive.

Visualization

The visualization functions, which begin with plot_*, plot the various summary statistics and analyses as a way to visualize the data. While most plotting function statistics can be customized, some come pre-set with statistics that cannot be changed. Plots can be further modified by the user using the ggplot2 package and its functions. All plots functions produce lists of plots (even if just one produced). Can use write_plots() to customize saving the lists of plots to a local drive (within folders or PDF documents).

Function Options

Daily Rolling Means

If certain n-day rolling mean statistics are desired to be analyzed (e.g. 3- or 7-day rolling means) some functions provide the ability to select for that as function arguments (e.g. rolling_days = 7 and rolling_align = "right"). The rolling day align is the placement of the date amongst the n-day means, where “right” averages the day-of and previous n-1 days, “centre” date is in the middle of the averages, and “left” averages the day-of and the following n-1 days. For your own analyses you can add rolling means to your data set using the add_rolling_means() function.

Year and Month Filtering

To customize your analyses for specific time periods, you can designate the start and end years of your analysis using the start_year and end_year arguments and remove any unwanted years (for partial data sets for example) by listing them in the excluded_years argument (e.g. excluded_years = c(1990, 1992:1994)). Alternatively, some functions have an argument called complete_years that summarizes data from just those years which have complete flow records. Some functions will also allow you to select the months of a year to analyze, using the months argument, as opposed to all months (if you want just summer low-flows, for example). Leaving these arguments blank will result in the summary/analysis of all years and months of the provided data set.

To group analyses by water, or hydrologic, years instead of calendar years, if desired, you can set water_year_start within most