create a public plotting interfaces (#19)

* add cdippy lib version info to requests

add loggers to cdipnc and url_utils

mock all unit tests

* fix uninitialized variable in mop_data

* fix 'start' dates interpreted as local time rather than utc

* re-org package and define public api

config docs

* fix pyproject to include utils package

* re-org package and define public api

config docs

* create a top-level plotting interface to replace the plots lib; clean up API refs for plotting

* make import names more descriptive

Author: haileyajohnson

cdippy/__init__.py

@@ -1,5 +1,8 @@
 # import public top-level modules
-from . import cdipnc, nchashes, ncstats, ndbc, plots, spectra, stndata
+from . import cdipnc, nchashes, ncstats, ndbc, plotting, spectra, stndata
+
+# import plots library for backward compatibility
+from . import plots as plots  # noqa: F401
 
 # public API (i.e. "from cdippy import *")
-__all__ = ["cdipnc", "nchashes", "ncstats", "ndbc", "plots", "spectra", "stndata"]
+__all__ = ["cdipnc", "nchashes", "ncstats", "ndbc", "plotting", "spectra", "stndata"]

cdippy/cdipnc.py

@@ -9,11 +9,8 @@
 from bisect import bisect_left, bisect_right
 
 import cdippy.ndbc as ndbc
-import cdippy.utils.utils as cu
-import cdippy.utils.urls as uu
-
-
-logger = logging.getLogger(__name__)
+import cdippy.utils.utils as cdip_utils
+import cdippy.utils.urls as url_utils
 
 
 logger = logging.getLogger(__name__)
@@ -174,9 +171,9 @@ def set_timespan(self, start, end):
             )
         else:
             self.end_dt = end
-        self.start_stamp = cu.datetime_to_timestamp(self.start_dt)
+        self.start_stamp = cdip_utils.datetime_to_timestamp(self.start_dt)
 
