Merge pull request #7 from pbutting/master

Merge ismn fork into base package. This fork includes functionality to select ISMN stations based on climate and landcover classes.

.gitignore

@@ -7,6 +7,7 @@
 *.orig
 *.log
 *.pot
+.pytest_cache
 __pycache__/*
 .cache/*
 .*.swp

AUTHORS.rst

@@ -5,3 +5,4 @@ Developers
 * Christoph Paulik <[email protected]>
 * Irene Himmelbauer <[email protected]>
 * Luca Zappa <[email protected]>
+* Philip Buttinger <[email protected]>

CHANGES.rst

@@ -2,11 +2,14 @@
 Changelog
 =========
 
-Version 0.X
+Version 0.x
+===========
+
+Version 0.3
 ===========
 
 - Update readme
-- Bugfix for new pandas v0.23
+- Added information about landcover and climate to metadata.
 
 Version 0.2
 ===========

LICENSE.txt

@@ -1,21 +1,21 @@
-The MIT License (MIT)
-
-Copyright (c) 2017 Christoph Paulik
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+# The MIT License (MIT)
+#
+# Copyright (c) 2019 TU Wien
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.

README.rst

@@ -40,6 +40,12 @@ This package should be installable through pip:
 
     pip install ismn
 
+The cartopy-package needs to be installed manually by using the following command:
+
+.. code::
+
+    conda install -c conda-forge cartopy
+
 Example installation script
 ---------------------------
 
@@ -93,6 +99,97 @@ be that station names are not recognized correctly because they contained the
 because of this please download new data from the ISMN since this issue should
 be fixed.
 
+Landcover Classification
+------------------------
+The ISMN data comes with information about landcover classification from the
+ESA CCI land cover project (years 2000, 2005 and 2010) as well as from in-situ
+measurements. To use ESA CCI land cover variables for filtering the data in the get_dataset_ids
+function, set the keyword parameters (landcover_2000, landcover_2005 or landcover_2010)
+to the corresponding integer values (e.g. 10) in the list below. To get a list of
+possible values for filtering by in-situ values (keyword parameter: "landcover_insitu"),
+call the get_landcover_types method of your ISMN_Interface object and set landcover='landcover_insitu'.
+
+* 10: Cropland, rainfed
+* 11: Cropland, rainfed / Herbaceous cover
+* 12: Cropland, rainfed / Tree or shrub cover,
+* 20: Cropland, irrigated or post-flooding,
+* 30: Mosaic cropland (>50%) / natural vegetation (tree, shrub, herbaceous,
+* 40: Mosaic natural vegetation (tree, shrub, herbaceous cover) (>50%) / cropland (<50%),
+* 50: Tree cover, broadleaved, evergreen, Closed to open (>15%),
+* 60: Tree cover, broadleaved, deciduous, Closed to open (>15%),
+* 61: Tree cover, broadleaved, deciduous, Closed (>40%),
+* 62: Tree cover, broadleaved, deciduous, Open (15-40%),
+* 70: Tree cover, needleleaved, evergreen, closed to open (>15%),
+* 71: Tree cover, needleleaved, evergreen, closed (>40%),
+* 72: Tree cover, needleleaved, evergreen, open (15-40%),
+* 80: Tree cover, needleleaved, deciduous, closed to open (>15%),
+* 81: Tree cover, needleleaved, deciduous, closed (>40%),
+* 82: Tree cover, needleleaved, deciduous, open (15-40%),
+* 90: Tree cover, mixed leaf type (broadleaved and needleleaved),
+* 100: Mosaic tree and shrub (>50%) / herbaceous cover (<50%),
+* 110: Mosaic herbaceous cover (>50%) / tree and shrub (<50%),
+* 120: Shrubland,
+* 121: Shrubland / Evergreen Shrubland,
+* 122: Shrubland / Deciduous Shrubland,
+* 130: Grassland,
+* 140: Lichens and mosses,
+* 150: Sparse vegetation (tree, shrub, herbaceous cover) (<15%),
+* 152: Sparse vegetation (tree, shrub, herbaceous cover) (<15%) / Sparse shrub (<15%),
+* 153: Sparse vegetation (tree, shrub, herbaceous cover) (<15%) / Sparse herbaceous cover (<15%),
+* 160: Tree cover, flooded, fresh or brakish water,
+* 170: Tree cover, flooded, saline water,
+* 180: Shrub or herbaceous cover, flooded, fresh/saline/brakish water,
+* 190: Urban areas,
+* 200: Bare areas,
+* 201: Consolidated bare areas,
+* 202: Unconsolidated bare areas,
+* 210: Water,
+* 220: Permanent snow and ice,
+
+Climate Classification
+----------------------
+The ISMN data comes with information about climate classification from the Koeppen-Geiger
+Climate Classification (2007) as well as in-situ measurements. To use
+Koeppen-Geiger variable for filtering the data in the get_dataset_ids function, set the
+keyword parameter "climate" to the corresponding keys (e.g. 'Af') in the list below. To get a list of
+possible values for filtering by in-situ values (keyword parameter: "climate_insitu"), call the
+get_climate_types method of your ISMN_Interface object and set climate='climate_insitu'.
+
+* Af: Tropical Rainforest
+* Am: Tropical Monsoon
+* As: Tropical Savanna Dry
+* Aw: Tropical Savanna Wet
+* BWk: Arid Desert Cold
+* BWh: Arid Desert Hot
+* BWn: Arid Desert With Frequent Fog
+* BSk: Arid Steppe Cold
+* BSh: Arid Steppe Hot
+* BSn: Arid Steppe With Frequent Fog
+* Csa: Temperate Dry Hot Summer
+* Csb: Temperate Dry Warm Summer
+* Csc: Temperate Dry Cold Summer
+* Cwa: Temperate Dry Winter, Hot Summer
+* Cwb: Temperate Dry Winter, Warm Summer
+* Cwc: Temperate Dry Winter, Cold Summer
+* Cfa: Temperate Without Dry Season, Hot Summer
+* Cfb: Temperate Without Dry Season, Warm Summer
+* Cfc: Temperate Without Dry Season, Cold Summer
+* Dsa: Cold Dry Summer, Hot Summer
+* Dsb: Cold Dry Summer, Warm Summer
+* Dsc: Cold Dry Summer, Cold Summer
+* Dsd: Cold Dry Summer, Very Cold Winter
+* Dwa: Cold Dry Winter, Hot Summer
+* Dwb: Cold Dry Winter, Warm Summer
+* Dwc: Cold Dry Winter, Cold Summer
+* Dwd: Cold Dry Winter, Very Cold Winter
+* Dfa: Cold Dry Without Dry Season, Hot Summer
+* Dfb: Cold Dry Without Dry Season, Warm Summer
+* Dfc: Cold Dry Without Dry Season, Cold Summer
+* Dfd: Cold Dry Without Dry Season, Very Cold Winter
+* ET: Polar Tundra
+* EF: Polar Eternal Winter
+* W: Water
+
 Contribute
 ==========
 

docs/read_and_plot_ismn_data/Read and plot ISMN data.rst

@@ -650,4 +650,51 @@ network and station to plot data from
     </div>
 
 
+Selection of ISMN stations by landcover or climate classification:
+
+.. code:: python
+
+    # Return all available landcover classifications (ESA CCI landcover 2000) for the variable soil moisture.
+    # To use ESA CCI landcover data from the year 2005 or 2010 set landcover parameter to 'landcover_2005' and
+    # 'landcover_2010', respectively.
+    lc_2000 = ISMN_reader.get_landcover_types(variable='soil moisture', landcover='landcover_2000')
+
+    # return all available landcover classifications (ESA CCI landcover 2005) for the variable soil moisture
+    # (depths from 0 to 0.1m)
+    lc_2005 = ISMN_reader.get_landcover_types(variable='soil moisture', landcover='landcover_2005'
+                                              min_depth=0, max_depth=0.1)
+    # return all available landcover classifications (ESA CCI landcover 2010) for the variable soil moisture
+    # (depths from 0.1 to 0.5m)
+    lc_2010 = ISMN_reader.get_landcover_types(variable='soil moisture', landcover='landcover_2010'
+                                              min_depth=0.1, max_depth=0.5)
+    # return all available landcover classifications (in situ) for the variable soil moisture
+    lc_insitu = ISMN_reader.get_landcover_types(variable='soil moisture', landcover='landcover_insitu')
+
+    # return all available climate classifications (Koeppen-Geiger 2007) for the variable soil moisture
+    clim = ISMN_reader.get_climate_types(variable='soil moisture', climate='climate')
+    # return all available climate classifications (in situ) for the variable soil moisture
+    clim_insitu = ISMN_reader.get_climate_types(variable='soil moisture', climate='climate_insitu')
+
+
+    # print all landcover classes covered by the ESA CCI landcover classification
+    ISMN_reader.print_landcover_dict()
+    # print all climate classes covered by the Koeppen-Geiger classification
+    ISMN_reader.print_climate_dict()
+
+
+    # Select ISMN stations where soil moisture at depths from 0 to 0.1m is available and the landcover
+    # classification is equal to 130 (Grassland). In this example the ESA CCI landcover classification
+    # for the year 2010 (landcover_2010) is used.
+    ids1 = ISMN_reader.get_dataset_ids(variable='soil moisture', min_depth=0, max_depth=0.1, landcover_2010=130)
+    # read time series from first element in the returned list
+    ts_1 = ISMN_reader.read_ts(ids1[0])
+
+    # Select ISMN stations where soil moisture at depths from 0 to 0.1m is available, the landcover
+    # class (year 2005) is equal to 130 (Grassland) and the climate class is equal to Csa (Temperate
+    # Dry Hot Summer)
+    ids2 = ISMN_reader.get_dataset_ids(variable='soil moisture', min_depth=0, max_depth=1,
+                                       landcover_2005=130, climate='Csa')
+    # read time series from first element in the returned list
+    ts_2 = ISMN_reader.read_ts(ids2[0])
+
 

environment.yml

@@ -2,10 +2,12 @@ name: ismn
 channels:
   - conda-forge
 dependencies:
+  - cython
   - numpy
   - scipy
   - pandas
   - matplotlib
-  - basemap
+  - cartopy
   - pip:
-      - pygeogrids
+     - pygeogrids
+     - configparser

ismn/classifications.ini

@@ -0,0 +1,112 @@
+# The MIT License (MIT)
+#
+# Copyright (c) 2019 TU Wien
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+
+
+# This configuration file specifies all valid values for filtering the ismn stations
+# by landcover classification (ESA CCI landcover) and/or climate classification (KOEPPEN GEIGER).
+# It is used to store landcover and climate information inside an ISMN_Interface object.
+
+
+# ESA CCI landcover classification:
+# This landcover information is available for the years 2000, 2005 and 2010.
+# To filter the data by landcover classes in the get_dataset_ids function,
+# set the parameter (landcover_2000, landcover_2005 or landcover_2010) to an
+# integer value in the list below (e.g. landcover_2000=10).
+[LANDCOVER]
+Cropland, rainfed: 10
+Cropland, rainfed / Herbaceous cover: 11
+Cropland, rainfed / Tree or shrub cover: 12
+Cropland, irrigated or post-flooding: 20
+Mosaic cropland (>50%) / natural vegetation (tree, shrub, herbaceous: 30
+Mosaic natural vegetation (tree, shrub, herbaceous cover) (>50%) / cropland (<50%): 40
+Tree cover, broadleaved, evergreen, Closed to open (>15%): 50
+Tree cover, broadleaved, deciduous, Closed to open (>15%): 60
+Tree cover, broadleaved, deciduous, Closed (>40%): 61
+Tree cover, broadleaved, deciduous, Open (15-40%): 62
+Tree cover, needleleaved, evergreen, closed to open (>15%): 70
+Tree cover, needleleaved, evergreen, closed (>40%): 71
+Tree cover, needleleaved, evergreen, open (15-40%): 72
+Tree cover, needleleaved, deciduous, closed to open (>15%): 80
+Tree cover, needleleaved, deciduous, closed (>40%): 81
+Tree cover, needleleaved, deciduous, open (15-40%): 82
+Tree cover, mixed leaf type (broadleaved and needleleaved): 90
+Mosaic tree and shrub (>50%) / herbaceous cover (<50%): 100
+Mosaic herbaceous cover (>50%) / tree and shrub (<50%): 110
+Shrubland: 120
+Shrubland / Evergreen Shrubland: 121
+Shrubland / Deciduous Shrubland: 122
+Grassland: 130
+Lichens and mosses: 140
+Sparse vegetation (tree, shrub, herbaceous cover) (<15%): 150
+Sparse vegetation (tree, shrub, herbaceous cover) (<15%) / Sparse shrub (<15%): 152
+Sparse vegetation (tree, shrub, herbaceous cover) (<15%) / Sparse herbaceous cover (<15%): 153
+Tree cover, flooded, fresh or brakish water: 160
+Tree cover, flooded, saline water: 170
+Shrub or herbaceous cover, flooded, fresh/saline/brakish water: 180
+Urban areas: 190
+Bare areas: 200
+Consolidated bare areas: 201
+Unconsolidated bare areas: 202
+Water: 210
+Permanent snow and ice: 220
+
+
+# Koeppen-Geiger 2007 climate classification:
+# To filter the data by Koeppen-Geiger climate classes (2007) in the get_dataset_ids function,
+# set the parameter 'climate' to a valid value from the list below (e.g.
+# climate='Af').
+[KOEPPENGEIGER]
+Af: Tropical Rainforest
+Am: Tropical Monsoon
+As: Tropical Savanna Dry
+Aw: Tropical Savanna Wet
+BWk: Arid Desert Cold
+BWh: Arid Desert Hot
+BWn: Arid Desert With Frequent Fog
+BSk: Arid Steppe Cold
+BSh: Arid Steppe Hot
+BSn: Arid Steppe With Frequent Fog
+Csa: Temperate Dry Hot Summer
+Csb: Temperate Dry Warm Summer
+Csc: Temperate Dry Cold Summer
+Cwa: Temperate Dry Winter, Hot Summer
+Cwb: Temperate Dry Winter, Warm Summer
+Cwc: Temperate Dry Winter, Cold Summer
+Cfa: Temperate Without Dry Season, Hot Summer
+Cfb: Temperate Without Dry Season, Warm Summer
+Cfc: Temperate Without Dry Season, Cold Summer
+Dsa: Cold Dry Summer, Hot Summer
+Dsb: Cold Dry Summer, Warm Summer
+Dsc: Cold Dry Summer, Cold Summer
+Dsd: Cold Dry Summer, Very Cold Winter
+Dwa: Cold Dry Winter, Hot Summer
+Dwb: Cold Dry Winter, Warm Summer
+Dwc: Cold Dry Winter, Cold Summer
+Dwd: Cold Dry Winter, Very Cold Winter
+Dfa: Cold Dry Without Dry Season, Hot Summer
+Dfb: Cold Dry Without Dry Season, Warm Summer
+Dfc: Cold Dry Without Dry Season, Cold Summer
+Dfd: Cold Dry Without Dry Season, Very Cold Winter
+ET: Polar Tundra
+EF: Polar Eternal Winter
+W: Water
+