fasstrshiny_users_guide.RmdVisit https://bcgov-env.shinyapps.io/fasstrshiny/
Pros
fasstrshiny!Cons
To install, in the R console run the following (this needs to be done once)
install.packages("remotes")
remotes::install_github("bcgov/fasstrshiny")To use HYDAT data in the app, the Environment and Climate Change Canada’s HYDAT database must be downloaded (this needs to be done once or as needed to update):
tidyhydat::download_hydat()To the Shiny App run, in the R console, run the following (this needs to be done everytime):
library(fasstrshiny) # Loads the package
fasstr_shiny() # Launches the Shiny AppPros
fasstr code output by the Shiny App to learn more!Cons
fasstrshiny packageremotes::update_packages())Side bar - Navigate through the different pages on the left sidebar - can close to make more space by clicking 3 bars beside fasstr shiny title
Within page, there are multiple tabs and a sidebar with explanation and data options for the page. For most pages, will be a sidebar with data options for entire page (some exceptions), tab for plotting results, tab for table of results
The first thing you’ll need to do is load some daily streamflow data. Go to Data >> Loading & Options. Here you can choose whether to load HYDAT data or your own local data from a .csv file format.
The map shows all the HYDAT stations in BC. To look at all of Canada, toggle the “BC Stations Only” switch. Hover over stations for more information, click on a station to select that station. Below the map is a table of HYDAT stations. You can filter stations by typing into the box above each column. As you filter the stations list, the map will update to show only the stations you’ve filtered. Once you’ve decided on a station, make sure it is selected in the panel on the left and click the “Load Data” button. You can now preview the data on the “Daily Flow Plot” and “Daily Flow Table” tabs.
If there is missing data between the start and end of the period of record, a note in red text will pop up below this section. Missing data may cause plots or tables to have gaps throughout the app. To manage how to deal with missing dates, see the ‘handling Missing Dates’ options at the bottom of the options.
Click on the CSV button to change the data source to local csv. Your data must be in csv format with at least two columns: one for the date, and one for the flow value (in cms). Click on the “Browse” button to locate your file. You can preview the file on the right. Make sure the Date and Flow columns are correctly identified. If you have a Symbol column (with daily flow qualifers, Estimate, Partial day etc.) you can add that as well, otherwise leave that entry blank. If you know the basin area for your data, add it to under “Station Information”. Click “Load Data”.
If your dates are not standardized (YYYY-MM-DD) or if you have more than one flow value per date, you will be warned and will have to fix your data before it can be loaded.
You can now preview the data on the “Daily Flow Plot” and “Daily Flow Table” tabs.
If there is missing data between the start and end of the period of record, a note in red text will pop up below this section. Missing data may cause plots or tables to have gaps throughout the app. To manage how to deal with missing dates, see the ‘handling Missing Dates’ options at the bottom of the options.
Click this toggle to view and/or change the station name (used for titles throughout the app) and the upstream basin area, in square kilometres (used for area-based runoff calculations). When using HYDAT data, these will default to the provided HYDAT information, but can be modified as necessary.
Below the Load Station Data and Station Information (can click the toggles to close), explore data and date settings to customize the station information, filter your dates, adjust the types of data you’re using or handle missing dates differently (also see the section below, Data Options). These options will also be shown in the sidebar on the left below all the tab selections for viewing throughout the app. Options sections:
Change the duration of the daily data by averaging sequential daily data (ie. 7-day rolling average); alignment will determine where the date of rolling average will align (‘right’ = last of n-days, ‘left’ = first of n-days, and ‘centre’ = middle of n-days). These correspond to the ‘roll_days’ and ‘roll_align’ arguments found in the
Convert the daily cubic metres per second data into a daily volumetric (cubic metres) or a daily runoff yield (millimetres depth; requires an upstream basin area) before calculating statistics and plots.
Filter the flow data set for only those years which have complete data (no missing values). By toggling this, it will change the Start/End years slider to the first and last years of complete data and will add any years with complete data between those years into Years to Exclude box.
If complete years are not require, choose to ignore any missing values and calculate statistics for a given time period regardless of any missing dates. This will move the ‘Allowed Missing’ slider to jump to 100% below, select the percent allowed missing values per period below.
Adjust the percent of allowed missing values per time period (months, years). If 100%, statistics will be calculated regardless of the number of missing values (i.e. even if 1 good value per year or month). If 25%, statistics will be calculated if there is if 25% or less missing data per period (at least 75% non-missing values). If set to 0%, then no statistics will be calculated per period if there is missing data.
Now that you’ve loaded your data, you’ll want review your data and screen the data for data availability (missing dates) and data quality (data qualifiers/symbols or outliers). Click on Data >> Availability & Screening to view these plots and tables.
This section contains several different plots and tables for exploring your data:
plot_flow_data_symbols().plot_annual_symbols().plot_missing_dates().plot_data_screening().screen_flow_data().Filtering and Missing Dates. If after reviewing your data you find any periods that are problematic and you would like to omit from your analysis, go to Data >> Loading & Options, and adjust the dates under “Years and Months”. Similarly, if you have a lot of missing data, you can specify how these values should be handled under “Handling Missing Dates”. See previous section for more descriptions of the options.
For an overview of the summary statistics and flow patterns for your selected station, explore the Overview tab. This tab will provide the following information:
fasstr functions
These
Annual hydrographs summarizing flow statistics (means, maximums, mininums, percentiles).
Summary statistics of all years of data group by day of year, monthly daily averages, or monthly monthly averages
fasstr functions:
calc_daily_stats() and plot_daily_stats()
calc_longterm_daily_stats() and plot_longterm_daily_stats()
calc_longterm_monthly_stats() and plot_longterm_monthly_stats()
Cumulative summary statistics of all years of data group by day of year, monthly monthly totals
fasstr functions:
Various statistics produced on an annual basis (data grouped by years)
loading Rstudio/R and packages see fasstr user guide copying code, running code using tidyverse for manipulation
Every page in this app has an “R Code” tab. This tab shows the R code used to create all the plots and figures on that particular page.
Playing around with this code on your own is a great way to become more familiar with R and fasstr.
First, if you’re brand new to R, consider running through a primer on getting started in R and RStudio.
Once you’re comfortable working with basic R scripts, you’re ready to take a stab playing with fasstr code!
First, you’ll need to make sure you have the right packages loaded. If you’ve already installed the fasstrshiny package (as above) and have been using fasstrshiny locally, you’re good to go. Otherwise, install fasstr and the HYDAT database using the instructions above.
library(fasstr) # Loads the packages
library(dplyr)
library(tidyr) Each series of code starts with a block loading the data (data_flow = ...), either from the HYDAT data base or a local file (see Things to remember, below if loading local data).
To run this code locally, copy all the code, and paste it into a script in RStudio (or similar R IDE).
There is one very important step to do now: Add library(fasstr) to the top of the script. This only needs to be done once per script, and it’s best to put this code at the top of a script since it needs to be loaded before any thing else.
Now you can run the script! It should produce the figures and/or output you see in the fasstrshiny app.
Note that some complex figures (e.g. hydrographs with added dates and added MAD values) have been modified after the fasstr figure was produced so the code won’t reproduce those figures exactly.
Saving this script is a great way to keep track of your analyses for future use. You can also share them with colleagues.
The R code panel generally only shows the last figure you produced. So if you’re on that tab and change a setting, it won’t always be updated in the code. To be safe, always look at the figure/table you want to reproduce first, and then grab the code.
This also means that if you don’t look at a tab, the code won’t appear in the R Code tab.
If you load a local data set, the R code data block will only show the name of the file. This means that unless your file is in your working directory the loading code will error. For a better understanding of working directories, see An Introduction to R - 1.7 Working directories.
In general, try to work with RStudio projects, and keep your scripts and data together. If your data is in your working directory, you can run the code as is, otherwise you’ll need to modify the file name to include a location.
For example, “test.csv” becomes “data/test.csv” if I have test.csv in a data folder in my working directory.
There are three main areas in which you can adjust the settings in this app.
First, as mentioned above, most settings are in the Data >> Loading page. These settings apply to every other page in the app. If you wish to change them, go back to the Data > Loading page and change them, then return to the page you were using.
Second, most pages have specific settings to that set of calculations. You can set these settings on the page in question, they have no bearing on any other calculations (but do apply to all tabs on a page, e.g., Plot and Table).
Finally, plots and tables sometimes have specific settings available by clicking on the “gear” button on the upper right side. These are like the page settings, but even more specific, they only apply the plot or table on that page, on that tab.
All plots and table in this app are interactive.
You can hover the mouse over any plot to get more information about the values presented.
There are also two plotly plots (Data > Loading > Daily Flows Plot and Data > Available > Symbols Flow) which can be zoomed in on by clicking and dragging over a time period.
Finally, in Analyses > Annual Trends and Analyses > Volume Frequency, you can click on specific points on the plot in order to identify years to omit from the analysis. You can also use the lasso to drag around the points to select a group.
Note that these last two special types of plots each have reminder instructions on the page itself to help you out.
Downloading. All plots can be downloaded by hovering over the plot and clicking on the small download button that appears in the upper right corner. This button looks like a small camera for plotly plots and a download icon for others. Plots that are relevant for reports also have an additional Plot download button (small blue button with download icon saying “Plot”, usually in the left hand settings tab). This results in a higher quality PNG than the other buttons.
Tables can be sorted by clicking on the desired column and exported to “Excel” or “CSV”. You can also copy the table and paste it into a spreadsheet by clicking the “Copy” button.
One table, the HYDAT stations table in Data > Loading, can also be filtered by typing filter text into the boxes above each column. This results in the HYDAT map showing only filtering stations.
Finally there is another special table in Analyses > Annual Trends. Once a trend analysis has been computed, the plot of a relevant statistic can be viewed by clicking on that statistic in the table. As with other tables you can also sort this table.
If you wish to save the status of your analysis so you can return to it later, you can click on the “Bookmark” button in the lower right corner of the window.
Note: While we have made every effort to ensure bookmarking works well, it can be slightly unstable and may not work between versions of this App. We therefore recommend using it as a helper or shortcut tool, rather than relying on it to save all your work as a complete record.
If you are using fasstrshiny from your local computer, this will save the details into a folder called shiny_bookmarks and you’ll get a link like:
http://127.0.0.1:7493/?_state_id_=a5fa7412c08683dd
The important part that identifies your bookmark is the id a5fa7412c08683dd.
Next time you run fasstr_shiny() you might have a different port (here, 7493). But if you paste the end of this link ?_state_id_=a5fa7412c08683dd to your new url and hit enter, you will recover the bookmark. Give the app a couple of seconds to reset all the inputs.
If you are using fasstrshiny from the web (shinyapps.io), then when you click the bookmark button you will get a VERY long URL. We recommend that you follow the instructions presented to shorten that URL with a service such as tinyURL. That url should then work to recover the app in future.