Skip to content

Welcome to TopoPyScale Documentation

TopoPyScale1 is a downscaling toolbox for global and regional climate model datasets, particularly relevant to mountain ranges, and hillslopes.

If you are here to use TopoPyScale, then head to the Quick Start page. Further configuration setup are explained in detail.

General Concept

TopoPyScale1 uses both climate model data and Digital Elevation Models (DEM) for correcting atmospheric state variables (e.g. temperature, pressure, humidity, etc). TopoPyScale provides tools to interpolate and correct such variables to be relevant locally given a topographical context.

Comparison of the surface temperature on January 1, 2020 at 12:00 UTC over the Southern Carpathians, Romania, in between ERA5 Surface product and the downscaled result using `TopoPyScale`. The DEM was segmented in 2000 clusters.

The most basic requirements of TopoPyScale is a DEM used to defined the spatial domain of interest as well as compute a number of morphometrics, and configuration file defining the temporal period, the downscaling methods and other parameters. In its current version, TopoPyScale includes the topoclass class that wraps all functionalities for ease of use. It automatically fetches data from the ERA52 repositories (Pressure and Surface levels). Other climate data sources can be added. Based on the high resolution (30-100m) DEM and the climate data, methods in the topoclass will compute, correct and interpolate variables needed to force specialized land surface models.

TopoPyScale includes a number of export formats inter-operable with specialized energy and mass balance land surface models like CRYOGRID3, SURFEX4, CROCUS5, SNOWPACK6, FSM7, Snowmodel8, GEOTOP or MuSa9.

Downscaled variable includes:

  • 2m air temperature
  • 2m air humidity
  • 2m air pressure
  • 10m wind speed and direction
  • Surface incoming shortwave radiation
  • Surface incoming longwave radiation
  • Precipitation (possibility to partition snow and rain)

Quick Installation

Release Installation

To install the latest release, in a Python 3.9/3.10 virtual environment simply use pip. It is adviced to first install dependencies using conda. More detailed installation instructions here.

As of now, TopoPyScale uses the Copernicus cdsapi to download data. For this to work, you will need to setup the Copernicus API key in your 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}

How to Cite

You are invited to cite TopoPyScale when using it with the following:

Filhol S., Fiddes J., Aalstad K., (2023). TopoPyScale: A Python Package for Hillslope Climate Downscaling. Journal of Open Source Software, 8(86), 5059, https://doi.org/10.21105/joss.05059

or in bibtex: 

@article{Filhol2023, doi = {10.21105/joss.05059}, url = {https://doi.org/10.21105/joss.05059}, year = {2023}, publisher = {The Open Journal}, volume = {8}, number = {86}, pages = {5059}, author = {Simon Filhol and Joel Fiddes and Kristoffer Aalstad}, title = {TopoPyScale: A Python Package for Hillslope Climate Downscaling}, journal = {Journal of Open Source Software} }

Use Cases

TopoPyScale has been used in a number of projects. We are trying to keep track on the usage we hear about or you let us know about on the page Use Cases. So please drop us a line about your project to be featured on the page :)

Contribution

We welcome, and are pleased for any new contribution to this downscaling toolbox. So if you have suggestions, correction and addition to the current code, please come join us on GitHub and talk to us on the Discussion page.

Need Help?

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

References

  1. S. Filhol, J. Fiddes, and K. Aalstad. Topopyscale: a python package for hillslope climate downscaling. Journal of Open Source Software, 8(86):5059, 2023. URL: https://doi.org/10.21105/joss.05059, doi:10.21105/joss.05059. ↩↩

  2. H. Hersbach, B. Bell, P. Berrisford, S. Hirahara, A. Horányi, J. Muñoz-Sabater, J. Nicolas, C. Peubey, R. Radu, D. Schepers, A. Simmons, Cornel Soci, S. Abdalla, X. Abellan, G. Balsamo, P. Bechtold, G. Biavati, J. Bidlot, Massimo Bonavita, Giovanna De Chiara, Per Dahlgren, Dick Dee, Michail Diamantakis, Rossana Dragani, Johannes Flemming, R. Forbes, M. Fuentes, Alan. Geer, L. Haimberger, S. Healy, R. J. Hogan, E. Hólm, M. Janisková, S. Keeley, P. Laloyaux, P. Lopez, C. Lupu, G. Radnoti, P. de Rosnay, I. Rozum, F. Vamborg, S. Villaume, and J. Thépaut. The era5 global reanalysis. Quarterly Journal of the Royal Meteorological Society, 146(730):1999–2049, 2020. doi:https://doi.org/10.1002/qj.3803. ↩

  3. S. Westermann, T. Ingeman-Nielsen, J. Scheer, K. Aalstad, J. Aga, N. Chaudhary, B. Etzelmüller, S. Filhol, A. Kääb, C. Renette, L. S. Schmidt, T. V. Schuler, R. B. Zweigel, L. Martin, S. Morard, M. Ben-Asher, M. Angelopoulos, J. Boike, B. Groenke, F. Miesner, J. Nitzbon, P. Overduin, S. M. Stuenzi, and M. Langer. The cryogrid community model (version 1.0) – a multi-physics toolbox for climate-driven simulations in the terrestrial cryosphere. Geoscientific Model Development, 16(9):2607–2647, 2023. URL: https://gmd.copernicus.org/articles/16/2607/2023/, doi:10.5194/gmd-16-2607-2023. ↩

  4. P. Le Moigne, A. Boone, JC. Calvet, B. Decharme, S. Faroux, AL. Gibelin, C. Lebeaupin, JF. Mahfouf, E. Martin, V. Masson, and others. Surfex scientific documentation. Note de centre (CNRM/GMME), Météo-France, Toulouse, France, 268:51, 2009. URL: https://www.umr-cnrm.fr/surfex/IMG/pdf/surfex_scidoc_v2-2.pdf. ↩

  5. V. Vionnet, E. Brun, S. Morin, A. Boone, S. Faroux, P. Le Moigne, E. Martin, and J.-M. Willemet. The detailed snowpack scheme crocus and its implementation in surfex v7.2. Geoscientific Model Development, 5(3):773–791, 2012. URL: https://gmd.copernicus.org/articles/5/773/2012/, doi:10.5194/gmd-5-773-2012. ↩

  6. Perry Bartelt and Michael Lehning. A physical snowpack model for the swiss avalanche warning: part i: numerical model. Cold Regions Science and Technology, 35(3):123–145, 2002. URL: https://www.sciencedirect.com/science/article/pii/S0165232X02000745, doi:https://doi.org/10.1016/S0165-232X(02)00074-5. ↩

  7. R. Essery. A factorial snowpack model (fsm 1.0). Geoscientific Model Development, 8(12):3867–3876, 2015. URL: https://gmd.copernicus.org/articles/8/3867/2015/, doi:10.5194/gmd-8-3867-2015. ↩

  8. Glen E. Liston and Kelly Elder. A distributed snow-evolution modeling system (snowmodel). Journal of Hydrometeorology, 7(6):1259 – 1276, 2006. URL: https://journals.ametsoc.org/view/journals/hydr/7/6/jhm548_1.xml, doi:10.1175/JHM548.1. ↩

  9. E. Alonso-González, K. Aalstad, M. W. Baba, J. Revuelto, J. I. López-Moreno, J. Fiddes, R. Essery, and S. Gascoin. The multiple snow data assimilation system (musa v1.0). Geoscientific Model Development, 15(24):9127–9155, 2022. URL: https://gmd.copernicus.org/articles/15/9127/2022/, doi:10.5194/gmd-15-9127-2022. ↩