Merge pull request #1 from gantian127/release-0.2

Release 0.2

CHANGES.rst

@@ -1,9 +1,11 @@
 Changelog for pymt_nwis
 =======================
 
-0.2.0 (unreleased)
+0.2.0 (2022-09-13)
 -------------------
 
+- Update nwis to bmi_nwis
+- Update the notebook content
 
 0.1.0 (2021-03-31)
 ------------------

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2021, Tian Gan
+Copyright (c) 2022, Tian Gan
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.rst

@@ -18,9 +18,9 @@ pymt_nwis
         :target: hhttps://github.com/gantian127/pymt_nwis/blob/master/LICENSE
 
 
-pymt_nwis is a package that converts `nwis package <https://github.com/gantian127/nwis>`_ into a reusable,
+pymt_nwis is a package that converts `bmi_nwis package <https://github.com/gantian127/bmi_nwis>`_ into a reusable,
 plug-and-play data component for `PyMT <https://pymt.readthedocs.io/en/latest/?badge=latest>`_ modeling framework.
-This allows the National Water Information System data to be easily coupled with other data or models that expose
+This allows the National Water Information System (`NWIS <https://waterdata.usgs.gov/nwis>`_) data to be easily coupled with other data or models that expose
 a `Basic Model Interface <https://bmi.readthedocs.io/en/latest/>`_.
 
 ---------------
@@ -65,3 +65,10 @@ To install `pymt_nwis`,
 .. code::
 
   pip install pymt_nwis
+
+--------------------
+Coding Example
+--------------------
+
+You can learn more details about the coding example from the
+`tutorial notebook <https://github.com/gantian127/pymt_nwis/blob/master/notebooks/pymt_nwis.ipynb>`_.

babel.toml

@@ -1,7 +1,7 @@
 [library]
 [library.Nwis]
 language = "python"
-library = "nwis"
+library = "bmi_nwis"
 header = ""
 entry_point = "BmiNwis"
 

docs/index.rst

@@ -5,7 +5,7 @@
     :target: https://pymt_nwis.readthedocs.io/
 
 
-pymt_nwis converts `nwis <https://nwis.readthedocs.io/en/latest/?badge=latest>`_ into a reusable,
+pymt_nwis converts `bmi_nwis <https://bmi_nwis.readthedocs.io/en/latest/?badge=latest>`_ into a reusable,
 plug-and-play data component for `PyMT <https://pymt.readthedocs.io/en/latest/?badge=latest>`_ modeling framework.
 pymt_nwis allows the National Water Information System data to be easily coupled with other data or models that expose
 a `Basic Model Interface <https://bmi.readthedocs.io/en/latest/>`_.
@@ -33,30 +33,32 @@ Install the pymt_nwis using pip:
 Coding Example
 --------------
 
+You can learn more details about the coding example from the
+`tutorial notebook <https://github.com/gantian127/pymt_nwis/blob/master/notebooks/pymt_nwis.ipynb>`_.
+
 .. code-block:: python
 
-    import matplotlib.pyplot as plt
     import numpy as np
     import cftime
+    import pandas as pd
 
     from pymt.models import Nwis
 
     # initiate a data component
     data_comp = Nwis()
     data_comp.initialize('config_file.yaml')
 
-    # get variables info
-    var_names = data_comp.output_var_names
-    print('time series variable names: {}'.format(var_names))
-
-    var_name = 'discharge'
-    var_unit = data_comp.var_units(var_name)
-    var_location = data_comp.var_location(var_name)
-    var_type = data_comp.var_type(var_name)
-    var_grid = data_comp.var_grid(var_name)
+    # get variable info
+    for var_name in data_comp.output_var_names:
+        var_unit = data_comp.var_units(var_name)
+        var_location = data_comp.var_location(var_name)
+        var_type = data_comp.var_type(var_name)
+        var_grid = data_comp.var_grid(var_name)
+        var_itemsize = data_comp.var_itemsize(var_name)
+        var_nbytes = data_comp.var_nbytes(var_name)
 
-    print('variable_name: {} \nvar_unit: {} \nvar_location: {} \nvar_type: {} \nvar_grid: {}'.format(
-        var_name, var_unit, var_location, var_type, var_grid))
+        print('variable_name: {} \nvar_unit: {} \nvar_location: {} \nvar_type: {} \nvar_grid: {} \nvar_itemsize: {}'
+            '\nvar_nbytes: {} \n'. format(var_name, var_unit, var_location, var_type, var_grid, var_itemsize, var_nbytes))
 
     # get time info
     start_time = data_comp.start_time
@@ -65,36 +67,51 @@ Coding Example
     time_units = data_comp.time_units
     time_steps = int((end_time - start_time)/time_step) + 1
 
