Merge pull request #1 from gantian127/release-0.1.1

Release 0.1.1

README.md

@@ -1,15 +1,15 @@
 # bmi_era5
 [![Documentation Status](https://readthedocs.org/projects/bmi_era5/badge/?version=latest)](https://bmi_era5.readthedocs.io/en/latest/?badge=latest)
 [![MIT license](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/gantian127/bmi_era5/blob/master/LICENSE.txt)
-<!--[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/gantian127/bmi_era5/master?filepath=notebooks%2Fbmi_era5.ipynb)-->
+[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/gantian127/bmi_era5/master?filepath=notebooks%2Fbmi_era5.ipynb)
 
 
-
-A Python library as a Basic Model Interface ([BMI](https://bmi-spec.readthedocs.io/en/latest/)) implementation 
+bmi_era5 package is an implementation of the Basic Model Interface ([BMI](https://bmi-spec.readthedocs.io/en/latest/)) 
 for the [ERA5](https://confluence.ecmwf.int/display/CKB/ERA5) dataset. 
-This package can help convert the ERA5 data into a reusable, plug-and-play 
-data component (currently support 3 dimensional ERA5 data) for [PyMT](https://pymt.readthedocs.io/en/latest/?badge=latest) 
-modeling framework developed by Community Surface Dynamics Modeling System 
+This package uses the [CDS API](https://cds.climate.copernicus.eu/api-how-to) to download the ERA5 dataset and wraps the dataset with BMI for data control and query 
+(currently support 3 dimensional ERA5 dataset). 
+This package is not implemented for people to use but is the key element to convert the ERA5 dataset into 
+a data component for the [PyMT](https://pymt.readthedocs.io/en/latest/?badge=latest) modeling framework developed by Community Surface Dynamics Modeling System 
 ([CSDMS](https://csdms.colorado.edu/wiki/Main_Page)).
 
 If you have any suggestion to improve the current function, please create a github issue 
@@ -20,7 +20,7 @@ If you have any suggestion to improve the current function, please create a gith
 #### Install package
 
 Please make sure to first install the
-[CDS API](https://confluence.ecmwf.int/display/CKB/How+to+download+ERA5#HowtodownloadERA5-4-DownloadERA5familydatathroughtheCDSAPI) 
+[CDS API](https://cds.climate.copernicus.eu/api-how-to)
 and then follow the instructions below to install the bmi_era5 package.
 
 ##### Stable Release
@@ -46,8 +46,8 @@ $ pip install -e .
 
 #### Download ERA5 Data
 
-Learn more details of the examples from the [tutorial notebook](https://github.com/gantian127/bmi_era5/tree/master/notebooks) 
-provided in this package. 
+Learn more details of the examples from the [tutorial notebook](https://github.com/gantian127/bmi_era5/blob/master/notebooks/bmi_era5.ipynb) 
+provided in this package. You can also launch binder to test and run the code below.
 
 ##### Example 1: use CDS API to download the ERA5 data 
 

binder/environment.yml

@@ -0,0 +1,14 @@
+name: bmi_era5
+channels:
+  - conda-forge
+dependencies:
+  - bmipy
+  - netcdf4
+  - numpy
+  - pyyaml
+  - requests
+  - xarray
+  - matplotlib
+
+
+

binder/postBuild

@@ -0,0 +1,3 @@
+#!/bin/bash
+
+python setup.py install

docs/source/index.rst

@@ -4,10 +4,12 @@
     :alt: bmi_era5
     :target: https://bmi_era5.readthedocs.io/
 
-`bmi_era5 <https://github.com/gantian127/bmi_era5/>`_ is the Basic Model Interface (`BMI <https://bmi-spec.readthedocs.io/en/latest/>`_) implementation
+`bmi_era5 <https://github.com/gantian127/bmi_era5/>`_ package is an implementation of the Basic Model Interface (`BMI <https://bmi-spec.readthedocs.io/en/latest/>`_)
 for the `ERA5 <https://confluence.ecmwf.int/display/CKB/ERA5>`_ dataset.
-This package can help convert the ERA5 data  into a reusable, plug-and-play
-data component (currently support 3 dimensional ERA5 data) for `PyMT <https://pymt.readthedocs.io/en/latest/?badge=latest>`_ modeling framework developed by Community Surface Dynamics Modeling System
+This package uses the `CDS API <https://cds.climate.copernicus.eu/api-how-to>`_ to download the ERA5 dataset and wraps the dataset with BMI for data control and query
+(currently support 3 dimensional ERA5 dataset).
+This package is not implemented for people to use but is the key element to convert the ERA5 dataset into
+a data component for the `PyMT <https://pymt.readthedocs.io/en/latest/?badge=latest>`_ modeling framework developed by Community Surface Dynamics Modeling System
 (`CSDMS <https://csdms.colorado.edu/wiki/Main_Page>`_).
 
 If you have any suggestion to improve the current function, please create a github issue
@@ -50,7 +52,8 @@ After downloading the source code, run the following command from top-level fold
 Download ERA5 Data
 ++++++++++++++++++++++++
 
-Learn more details of the examples from the `tutorial notebook <https://github.com/gantian127/bmi_era5/tree/master/notebooks>`_ provided in this package.
+Learn more details of the examples from the `tutorial notebook <https://github.com/gantian127/bmi_era5/blob/master/notebooks/bmi_era5.ipynb>`_ provided in this package.
+You can also launch binder to test and run the code below. |binder|
 
 **Example 1**: use CDS API to download the ERA5 data.
 

notebooks/bmi_era5.ipynb

@@ -7,6 +7,18 @@
     "<img src=\"https://github.com/gantian127/bmi_era5/blob/master/docs/source/_static/bmi_era5_logo.png?raw=true\" width='600' align='center'></a>"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Basic Info\n",
+    "This Jupyter Notebook was created by Tian Gan. You can test this Jupyter Notebook through [Binder](https://mybinder.org/v2/gh/gantian127/bmi_era5/master?filepath=notebooks%2Fbmi_era5.ipynb) or [HydroShare](https://www.hydroshare.org/resource/765e4e8bebab4eea8d72ee447a27c2fa/).\n",
+    "\n",
+    "If you have any suggestion to improve the current functions of the bmi_era5 package, please create a github issue [here](https://github.com/gantian127/bmi_era5/issues).\n",
+    "\n",
+    "Suggested citation: Gan, T. (2021). Jupyter Notebooks for the ERA5 Data Component, HydroShare, https://www.hydroshare.org/resource/765e4e8bebab4eea8d72ee447a27c2fa/"
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},
@@ -45,14 +57,31 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "bmi_era5 package is a Basic Model Interface ([BMI](https://bmi.readthedocs.io/en/latest/)) implementation for the ERA5 data API ([CDS API](https://confluence.ecmwf.int/display/CKB/How+to+download+ERA5#HowtodownloadERA5-4-DownloadERA5familydatathroughtheCDSAPI)). This package can help convert the ERA5 data (currently support 3 dimensional data) into a reusable, plug-and-play data component for [PyMT](https://pymt.readthedocs.io/en/latest/?badge=latest) modeling framework developed by Community Surface Dynamics Modeling System ([CSDMS](https://csdms.colorado.edu/wiki/Main_Page)). "
+    "bmi_era5 package is an implementation of the Basic Model Interface ([BMI](https://bmi.readthedocs.io/en/latest/)) for the [ERA5](https://confluence.ecmwf.int/display/CKB/ERA5) dataset. This package uses the [CDS API](https://cds.climate.copernicus.eu/api-how-to) to download the ERA5 dataset and wraps the dataset with BMI for data control and query (currently support 3 dimensional ERA5 dataset). This package is not implemented for people to use but is the key element to convert the ERA5 dataset into a data component for the PyMT modeling framework."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Let's first use a helper function to install the CDS API and create the CDS API Key file. The \"install_cds( )\" function will ask you to enter your CDS API. So please make sure you have already created an account at the [CDS registration page](https://cds.climate.copernicus.eu/#!/home) and obtained your CDS API Key. For more details please check [here](https://cds.climate.copernicus.eu/api-how-to)."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from installation import install_cds\n",
+    "install_cds()"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Please make sure you first successfully install the [CDS API](https://confluence.ecmwf.int/display/CKB/How+to+download+ERA5#HowtodownloadERA5-4-DownloadERA5familydatathroughtheCDSAPI) . Then use the following command to install the bmi_era5 package."
+    "After you sucessfully run the helper function above, use the following command to install the bmi_era5 package. "
    ]
   },
   {
@@ -78,7 +107,7 @@
    "source": [
     "The CDS API (Climate Data Store Application Program Interface) is a service providing Python based programmatic access to CDS data. ERA5 is one of the CDS data products that can be accessed using the CDS API.  \n",
     "\n",
-    "In bmi_era5 package, BmiEra5 class is designed to download and convert the ERA5 dataset (currently support 3 dimensional data) as a data component for the [PyMT](https://pymt.readthedocs.io/en/latest/?badge=latest) modeling framework. The following examples demonstrate how to download the same dataset using the CDS API and BmiEra5 for data visualization. "
+    "In bmi_era5 package, BmiEra5 class is designed to download the ERA5 dataset and wrap the dataset with BMI (currently support 3 dimensional ERA5 data). The following examples demonstrate how to download the same dataset using the CDS API and BmiEra5 for data visualization. "
    ]
   },
   {

notebooks/installation.py

@@ -0,0 +1,23 @@
+import subprocess
+import os
+
+
+def install_cds(config_path=''):
+    # create configuration file
+    url = 'https://cds.climate.copernicus.eu/api/v2'
+    key = input('Enter Your CDS API Key: ')
+    config_content = 'url: {} \nkey: {}'.format(url, key)
+
+    home_dir = os.path.expanduser('~')
+    config_path = config_path if config_path else os.path.join(home_dir, '.cdsapirc')
+
+    with open(config_path, 'w') as config_file:
+        config_file.write(config_content)
+
+    print('CDS API Key file is created.')
+
+    # install cdsapi
+    install = subprocess.run(["pip", "install", "cdsapi"], check=True)
+    if install.returncode == 0:
+        print('cdsapi package is successfully installed.')
+