-        self.end_stamp = cu.datetime_to_timestamp(self.end_dt)
+        self.end_stamp = cdip_utils.datetime_to_timestamp(self.end_dt)
 
     def get_request(self) -> dict:
         """Returns the data specified using set_request_info.
@@ -444,23 +441,23 @@ def get_dataset_urls(self) -> dict:
         catalog_url = "/".join([self.THREDDS_url, "thredds", "catalog.xml"])
 
         result = {}
-        root = uu.load_et_root(catalog_url)
+        root = url_utils.load_et_root(catalog_url)
         catalogs = []
-        uu.rfindta(root, catalogs, "catalogRef", "href")
+        url_utils.rfindta(root, catalogs, "catalogRef", "href")
         for catalog in catalogs:
             # - Archive data sets
             url = self.THREDDS_url + catalog
-            cat = uu.load_et_root(url)
+            cat = url_utils.load_et_root(url)
             if catalog.find("archive") >= 0:
                 ar_urls = []
-                uu.rfindta(cat, ar_urls, "catalogRef", "href")
+                url_utils.rfindta(cat, ar_urls, "catalogRef", "href")
                 b_url = os.path.dirname(url)
                 # - Station datasets
                 ar_ds_urls = []
                 for u in ar_urls:
                     url = b_url + "/" + u
-                    ds = uu.load_et_root(url)
-                    uu.rfindta(ds, ar_ds_urls, "dataset", "urlPath")
+                    ds = url_utils.load_et_root(url)
+                    url_utils.rfindta(ds, ar_ds_urls, "dataset", "urlPath")
                 full_urls = []
                 for url in ar_ds_urls:
                     full_urls.append(
@@ -469,7 +466,7 @@ def get_dataset_urls(self) -> dict:
                 result["archive"] = full_urls
             elif catalog.find("realtime") >= 0:
                 rt_ds_urls = []
-                uu.rfindta(cat, rt_ds_urls, "dataset", "urlPath")
+                url_utils.rfindta(cat, rt_ds_urls, "dataset", "urlPath")
                 full_urls = []
                 for url in rt_ds_urls:
                     full_urls.append(
@@ -1000,8 +997,8 @@ def get_request(self):
         end_idx = self.__get_idx_from_timestamp(self.end_stamp)
         z = self.get_var("xyzZDisplacement")
         # Find out if the request timespan overlaps the data
-        ts1 = cu.Timespan(start_idx, end_idx)
-        ts2 = cu.Timespan(0, len(z) - 1)
+        ts1 = cdip_utils.Timespan(start_idx, end_idx)
+        ts2 = cdip_utils.Timespan(0, len(z) - 1)
         if not ts1.overlap(ts2):
             return {}
         # Make sure the indices will work with the arrays

cdippy/mopdata.py

@@ -2,7 +2,7 @@
 from bisect import bisect_left
 
 from cdippy.cdipnc import CDIPnc
-import cdippy.utils.utils as cu
+import cdippy.utils.utils as cdip_utils
 
 
 class MopData(CDIPnc):
@@ -238,11 +238,11 @@ def get_series(
                     tzinfo=timezone.utc
                 )
             ts_I = self.get_target_timespan(
-                cu.datetime_to_timestamp(start), target_records, prefix + "Time"
+                cdip_utils.datetime_to_timestamp(start), target_records, prefix + "Time"
             )
             if ts_I[0] is not None:
-                start = cu.timestamp_to_datetime(ts_I[0])
-                end = cu.timestamp_to_datetime(ts_I[1])
+                start = cdip_utils.timestamp_to_datetime(ts_I[0])
+                end = cdip_utils.timestamp_to_datetime(ts_I[1])
             else:
                 return None
         elif start is None:  # Use default 3 days back
@@ -289,12 +289,14 @@ def get_target_timespan(
         if i_b == last_idx or stamps[i_b] == target_timestamp:
             closest_idx = i_b
         elif i_b > 0:
-            closest_idx = cu.get_closest_index(i_b - 1, i_b, stamps, target_timestamp)
+            closest_idx = cdip_utils.get_closest_index(
+                i_b - 1, i_b, stamps, target_timestamp
+            )
 
         # Now we have the closest index, find the intervals
 
         if closest_idx is not None:
-            interval = cu.get_interval(stamps, closest_idx, num_target_records)
+            interval = cdip_utils.get_interval(stamps, closest_idx, num_target_records)
             return interval
 
         # If we get to here there's a problem

cdippy/nchashes.py

@@ -1,5 +1,5 @@
-import cdippy.utils.urls as uu
-import cdippy.utils.utils as cu
+import cdippy.utils.urls as url_utils
+import cdippy.utils.utils as cdip_utils
 
 
 class NcHashes:
@@ -12,7 +12,7 @@ def __init__(self, hash_file_location=""):
         self.hash_pkl = hash_file_location + "/HASH.pkl"
 
     def load_hash_table(self):
-        lines = uu.read_url(self.hashes_url).strip().split("\n")
+        lines = url_utils.read_url(self.hashes_url).strip().split("\n")
         for line in lines:
             if line[0:8] == "filename":
                 continue
@@ -44,7 +44,7 @@ def compare_hash_tables(self) -> list:
         return changed
 
     def save_new_hashes(self):
-        cu.pkl_dump(self.new_hashes, self.hash_pkl)
+        cdip_utils.pkl_dump(self.new_hashes, self.hash_pkl)
 
     def get_old_hashes(self):
-        return cu.pkl_load(self.hash_pkl)
+        return cdip_utils.pkl_load(self.hash_pkl)

cdippy/ndbc.py

@@ -3,8 +3,8 @@
 import os
 from datetime import datetime, timezone
 
-import cdippy.utils.urls as uu
-import cdippy.utils.utils as cu
+import cdippy.utils.urls as url_utils
+import cdippy.utils.utils as cdip_utils
 
 sos_base = "https://sdf.ndbc.noaa.gov/sos/server.php"
 request = "request=DescribeSensor"
@@ -20,9 +20,9 @@ def get_stn_info(wmo_id):
     """Work in progress, querying ndbc sos service."""
     qry = "&".join([request, service, version, outputformat, describe_stn + wmo_id])
     url = "?".join([sos_base, qry])
-    root = uu.load_et_root(url)
+    root = url_utils.load_et_root(url)
     results = []
-    uu.rfindt(root, results, "description")
+    url_utils.rfindt(root, results, "description")
 
 
 def get_wmo_id(
@@ -35,14 +35,14 @@ def get_wmo_id(
     now = datetime.now(timezone.utc)
     if not pkl_fl or now.minute == 23 or not os.path.isfile(pkl_fl):
         url = "/".join([cdip_base, "wmo_ids"])
-        r = uu.read_url(url)
+        r = url_utils.read_url(url)
         ids = {}
         for line in r.splitlines():
             ids[line[0:3]] = line[5:].strip()
         if pkl_fl:
-            cu.pkl_dump(ids, pkl_fl)
+            cdip_utils.pkl_dump(ids, pkl_fl)
     else:
-        ids = cu.pkl_load(pkl_fl)
+        ids = cdip_utils.pkl_load(pkl_fl)
     if stn in ids:
         return ids[stn]
     else:

cdippy/plots/compendium.py

@@ -1,5 +1,5 @@
-import cdippy.utils.utils as ut
-import cdippy.plots.utils as pu
+import cdippy.utils.utils as cdip_utils
+import cdippy.plots.utils as plot_utils
 from datetime import datetime
 import numpy as np
 import calendar
@@ -15,7 +15,7 @@
 
 
 def make_plot(
-    stns: str, start: datetime, end: datetime, params: str, x_inch: int
+    stns: str, start: datetime, end: datetime, params: str, x_inch: int = None
 ) -> tuple:
     """CDIP's classic compendium plot for multiple stations and parameters.
 
