Metadata-Version: 2.4
Name: sadc-cft
Version: 6.0.6
Summary: Climate Forecasting Tool package to support generation of seasonal forecast by SADC CSC and National Met Services
Author-email: Piotr Wolski <wolski@csag.uct.ac.za>, Sunshine Gamedze <sgamedze@sadc.int>
License-Expression: MIT
Project-URL: Homepage, https://github.com/sadccsc/cft
Requires-Python: >=3.12
Description-Content-Type: text/markdown
Requires-Dist: numpy
Requires-Dist: pandas
Requires-Dist: geopandas
Requires-Dist: xarray
Requires-Dist: dask
Requires-Dist: rioxarray
Requires-Dist: scipy
Requires-Dist: shapely
Requires-Dist: rasterio
Requires-Dist: rasterstats
Requires-Dist: scikit-learn
Requires-Dist: statsmodels
Requires-Dist: netCDF4
Requires-Dist: cftime
Requires-Dist: geojson
Requires-Dist: descartes
Requires-Dist: geocube
Requires-Dist: GDAL
Requires-Dist: requests
Requires-Dist: matplotlib
Requires-Dist: cartopy
Requires-Dist: PyQt5
Requires-Dist: cdsapi

# cft
Climate Forecasting Toolbox


INTRODUCTION
------------
The Climate Forecasting Toolbox is a Python based tool for statistical climate forecasting. 

CREDITS
=======
Piotr Wolski (wolski@csag.uct.ac.za)
Sunshine Gamedze (sgamedze@sadc.int)

Oringinal developer (2017-2022):
Thembani Moitlhobogi



Development history
=======
Current version is developed under funding from First Rains project.

Development in 2023-2025 has been funded under SADC CSC ClimSA project.

In November 2022, the software has been ported from the original personal github repo https://github.com/taxmanyana/cft to https://github.com/sadc-csc/cft

Original version developed during 2010-2017 under funding from SADC CSC project SARCIS-DR.


SOURCE CODE
------------
From version 6.0.0, the CFT code is available as pip package https://pypi.org/project/sadc-cft/
From version 4.0.0, the CFT code is maintained at:  https://github.com/sadc-csc


Basic functionality of v5 and later:
------------
Five modules:
data download (including from CDS from v6.0)
forecast (updated in v5)
zoning (since v3)
verification (since v4)
synthesis (since v4)

Download module
------------
Downloads following data types from sources:

1) gridded predictors from CDS:
- SST, GPH, rainfall, air temperature from all models (save UKMO one) available on CDS in July 2026.
2) gridded predictand from CDS:
- rainfall and temperatures from CDS ERA5 dataset
3) gridded predictors from IRIDL (legacy):
- SST
4) gridded predictand from IRIDL (legacy):
- CHIPRS precipitation
5) gridded forecast and hindcast data from IRIDL (legacy):
- SST, precipitation and geopotential height for three models from NMME that were operational in August 2025
6) teleconnection indices from JMA (because they have lowest latency)
- IOD, Nino3, Nino4

Data are downloaded to user-selected directory
All data are converted to a format ingestible by CFT


Forecast module
------------
Takes two types of data as predictand:
    - gridded data
    - station data

Takes three types of data as predictor:
    - observed teleconnection indices
    - observed gridded data (SST)
    - forecasted gridded fields (not yet implemented)

Produces forecast for:
    - grid - if predictand is gridded
    - zones - if predictand is either gridded or station data, with spatial aggregation of data into zonal average, and generation of forecast for that zonal average
    - points - if predictand is station data

Allows three pre-processing approaches:
    - PCR - gridded predictor is processed to derive Principal Components (aka EOFs), and these are used in a statistical model as predictors. This can be applied to gridded predictor, and any type of predictand.
    - CCA - canonical components are derived from predictor and predictand data
    - no preprocessing - this can be applied to gridded predictor and any type of predictand.
implements the following statistical models:
    - OLS regression
    - MLP regression
    - Decision trees
    - Random Forest
    - Lasso regression
    - Ridge regression

Two types of forecast are calculated:
    - deterministic forecast
    - tercile probabilistic forecast

Tercile forecast is also presented as a 4-category forecast, where normal category is split into normal-to-above and normal-to-below. No probabilities are allocated to these two categories. 

