Computing Annual Trends with fasstr

fasstr, the Flow Analysis Summary Statistics Tool for R, 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 trending and frequency analyses, with outputs in both table and plot formats.

This vignette documents the usage of the compute_annual_trends() function in fasstr. This vignette is a high-level adjunct to the details found in the function documentation (see ?compute_annual_trends()). You’ll learn what arguments to provide to the function to customize your analysis, what analyses are computed, and what outputs are produced.

Overview

Determining trends in streamflow data can provide information on potential changes in hydrological processes over time. The annual trending analysis with fasstr allows for customization of both the inputs and outputs. This function takes up to 107 annual streamflow metrics (calculated using various annual fasstr functions) and calculates prewhitened, non-parametric trends using the Mann-Kendall test performed using the zyp R package. See the zyp documentation for more information on the methods.

Each annual metric/time-series is analyzed for trends using trend-free prewhitening to remove lag-1 correlation (may artificially detect a significant trend). The slope of each metric over time is then estimated using the Theil-Sen approach. If the estimated slope is different from zero, then the data are detrended by the slope and the AR(1) 1s calculated for the detrended time series. The residuals and the trend are combined and then tested for significance using the Mann-Kendall trend test.

The trending function results in a list containing two tibble data frame outputs and, if selected, plot for each metric trended.

Annual_Trends_Data - data used for analysis calculated from various annual fasstr functions
Annual_Trends_Results - results of the zyp trending analysis, and includes various other statistics
‘Sep_Maximum’ - an example of each of 107 plots produced (one for each metric)

Function and Data Inputs

compute_annual_trends()

To determine annual trends from a daily streamflow data set, the compute_annual_trends() function will take daily data, either from HYDAT using the station_number argument or your own data frame of data using the data argument to complete the analysis. To complete a custom trends analysis of data please see the zyp functions for more information.

Usage, Options, and Outputs

Analysis Data

This function is provided to calculate trends on a multitude of annual metrics, as calculate by various annual and monthly fasstr functions. The functions will calculate metrics from each of the following functions:

calc_annual_stats() - calculate annual summary statistics
calc_annual_cumulative_stats() - calculate annual and seasonal cumulative flows, both volume and yield
calc_annual_flow_timing() - calculate annual flow timing
calc_annual_lowflows() - calculate annual lowflows
calc_annual_normal_days() - calculate annual days above and below normal
calc_monthly_stats() - calculate annual monthly summary statistics

While each of the different metrics have default variables for their arguments, many of them can be customized. The following table shows which arguments are used for which statistics and what the defaults are. See the documentation for more information.

Argument	Corresponding Function	Default
`annual_percentiles`	`calc_annual_stats()`	`c(10,90)`
`monthly_percentiles`	`calc_monthly_stats()`	`c(10,20)`
`stats_days`	`calc_annual_stats()` & `calc_monthly_stats()`	`1`
`stats_align`	`calc_annual_stats()` & `calc_monthly_stats()`	`"right"`
`lowflow_days`	`calc_annual_lowflows()`	`c(1,3,7,30)`
`lowflow_align`	`calc_annual_lowflows()`	`"right"`
`timing_percent`	`calc_annual_flow_timing()`	`c(25,33.3,50,75)`
`normal_percentiles`	`calc_annual_normal_days()`	`c(25,75)`

With fasstr version 0.4.0, the months argument is now included in the trending function to specify which months of the year to include for trending. For example, selecting months = 7:9 means that all annual and monthly statistics will be calculated just from July through September to be tested for trends. This gives the user more flexibility to trend more statistics. Since selecting months may complicate seasonal totals, seasonal yields and seasonal volumes are not included in the results if not all 12 months are selected.

Examples

Example with default arguments:

compute_annual_trends(station_number = "08NM116",
                      zyp_method = "zhang",
                      start_year = 1973, end_year = 2013)

Example with custom arguments:

