# Rainfall-Runoff Event Detection and Identification (RREDI) alogrithm - ReadMe.txt
# Canham, H., Lane, B. (2022). Rainfall-Runoff Event Detection and Identification (RREDI) algorithm, HydroShare, http://www.hydroshare.org/resource/797fe26dfefb4d658b8f8bc898b320de

# Utah Water Research Laboratory
# Utah State University

# November 2022
# Updated January 2024 - Additional operational details and streamline of input file names. Include DiurnalFlaggingFunction.py file.

# Contact
	Haley Canham - haley.canham@usu.edu
	Belize Lane - belize.lane@usu.edu
	
#Disclaimer
	RREDI is still in development and not in final release.

# Contents
	ReadMe.txt -> read me file for resource
	
	RREDI -> folder containing all algorithm code
	DiurnalFlaggingFunction.py -> python script containing diurnal cycling filter function to be called by Filtering.py
	func-flow-master -> folder containing adapted FFC code (Patterson et al., 2019) for rainfall-runoff event identification.
	EventAttributes_Functions.py -> python script containing required functions for rainfall-runoff event attribution.
	EventAttributes_Main.py -> python script for rainfall-runoff event attribution
	Filtering.py -> python script for flagging of rainfall-runoff event issues (NAN events, duplicate events, no end events)
	FlowData.py -> python script to get and format USGS flow data
	Storm_Flow_WYMatching.py -> python script to check aligned period of record and formatting for FFC input files
	StormGenerator.py -> python script to generate storms from instantaneous precipitation data
	
	ExampleFiles -> folder containing all example files
	FlowData_I.csv -> formatted 15-min flow data file from FlowData.py
	FlowData_D.csv -> formatted daily flow data file from FlowData.py
	Precip.csv -> formatted instantaneous precipitation data file (no script provided) 
	Storms.csv -> output file from StormGenerator.py with attributes for all storms from StormGenerator.py
		Magnitude folder -> contains .csv files for incremental cumulative magnitude for each storm from StormGenerator.py - NOTE: not inlcuded due to file size
		Intensity folder ->  contains .csv files for incremental 15-min intensity for each storm from StormGenerator.py - NOTE: not included due to file size
	P_Input -> formatted preciptation (storm) input file for event detection and identification from Storm_Flow_WYMatching.py
	Q_D_Input -> formatted daily flow input file for event detection and identification from Storm_Flow_WYMatching.py
	Q_I_Input -> formatted instantaneous (15-min) input file for event detection and identification from Storm_Flow_WYMatching.py
	FPEvents.csv -> daily event identification (FFC) output file from main.py (FFC)
	Event_Attirbutes_Output.csv -> event attribution output file from EventAttribtues_Main.py 
	FinalEvents.csv -> list of identified and attributed events that meet RREDI requirements output file fro Filtering.py
	
# Order of Operations
	1. FlowData.py -> retrieve and format 15-min and daily flow data for USGS gage of interest for specified POR
	2. Get and format precipitation data to instantaneous datetime (retreival and formatting script not inlcuded due to variety of data sources)
	3. StormGenerator.py -> create storms out of instant precip data based on specified storm time gap
	4. Storm_Flow_WYMatching.py -> run to ensure that preciptation and flow pors meet the requirements for FFC (aligned, >1wy)
	5. main.py (within FFC) -> run to identify rainfall-runoff events using daily data
	6. EventAttributes_Main.py -> run to attribute rainfall-runoff events using 15-min flow data
	7. Filtering.py -> run to filter out mis-attributed events inlcuding situations with NAN events, duplicate events, and no end events

# Applying RREDI
	RREDI is developed to automatie the identification and attributions of rainfall-runoff events using feature detection and signal processing of timeseries.  
	RREDI performs well in un-altered watersheds with distrinct rainfall-runoff events and has been applied in watersheds of varying size across the western US. 
	RREDI is not applicabale for seperating rainfall-runoff events from diurnal cycling (from melt cycles or irrigation) or other human caused hydrograph influence (ie below dams).
	RREDI should be applied for time periods greater than 1 wy otherwise error will be returned in the FFC. To decrease error, recommend running the Storm_Flow_WYMatching.py prior to subsequent scripts.
	RREDI should be applied for flow values >1. If values are less than 1, peaks will not be detected. Can alter flow units or magnify flow if all/majority of flow values are <1. Example: convert cms to cfs.

# Tips and Tricks
	Ensure exact file formatting otherwise code will not run.
	File paths will need to be specified and changed for each sub step along the way. - Update coming in the future.

# Future plans
	Main wrapper script - so that everything can be run together and not individually. 
	File path unification for simplicity and ease of transferability between users.