Drought

Drought Analysis module

This module provides user facing analyses of drought characteristics.

cdi_extractions(qmulti, pop, crop, rangeland, gdfs, adms, threshold=750)

Extract population, cropland, and rangeland by drought class

Parameters:

Name	Type	Description	Default
qmulti	DataArray	xr.DataArray of unclassified CDI values, at 5 km resolution	required
pop	DataArray	xr.DataArray of total population, at 1 km resolution	required
crop	DataArray	xr.DataArray of crop mask, 1 for cropland and 0 for non-crop, 1 km resolution	required
rangeland	DataArray	xr.DataArray of rangeland mask, 1 for rangeland and 0 for non-rangeland, 1 km resolution	required
gdfs	list	list of Geopandas Geodataframes containing all countries/administrative levels to extract	required
adms	list	list of admin levels to extract; format ['adm0,'adm1','adm2']	required
threshold	int	int, default 750, of people per sq. km. to delineate urban and rural areas	750

Returns:

Name	Type	Description
dfs_r		list of dataframes for rural population extractions at each adm level
dfs_u		list of dataframes for urban population extractions at each adm level
dfs_crop		list of dataframes for cropland extractions at each adm level
dfs_range		list of dataframes for rangeland extractions at each adm level

classify_CDI(da, q_labels)

Classifies CDI values into severe, intense, moderate, and no drought classes

Parameters:

Name	Type	Description	Default
da	DataArray	xr.DataArray of population or crop/rangeland mask	required
q_labels		list of strs, labels corresponding to each drought class	required

Returns:

Name	Type	Description
q_classes		xr.DataSet, with dimension q_class for each drought class

compute_probabilities(rfh, levels)

Combine all forecast members to calculate forecast probabilities of rainfall amount or anomaly being below a certain threshold

Parameters:

Name	Type	Description	Default
rfh	DataArray | Dataset	xarray.DataArray or xarray.Dataset, rainfall forecasts dataset	required
levels	dict	dict, dict of level name (eg "Severe"), level threshold (eg -1 for standardized SPI)	required

Returns:

Type	Description
DataArray | Dataset	xr.DataArray or xr.Dataset: dataset with drought probabilities for one or more drought levels

concat_obs_levels(observations, levels)

Concatenate observations data (raw or anomaly) into categories based on predefined levels.

Parameters:

Name	Type	Description	Default
obs		xr.Dataset or xr.DataArray, observations data scaled by a factor 1000.	required
levels	dict	dict, dictionary containing category levels as keys and corresponding thresholds as values.	required

Returns:

Type	Description
DataArray | Dataset	xr.Dataset or xr.DataArray, concatenated observations data categorized based on predefined levels.

extractions_processing(counts, gdfs, q_classes, q_labels, adms, counts_type, reproject='ESRI:54034', threshold=None)

Population or crop/rangeland extraction for classified CDI

Parameters:

Name	Type	Description	Default
counts	DataArray	xr.DataArray of population or crop/rangeland mask	required
gdfs	list	list of Geopandas Geodataframes containing all countries/administrative levels to extract	required
q_classes	list	xr.DataSet, with dimension q_class for each drought class	required
q_labels	list	list of strs, labels corresponding to each drought class	required
adms	list	list of admin levels to extract; format ['adm0,'adm1','adm2']	required
counts_type	str	str,	required
reproject		str of a CRS, default "ESRI:54034" (world equal area projection) to reproject before doing zonal extractions	'ESRI:54034'
threshold		int, default None, of people per sq. km. to delineate urban and rural areas (only for population extractions)	None

Returns:

Name	Type	Description
dfs_		list of dataframes for extractions at each adm level

get_accumulation_periods(rfh, start_month=1, end_month=12, min_period_len=1, max_period_len=3)

Get all possible combinations of consecutive months within the wet season or the entire year

Parameters:

Name	Type	Description	Default
rfh	Dataset	xarray.Dataset, containing a time dimension that will be used to filter the time interval	required
start_month	int	int, start of season month if filtering is necessary	1
end_month	int	int, end of season month	12
min_period_len	int	int, default 1, minimum desired duration (in months) for periods to be selected	1
max_period_len	int	int, default 3, maximum desired duration (in months) for periods to be selected	3

Returns:

Name	Type	Description
accumulation_periods	dict	dict of period name (eg "ON", "DJF" etc), period months tuple (eg (10, 11), (12, 1, 2) etc)

prepare_dataset(indicator, area, begin, end)

Helper function for Qmulti/composite indices aggregating indicators to monthly time steps

TODO Likely this functionality can also be used elsewhere, so should consider if this can be made more general.

q_multi(area, begin=None, end=None, config={0: [['CHIRPS', 'r1h_dekad'], 0.4, 'last_dekad', False], 1: [['FAO', 'ET0'], 0.3, 'average', True], 2: [['AGERA5', 'soil_moist'], 0.3, 'last_dekad', False]}, cropmask=False, sos=None, include_active=True, ref_begin_date=datetime.date(1981, 1, 1), ref_end_date=None)

Calculate Qmulti composite drought index

Parameters:

Name	Type	Description	Default
area	AnalysisArea	AnalysisArea object, datetime_range for this should be the dates for CDI calculation if begin and end are not provided	required
begin	date | datetime	datetime.date to begin CDI calculation, if different from datetime_range start of area	None
end	date | datetime	datetime.date to end CDI calculation, if different from datetime_range end of area	None
config	dict[int, list]	dict of [satellite, datasource] and importance weight at minimum, plus optionally: aggregation method (eg.last dekad, average etc), and whether to invert variable (for example, a higher number for dryspells indicates greater drought so the variable must be inverted before combining with other variables)	{0: [['CHIRPS', 'r1h_dekad'], 0.4, 'last_dekad', False], 1: [['FAO', 'ET0'], 0.3, 'average', True], 2: [['AGERA5', 'soil_moist'], 0.3, 'last_dekad', False]}
cropmask	bool	bool of whether to mask dataset by JRC-ASAP croplands	False
sos	DataArray	xr.DataArray of pixel level season start and end dekads	None
include_active	bool	bool, default True, of whether to include the active season if False returns the most recently completed season before the end date	True
ref_begin_date	date | datetime	begin date of full time series for standardization of variables, default 1981-01-01	date(1981, 1, 1)
ref_end_date	date | datetime	end date of full time series for standardization of variables, default present date	None

Returns:

Name	Type	Description
Q_multi	DataArray	xy xr.dataarray of Qmulti aggregated over time
indicators_Qs	Dataset	xy xr.dataset of indices aggregated over time
monthly_Qs	DataArray	xyt xr.dataarray of monthly Qmulti

run_accumulation_index(rfh, aggregate, accumulation_period, season, forecasts=False)

Group dataset by seasonal period and accumulate rainfall values. Set nodata as nan to avoid NA skipping and wrong accumulation values

Parameters:

Name	Type	Description	Default
rfh	DataArray	xarray.DataArray, contains rainfall forecasts or observations	required
aggregate	Callable	callable, generally defines sum over time but can also be dryspell or other	required
accumulation_period	tuple	tuple, period months tuple (eg (10, 11), (12, 1, 2) etc)	required
season	tuple	tuple, season start month and season end month provided as a tuple (eg (10, 6))	required
forecasts	bool	bool, default False, if True then zeros are reset to nans to deal with empty members between 1993 and 2016	False

Returns:

Type	Description
DataArray	xarray.DataArray: accumulated rainfall dataset on the specified period (note: each time step is identified using the first year of the season. ex: ON, DJ and JFM 1996 will have the coordinate 01-01-1995)

run_bias_correction(forecasts, observations, year=2022, nearest_neighbours=0, enso=True)

Calculate bias-corrected rainfall forecasts for year of interest using Empirical Quantile Mapping method

Parameters:

Name	Type	Description	Default
forecasts	DataArray	xarray.DataArray, rainfall forecasts dataset	required
observations	DataArray	xarray.DataArray, rainfall observations dataset	required
year	int	int, year to bias correct	2022
nearest_neighbours	int	int, number of nearest neighbouring pixels to consider in quantile mapping (only for observations)	0
enso	bool	bool, default True, if True then only years of the same enso type as the year to bias-correct are selected in the reference time series	True

Returns:

Type	Description
DataArray	xarray.DataArray: bias-corrected rainfall forecasts for specified year

run_gamma_standardization(rfh, calibration_begin=None, calibration_end=None, members=False)

Calculate a standardized index for forecasts and observations based on fitted gamma distribution

Parameters:

Name	Type	Description	Default
rfh	DataArray	xarray.DataArray, rainfall dataset with values as integers	required
calibration_begin	datetime | None	datetime.datetime, start date for values of time series used to perform gammafit	None
calibration_end	datetime | None	datetime.datetime, end date for values of time series used to perform gammafit	None
members	bool	bool, default False, if True then members are melted in time dimension while spi function (or hdc-algo.gammafit does not handle different members in historical time series)	False

Returns:

Type	Description
DataArray	xr.DataArray: standardized rainfall dataset (note: for forecasts, the different members are in the time dimension and sorted ascending: yyyy-1-1 = 1st member, yyyy-2-20 = 50th member)