compute_annual_trends(station_number = "08NM116",
                      zyp_method = "zhang",
                      start_year = 1973, end_year = 2013,
                      annual_percentiles = c(10,90),
                      monthly_percentiles = c(10,20),
                      stats_days = 1,
                      stats_align = "right",
                      lowflow_days = c(1,3,7,30),
                      lowflow_align = "right",
                      timing_percent = c(25,33,50,75),
                      normal_percentiles = c(25,75))

Example with custom months arguments that will trend data only from May through September:

compute_annual_trends(station_number = "08NM116",
                      zyp_method = "zhang",
                      start_year = 1973, end_year = 2013,
                      months = 5:9)

This annual data is provided in the Annual_Trends_Data tibble objects. The following is an example of the output, including all the annual metrics and a first few years of data used for the zyp trends analysis:

            Statistic          1973          1974          1975
1      Annual_Maximum        37.700        66.000        48.700
2         Annual_Mean         3.331         8.430         5.483
3       Annual_Median         0.980         1.340         1.540
4      Annual_Minimum         0.025         0.447         0.320
5          Annual_P10         0.549         0.709         0.580
6          Annual_P90         8.832        32.980        19.580
7           Min_1_Day         0.025         0.447         0.320
8       Min_1_Day_DoY       293.000       333.000        11.000
9           Min_3_Day         0.045         0.533         0.378
10      Min_3_Day_DoY       295.000       334.000        39.000
11          Min_7_Day         0.194         0.602         0.416
12      Min_7_Day_DoY       299.000       346.000        41.000
13         Min_30_Day         0.574         0.665         0.494
14     Min_30_Day_DoY       249.000       358.000        58.000
15    Total_Volume_m3 105036393.421 265854182.477 172900396.854
16  Jan-Jun_Volume_m3  84993926.226 223662988.720 136045958.439
17  Jul-Dec_Volume_m3  20042467.195  42191193.757  36854438.415
18  Jan-Mar_Volume_m3   5734540.834   8368012.779   5258217.605
19  Apr-Jun_Volume_m3  79259385.392 215294975.941 130787740.834
20  Jul-Sep_Volume_m3   7503580.782  35216640.131  24657350.460
21  Oct-Dec_Volume_m3  12538886.413   6974553.626  12197087.955
22     Total_Yield_mm       132.121       334.408       217.485
23   Jan-Jun_Yield_mm       106.911       281.337       171.127
24   Jul-Dec_Yield_mm        25.211        53.071        46.358
25   Jan-Mar_Yield_mm         7.213        10.526         6.614
26   Apr-Jun_Yield_mm        99.697       270.811       164.513
27   Jul-Sep_Yield_mm         9.438        44.298        31.016
28   Oct-Dec_Yield_mm        15.772         8.773        15.342
29   DoY_25pct_TotalQ       138.000       135.000       146.000
30   DoY_33pct_TotalQ       141.000       146.000       153.000
31   DoY_50pct_TotalQ       151.000       158.000       162.000
32   DoY_75pct_TotalQ       172.000       173.000       177.000
33        Normal_Days       120.000       221.000       206.000
34  Below_Normal_Days       230.000        69.000       129.000
35  Above_Normal_Days        15.000        75.000        30.000
36           Jan_Mean         0.730         1.023         0.625
37         Jan_Median         0.705         1.020         0.595
38        Jan_Maximum         0.963         1.260         1.050
39        Jan_Minimum         0.595         0.864         0.320
40            Jan_P10         0.626         0.906         0.507
41            Jan_P20         0.643         0.934         0.538
42           Feb_Mean         0.670         0.985         0.490
43         Feb_Median         0.676         0.984         0.483
44        Feb_Maximum         0.728         1.060         0.614
45        Feb_Minimum         0.595         0.830         0.368
46            Feb_P10         0.619         0.944         0.407
47            Feb_P20         0.632         0.957         0.449
48           Mar_Mean         0.806         1.211         0.896
49         Mar_Median         0.799         1.120         0.943
50        Mar_Maximum         0.951         2.140         1.390
51        Mar_Minimum         0.685         0.855         0.677
52            Mar_P10         0.708         0.937         0.694
53            Mar_P20         0.736         0.983         0.716
54           Apr_Mean         1.774         7.761         1.789
55         Apr_Median         1.510         4.910         1.780
56        Apr_Maximum         3.450        28.300         3.400
57        Apr_Minimum         0.852         1.850         0.949
58            Apr_P10         0.963         1.919         0.984
59            Apr_P20         1.116         2.070         1.036
60           May_Mean        16.395        29.845        16.274
61         May_Median        15.200        30.300        16.800
62        May_Maximum        37.700        50.400        32.300
63        May_Minimum         3.450        15.900         3.340
64            May_P10         4.420        17.500         5.210
65            May_P20         5.950        20.100         6.820
66           Jun_Mean        11.863        44.460        31.853
67         Jun_Median        10.350        44.900        30.850
68        Jun_Maximum        26.900        66.000        48.700
69        Jun_Minimum         3.880        20.600        13.000
70            Jun_P10         6.104        25.610        17.240
71            Jun_P20         7.204        33.280        23.820
72           Jul_Mean         1.422         9.966         4.922
73         Jul_Median         0.926         8.210         3.450
74        Jul_Maximum         4.980        24.800        10.900
75        Jul_Minimum         0.462         2.420         1.180
76            Jul_P10         0.518         3.790         1.250
77            Jul_P20         0.561         5.380         1.460
78           Aug_Mean         0.615         1.761         2.274
79         Aug_Median         0.564         1.610         1.680
80        Aug_Maximum         1.100         3.710         5.920
81        Aug_Minimum         0.326         0.960         0.736
82            Aug_P10         0.453         1.200         0.974
83            Aug_P20         0.476         1.280         1.180
84           Sep_Mean         0.789         1.468         2.076
85         Sep_Median         0.685         1.395         1.750
86        Sep_Maximum         2.270         2.100         5.100
87        Sep_Minimum         0.399         1.130         1.390
88            Sep_P10         0.470         1.199         1.460
89            Sep_P20         0.496         1.246         1.536
90           Oct_Mean         1.630         1.231         1.845
91         Oct_Median         0.867         1.120         1.840
92        Oct_Maximum         8.070         2.080         2.210
93        Oct_Minimum         0.025         0.838         1.510
94            Oct_P10         0.113         0.867         1.650
95            Oct_P20         0.416         0.903         1.740
96           Nov_Mean         1.760         0.710         1.488
97         Nov_Median         1.485         0.711         1.400
98        Nov_Maximum         3.060         0.943         2.940
99        Nov_Minimum         1.220         0.447         0.906
100           Nov_P10         1.327         0.616         1.047
101           Nov_P20         1.350         0.633         1.128
102          Dec_Mean         1.349         0.686         1.268
103        Dec_Median         1.400         0.680         1.290
104       Dec_Maximum         1.830         0.850         1.590
105       Dec_Minimum         0.977         0.541         0.991
106           Dec_P10         1.020         0.609         1.050
107           Dec_P20         1.210         0.637         1.120

