Module: AA.analytical

Runs the analytical stage for a given country (<ISO>) and indicator (SPI or DRYSPELL).

Usage

Pixi

pixi run python -m AA.analytical <ISO> <SPI/DRYSPELL>

Docker

docker run --rm \
  -e AWS_ACCESS_KEY_ID=${AWS_ACCESS_KEY_ID} \
  -e AWS_SECRET_ACCESS_KEY=${AWS_SECRET_ACCESS_KEY} \
  -e AWS_SESSION_TOKEN=${AWS_SESSION_TOKEN} \
  aa-runner:latest \
  python -m AA.analytical <ISO> <SPI/DRYSPELL> \
  --data-path <DATA_PATH> --output-path <OUTPUT_PATH>

Arguments

• <ISO>: 3-letter ISO code (e.g., KEN, ZMB).
• <SPI/DRYSPELL>: Which analytical track to run.

Configuration

Reads from config/{iso}_config.yml. See Configuration.

Notes

• Make sure HDC credentials are configured. See HDC Credentials.
• Data paths can be overridden via --data-path and --output-path in Docker.

calculate_forecast_probabilities(forecasts, observations, params, period_months, issue)

Calculate probabilities with and without bias correction, and extract numerical and categorical observations

Parameters:

Name	Type	Description	Default
forecasts		xarray.Dataset, rainfall forecasts dataset for specific issue month	required
observations		xarray.Dataset, rainfall observations dataset	required
params		Params, parameters class	required
period_months		tuple, months of index period (eg (10, 11))	required
issue		str, issue month of forecasts to analyse	required

Returns: probabilities: xarray.Dataset, raw probabilities at the pixel level for specified period and issue month probabilities_bc: xarray.Dataset, bias-corrected probabilities at the pixel level for specified period and issue month anomaly_obs: xarray.Dataset, numerical observations at the pixel level for specified period levels_obs: xarray.Dataset, categorical observations at the pixel level for specified index

run_issue_verification(forecasts, observations, issue, params, area)

Run analytical / verification pipeline for one issue month

Parameters:

Name	Type	Description	Default
observations		xarray.Dataset, rainfall observations dataset	required
issue		str, issue month of forecasts to analyse	required
params		Params, parameters class	required
area		hip.analysis.AnalysisArea object with aoi information	required

Returns: fbf_issue: pandas.DataFrame, dataframe with roc scores for all indexes, districts, categories and a specified issue month

verify_index_across_districts(forecasts, observations, params, area, period_name, period_months, issue)

Run analytical / verification pipeline for a single issue month and a single index (period)

Parameters:

Name	Type	Description	Default
forecasts		xarray.Dataset, rainfall forecasts dataset for specific issue month	required
observations		xarray.Dataset, rainfall observations dataset	required
params		Params, parameters class	required
area		hip.analysis.AnalysisArea object with aoi information	required
period_name		str, name of index period (eg "ON")	required
period_months		tuple, months of index period (eg (10, 11))	required

Returns: fbf_issue_df: pandas.DataFrame, dataframe with roc scores for all districts, categories and specified issue month / period