# 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.

1. Annual_Trends_Data - data used for analysis calculated from various annual `fasstr` functions
2. Annual_Trends_Results - results of the `zyp` trending analysis, and includes various other statistics
3. ‘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_outside_normal()` - 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_outside_normal()` | `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    Days_Below_Normal       230.000        69.000       129.000
    34    Days_Above_Normal        15.000        75.000        30.000
    35  Days_Outside_Normal       245.000       144.000       159.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

    # A tibble: 107 x 43
       STATION_NUMBER Statistic  `1973`  `1974` `1975` `1976`  `1977` `1978`  `1979`
       <chr>          <fct>       <dbl>   <dbl>  <dbl>  <dbl>   <dbl>  <dbl>   <dbl>
     1 08NM116        Annual_M~ 3.77e+1  66     48.7   71.1    36     44.5    43
     2 08NM116        Annual_M~ 3.33e+0   8.43   5.48   8.18    4.38   6.75    4.40
     3 08NM116        Annual_M~ 9.80e-1   1.34   1.54   3.84    1.26   3.28    1.56
     4 08NM116        Annual_M~ 2.50e-2   0.447  0.320  0.736   0.564  0.532   0.411
     5 08NM116        Annual_P~ 5.49e-1   0.709  0.580  0.884   0.776  0.828   0.618
     6 08NM116        Annual_P~ 8.83e+0  33.0   19.6   25.6    17.2   19.7    15.9
     7 08NM116        Min_1_Day 2.50e-2   0.447  0.320  0.736   0.564  0.532   0.411
     8 08NM116        Min_1_Da~ 2.93e+2 333     11     38      73     55     268
     9 08NM116        Min_3_Day 4.53e-2   0.533  0.378  0.741   0.627  0.630   0.416
    10 08NM116        Min_3_Da~ 2.95e+2 334     39     63     252      3     269
    # ... with 97 more rows, and 34 more variables: 1980 <dbl>, 1981 <dbl>,
    #   1982 <dbl>, 1983 <dbl>, 1984 <dbl>, 1985 <dbl>, 1986 <dbl>, 1987 <dbl>,
    #   1988 <dbl>, 1989 <dbl>, 1990 <dbl>, 1991 <dbl>, 1992 <dbl>, 1993 <dbl>,
    #   1994 <dbl>, 1995 <dbl>, 1996 <dbl>, 1997 <dbl>, 1998 <dbl>, 1999 <dbl>,
    #   2000 <dbl>, 2001 <dbl>, 2002 <dbl>, 2003 <dbl>, 2004 <dbl>, 2005 <dbl>,
    #   2006 <dbl>, 2007 <dbl>, 2008 <dbl>, 2009 <dbl>, 2010 <dbl>, 2011 <dbl>,
    #   2012 <dbl>, 2013 <dbl>

### 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

    # A tibble: 107 x 20
       STATION_NUMBER Statistic        lbound    trend  trendp  ubound     tau   sig
       <chr>          <fct>             <dbl>    <dbl>   <dbl>   <dbl>   <dbl> <dbl>
     1 08NM116        Annual_Maximum -0.368    5.71e-2  2.34   0.517    0.0403 0.719
     2 08NM116        Annual_Mean    -0.0742  -2.10e-2 -0.862  0.0385  -0.0718 0.522
     3 08NM116        Annual_Median  -0.0353  -1.25e-2 -0.512  0.00769 -0.141  0.204
     4 08NM116        Annual_Minimum -0.00667 -9.81e-4 -0.0402 0.00409 -0.0487 0.666
     5 08NM116        Annual_P10     -0.0175  -6.39e-3 -0.262  0.00570 -0.105  0.345
     6 08NM116        Annual_P90     -0.256   -3.03e-2 -1.24   0.199   -0.0333 0.771
     7 08NM116        Min_1_Day      -0.00667 -9.81e-4 -0.0402 0.00409 -0.0487 0.666
     8 08NM116        Min_1_Day_DoY  -0.5      1.74e+0 71.3    6.55     0.151  0.170
     9 08NM116        Min_3_Day      -0.00694 -1.22e-3 -0.0501 0.00534 -0.0282 0.807
    10 08NM116        Min_3_Day_DoY  -1.65     7.57e-1 31.0    3        0.0758 0.493
    # ... with 97 more rows, and 12 more variables: nruns <dbl>, autocor <dbl>,
    #   valid_frac <dbl>, linear <dbl>, intercept <dbl>, min_year <dbl>,
    #   max_year <dbl>, n_years <int>, mean <dbl>, median <dbl>, min <dbl>,
    #   max <dbl>

### 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.