sadc-cft 6.0.2__tar.gz

sadc_cft-6.0.2/PKG-INFO

@@ -0,0 +1,306 @@
+Metadata-Version: 2.4
+Name: sadc-cft
+Version: 6.0.2
+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: 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...)
+

sadc_cft-6.0.2/README.md

@@ -0,0 +1,274 @@
+# 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...)
+

sadc_cft-6.0.2/pyproject.toml

@@ -0,0 +1,74 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "sadc-cft"
+version = "6.0.2"
+description = "Climate Forecasting Tool package to support generation of seasonal forecast by SADC CSC and National Met Services"
+readme = "README.md"
+requires-python = ">=3.12"
+license = "MIT"
+authors=[
+{name="Piotr Wolski", email="wolski@csag.uct.ac.za"},
+{name="Sunshine Gamedze",email="sgamedze@sadc.int"}
+]
+dependencies = [
+    # 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",
+]
+
+[project.optional-dependencies]
+ 
+
+[project.urls]
+Homepage = "https://github.com/sadccsc/cft"
+
+[project.scripts]
+cft = "cft.__main__:main"
+forecast-tool = "cft.forecast:main"
+download-tool = "cft.download:main"
+synthesis-tool = "cft.synthesis:main"
+verification-tool = "cft.verification:main"
+zoning-tool = "cft.zoning:main"
+
+
+# [project.scripts] or [project.gui-scripts] 
+# the firs will show terminal window alongside each app on Windows. 
+# No difference on Mac/Linux.
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+# adjust these globs once you know the real folder layout -
+# e.g. if functions_forecast.py's "dictionaries" folder actually lives
+# under cft/ rather than cft/functions/, move the entry accordingly
+cft = ["*.ui", "dictionaries/*.json", "*.ico"]

sadc_cft-6.0.2/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+