Package: topopyscale
Binder Notebooks Examples:TopoPyScalePython 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.ioReferences: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.05059And 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/TopoLABContribution WorkflowPlease follow these simple rules:a bug -> fix it!an idea or a bug you cannot fix? -> create a newissueif none doesn't already exist. If one exist, then add material to it.wanna develop a new feature/idea? -> create a new branch. Go wild. Merge with main branch when accomplished.Create release version when significant improvements and bug fixes have been done. Coordinate with others onDiscussionsCreate a new release:Follow procedure and conventions described in:https://www.youtube.com/watch?v=Ob9llA_QhQYOur forum is now onGithub Discussions. Come visit!DesignInputsClimate data from reanalysis (ERA5, etc)Climate data from future projections (CORDEX) (TBD)DEM from local source, or fetch from public repository: SRTM, ArcticDEM, ASTERRun TopoScalecompute derived values (from DEM)toposcale (k-mean clustering)interpolation (bilinear, inverse square dist.)OutputCryogrid formatFSM formatCROCUS formatSnowmodel formatbasic netcfdFor each method, have the choice to output either the abstract cluster points, or the gridded product after interpolationValidation toolsetvalidation to local observation timeseriesplottingGap filling algorithmrandom forest temporal gap filling (TBD)Validation (4) and Gap filling (4) are future implementation.InstallationWe 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.ymlAlternatively you can follow this method for dependencies (to be deprecated):condacreate-ndownscalingpython=3.9ipython
condaactivatedownscaling# Recomended way to install dependencies:condainstall-cconda-forgexarraymatplotlibscikit-learnpandasnumpynetcdf4h5netcdfrasteriopyprojdaskrioxarrayThen 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 lazydocsThen you need to setup yourcdsapiwith the Copernicus API key system. Followthis tutorialafter creating an account withCopernicus. On Linux, create a filenano ~/.cdsapircwith inside:url: https://cds.climate.copernicus.eu/api/v2
key: {uid}:{api-key}Basic usageSetup your Python environmentCreate your project directoryConfigure the fileconfig.inito fit your problem (seeconfig.ymlfor an example)Run TopoPyScaleimportpandasaspdfromTopoPyScaleimporttopoclassastcfrommatplotlibimportpyplotasplt# ========= STEP 1 ==========# Load Configurationconfig_file='./config.yml'mp=tc.Topoclass(config_file)# Compute parameters of the DEM (slope, aspect, sky view factor)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 anglesmp.compute_solar_geometry()mp.compute_horizon()# ========= STEP 4 ==========# Perform the downscalingmp.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 formatmp.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 inpts_list.csvcan be provided. Make sure all parameters inconfig.iniare correct.my_project/
    ├── inputs/
        ├── dem/ 
            ├── my_dem.tif
            └── pts_list.csv  (optional)
        └── climate/
            ├── PLEV*.nc
            └── SURF*.nc
    ├── outputs/
    └── config.ini