@@ -66,7 +66,7 @@ def make_plot(
         return fig, "Error: start is not set"
 
     if type(start) is str:
-        start = ut.cdip_datetime(start)
+        start = cdip_utils.cdip_datetime(start)
 
     month_plot = False
     if end is None:  # Month compendium plot
@@ -81,7 +81,7 @@ def make_plot(
         )
         month_plot = True
     elif type(end) is str:
-        end = ut.cdip_datetime(end)
+        end = cdip_utils.cdip_datetime(end)
 
     if params is None:
         params = "waveHs,waveTp,waveDp"
@@ -123,7 +123,7 @@ def make_plot(
 
         # Get the color for the station (circular list)
         if multiple_stns:
-            stn_color = pu.stn_colors[stn_idx]
+            stn_color = plot_utils.stn_colors[stn_idx]
         else:
             stn_color = "k"
         stn_idx += 1
@@ -155,13 +155,13 @@ def make_plot(
 
         # Prepare data to show gaps where there is no data
         index_name = "waveTime"
-        data = pu.prepare_gaps_dict(data, index_name)
+        data = plot_utils.prepare_gaps_dict(data, index_name)
 
         # Plot the processed data.
         if len(data) > 0:
-            wT = [ut.timestamp_to_datetime(x) for x in data["waveTime"]]
+            wT = [cdip_utils.timestamp_to_datetime(x) for x in data["waveTime"]]
             for idx in range(len(params)):
-                attr = pu.pm_data[params[idx]]
+                attr = plot_utils.pm_data[params[idx]]
                 ax = pm_axes[idx]
                 if multiple_stns:
                     plot_color = stn_color
@@ -201,12 +201,16 @@ def make_plot(
     plt.minorticks_on()
     for idx in range(len(params)):
         ax = pm_axes[idx]
-        attr = pu.pm_data[params[idx]]
+        attr = plot_utils.pm_data[params[idx]]
         # Grids
         ax.grid(
-            axis="x", which="major", color=pu.grid_color, linestyle="-", linewidth=2
+            axis="x",
+            which="major",
+            color=plot_utils.grid_color,
+            linestyle="-",
+            linewidth=2,
         )
-        ax.grid(axis="y", which="major", color=pu.grid_color, linestyle="-")
+        ax.grid(axis="y", which="major", color=plot_utils.grid_color, linestyle="-")
         # Ticks
         ax.tick_params(axis="x", which="minor", length=4, top="off")
         ax.tick_params(
@@ -227,12 +231,12 @@ def make_plot(
     # Note waveHs may not be in current stn data, hence check if in params.
     if "waveHs" in params:
         hs_ax = pm_axes[params.index("waveHs")]
-        low = pu.pm_data["waveHs"]["ylim"][0]
-        high = pu.pm_data["waveHs"]["ylim"][1]
+        low = plot_utils.pm_data["waveHs"]["ylim"][0]
+        high = plot_utils.pm_data["waveHs"]["ylim"][1]
         if hs_ylim_max < high:
             hs_ax.set_ylim(low, high)
         # Add second Hs axes
-        attr = pu.pm_data["waveHs"]
+        attr = plot_utils.pm_data["waveHs"]
         pHs2 = hs_ax.twinx()
         pHs2.set_ylabel(attr["ylabel_ft"], fontsize=label_font_size)
         pHs2.tick_params(axis="y", which="major", labelsize=label_font_size)
@@ -241,7 +245,7 @@ def make_plot(
 
     if "waveDp" in params:
         dp_ax = pm_axes[params.index("waveDp")]
-        attr = pu.pm_data["waveDp"]
+        attr = plot_utils.pm_data["waveDp"]
         pDp2 = dp_ax.twinx()
         pDp2.set_ylabel(attr["ylabel_compass"], fontsize=label_font_size)
         pDp2.tick_params(axis="y", which="major", labelsize=label_font_size)

cdippy/plots/sst_climatology.py

@@ -5,7 +5,7 @@
 
 
 # CDIP imports
-from cdippy.utils import utils as ut
+from cdippy.utils import utils as cdip_utils
 from cdippy.stndata import StnData
 
 import matplotlib as mpl
@@ -14,7 +14,7 @@
 import matplotlib.pyplot as plt  # noqa: E402
 
 
-def make_plot(stn: str, x_inch: int = None, y_inch: int = None):
+def make_plot(stn: str, x_inch: int = None, y_inch: int = None) -> tuple:
     """
     Year-long Climatology of Sea Surface Temperature across all years of available data for a station.
 
@@ -87,11 +87,11 @@ def Tf(Tc):
 
     for year in yearsort:
 
-        unixstart = ut.datetime_to_timestamp(datetime(year, 1, 1))
+        unixstart = cdip_utils.datetime_to_timestamp(datetime(year, 1, 1))
         ncstart = timefillunix[bisect.bisect_left(timefillunix, unixstart)]
         nearidx = np.where(timefillunix == ncstart)[0][0]
 
-        unixend = ut.datetime_to_timestamp(datetime(year, 12, 31, 23, 59, 59))
+        unixend = cdip_utils.datetime_to_timestamp(datetime(year, 12, 31, 23, 59, 59))
         ncend = timefillunix[(bisect.bisect_right(timefillunix, unixend)) - 1]
         futureidx = np.where(timefillunix == ncend)[0][0]
 

cdippy/plotting.py

@@ -0,0 +1,52 @@
+from . import plots
+from matplotlib.pyplot import Figure
+
+
+def make_annual_hs_boxplot(stn: str, year: int) -> Figure:
+    """
+    Create a boxplot of annual significant wave heights for a station.
+
+    Args:
+        stn (str): A 5-char station identifier, e.g. '100p1'.
+        year (int): The year to plot.
+
+    Returns:
+        fig (Figure): A matplotlib.pyplot.Figure object for the created plot.
+    """
+
+    return plots.annual_hs_boxplot.make_plot(stn, year)
+
+
+def make_compendium_plot(
+    stns: str, start: str, end: str, params: str, x_inch: int
+) -> Figure:
+    """CDIP's classic compendium plot for multiple stations and parameters.
+
+    Args:
+        stns (str): A comma-delimited list of 5-char station identifiers, e.g. '100p1,201p1'.
+        start (str): Start time of data series formatted as 'yyyymm[ddHHMMss]' where 'ddHHMMss' are optional components.
+        end (str): End time of data series ('yyyymm[ddHHMMss]') If 'None' is provided, defaults to the current date and time.
+        params (str): A comma-delimited string of parameter names, e.g. 'waveHs,waveTp'.
+
+    Returns:
+        fig (Figure): A matplotlib.pyplot.Figure object for the created plot.
+
+    """
+
+    return plots.compendium.make_plot(stns, start, end, params, x_inch)
+
+
+def make_sst_climatology_plot(
+    stn: str, x_inch: int = None, y_inch: int = None
+) -> Figure:
+    """
+    Create a plot of yearly climatology of sea surface temperature at a station for all years of available data.
+
+    Args:
+        stn (str): A 5-char station identifier, e.g. '100p1'.
+
+    Returns:
+        fig (Figure): A matplotlib.pyplot.Figure object for the created plot.
+    """
+
+    return plots.sst_climatology.make_plot(stn, x_inch, y_inch)