-    print('start_time: {} \nend_time: {} \ntime_step: {} \ntime_units: {} \ntime_steps: {}'.format(
+    print('start_time: {} \nend_time: {} \ntime_step: {} \ntime_units: {} \ntime_steps: {} \n'.format(
         start_time, end_time, time_step, time_units, time_steps))
 
-    # get variable data
-    stream_array = np.empty(time_steps)
-    cftime_array = np.empty(time_steps)
+    # get variable grid info
+    grid_type = data_comp.grid_type(var_grid)
+    grid_rank = data_comp.grid_ndim(var_grid)
+    grid_node_count = data_comp.grid_node_count(var_grid)
+    site_lon = data_comp.grid_x(var_grid)[0]
+    site_lat = data_comp.grid_y(var_grid)[0]
+
+    print('grid_type: {} \ngrid_rank: {} \ngrid_node_count: {} \nsite_lon: {} \nsite_lat: {}'.format(
+        grid_type, grid_rank, grid_node_count, site_lon, site_lat))
+
+    # initiate dataframe to store data
+    dataset = pd.DataFrame(columns = ['00060','00065','time'])
 
     for i in range(0, time_steps):
-        stream_array[i] = data_comp.get_value(var_name)
-        cftime_array[i] = data_comp.time
-        data_comp.update()
+        # get values
+        stream_flow = data_comp.get_value('Stream flow')
+        gage_height = data_comp.get_value('Height')
+        time = cftime.num2pydate(data_comp.time, time_units)
+
+        # add new row to dataframe
+        dataset.loc[len(dataset)]=[stream_flow[0], gage_height[0], time]
 
-    time_array = cftime.num2date(cftime_array, time_units, only_use_cftime_datetimes=False, only_use_python_datetimes=True )
+        # update to next time step
+        data_comp.update()
 
+    # convert time to local time
+    dataset = dataset.set_index('time').tz_localize(tz='UTC').tz_convert(tz='US/Central')
 
     # plot data
-    plt.figure(figsize=(9,5))
-    plt.plot(time_array, stream_array)
-    plt.xlabel('Year 2017')
-    plt.ylabel('{} ({})'.format(var_name, var_unit))
-    plt.title('Discharge Observation at USGS Gage 03339000')
+    ax = dataset.plot(y=['00060','00065'], subplots=True, figsize=(8,8),
+                      xlabel='Time', title = 'Time Series Data at USGS Gage 03339000')
+    ax[0].set_ylabel('Stream flow (ft3/s)')
+    ax[1].set_ylabel('Gage height (ft)')
 
-    # complete the example by finalizing the component
     data_comp.finalize()
 
+
 |ts_plot|
 
 .. links:
 
 .. |binder| image:: https://mybinder.org/badge_logo.svg
- :target: https://mybinder.org/v2/gh/gantian127/pymt_soilgrids/master?filepath=notebooks%2Fpymt_soilgrids.ipynb
+ :target: https://mybinder.org/v2/gh/gantian127/pymt_nwis/master?filepath=notebooks%2Fpymt_nwis.ipynb
 
-.. |ts_plot| image:: _static/ts_plot.png
+.. |ts_plot| image:: _static/plot.png

meta/Nwis/config.yaml

@@ -1,6 +1,7 @@
 bmi-nwis:
-  site: {{site}}
-  start_date: {{start_date}}
-  end_date: {{end_date}}
-  data_type: {{data_type}}
-  nc_output: {{nc_output}}
+  sites: {{sites}}
+  service: {{service}}
+  start: {{start}}
+  end: {{end}}
+  parameterCd: {{parameterCd}}
+  output: {{output}}

meta/Nwis/info.yaml

@@ -1,6 +1,6 @@
 summary: This data component downloads the National Water Information System datasets for data analysis and visualization.
-url: https://github.com/gantian127/nwis/
+url: https://github.com/gantian127/bmi_nwis/
 author: Tian Gan
 email: [email protected]
-version: 0.1
+version: 0.2.0
 license: MIT

meta/Nwis/parameters.yaml

@@ -1,32 +1,39 @@
-site:
-  name: Site
+sites:
+  name: Site code
   description: The Identifier of the USGS Gauge Site
   value:
     type: string
-    default: 03339000
+    default: '03339000'
     units: 1
-data_type:
-  name: Data type
-  description: The data type of the download datasets.
+service:
+  name: Service type
+  description: The service type of the download datasets. Options include 'dv'(daily mean value) and 'iv' (instantaneous value)
   value:
     type: string
-    default: dv
+    default: iv
     units: 1
-start_date:
+start:
   name: Start date
   description: The start date of the time series dataset.
   value:
     type: string
-    default: "2020-01-01"
+    default: "2022-01-01"
     units: 1
-end_date:
+end:
   name: End date
   description: The end date of the time series dataset.
   value:
     type: string
-    default: "2020-01-15"
+    default: "2022-01-3"
     units: 1
-nc_output:
+parameterCd:
+  name: Parameter Code
+  description: The identifier representing a variable for the time series data.
+  value:
+    type: string
+    default: '00060'
+    units: 1
+output:
   name: NetCDF file output
   description: The file path of the NetCDF file to store the time series data.
   value:

notebooks/config_file.yaml

@@ -1,7 +1,7 @@
 bmi-nwis:
   sites: 03339000
+  service: iv
   start: '2022-01-01'
   end: '2022-01-03'
-  service: iv
   output: demo.nc
 

pymt_nwis/bmi.py

@@ -1,7 +1,7 @@
 from __future__ import absolute_import
 
 import pkg_resources
-from nwis import BmiNwis as Nwis
+from bmi_nwis import BmiNwis as Nwis
 
 Nwis.__name__ = "Nwis"
 Nwis.METADATA = pkg_resources.resource_filename(__name__, "data/Nwis")

requirements.txt

@@ -1,2 +1,2 @@
 numpy
-nwis
+bmi_nwis

setup.py

@@ -27,7 +27,7 @@ def read(filename):
     author_email="[email protected]",
     description="PyMT plugin for pymt_nwis",
     long_description=long_description,
-    version="0.1.0",
+    version="0.2.0",
     url="https://github.com/gantian127/pymt_nwis",
     classifiers=[
         "Development Status :: 4 - Beta",