#########################################
##Soil Moisture Volatility Index (SMVI)##
#########################################
############Global Inventory#############
######################################### 
###Corresponding Author: Mahmoud Osman###
######Email-1: mahosman01@gmail.com######
######Emain-2: mahmoud.osman@jhu.edu#####
#######Last Update: February 2024########
#########################################

SMVI data is in this inventory is based on the published studies of flash droughts over the contiguous United States (Osman et al. 2021 & 2022) with slight modifations and enhancements.

Description of data:
-------------------- 
- The main directory has 2 sub-directories: 1- FD_Events, 2-Composites, and 1 single .csv file: LonLat.csv.

1-FD_Events: Contains the detected flash drought events as described in (Osman et al. 2021) with some modifications as following:
	- A flash drought is idenified in a gridpoint when the following conditions are fulfilled:
		1- The 5-day running average (1-Pentad) RZSM fall below the 20-days running average RZSM.
		2- The crossover occurs below the 20th percentile RZSM of the corresponding day's long-term record.
		3- The previous conditions are persistent for at least 4-pentads period.
		4- The grid-point's average temperature during the detected period is more than Zero C (273 K).
		5- The grid-point's computed average Bowen's ratio during the detected period is between 0.2 and 7.
	
	- In this version multiple flash drought events are allowed to be detected up to 6 events per year, sorted by onset date of event
	- Events 15 days or less apart are considered to be 1 event, and merged into one.
	- Severity of the event is quantified according basedon RZSM deficit during the identified flash drought event according to 	Eq-1 in Osman et al. (2022).
	
	- File header goes as:
		fstdate#:	Date of onset of event #n
		lstdate#:	Date of recovery (end of rapid intensifiaction) of event #n
		SV#:		Severity of event #n
		VEGID:		Landcover class number according to GLDAS dominant vegetation type in CLSMF2.5.


2-Composites: Contains some associated atmospheric standardized anomalies (derived from ERA5 dataset) at onset, pre-set and recovery stages as discussed in (Osman et. al 2022).
	- There is a separate file for each variable/year/event#.
	- the file naming goes as: SMVI_GLDAS_E[event#]_[variable name]_[Year].csv
	- Variables are: 
		ARAIN:	Total Liquid Precipitation
		EVP:	actual evapotranspiration
		PRES:	surface pressure
		RZSM:	root-zone soil moisture
		TMP:	2-m above ground temperature
		VPD:	vapor pressure deficit
		WS:	10-m above ground wind speed
		PEVPR:	potential evapotranspiration
	- File header goes as:
		On01:	The 5-days average (1-pentad) value for the variable's anomaly 1-pentad (5-days) before Onset date.
		On02:	The 5-days average (1-pentad) value for the variable's anomaly 2-pentads (10-days) before Onset date.
		On03:	The 5-days average (1-pentad) value for the variable's anomaly 3-pentads (15-days) before Onset date.
		On00:	The 5-days average (1-pentad) value for the variable's anomaly at "Onset" date.
		Re00:	The 5-days average (1-pentad) value for the variable's anomaly at "Recovery" date.
		Re01:	The 5-days average (1-pentad) value for the variable's anomaly 1-pentad (5-days) after Recovery date.
		Re02:	The 5-days average (1-pentad) value for the variable's anomaly 2-pentads (10-days) after Recovery date.
		Re03:	The 5-days average (1-pentad) value for the variable's anomaly 3-pentads (15-days) after Recovery date.
		On3Pn:	The 15-days average (3-pentads) value for the variable's anomaly 3-pentad (15-days) back from Onset date (i.e. average from Onset to Onset-15d).

- LonLat.csv: contains the corresponding Longitude and Latitude for each row in all files.

- Sample snippet to read data in R:
	#Load Libraries
	list.of.packages <- c("maps","maptools","ncdf4","data.table","RColorBrewer","Cairo",'latticeExtra','lattice')
	lapply(list.of.packages, library, character.only = TRUE)
	color_palette <- c("dodgerblue2", "#E31A1C","green4","#6A3D9A","#FF7F00", "gold1", "skyblue2", "#FB9A99", "palegreen2","#CAB2D6", "#FDBF6F", "gray70")
	nlon <- 1440		#Longitude size (as GLDAS)
	nlat <- 600		#Latitude size (as GLDAS)
	YYYY <- 2017		#Selected year
	n_reg <- nlon * nlat
	csv_in<- fread(file= paste(OUT_DIR,'/FD_Events/SMVI_GLDAS_Summ_table_SMVI_',YYYY,'_n',n_reg,".csv",sep=''))
	fd_YY <- as.data.frame(csv_in[,'fstdate1'],colClasses = c("date"))  #just selecting the a vector that contains the date of the first deteceted FD event to plot
	fd_YY_Mon <- month(fd_YY[,])
	month_matrix <- array(fd_YY_Mon, dim = c(nlon, nlat))
	var_MAT <- array(fd_YY, dim = c(nlon, nlat))    #Converts the vector to matrix of size nlon x nlat
	month_names <- month.abb
	wld <- maps::map('world',plot=F)
	wld <- data.frame(lon=wld$x, lat=wld$y)
	Plt<-levelplot(month_matrix, row.values = lon, column.values = lat, xlab = 'Longitude', ylab = 'Latitude',
		 ylim = c(-60, 90), xlim = c(-180, 180), main = paste(YYYY), col.regions = color_palette[1:12],
		 at = seq(0, 13), colorkey = list(at = seq(1, 13), labels = list(at = seq(1.5, 12.5), labels = month_names)), 
		scales = list(x = list(at = seq(-180, 180, by = 20)),y = list(at = seq(-60, 90, by = 20))),
		 panel.grid = list(col = "lightgray", lty = "dotted"))+
		 xyplot(lat ~ lon, wld, type='l', lty=1, lwd=1, col='black')

	png(filename=paste("SMVI_GLDAS_E1_OnsetMon_",YYYY,".png",sep=''), width = 7000, height = 3500,res=300,type='cairo')
		print(Plt)
		dev.off()
	#image(month_matrix)	#Or comment the "Plt" line and uncomment this to do a quick visualization for data
	

References:
-----------
Osman, M., B. Zaitchik, J. Otkin, M. Anderson (2024). SMVI Global Flash Droughts Dataset. HydroShare. https://doi.org/10.4211/hs.cd719845742049a199424555d160fa24. http://www.hydroshare.org/resource/cd719845742049a199424555d160fa24.

Osman, M., Zaitchik, B. F., Badr, H. S., Christian, J. I., Tadesse, T., Otkin, J. A., & Anderson, M. C. (2021). Flash drought onset over the contiguous United States: sensitivity of inventories and trends to quantitative definitions. Hydrology and Earth System Sciences, 25(2), 565–581. https://doi.org/10.5194/hess-25-565-2021. 

Osman, M., Zaitchik, B. F., Badr, H. S., Otkin, J., Zhong, Y., Lorenz, D., et al. (2022). Diagnostic Classification of Flash Drought Events Reveals Distinct Classes of Forcings and Impacts. Journal of Hydrometeorology, 23(2), 275–289. https://doi.org/10.1175/JHM-D-21-0134.1.