To provide examples of the outputs, an analysis will be completed on a Mission Creek HYDAT station from 1973 to 2013. The argument zyp_method is described below in the Analysis Results section:

trends_analysis <- compute_annual_trends(station_number = "08NM116",
                                         zyp_method = "zhang",
                                         start_year = 1973, end_year = 2013)

The following is an example of the outputted Annual_Trends_Data tibble:

trends_analysis$Annual_Trends_Data

  STATION_NUMBER      Statistic     X1973     X1974     X1975     X1976
1        08NM116 Annual_Maximum 37.700001 66.000000 48.700001 71.099998
2        08NM116    Annual_Mean  3.330682  8.430181  5.482636  8.180694
3        08NM116  Annual_Median  0.980000  1.340000  1.540000  3.840000
4        08NM116 Annual_Minimum  0.025000  0.447000  0.320000  0.736000
5        08NM116     Annual_P10  0.549000  0.709200  0.580000  0.883500
6        08NM116     Annual_P90  8.832000 32.979999 19.580000 25.550000
      X1977     X1978     X1979     X1980     X1981     X1982     X1983
1 36.000000 44.500000 43.000000 46.200001 60.599998 54.500000 60.200001
2  4.381567  6.747608  4.401564  5.374555  7.669145  8.458134  7.851918
3  1.260000  3.280000  1.560000  1.880000  2.770000  2.680000  3.130000
4  0.564000  0.532000  0.411000  0.623000  0.398000  0.815000  0.530000
5  0.776000  0.827800  0.618200  0.793000  1.500000  1.404000  1.436000
6 17.200001 19.700001 15.880000 20.100000 22.340000 30.299999 23.480000
      X1984     X1985     X1986     X1987     X1988     X1989    X1990
