## Paired Storms Framework for Post-Fire Flood Analysis - ReadMe.txt ##
## Canham, H., Lane, B. (2025). Paired Storms Framework for Post-Fire Flood Analysis, HydroShare, https://www.hydroshare.org/resource/e232f1ee789a4d03aa276008da2b7afb  ##

## Utah Water Research Laboratory ##
## Utah State University ##

## March 2025 ##

## Contact ##
	Haley Canham - haley.canham@usu.edu
	Belize Lane - belize.lane@usu.edu


## Code repository for paired storms framework to accompany Canham and Lane (2025) ##

## Contents ##
	ReadMe.txt - Start here
	Example Files - Directory containing example input and output files for paired storms framework workflow
		1Out_AORC_1km_lats.csv
		1Out_AORC_1km_longs.csv
		2Out_AORC_1km_grid.csv
		3In_AORC_1km_grid.csv
		3Out_AORC_1km_coordinates.csv
		4In_AORC_1km_coordinates.csv
		4Out_ArroyoSeco_Burnedpoints.csv
		4Out_ArroyoSeco_points.csv
		5In_ArroyoSeco_points.csv
		5Out_ArroyoSeco_AORCPrecip_1979.csv
		6In_ArroyoSeco_AORCPrecip_1979.csv
		6In_ArroyoSeco_points.csv
		6Out_ArroyoSeco_raw_precip.csv
		7In_ArroyoSeco_raw_precip.csv
		7Out_ArroyoSeco_precip_MaxSummary.csv
		8In_ArroyoSeco_precip_MaxSummary.csv
		8Out_ArroyoSeco_Storms_3.csv
		9In_ArroyoSeco_points.csv
		9In_ArroyoSeco_raw_precip.csv
		9In_ArroyoSeco_Storms_3.csv
		9Out_ArroyoSeco_StormGrids.csv
		10biIn_ArroyoSeco_OutletValue.csv
		10biIn_ArroyoSeco_points.csv
		10biIn_ArroyoSeco_StormDepthGrids.csv
		10biOut_ArroyoSeco_SpatialChars.csv
		10biiIn_ArroyoSeco_Burnedpoints.csv
		10biiIn_ArroyoSeco_StormDepthGrids.csv
		10biiOut_ArroyoSeco_StormFireOverlap.csv
		12In_ArroyoSeco_RainfallRunoffEvents.csv
		12Out_ArroyoSeco_PFFs_80post3.csv
		13In_ArroyoSeco_PFFs_80post3.csv
		13In_ArroyoSeco_RainfallRunoffEvents.csv
		13Out_ArroyoSeco_PFFs.csv
		13Out_ArroyoSeco_PostFloods_Storm0.csv
		14In_ArroyoSeco_AllStorms.csv
		14In_ArroyoSeco_PFFs.csv
		14In_ArroyoSeco_RainfallRunoffEvents.csv
		14Out_ArroyoSeco_PFF_percentiles.csv
		15In_ArroyoSeco_PFFs.csv
		15In_ArroyoSeco_PFF_Storm0.csv
		15Out_ArroyoSeco_Multipliers.csv
	Scripts - Directory containing developed .py scripts for paired storms framework
		1_AORC_LatLongs.py
		2_AORC_1km_grid.xlsx
		3_AORC_1km_coords.py
		5_Retrieve_AORCPrecip_Zarr_parallel_multiyr.py
		6_Combine_AORCPrecip_Years.py
		7_SummarizeAORCData.py
		9_StormGrids.py
		10bi_SpatialStomCharacteristics.py
		10bii_StormFireOverlap.py
		12_PFFs_80post3yr.py
		13_PairedStorms.py
		14_PFF_percentiles.py
		15_Multipliers.py

## Data sources ##
NOAA Analysis of Record for Calibration (AORC) Dataset was accessed on May 3, 2024 from https://registry.opendata.aws/noaa-nws-aorc.

USGS 11098000 Arroyo Seco NR Pasadena CA streamflow data was accessed on May 31, 2024 from https://waterdata.usgs.gov/nwis/inventory/?site_no=11098000.

## Additional Resources Used ##
Canham, H., B. Lane (2024). Rainfall-Runoff Event Detection and Identification (RREDI) toolkit, HydroShare, http://www.hydroshare.org/resource/797fe26dfefb4d658b8f8bc898b320de


## Paired Storms Framework Workflow ##
Note: Steps 4-15 code and example input and output files are for Arroyo Seco watershed (USGS 11098000). 	

1.	Retrieve AORC 1km2 lat and long coordinate values - 1_AORC_LatLongs.py
	Outputs: 
		1Out_AORC_1km_lats.csv
		1Out_AORC_1km_longs.csv
2.	Create grid of AORC lat,long coordinates with available precipitation data - manually 
		done in excel - 2_AORC_1km_grid.xlsx
		Note: trimmed version included for file management size 
	Outputs:
		2Out_AORC_1km_grid.csv
