<a style="border-width:0" href="https://doi.org/10.21105/joss.05059">
<img src="https://joss.theoj.org/papers/10.21105/joss.05059/status.svg" alt="DOI badge" ></a>
[](https://zenodo.org/badge/latestdoi/411249045)
[](https://github.com/ArcticSnow/TopoPyScale/blob/main/LICENSE)
[![][docs-dev-img]][docs-dev-url]
Binder Notebooks Examples: [](https://mybinder.org/v2/gh/ArcticSnow/TopoPyScale_examples/HEAD)
[docs-dev-img]: https://img.shields.io/badge/docs-latest-blue.svg
[docs-dev-url]: https://topopyscale.readthedocs.io
# 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
**Please follow these simple rules:**
1. a bug -> fix it!
2. an idea or a bug you cannot fix? -> create a new [issue](https://github.com/ArcticSnow/TopoPyScale/issues) if none doesn't already exist. If one exist, then add material to it.
3. wanna develop a new feature/idea? -> create a new branch. Go wild. Merge with main branch when accomplished.
4. Create release version when significant improvements and bug fixes have been done. Coordinate with others on [Discussions](https://github.com/ArcticSnow/TopoPyScale/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](https://github.com/ArcticSnow/TopoPyScale/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=3.9 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
```
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](https://cds.climate.copernicus.eu/api-how-to#install-the-cds-api-key) after creating an account with [Copernicus](https://cds.climate.copernicus.eu/). 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`](https://github.com/ArcticSnow/TopoPyScale_examples/blob/main/ex1_norway_finse/config_spatial.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
config_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 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/
├── PLEV*.nc
└── SURF*.nc
├── outputs/
└── config.ini
```
Raw data
{
"_id": null,
"home_page": "https://github.com/ArcticSnow/TopoPyScale",
"name": "topopyscale",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "climate,downscaling,meteorology,xarray",
"author": "['Simon Filhol', 'Joel Fiddes', 'Kristoffer Aalstad']",
"author_email": "simon.filhol@geo.uio.no",
"download_url": "https://files.pythonhosted.org/packages/23/d7/9a83104874c07f5f329253f6fe55eceb78fa23578bd36601afc4f0483438/topopyscale-0.2.5.tar.gz",
"platform": null,
"description": "<a style=\"border-width:0\" href=\"https://doi.org/10.21105/joss.05059\">\n <img src=\"https://joss.theoj.org/papers/10.21105/joss.05059/status.svg\" alt=\"DOI badge\" ></a>\n \n[](https://zenodo.org/badge/latestdoi/411249045)\n[](https://github.com/ArcticSnow/TopoPyScale/blob/main/LICENSE)\n\n[![][docs-dev-img]][docs-dev-url]\n\n\nBinder Notebooks Examples: [](https://mybinder.org/v2/gh/ArcticSnow/TopoPyScale_examples/HEAD)\n\n[docs-dev-img]: https://img.shields.io/badge/docs-latest-blue.svg\n[docs-dev-url]: https://topopyscale.readthedocs.io\n\n# TopoPyScale\nPython 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.\n\nDocumentation avalaible: https://topopyscale.readthedocs.io\n\n\n\n**References:**\n\n- 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\n\nAnd the original method it relies on:\n- Fiddes, J. and Gruber, S.: TopoSCALE v.1.0: downscaling gridded climate data in complex terrain, Geosci. Model Dev., 7, 387\u2013405, https://doi.org/10.5194/gmd-7-387-2014, 2014.\n- 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\u20131257, https://doi.org/10.5194/gmd-5-1245-2012, 2012. \n\nKristoffer Aalstad has a Matlab implementation: https://github.com/krisaalstad/TopoLAB\n\n## Contribution Workflow\n**Please follow these simple rules:**\n1. a bug -> fix it! \n2. an idea or a bug you cannot fix? -> create a new [issue](https://github.com/ArcticSnow/TopoPyScale/issues) if none doesn't already exist. If one exist, then add material to it.\n3. wanna develop a new feature/idea? -> create a new branch. Go wild. Merge with main branch when accomplished.\n4. Create release version when significant improvements and bug fixes have been done. Coordinate with others on [Discussions](https://github.com/ArcticSnow/TopoPyScale/discussions)\n\n**Create a new release:**\nFollow procedure and conventions described in: https://www.youtube.com/watch?v=Ob9llA_QhQY\n\nOur forum is now on [Github Discussions](https://github.com/ArcticSnow/TopoPyScale/discussions). Come visit!\n\n\n## Design\n\n1. Inputs\n - Climate data from reanalysis (ERA5, etc)\n - Climate data from future projections (CORDEX) (TBD)\n - DEM from local source, or fetch from public repository: SRTM, ArcticDEM, ASTER\n2. Run TopoScale\n - compute derived values (from DEM)\n - toposcale (k-mean clustering)\n - interpolation (bilinear, inverse square dist.)\n3. Output\n - Cryogrid format\n - FSM format\n - CROCUS format\n - Snowmodel format\n - basic netcfd\n - For each method, have the choice to output either the abstract cluster points, or the gridded product after interpolation\n4. Validation toolset\n - validation to local observation timeseries\n - plotting\n5. Gap filling algorithm\n - random forest temporal gap filling (TBD)\n\nValidation (4) and Gap filling (4) are future implementation.\n\n## Installation\n\nWe have now added an environments.yml file to handle versions of depencencies that are tested with the current codebase, to use this run:\n\n`conda env create -f environment.yml`\n\nAlternatively you can follow this method for dependencies (to be deprecated):\n\n```bash\nconda create -n downscaling python=3.9 ipython\nconda activate downscaling\n\n# Recomended way to install dependencies:\nconda install -c conda-forge xarray matplotlib scikit-learn pandas numpy netcdf4 h5netcdf rasterio pyproj dask rioxarray\n```\n\nThen install the code:\n\n```\n# OPTION 1 (Pypi release):\npip install TopoPyScale\n\n# OPTION 2 (development):\ncd github # navigate to where you want to clone TopoPyScale\ngit clone git@github.com:ArcticSnow/TopoPyScale.git\npip install -e TopoPyScale #install a development version\n\n#----------------------------------------------------------\n# OPTIONAL: if using jupyter lab\n# add this new Python kernel to your jupyter lab PATH\npython -m ipykernel install --user --name downscaling\n\n# Tool for generating documentation from code docstring\npip install lazydocs\n```\n\nThen you need to setup your `cdsapi` with the Copernicus API key system. Follow [this tutorial](https://cds.climate.copernicus.eu/api-how-to#install-the-cds-api-key) after creating an account with [Copernicus](https://cds.climate.copernicus.eu/). On Linux, create a file `nano ~/.cdsapirc` with inside:\n\n```\nurl: https://cds.climate.copernicus.eu/api/v2\nkey: {uid}:{api-key}\n```\n\n## Basic usage\n\n1. Setup your Python environment\n2. Create your project directory\n3. Configure the file `config.ini` to fit your problem (see [`config.yml`](https://github.com/ArcticSnow/TopoPyScale_examples/blob/main/ex1_norway_finse/config_spatial.yml) for an example)\n4. Run TopoPyScale\n\n```python\nimport pandas as pd\nfrom TopoPyScale import topoclass as tc\nfrom matplotlib import pyplot as plt\n\n# ========= STEP 1 ==========\n# Load Configuration\nconfig_file = './config.yml'\nmp = tc.Topoclass(config_file)\n# Compute parameters of the DEM (slope, aspect, sky view factor)\nmp.compute_dem_param()\n\n# ========== STEP 2 ===========\n# Extract DEM parameters for points of interest (centroids or physical points)\n\nmp.extract_topo_param()\n\n# ----- Option 1:\n# Compute clustering of the input DEM and extract cluster centroids\n#mp.extract_dem_cluster_param()\n# plot clusters\n#mp.toposub.plot_clusters_map()\n# plot sky view factor\n#mp.toposub.plot_clusters_map(var='svf', cmap=plt.cm.viridis)\n\n# ------ Option 2:\n# inidicate in the config file the .csv file containing a list of point coordinates (!!! must same coordinate system as DEM !!!)\n#mp.extract_pts_param(method='linear',index_col=0)\n\n# ========= STEP 3 ==========\n# compute solar geometry and horizon angles\nmp.compute_solar_geometry()\nmp.compute_horizon()\n\n# ========= STEP 4 ==========\n# Perform the downscaling\nmp.downscale_climate()\n\n# ========= STEP 5 ==========\n# explore the downscaled dataset. For instance the temperature difference between each point and the first one\n(mp.downscaled_pts.t-mp.downscaled_pts.t.isel(point_id=0)).plot()\nplt.show()\n\n# ========= STEP 6 ==========\n# Export output to desired format\nmp.to_netcdf()\n```\n\nTopoClass 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). \nTopoPyScale 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.\n```\nmy_project/\n \u251c\u2500\u2500 inputs/\n \u251c\u2500\u2500 dem/ \n \u251c\u2500\u2500 my_dem.tif\n \u2514\u2500\u2500 pts_list.csv (optional)\n \u2514\u2500\u2500 climate/\n \u251c\u2500\u2500 PLEV*.nc\n \u2514\u2500\u2500 SURF*.nc\n \u251c\u2500\u2500 outputs/\n \u2514\u2500\u2500 config.ini\n```\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "TopoPyScale: A Python Package for Hillslope Climate Downscaling",
"version": "0.2.5",
"project_urls": {
"Documentation": "https://topopyscale.readthedocs.io/en/latest/",
"Download": "https://github.com/ArcticSnow/TopoPyScale/releases/latest",
"Examples": "https://github.com/ArcticSnow/TopoPyScale_examples",
"Homepage": "https://github.com/ArcticSnow/TopoPyScale",
"Source": "https://github.com/ArcticSnow/TopoPyScale"
},
"split_keywords": [
"climate",
"downscaling",
"meteorology",
"xarray"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "23d79a83104874c07f5f329253f6fe55eceb78fa23578bd36601afc4f0483438",
"md5": "80e0fbe06941eb8f3072777d9e7c6e44",
"sha256": "19135ddeb5858a57b4c14d2ef668fedd12c857e52c6da13578afad75300120fc"
},
"downloads": -1,
"filename": "topopyscale-0.2.5.tar.gz",
"has_sig": false,
"md5_digest": "80e0fbe06941eb8f3072777d9e7c6e44",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 3141234,
"upload_time": "2024-02-26T13:36:31",
"upload_time_iso_8601": "2024-02-26T13:36:31.715622Z",
"url": "https://files.pythonhosted.org/packages/23/d7/9a83104874c07f5f329253f6fe55eceb78fa23578bd36601afc4f0483438/topopyscale-0.2.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-02-26 13:36:31",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ArcticSnow",
"github_project": "TopoPyScale",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "topopyscale"
}
JSON