1 52.400002 52.299999 72.500000 43.400002 37.900002 39.000000 69.90000
2  7.333208  5.017438  6.347041  2.876137  4.547973  5.442384  9.20929
3  2.185000  1.380000  1.930000  0.880000  1.560000  1.750000  1.98000
4  0.735000  0.332000  0.635000  0.274000  0.140000  0.498000  0.56000
5  1.150000  0.870000  0.937000  0.433400  0.341000  1.020000  1.09000
6 25.800000 12.760000 14.260000  5.874000 14.750000 17.160001 34.10000
      X1991     X1992     X1993     X1994    X1995     X1996    X1997     X1998
1 56.700001 29.799999 58.000000 39.700001 33.10000 53.900002 84.50000 44.700001
2  7.472605  3.256295  6.927921  6.030022  5.64783  8.041762 11.13412  5.538548
3  1.740000  1.190000  2.570000  1.260000  2.26000  3.000000  3.95000  1.450000
4  0.439000  0.436000  0.270000  0.430000  0.55600  0.822000  0.81400  0.490000
5  0.714600  0.632000  0.650000  0.684000  0.73020  1.465000  1.50000  0.775400
6 27.080000  8.295000 18.340000 22.700001 20.00000 22.550000 36.62000 18.020000
      X1999    X2000     X2001     X2002     X2003    X2004     X2005     X2006
1 52.000000 52.50000 34.599998 59.000000 33.000000 40.10000 54.400002 72.000000
2  8.134885  6.55276  4.628427  6.274479  3.780022  6.03715  6.760318  6.520671
3  2.860000  1.92500  1.470000  1.170000  0.856000  3.75500  3.490000  1.200000
4  0.630000  0.29500  0.485000  0.260000  0.340000  0.49000  0.729000  0.353000
5  0.846200  0.70000  0.704000  0.532400  0.400000  0.60000  1.164000  0.853000
6 25.180000 21.75000 15.980000 20.900000 10.860000 16.70000 18.780000 21.740000
      X2007     X2008     X2009    X2010     X2011     X2012     X2013
1 39.299999 60.700001 33.099998 39.10000 56.200001 86.199997 81.800003
2  4.419003  5.112333  3.504414  4.50091  6.235263  8.546167  8.015493
3  1.710000  1.185000  1.110000  1.24000  1.220000  1.580000  2.050000
4  0.420000  0.440000  0.376000  0.42700  0.520000  0.518000  0.609000
5  0.560000  0.577500  0.600400  0.53880  0.741200  0.633000  0.884000
6 14.060000 18.500000 10.200000 14.74000 28.980000 29.950000 27.500000

Analysis Results

To complete a trends analysis, a variable to the zyp_method argument must be provided, either "zhang" or "yuepilon", designating the two different approaches to analyzing data for trends. The zhang method is recommended for hydrologic applications over yuepilon (see zyp documentation for more information on the differences between the two methods). After running the function, the results of the trending analysis will be outputted in the Annual_Trends_Results tibble data frame. See the zyp documentation for how to interpret the results. The results tibble contains the following columns:

