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

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 modifications and enhancements.

Description of data:
-------------------- 
- The main directory has 2 sub-directories: 1- FD_Events, 2-Composites, and 1 single .csv file: LonLat.csv.
- Note! Each sub-direcory has 2 more subdirecories: 1-CSV, and 2-NetCDF
for the convenience of the user any of the 2 formats can be used.

1-FD_Events: It contains the detected flash drought events as described in (Osman et al. 2021) with some modifications as following:
	- A flash drought is identified at 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: It contains some associated atmospheric standardized anomalies (derived from ERA5 dataset) at onset, pre-onset 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
		PRESS:	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.
		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.

- The NetCDF direcories are created using a Pyhthon script developed by Mahdad Talebpour, that can be accessed from: https://github.com/mahdadt/SMVI_GFD_Conversion/


----------------------------------------------
### Sample snippet to read csv 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, M. Talebpour (2024). SMVI Global Flash Droughts Dataset. HydroShare. https://doi.org/10.4211/hs.b6d1d853b82247e1aeaf907ac254c99e . http://www.hydroshare.org/resource/b6d1d853b82247e1aeaf907ac254c99e

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.