3. 	Convert AORC lat/long grid to list of lat/long coordinates - 3_AORC_1km_coords.py
	Inputs:
		3In_AORC_1km_grid.csv
	Outputs:
		3Out_AORC_1km_coordinates.csv
4. 	GIS spatial analysis to identify AORC coordinates of interest within watershed and burned points 
	Inputs:
		4In_AORC_1km_coordinates.csv
	Outputs:
		4Out_ArroyoSeco_points.csv
		4Out_ArroyoSeco_Burnedpoints.csv
5.	Retrieve AORC 1km2 precipitation data for list of coordinates, for specified year(s) - 5_Retrieve_AORCPrecip_Zarr_parallel_multiyr.py
	Inputs: 
		5In_ArroyoSeco_points.csv
		Used slurm batch processing to run script 
	Outputs:
		5Out_ArroyoSeco_AORCPrecip_XXXX.csv where XXXX is year
		Note: only 1979 inlcuded in file repository
6. 	Combine individual year AORC gridded precipitation files to one single file - 6_Combine_AORCPrecip_Years.py
	Inputs:
		6In_ArroyoSeco_AORCPrecip_XXXX.csv #where XXXX is year, only 1979 included
		6In_ArroyoSeco_points.csv 
	Outputs:
		6Out_ArroyoSeco_raw_precip.csv
7. 	Summarize raw gridded AORC precipitation data in a watershed to a watershed summary timeseries using 
		the maximum value - 7_SummarizeAORCData.py
	Inputs: 
		7In_ArroyoSeco_raw_precip.csv
	Outputs: 
		7Out_ArroyoSeco_precip_MaxSummary.csv
8. 	Generate Storms - RREDI, Canham and Lane (2022)
	Inputs:
		see RREDI, Canham and Lane (2022)
		8In_ArroyoSeco_precip_MaxSummary.csv
	Ouput:
		8Out_ArroyoSeco_Storms_3.csv
9. 	Make storm depth precipitation grids (lat, longs) for each storm - 9_StormGrids.py
	Inputs:
		9In_ArroyoSeco_points.csv
		9In_ArroyoSeco_raw_precip.csv
		9In_ArroyoSeco_Storms_3.csv
	Ouputs:
		9Out_ArroyoSeco_StormGrids.csv
10. 	Calculate storm characteristics
	a. Calculate temporal storm characteristcs - RREDI, Canham and Lane (2022)
	b. Calculate spatial storm characteristcs 
		i.	Calculate Ce, CV, and storm-watershed overlap - 10bii_StormFireOverlap.py
			Inputs:
				10biIn_ArroyoSeco_OutletValue.csv
				10biIn_ArroyoSeco_points.csv
				10biIn_ArroyoSeco_StormDepthGrids.csv
			Outputs:
				10biOut_ArroyoSeco_SpatialChars.csv
		ii.	Calculate storm-burned area overlap - 10bii_StormFireOverlap.py
			Inputs:
				10biiIn_ArroyoSeco_Burnedpoints.csv
				10biiIn_ArroyoSeco_StormDepthGrids.csv
			Outputs:
				10biiOut_ArroyoSeco_StormFireOverlap.csv
	c. 	Calculate interannual and seasonal cotext - RREDI, Canham and Lane (2022)
11.	Identify rainfall-runoff events - RREDI, Canham and Lane (2022)
12.	Identify rainfall-runoff events where runoff peak magnitude exceeds 80 percentile daily flow and within 3 years post-fire - 12_PFFs_80post3yr.py
	Inputs: 
		12In_ArroyoSeco_RainfallRunoffEvents.csv
	Outputs:
		12Out_ArroyoSeco_PFFs_80post3.csv
13.	Identify 5 largest post-fire floods, identify paired storms for each flood - 13_PairedStorms.py
	Inputs:
		13In_ArroyoSeco_PFFs_80post3.csv
		13In_ArroyoSeco_RainfallRunoffEvents.csv
	Outputs:
		13Out_ArroyoSeco_PFFs.csv
		13Out_ArroyoSeco_PostFloods_StormX.csv #where X is the PFF number, only included example for one identified PFF
14.	Calculate percentiles of PFF storm metrics - 14_PFF_percentiles.py
	Inputs:
		14In_ArroyoSeco_AllStorms.csv
		14In_ArroyoSeco_PFFs.csv
		14In_ArroyoSeco_RainfallRunoffEvents.csv
	Outputs:
		14Out_ArroyoSeco_PFF_percentiles.csv
15.	Calculate post-fire flood runoff peak multipliers (post/paired) - 15_Multipliers.py
	Inputs:
		15In_ArroyoSeco_PFF_Storm0.csv
		15In_ArroyoSeco_PFFs.csv
	Outputs:
		15Out_ArroyoSeco_Multipliers.csv