All forecasts are cross-validated. 

Two cross-validation approaches are possible:
    - leave-one-out
    - k-fold

Skill indices are calculated through cross-validation from out-of-fold predictions. The following skill indices are included:
    - ROC score (above, below, normal) 
    - RPSS
    - correlation
    - Heidke skill score for highest probability category
    - ignorance score 
    - reliability score
    - Brier skill score
    - 2AFC

Probabilistic forecast are calibrated using quantile mapping approach:
    -  quantile transform is developed based on overlapping hindcast and observed predictand data 
    - transform is applied to hindcast and forecast data



Other modules - zoning, verification, synthesis
------------

In v5.1 zoning module has been adapted to run under v5 environment.

Other packages were not updated in v5.0 , thus not described here explicitly


Requirements:
------------
python 3.12 
python packages:
    # scientific / data stack - used throughout functions_forecast.py
    "numpy",
    "pandas",
    "geopandas",
    "xarray",
    "rioxarray",
    "scipy",
    "shapely",
    "rasterio",
    "rasterstats",
    "scikit-learn",
    "statsmodels",
    "netCDF4",
    "cftime",
    "geojson",
    "descartes",
    "geocube",
    "GDAL",          # provides the 'osgeo' module (zoning.py's ogr usage)
    "requests",

    # plotting / mapping
    "matplotlib",
    "cartopy",

    # GUI
    "PyQt5",

    #CDS api
    "cdsapi",

Installation
------------

Python environment
=======

Installation should be done into a dedicated Python environment.

This requires installation of either:
    - Ancaconda framework (bulky, >1GB) https://www.anaconda.com/download/success
    - Miniforge (installs both Conda and Mamba) - https://github.com/conda-forge/miniforge
    - Micromamba (installs Mamba - lightweight, but for advanced users) https://mamba.readthedocs.io/en/latest/installation/micromamba-installation.html


Once installed, create a python enviroment e.g.

mamba create --name cft-env python=3.12

note - it is recommended that python 3.12 is used for version 6.0


Prerequisites
=======
The sadc-cft package is installed with pip, but pip does not handle GDAL libraries well. These have to be preinstalled using conda or mamba:

(one has to activate the cft environment first, of course)
mamba activate cft-env

(and then:)
mamba install -c conda-forge gdal=3.13.2

Installation with pip
=======
Once gdal is installed, sadc-cft package is installed using pip.

pip install sadc-cft


confirm that installation is complete:

python cft


How to use - GUI
------------

The main GUI of sadc-cft can be invoked as follows:

(one has to activate the cft environment first, of course)
mamba activate cft-env

(and then simply:)
cft

(or:)

python -m cft

Individual components (forecast, verification, synthesis, zoning and download) can be started directly as follows:

>forecast-tool

(or:)

python -m cft.forecast


How to use - without GUI
------------

individual packages can be invoked in Python without GUI. 

from cft.forecast import computeModelNoGui

and then run as follows:

computeModelNoGui(config)

where config is a dictionary containing forecast model configuration entries e.g. 

config={'rootDir': '../test',
 'predictorYear': 2026,
 'predictorMonth': 'Jun',
 'fcstTargetSeas': 'Aug-Oct',
 'fcstTargetYear': 2026,
 'climEndYr': 2015,
 'climStartYr': 1994,
 'predictorExtents': {'minLon': -180.0,
  'maxLon': 180.0,
  'minLat': -60.0,
  'maxLat': 60.0},
 'predictorFileName': '/work/code/csc/cft/test/GPH850_System9_CDS_Jun_s300s200e150e250_1981-2026.nc',
 'predictorVar': 'z',
 'predictorCode': 'z',
 'crossval': 'KF',
 'preproc': 'PCR',
 'regression': 'OLS',
 'timeAggregation': 'mean',
 'predictandFileName': '../test/PRCP_CHIRPSp25_IRIDL_Aug-Oct_s340s200e150e250_1981-2025.nc',
 'predictandVar': 'prcp',
 'predictandCategory': 'temperature',
 'predictandMissingValue': '-999',
 'zonesFile': None,
 'zonesAttribute': 'Name',
 'zonesAggregate': False,
 'regridPredictand': False,
 'overlayFile': '../gis/sadc/gadm41_ZAF_1.json'
}

(more to follow...)

