evaluate_gage_alteration.RdThis is a shortcut function that does most of the heavy lifting for you. Runs data through the FFC and transforms all results.
evaluate_gage_alteration(
gage_id,
token,
comid,
plot_output_folder,
plot_results,
force_comid_lookup,
return_processor
)The USGS gage ID to pull timeseries data from
The token used to access the online FFC - see the Github repository's README under Setup for how to get this.
The stream segment COMID where the gage is located. In the past, the package looked this information up automatically
but we discovered that our method for looking gage COMIDs up was error prone, and there is no authoritative dataset
that relates gages to COMIDs. It will be most accurate if you provide the comid yourself by looking it up (don't
use nhdPlusTools with the latitude and longitude - that's what we did that was error prone). You can re-enable
the lookup behavior setting the force_comid_lookup parameter to TRUE.
Optional - when not provided, plots are displayed interactively only. When provided, they are displayed interactively and saved as files named by the functional flow componenent into the provided folder
boolean, default TRUE - when TRUE, results are plotted to the screen and any folder provided. When
FALSE, does no plotting.
default FALSE. When TRUE, the COMID for the segment will be automatically
looked up based on the latitude and longitude. This method is error prone and it is advised you leave it off.
Where an error is known, the package corrects the COMID based on an internal list of gage/comid pairs (eg:
Jones Bar on the Yuba River). It is recommended you leave this as FALSE and look up the comid yourself to
ensure that you choose the correct mainstem or tributary near stream junctions, but if you need to bulk
process data, this parameter is available to retrieve COMIDs.
If you provide it a USGS gage ID and your token to access the online functional flows calculator, this function then:
1. Download the timeseries data for the USGS gage
2. Look up the predicted unimpaired metric values for the gage's stream segment
3. Send the timeseries data through the functional flows calculator
4. Transform the results into a data frame with rows for years and metric values as columns
5. Produce percentiles for those metric values using R's recommended quantile method type 7 (which may return differing results from other methods, Excel, etc)
6. Transform the dimensionless reference hydrograph data into a data frame
7. Determines the alteration by flow metric for the observed versus predicted values
8. Output plots comparing the observed timeseries data with the predicted unimpaired metric values.
Items 4, 5, 6, and 7 are returned back to the caller as a list with keys "ffc_results", "ffc_percentiles", "drh_data", and "alteration" for any further processing. The list also includes "predicted_percentiles", with the predicted flow metrics for the segment.