Drought Metrics

SSI

SSI dataclass

SSI(dist: Union[str, ContinuousDist] = 'gamma', timescale: int = 12, fit_freq: str | None = None, fit_window: int = 0, prob_zero: bool = False, normal_scores_transform: bool = False, agg_func: Literal['sum', 'mean'] = 'sum')

Independent SSI calculator that separates training and scoring phases.

Uses the original spei.SI class internally for distribution fitting, then applies those fitted distributions to new data.

Parameters:

Name	Type	Description	Default
dist	str or ContinuousDist	Probability distribution for SSI calculation. Can be string name: 'gamma', 'lognorm', 'pearson3', 'weibull', etc. Or scipy distribution object.	'gamma'
timescale	int	Rolling window size for temporal aggregation.	12
fit_freq	str	Frequency for seasonal fitting ('M' for monthly, 'D' for daily). If None, fits single distribution to entire dataset.	None
fit_window	int	Moving window for distribution fitting.	0
prob_zero	bool	Whether to handle zero probability separately.	False
normal_scores_transform	bool	Whether to use normal scores transform instead of parametric fitting.	False
agg_func	(sum, mean)	Aggregation function for rolling window.	'sum'

Examples:

>>> # Basic usage with default gamma distribution
>>> ssi = SSI()
>>> ssi.fit(training_data)
>>> ssi_values = ssi.transform(new_data)

>>> # Using different distribution
>>> ssi = SSI(dist='lognorm', timescale=6)
>>> ssi.fit(training_data)

fitted_distributions property

fitted_distributions: dict

Access to fitted distributions (read-only).

fit

fit(training_series: Series) -> SSI

Fit distributions using training data.

Parameters:

Name	Type	Description	Default
training_series	Series	Time series data for fitting distributions	required

Returns:

Type	Description
SSI	Self for method chaining

transform

transform(new_series: Series) -> Series

Calculate SSI values for new data using fitted distributions.

Parameters:

Name	Type	Description	Default
new_series	Series	New time series data to transform	required

Returns:

Type	Description
Series	SSI values for the new series

fit_transform

fit_transform(training_series: Series, new_series: Series = None) -> Series

Fit on training data and transform new data in one step.

Parameters:

Name	Type	Description	Default
training_series	Series	Data for fitting distributions	required
new_series	Series	Data to transform. If None, transforms training_series.	None

Returns:

Type	Description
Series	SSI values

get_training_ssi

get_training_ssi() -> Series

Get SSI values for the training data.

Returns:

Type	Description
Series	SSI values for training data

---

Functions

get_drought_metrics

get_drought_metrics(ssi, end_drought_threshold_months=3)

Calculate drought metrics from standardized supply index (SSI) time series.

Parameters:

Name	Type	Description	Default
ssi	Series	Time series of standardized supply index values	required
end_drought_threshold_months	int	Number of consecutive days with SSI > 0 required to end a critical drought	3

Returns:

Type	Description
DataFrame	DataFrame containing drought metrics for each identified drought event

---

Distribution Utilities

distributions

Distribution management for drought analysis.

This module provides utilities for working with probability distributions in drought analysis, including a registry of common distributions and helper functions for distribution selection.

get_distribution

get_distribution(name: Union[str, ContinuousDist]) -> ContinuousDist

Get a distribution object by name or pass through if already a distribution.

Parameters:

Name	Type	Description	Default
name	str or ContinuousDist	Distribution name (e.g., 'gamma') or scipy distribution object.	required

Returns:

Type	Description
ContinuousDist	Scipy continuous distribution object.

Raises:

Type	Description
ValueError	If distribution name is not recognized.

Examples:

>>> dist = get_distribution('gamma')
>>> dist = get_distribution(scs.gamma)  # Pass through

list_distributions

list_distributions(include_info: bool = False) -> Union[List[str], Dict[str, Dict[str, str]]]

List available distributions for drought analysis.

Parameters:

Name	Type	Description	Default
include_info	bool	If True, returns detailed information about each distribution. If False, returns only distribution names.	False

Returns:

Type	Description
list or dict	List of distribution names or dict with detailed information.

Examples:

>>> distributions = list_distributions()
>>> print(distributions)
['gamma', 'lognorm', 'pearson3', ...]

>>> info = list_distributions(include_info=True)
>>> print(info['gamma']['description'])

get_distribution_info

get_distribution_info(name: str) -> Dict[str, str]

Get detailed information about a specific distribution.

Parameters:

Name	Type	Description	Default
name	str	Distribution name.	required

Returns:

Type	Description
dict	Dictionary with keys: name, description, best_for, parameters.

Raises:

Type	Description
ValueError	If distribution name is not recognized.

Examples:

>>> info = get_distribution_info('gamma')
>>> print(info['description'])

print_distribution_guide

print_distribution_guide()

Print a user-friendly guide to available distributions.

Examples:

>>> print_distribution_guide()

validate_distribution

validate_distribution(dist: Union[str, ContinuousDist]) -> ContinuousDist

Validate and normalize a distribution specification.

Parameters:

Name	Type	Description	Default
dist	str or ContinuousDist	Distribution name or scipy distribution object.	required

Returns:

Type	Description
ContinuousDist	Validated scipy distribution object.

Raises:

Type	Description
ValueError	If distribution is invalid.
TypeError	If distribution type is not supported.

Examples:

>>> dist = validate_distribution('gamma')
>>> dist = validate_distribution(scs.lognorm)