Column Name	Description
Statistic	the annual statistic used for trending
lbound	the lower bound of the trend’s confidence interval (`zyp`)
trend	the Sens’ slope (trend) per unit time (`zyp`)
trendp	the Sen’s slope (trend) over the time period (`zyp`)
ubound	the upper bound of the trend’s confidence interval (`zyp`)
tau	Kendall’s tau statistic computed on the final detrended timeseries (`zyp`)
sig	Kendall’s P-value computed for the final detrended timeseries (`zyp`)
nruns	the number of runs required to converge upon a trend (`zyp`)
autocor	the autocorrelation of the final detrended timeseries (`zyp`)
valid_frac	the fraction of the data which is valid (not NA) once autocorrelation is removed (`zyp`)
linear	the least squares fit trend on the same data (`zyp`)
intercept	the intercept of the Sen’s slope (trend) (`zyp`)
min_year	the minimum year used in the trending
max_year	the maximum year used in the trending
n_years	the number of years with data for trending
mean	the mean of all values used for trending
median	the median of all values used for trending
min	the minimum of all values used for trending
max	the maximum of all values used for trending

The following is an example of the outputted Annual_Trends_Results tibble from the Mission Creek HYDAT station from 1973 to 2013:

trends_analysis$Annual_Trends_Results

  STATION_NUMBER      Statistic       lbound         trend     trendp
1        08NM116 Annual_Maximum -0.367741985  0.0570881358  2.3406136
2        08NM116    Annual_Mean -0.074223160 -0.0210267927 -0.8620985
3        08NM116  Annual_Median -0.035271133 -0.0124905012 -0.5121105
4        08NM116 Annual_Minimum -0.006666194 -0.0009808123 -0.0402133
5        08NM116     Annual_P10 -0.017499298 -0.0063876706 -0.2618945
6        08NM116     Annual_P90 -0.255726706 -0.0302831595 -1.2416095
       ubound         tau       sig nruns    autocor valid_frac        linear
1 0.516666624  0.04026846 0.7192625     1 0.01369972          1  0.1380313468
2 0.038457631 -0.07179487 0.5216482     4 0.08208012          1 -0.0019323059
3 0.007693628 -0.14102565 0.2040979     3 0.06435808          1 -0.0088832751
4 0.004085119 -0.04871795 0.6664041     4 0.08440387          1  0.0004937281
5 0.005695283 -0.10512821 0.3453057     5 0.47516677          1 -0.0049319510
6 0.199289847 -0.03333334 0.7708403     4 0.13185024          1  0.0101482580
   intercept lbound_intercept ubound_intercept min_year max_year n_years
1 50.9015322     21.804136811       79.7152348     1973     2013      41
2  6.9349161      2.866094958       10.5580963     1973     2013      41
3  1.9761652      0.454868274        4.0202190     1973     2013      41
4  0.5002090      0.166538940        0.8613161     1973     2013      41
5  0.8558584     -0.007427143        1.9272266     1973     2013      41
6 20.3637020      5.576070188       36.8692482     1973     2013      41
        mean    median       min      max
1 51.9585367 52.299999 29.799999 86.20000
2  6.1988672  6.235263  2.876137 11.13412
3  1.9552683  1.710000  0.856000  3.95000
4  0.4810732  0.485000  0.025000  0.82200
5  0.8147268  0.730200  0.341000  1.50000
6 20.2456342 19.700001  5.874000 36.62000

Annual Trends Plots

To provide the ability to visualize the trends, a time-series plot for each metric is provided when include_plots = TRUE (default; set it to FALSE to produce no plots). Each plot will show the annual value for all years and if a numerical zyp_alpha value, a significance level indicating the trend exists, is provided (typically 0.05) then a trend line of the calculated Sen’s Slope will also be plotted through the data. To plot no slopes, set zyp_alpha = NA (default) and to plot the lines regardless of significance, set zyp_alpha = 1. The metric name along with the significance level will be included as the title of the plot.

The following plots demonstrate examples of where the zyp_alpha value is set to 0.05 and Sen’s Slopes trends are not and are significant, respectively.