TopoPyScale

Binder Notebooks Examples:

TopoPyScale

Python version of Toposcale packaged as a Pypi library. Toposcale is an original idea of Joel Fiddes to perform topography-based downscaling of climate data to the hillslope scale.

Documentation avalaible: https://topopyscale.readthedocs.io

References:

• Filhol et al., (2023). TopoPyScale: A Python Package for Hillslope Climate Downscaling. Journal of Open Source Software, 8(86), 5059, https://doi.org/10.21105/joss.05059

And the original method it relies on:

• Fiddes, J. and Gruber, S.: TopoSCALE v.1.0: downscaling gridded climate data in complex terrain, Geosci. Model Dev., 7, 387–405, https://doi.org/10.5194/gmd-7-387-2014, 2014.
• Fiddes, J. and Gruber, S.: TopoSUB: a tool for efficient large area numerical modelling in complex topography at sub-grid scales, Geosci. Model Dev., 5, 1245–1257, https://doi.org/10.5194/gmd-5-1245-2012, 2012.

Kristoffer Aalstad has a Matlab implementation: https://github.com/krisaalstad/TopoLAB

Contribution Workflow

1. All contribution welcome!
2. Found a bug -> Check the issue page. If you have a solution let us know.
3. No idea on moving furhter -> then create a new issue
4. Wanna develop a new feature/idea? -> create a new branch. Go wild. Merge with main branch when accomplished.
5. Create release version when significant improvements and bug fixes have been done. Coordinate with others on Discussions

Create a new release: Follow procedure and conventions described in: https://www.youtube.com/watch?v=Ob9llA_QhQY

Our forum is now on Github Discussions. Come visit!

Need help

Please reach out in case you need help in approaching your problem with TopoPyScale. We always appreciate to know the various usages people find to TopoPyScale. And we also welcome academic collaboration.

Design

1. Inputs
   • Climate data from reanalysis (ERA5, etc)
   • Climate data from future projections (CORDEX) (TBD)
   • DEM from local source, or fetch from public repository: SRTM, ArcticDEM, ASTER
2. Run TopoScale
   • compute derived values (from DEM)
   • toposcale (k-mean clustering)
   • interpolation (bilinear, inverse square dist.)
3. Output
   • Cryogrid format
   • FSM format
   • CROCUS format
   • Snowmodel format
   • basic netcfd
   • For each method, have the choice to output either the abstract cluster points, or the gridded product after interpolation
4. Validation toolset
   • validation to local observation timeseries
   • plotting
5. Gap filling algorithm
   • random forest temporal gap filling (TBD)

Validation (4) and Gap filling (4) are future implementation.

Installation

We have now added an environments.yml file to handle versions of depencencies that are tested with the current codebase, to use this run:

conda env create -f environment.yml

Alternatively you can follow this method for dependencies (to be deprecated):

conda create -n downscaling python ipython
conda activate downscaling

# Recomended way to install dependencies:
conda install -c conda-forge xarray matplotlib scikit-learn pandas numpy netcdf4 h5netcdf rasterio pyproj dask rioxarray
# install forked version of Topocalc compatible with Python >3.9 (tested with 3.13)
pip install pip@git+https://github.com/ArcticSnow/topocalc

Then install the code:

# OPTION 1 (Pypi release):
pip install TopoPyScale

# OPTION 2 (development):
cd github  # navigate to where you want to clone TopoPyScale
git clone [email protected]:ArcticSnow/TopoPyScale.git
pip install -e TopoPyScale    #install a development version

#----------------------------------------------------------
#            OPTIONAL: if using jupyter lab
# add this new Python kernel to your jupyter lab PATH
python -m ipykernel install --user --name downscaling

# Tool for generating documentation from code docstring
pip install lazydocs

Then you need to setup your cdsapi with the Copernicus API key system. Follow this tutorial after creating an account with Copernicus. On Linux, create a file nano ~/.cdsapirc with inside:

url: https://cds.climate.copernicus.eu/api/v2
key: {uid}:{api-key}

Basic usage

1. Setup your Python environment
2. Create your project directory
3. Configure the file config.ini to fit your problem (see config.yml for an example)
4. Run TopoPyScale

import pandas as pd
from TopoPyScale import topoclass as tc
from matplotlib import pyplot as plt

# ========= STEP 1 ==========
# Load Configuration
config_file = './config.yml'
mp = tc.Topoclass(config_file)
# Compute parameters of the DEM (slope, aspect, sky view factor)

mp.get_era5()
mp.compute_dem_param()

# ========== STEP 2 ===========
# Extract DEM parameters for points of interest (centroids or physical points)

mp.extract_topo_param()

# ----- Option 1:
# Compute clustering of the input DEM and extract cluster centroids
#mp.extract_dem_cluster_param()
# plot clusters
#mp.toposub.plot_clusters_map()
# plot sky view factor
#mp.toposub.plot_clusters_map(var='svf', cmap=plt.cm.viridis)

# ------ Option 2:
# inidicate in the config file the .csv file containing a list of point coordinates (!!! must same coordinate system as DEM !!!)
#mp.extract_pts_param(method='linear',index_col=0)

# ========= STEP 3 ==========
# compute solar geometry and horizon angles
mp.compute_solar_geometry()
mp.compute_horizon()

# ========= STEP 4 ==========
# Perform the downscaling
mp.downscale_climate()

# ========= STEP 5 ==========
# explore the downscaled dataset. For instance the temperature difference between each point and the first one
(mp.downscaled_pts.t-mp.downscaled_pts.t.isel(point_id=0)).plot()
plt.show()

# ========= STEP 6 ==========
# Export output to desired format
mp.to_netcdf()

TopoClass will create a file structure in the project folder (see below). TopoPyScale assumes you have a DEM in GeoTiFF, and a set of climate data in netcdf (following ERA5 variable conventions). TopoPyScale can easier segment the DEM using clustering (e.g. K-mean), or a list of predefined point coordinates in pts_list.csv can be provided. Make sure all parameters in config.ini are correct.

my_project/
    ├── inputs/
        ├── dem/ 
            ├── my_dem.tif
            └── pts_list.csv  (optional)
        └── climate/
            └── yearly/
                ├── PLEV*.nc
                └── SURF*.nc
    ├── outputs/
    └── config.ini