Merge pull request #29 from pyet-org/dev

Update master-branch to pyet 1.2.0
pyet-org · Nov 14, 2022 · d8224ed · d8224ed
2 parents f9f3d69 + cd773f7
commit d8224ed
Show file tree

Hide file tree

Showing 82 changed files with 6,766 additions and 11,101 deletions.
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -13,7 +13,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: [3.7, 3.8, 3.9]
+        python-version: ['3.7', '3.8', '3.9', '3.10']
 
     steps:
       - uses: actions/checkout@v2

diff --git a/.travis.yml b/.travis.yml
diff --git a/.zenodo.json b/.zenodo.json
@@ -0,0 +1,26 @@
+{
+  "description": "",
+  "license": "MIT",
+  "title": "PyEt: A Python package for estimating evaporation",
+  "upload_type": "software",
+  "creators": [
+    {
+      "affiliation": "University of Graz, Graz, Austria.",
+      "name": "Matevz Vremec",
+      "orcid": "0000-0002-2730-494X"
+    },
+    {
+      "affiliation": "University of Graz, Graz, Austria.",
+      "name": "Raoul Collenteur",
+      "orcid": "0000-0001-7843-1538"
+    }
+  ],
+  "access_right": "open",
+  "keywords": [
+    "python",
+    "evaporation",
+    "hydrology",
+    "water balance",
+    "open source"
+  ]
+}
diff --git a/CITATION.cff b/CITATION.cff
@@ -0,0 +1,27 @@
+cff-version: 1.2.0
+message: "If you use this software, please cite it as below."
+authors:
+- family-names: "Vremec"
+  given-names: "Matevz"
+  orcid: "https://orcid.org/0000-0002-2730-494X"
+- family-names: "Collenteur"
+  given-names: "Matevz"
+  orcid: "https://orcid.org/0000-0001-7843-1538"
+title: "PyEt-a Python package to estimate potential and reference evapotranspiration"
+version: 1.1.0
+doi: https://doi.org/10.5194/egusphere-egu21-15008
+date-released: 2021
+url: "https://github.com/phydrus/pyet"
+preferred-citation:
+    type: inproceedings
+    authors:
+    - family-names: "Vremec"
+      given-names: "Matevz"
+      orcid: "https://orcid.org/0000-0002-2730-494X"
+    - family-names: "Collenteur"
+      given-names: "Matevz"
+      orcid: "https://orcid.org/0000-0001-7843-1538"
+    doi: "10.5194/egusphere-egu21-15008"
+    journal: "EGU General Assembly Conference Abstracts"
+    year: "2021"
+    title: "PyEt-a Python package to estimate potential and reference evapotranspiration"
diff --git a/README.md b/README.md
@@ -1,65 +1,104 @@
 <img src=https://raw.githubusercontent.com/phydrus/pyet/d7fdd87719588c00326e692f3b1a47b32161e533/docs/_static/logo.png width=120, align=left>
 
-# pyet: Estimation of Potential Evaporation
+# pyet: Estimation of Potential Evapotranspiration
 
