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!

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):

```bash 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 git@github.com: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

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

========= STEP 1 ==========

Load Configuration

configfile = './config.yml' mp = tc.Topoclass(configfile)

Compute parameters of the DEM (slope, aspect, sky view factor)

mp.getera5() mp.computedem_param()

========== STEP 2 ===========

Extract DEM parameters for points of interest (centroids or physical points)

mp.extracttopoparam()

----- Option 1:

Compute clustering of the input DEM and extract cluster centroids

mp.extractdemcluster_param()

plot clusters

mp.toposub.plotclustersmap()

plot sky view factor

mp.toposub.plotclustersmap(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.extractptsparam(method='linear',index_col=0)

========= STEP 3 ==========

compute solar geometry and horizon angles

mp.computesolargeometry() 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.downscaledpts.t-mp.downscaledpts.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/ ├── PLEV*.nc └── SURF*.nc ├── outputs/ └── config.ini