Merge pull request #118 from jarq6c/nwis_update

Add value_time_label option to nwis_client

python/nwis_client/README.md

@@ -31,7 +31,9 @@ The following example demonstrates how one might use `hydrotools.nwis_client` to
 from hydrotools.nwis_client.iv import IVDataService
 
 # Retrieve data from a single site
-service = IVDataService()
+service = IVDataService(
+    value_time_label="value_time"
+)
 observations_data = service.get(
     sites='01646500',
     startDT='2019-08-01',

python/nwis_client/setup.cfg

@@ -1,6 +1,6 @@
 [metadata]
 name = hydrotools.nwis_client
-version = 3.0.2
+version = 3.0.3
 author = Austin Raney
 author_email = [email protected]
 description = A convenient interface to the USGS NWIS Instantaneous Values (IV) REST Service API.

python/nwis_client/src/hydrotools/nwis_client/iv.py

@@ -38,6 +38,8 @@ class IVDataService:
         Toggle sqlite3 request caching
     cache_expire_after : int
         Cached item life length in seconds
+    value_time_label: str, default 'value_date'
+        Label to use for datetime column returned by IVDataService.get
 
     Examples
     --------
@@ -85,8 +87,13 @@ class IVDataService:
     )
     _requests_cache_filename = "nwisiv_cache"
     _headers = {"Accept-Encoding": "gzip, compress"}
+    _value_time_label = None
 
-    def __init__(self, *, enable_cache: bool = True, cache_expire_after: int = 43200):
+    def __init__(self, *, 
+        enable_cache: bool = True, 
+        cache_expire_after: int = 43200,
+        value_time_label: str = None
+        ):
         self._cache_enabled = enable_cache
         self._restclient = RestClient(
             base_url=self._base_url,
@@ -95,6 +102,12 @@ def __init__(self, *, enable_cache: bool = True, cache_expire_after: int = 43200
             cache_filename=self._requests_cache_filename,
             cache_expire_after=cache_expire_after,
         )
+        if value_time_label == None:
+            self._value_time_label = "value_date"
+            warning_message = "Setting value_time_label to value_date. Future versions will default to value_time. To silence this warning set value_time_label."
+            warnings.warn(warning_message, UserWarning)
+        else:
+            self._value_time_label = value_time_label
 
     def get(
         self,
@@ -237,8 +250,6 @@ def list_to_df_helper(item: dict):
 
         # Empty list. No data was returned in the request
         if not list_of_frames:
-            import warnings
-
             warning_message = "No data was returned by the request."
             warnings.warn(warning_message)
             return pd.DataFrame(None)
@@ -250,7 +261,7 @@ def list_to_df_helper(item: dict):
         dfs.loc[:, "value"] = pd.to_numeric(dfs["value"], downcast="float")
 
         # Convert all times to UTC
-        dfs["value_date"] = pd.to_datetime(
+        dfs[self.value_time_label] = pd.to_datetime(
             dfs["dateTime"], utc=True, infer_datetime_format=True
         ).dt.tz_localize(None)
 
@@ -259,7 +270,7 @@ def list_to_df_helper(item: dict):
 
         # Sort DataFrame
         dfs = dfs.sort_values(
-            ["usgs_site_code", "measurement_unit", "value_date"], ignore_index=True
+            ["usgs_site_code", "measurement_unit", self.value_time_label], ignore_index=True
         )
 
         # Fill NaNs
@@ -284,7 +295,7 @@ def list_to_df_helper(item: dict):
         # DataFrame in semi-WRES compatible format
         return dfs[
             [
-                "value_date",
+                self.value_time_label,
                 "variable_name",
                 "usgs_site_code",
                 "measurement_unit",
@@ -693,6 +704,11 @@ def datetime_format(self) -> str:
         """ API's expected datetime format """
         return self._datetime_format
 
+    @property
+    def value_time_label(self) -> str:
+        """ Label to use for datetime column """
+        return self._value_time_label
+
 
 def validate_optional_combinations(
     arg_mapping: Dict[str, T],

python/nwis_client/tests/test_nwis.py

@@ -79,6 +79,12 @@ def setup_iv(loop):
     yield o
     o._restclient.close()
 
+@pytest.fixture
+def setup_iv_value_time(loop):
+    o = iv.IVDataService(value_time_label="value_time")
+    yield o
+    o._restclient.close()
+
 
 simplify_variable_test_data = [
     ("test", ",", "test"),
@@ -135,6 +141,13 @@ def test_get(setup_iv, sites, validation):
     df = setup_iv.get(sites=sites, parameterCd="00060")
     assert df["usgs_site_code"].isin(validation).all()
 
+@pytest.mark.slow
+@pytest.mark.parametrize("sites,validation", GET_PARAM_SITES)
+def test_get_value_time(setup_iv_value_time, sites, validation):
+    """Test data retrieval and parsing"""
+    df = setup_iv_value_time.get(sites=sites, parameterCd="00060")
+    assert df["usgs_site_code"].isin(validation).all()
+    assert "value_time" in df
 
 def test_get_raw_with_mock(setup_iv, monkeypatch):
     """Test data retrieval and parsing"""