-<a href="http://www.gnu.org/licenses/gpl-3.0.txt"><img src=https://img.shields.io/github/license/phydrus/pyet> </a>
-[![Build Status](https://travis-ci.org/phydrus/PyEt.svg?branch=master)](https://travis-ci.org/github/phydrus/PyEt)
-<a href="https://pypi.python.org/pypi/pyet"> <img src=https://img.shields.io/pypi/v/pyet.svg> </a>
-[![Documentation Status](https://readthedocs.org/projects/pyet/badge/?version=latest)](https://pyet.readthedocs.io/en/latest/?badge=latest)
-[![Codacy Badge](https://api.codacy.com/project/badge/Grade/7ed73a2e80784ccf90317c1af8c0cc17)](https://app.codacy.com/gh/phydrus/pyet?utm_source=github.com&utm_medium=referral&utm_content=phydrus/pyet&utm_campaign=Badge_Grade_Dashboard)
+<a href="https://travis-ci.org/github/phydrus/PyEt"><img src="https://api.travis-ci.org/phydrus/PyEt.svg?branch=master"><a>
+<a href="https://mit-license.org/"><img src=https://img.shields.io/pypi/v/pyet.svg><a>
+<a href="https://travis-ci.org/github/phydrus/PyEt"><img src=https://img.shields.io/pypi/l/pyet.svg><a>
+[![Codacy Badge](https://app.codacy.com/project/badge/Grade/e49f23e356f441688422ec32cfcf6aaa)](https://www.codacy.com/gh/phydrus/pyet/dashboard?utm_source=github.com&amp;utm_medium=referral&amp;utm_content=phydrus/pyet&amp;utm_campaign=Badge_Grade)
 [![Codacy Badge](https://app.codacy.com/project/badge/Coverage/e49f23e356f441688422ec32cfcf6aaa)](https://www.codacy.com/gh/phydrus/pyet/dashboard?utm_source=github.com&utm_medium=referral&utm_content=phydrus/pyet&utm_campaign=Badge_Coverage)
+<a href="https://pyet.readthedocs.io/en/latest/?badge=latest"><img src="https://readthedocs.org/projects/pyet/badge/?version=latest"><a>   
+<a href="https://doi.org/10.5281/zenodo.5896800"><img src=https://zenodo.org/badge/DOI/10.5281/zenodo.5896800.svg><a>
+
+pyet is an open source python package for calculating reference and potential Evapotranspiration (PET) for 1D (pandas.Series)
+and 3D (xarray.DataArrray) data. Currently, eighteen methods for calculating daily PET are implemented:
+
+| Method name       | pyet function     | T      | RH         | R      | u2     | Lat.   | El.    | Benchmarked? |
+|:------------------|:------------------|:-------|:-----------|:-------|:-------|:-------|:-------|:---------|
+| Penman            | penman            | &check; $^a$ | &check; $^{b,c}$ | &check; $^d$ | &check;      | &check; $^d$ | &check; $^e$ | -        |
+| Penman-Monteith   | pm                | &check; $^a$ | &check; $^{b,c}$ | &check; $^d$ | &check;      | &check; $^d$ | &check; $^e$ | &check;        |
+| ASCE-PM           | pm_asce           | &check; $^a$ | &check; $^{b,c}$ | &check; $^d$ | &check;      | &check; $^d$ | &check; $^e$ | &check;        |
+| FAO-56            | pm_fao56          | &check; $^a$ | &check; $^{b,c}$ | &check; $^d$ | &check;      | &check; $^d$ | &check; $^e$ | &check;        |
+| Priestley-Taylor  | priestley_taylor  | &check;      | &check; $^h$     | &check; $^h$ | -      | &check; $^h$ | &check; $^e$ | &check;        |
+| Kimberly-Penman   | kimberly_penman   | &check; $^a$ | &check; $^{b,c}$ | &check; $^d$ | &check;      | &check; $^d$ | &check; $^e$ | -        |
+| Thom-Oliver       | thom_oliver       | &check; $^a$ | &check; $^{b,c}$ | &check; $^d$ | &check;      | &check; $^d$ | &check; $^e$ | -        |
+| Blaney-Criddle    | blaney_criddle    | &check;      | - $^i$     | - $^i$ | - $^i$ | &check;      | -      | &check;        |
+| Hamon             | hamon             | &check;      | -          | -      | -      | &check;      | -      | -        |
+| Romanenko         | romanenko         | &check;      | &check;          | -      | -      | -      | -      | -        |
+| Linacre           | linacre           | &check; $^j$ | -          | -      | -      | -      | &check;      | -        |
+| Haude             | haude             | &check;      | &check; $^k$     | -      | -      | -      | -      | &check;        |
+| Turc              | turc              | &check;      | &check;          | &check;      | -      | -      | -      | &check;        |
+| Jensen-Haise      | jensen_haise      | &check;      | -          | &check; $^l$ | -      | &check; $^l$ | -      | -        |
+| McGuinness-Bordne | mcguinness_bordne | &check;      | -          | -      | -      | &check;      | -      | -        |
+| Hargreaves        | hargreaves        | &check; $^m$ | -          | -      | -      | &check;      | -      | &check;        |
+| FAO-24            | fao_24            | &check;      | &check;          | &check;      | &check;      | -      | &check; $^e$ | -        |
+| Abtew             | abtew             | &check;      | -          | &check;      | -      | -      | -      | -        |
+| Makkink           | makkink           | &check;      | -          | &check;      | -      | -      | &check; $^e$ | &check;        |
+| Oudin             | oudin             | &check;      | -          | -      | -      | &check;      | -      | -        |
+
+$^a$ $T_{max}$ and $T_{min}$ can also be provided. $^b$ $RH_{max}$ and $RH_{min}$ can also be provided. $^c$ If actual vapor pressure is provided, RH is not needed.  $^d$ Input for radiation can be (1) Net radiation, (2) solar radiation or (3) sunshine hours. If (1), then latitude is not needed. If (1, 3) latitude and elevation is needed. $^e$ One must provide either the atmospheric pressure or elevation. $^f$ The PM method can be used to estimate potential crop evapotranspiration, if leaf area index or crop height data is available. $^g$ The effect of $CO_2$ on stomatal resistance can be included using the formulation of Yang et al. 2019.  $^h$ If net radiation is provided, RH and Lat are not needed. $^i$ If method==2, $u_2$, $RH_{min}$ and sunshine hours are required. $^j$ Additional input of $T_{max}$ and $T_{min}$, or $T_{dew}$. $^k$ Input can be $RH$ or actual vapor pressure. $^l$ If method==1, latitude is needed instead of $R_s$. $^m$ $T_{max}$ and $T_{min}$ also needed.
+
+## Examples and Documentation
 
-pyet is an open source python package for calculating reference and potential 
-evaporation (PE). Currently eighteen methods for calculating daily PE are 
-implemented:
-
-| Classification | Common method name        | Data needed | pyet Method        | Reference                   |
-|----------------|---------------------------|-------------|--------------------|-----------------------------|
-| Combination    | Penman                    | RH, T, U, D |`penman`            |Penman (1948)                |
-|                | Penman-Monteith           | RH, T, U, D |`pm`                |Monteith (1965)              |
-|                | Penman-Monteith ASCE      | RH, T, U, D |`pm`                |ASCE (2005)                  |
-|                | FAO-56                    | RH, T, U, D |`pm_fao56`          |Allen et al. (1998)          |
-|                | Priestley-Taylor          | T, D        |`priestley_taylor`  |Priestley and Taylor (1972)  |
-|                | Kimberly-Penman           | RH, T, U, D |`kimberly_penman`   |Wright (1982)                |
-|                | Thom-Oliver               | RH, T, U, D |`thom_oliver`       |Thom and Oliver (1977)       |
-| Temperature    | Blaney–Criddle            | T, D        |`blaney_criddle`    |Blaney and Criddle (1952)    |
-|                | Hamon                     | T           |`hamon`             |Hamon (1963)                 |
-|                | Romanenko                 | RH, T       |`romanenko`         |Xu and Singh (2001)          |
-|                | Linacre                   | T           |`linacre`           |Linacre (1977)               |
-| Radiation      | Turc                      | T, D        |`turc`              |Xu and Singh (2001)          |
-|                | Jensen–Haise              | T, D        |`jensen_haise`      |Jensen (1963)                |
-|                | McGuinness–Bordne         | T, D        |`mcguinness_bordne` |McGuinness (1972)            |
-|                | Hargreaves                | T           |`hargreaves`        |Hargreaves and Samani (1982) |
-|                | Doorenbos–Pruitt (FAO-24) | RH, T, U, D |`fao_24`            |Jensen et al. (1990)         |
-|                | Abtew                     | T, D        |`abtew`             |Abtew (1996)                 |
-|                | Makkink                   | T, D        |`makkink`           |Makkink (1957)               |
-|                | Oudin                     | T           |`oudin`             |Oudin (2005)                 |
-
-T, Temperature; U, Wind Speed; D, Radiation; RH, Relative Humidity. Adapted from [@oudin2005potential].
-
-Note: The Penman-Monteith ASCE method can be applied on the hourly and daily time scales.
+Examples of using *pyet* can be found in the example folder:
 
-## Examples and Documentation
+*   [Example 1](/examples/01_example_zamg.ipynb): Estimating PET using pandas.Series
+
+*   [Example 2](/examples/02_example_zamg_netcdf.ipynb): Estimating PET using xarray.DataArray
+
+*   [Example 3](/examples/03_example_knmi.ipynb): Benchmarking Makkink
+  against [KNMI data](https://www.knmi.nl/over-het-knmi/about)
+
+*   [Example 4](/examples/04_example_coagmet.ipynb): Benchmarking FAO56
+  against [CoAgMET data](https://coagmet.colostate.edu/)
+
+*   [Example 5](/examples/05_example_calibration.ipynb): Calibrating the Romanenko and Abtew method against the PM-FAO56
+
+*   [Example 6](/examples/06_worked_examples_McMahon_etal_2013.ipynb): Worked examples for estimating meteorological
+  variables and potential evapotranspiration after McMahon et al., 2013
+
+*   [Example 7](/examples/07_example_climate_change.ipynb): Example for estimating potential evapotranspiration under 
+  warming and elevated $CO_2$ concentrations following Yang et al., (2019) 
+
+*   [Example 8](/examples/08_crop_coefficient.ipynb): Determining the crop coefficient function with Python 
 
-Examples of using pyet can be found in the example folder. This folder also 
-contains a number of Jupyter Notebooks that thoroughly explain the use of the 
-software. Documentation is hosted on [ReadTheDocs](https://pyet.readthedocs.io).
+Documentation is hosted on [ReadTheDocs](https://pyet.readthedocs.io).
 
-After defining the input data, evaporation is estimated using only one 
+After defining the input data, evapotranspiration is estimated using only one
 line of python code:
 
 `>>> pyet.pm_fao56(tmean, wind, rn=rn, tmax=tmax, tmin=tmin, rh=rh, elevation=elevation)`
 
+We support Python >= 3.8.
+
+## Benchmarking
+
+Most of the methods implemented in *pyet* are benchmarked against literature values from the [FAO Irrigation and
+drainage paper 56](https://www.fao.org/3/x0490e/x0490e00.htm), [McMahon et al., 2013 (supplementary)](https://hess.copernicus.org/articles/17/4865/2013/) and [Schrödter, 1985](https://link.springer.com/book/10.1007/978-3-642-70434-5). In addition, two comparative analysis between daily PE estimated with *pyet* and other organizations is
+made:
+
+*   `pyet.pm_fao56` against daily PET estimated with ASCE Penman-Monteith from [CoAgMET](https://coagmet.colostate.edu/) (
+  Colorado State University),
+
+*   `pyet.makkink` against daily PET estimated with Makkink from The Royal Netherlands Meteorological
+  Institute ([KNMI](https://www.knmi.nl/over-het-knmi/about)).
+
+## Dimensions
+
+As of version v1.2., *pyet* is compatible with both Pandas.Series and xarray.DataArray, which means you can now estimate
+potential evapotranspiration for both point and gridded data.
+
 ## Bug reports and Questions
 
-pyet is in active development, and bug reports are welcome as [GitHub 
+pyet is in active development, and bug reports are welcome as [GitHub
 Issues](https://github.com/phydrus/pyet/issues).
-General questions or discussions are possible through 
+General questions or discussions are possible through
 [GitHub Discussions](https://github.com/phydrus/pyet/discussions).
 
 ## Installation
-The pyet package is available from the Pypi package index and can be installed 
-as follows:
+
+The *pyet* package is available from the Pypi package index and can be installed
+as follows::
 
 `>>> pip install pyet`
 
@@ -68,5 +107,19 @@ To install in developer mode, use the following syntax:
 `>>> pip install -e .`
 
 ## Citing
-If you use pyet for one of your projects, we ask that you cite the code as follows:
-*Vremec, M., Collenteur, R., (XXXX). PyEt-open source python package for calculating reference and potential evaporation (Version X.X.X). Zenodo.* 
+
+If you use *pyet* in one of your studies, please cite the *pyet* EGU abstract:
+
+*   Vremec, M. and Collenteur, R.: *pyet* - a Python package to estimate potential and reference evapotranspiration, EGU
+  General Assembly 2021, online, 19–30 Apr 2021, EGU21-15008, https://doi.org/10.5194/egusphere-egu21-15008, 2021.
+
+```Reference
+@inproceedings{vremec2021pyet,
+  title={PyEt-a Python package to estimate potential and reference evapotranspiration},
+  author={Vremec, Matev{\v{z}} and Collenteur, Raoul},
+  booktitle={EGU General Assembly Conference Abstracts},
+  pages={EGU21--15008},
+  year={2021},
+  doi={https://doi.org/10.5194/egusphere-egu21-15008}
+}
+```
diff --git a/docs/api/index.rst b/docs/api/index.rst
@@ -16,4 +16,5 @@ left-hand menu you will find the different categories of the API documentation.
     temperature
     radiation
     meteo_utils
-    rad_utils
+    rad_utils
+    utils