feat: improve conversion of timescale to datetime arrays (#220)

* docs: update `graphviz` fonts
* refactor: switch from import `warnings` to debug `logging`

doc/source/getting_started/Getting-Started.rst

@@ -31,7 +31,6 @@ Presently, the following models and their directories parameterized within ``pyT
     * CATS0201: ``<path_to_tide_models>/cats0201_tmd/``
     * `CATS2008 <https://www.usap-dc.org/view/dataset/601235>`_: ``<path_to_tide_models>/CATS2008/``
     * CATS2008_load: ``<path_to_tide_models>/CATS2008a_SPOTL_Load/``
-    * CATS2022: ``<path_to_tide_models>/CATS2022/``
 
 - Arctic Ocean and Greenland Coast Tidal Simulations [Padman2004]_
 

doc/source/getting_started/Overview.rst

@@ -19,33 +19,93 @@ the output ocean, load, solid Earth and pole tide variables as shown in the flow
     :align: center
 
     digraph {
-        S [label="Spatial Coordinates" shape=box style="filled" color="#7570b3"]
-        E [label="Temporal Values" shape=box style="filled" color="#7570b3"]
-        M [label="Tide Model" shape=box style="filled" color="#7570b3"]
-        T [label="pyTMD" shape=box style="filled" color="gray"]
-        P [label="Tide Predictions" shape=box style="filled" color="#1b9e77"]
-        H [label="Tide Heights" shape=box style="filled" color="#1b9e77"]
-        C [label="Average Tidal Currents" shape=box style="filled" color="#1b9e77"]
-        S -> T
-        E -> T
-        M -> T
-        T -> P
-        T -> H
-        T -> C
+        S [label="Spatial Coordinates"
+            fontname="Lato"
+            fontsize=11
+            shape=box
+            style="filled"
+            color="#7570b3"]
+        E [label="Temporal Values"
+            fontname="Lato"
+            fontsize=11
+            shape=box
+            style="filled"
+            color="#7570b3"]
+        M [label="Tide Model"
+            fontname="Lato"
+            fontsize=11
+            shape=box
+            style="filled"
+            color="#7570b3"]
+        T [label="pyTMD"
+            fontname="Lato"
+            fontsize=11
+            shape=box
+            style="filled"
+            color="gray"]
+        P [label="Tide Predictions"
+            fontname="Lato"
+            fontsize=11
+            shape=box
+            style="filled"
+            color="#1b9e77"]
+        H [label="Tide Heights"
+            fontname="Lato"
+            fontsize=11
+            shape=box
+            style="filled"
+            color="#1b9e77"]
+        C [label="Average Tidal Currents"
+            fontname="Lato"
+            fontsize=11
+            shape=box
+            style="filled"
+            color="#1b9e77"]
+        S -> T [arrowsize=0.8]
+        E -> T [arrowsize=0.8]
+        M -> T [arrowsize=0.8]
+        T -> P [arrowsize=0.8]
+        T -> H [arrowsize=0.8]
+        T -> C [arrowsize=0.8]
     }
 
 .. graphviz::
     :caption: Solid Earth and Pole Tide Framework
     :align: center
 
     digraph {
-        S [label="Spatial Coordinates" shape=box style="filled" color="#7570b3"]
-        E [label="Temporal Values" shape=box style="filled" color="#7570b3"]
-        T [label="pyTMD" shape=box style="filled" color="gray"]
-        D [label="Solid Earth Displacements" shape=box style="filled" color="#1b9e77"]
-        P [label="Pole Tide Displacements" shape=box style="filled" color="#1b9e77"]
-        S -> T
-        E -> T
-        T -> D
-        T -> P
+        S [label="Spatial Coordinates"
+            fontname="Lato"
+            fontsize=11
+            shape=box
+            style="filled"
+            color="#7570b3"]
+        E [label="Temporal Values"
+            fontname="Lato"
+            fontsize=11
+            shape=box
+            style="filled"
+            color="#7570b3"]
+        T [label="pyTMD"
+            fontname="Lato"
+            fontsize=11
+            shape=box
+            style="filled"
+            color="gray"]
+        D [label="Solid Earth Displacements"
+            fontname="Lato"
+            fontsize=11
+            shape=box
+            style="filled"
+            color="#1b9e77"]
+        P [label="Pole Tide Displacements"
+            fontname="Lato"
+            fontsize=11
+            shape=box
+            style="filled"
+            color="#1b9e77"]
+        S -> T [arrowsize=0.8]
+        E -> T [arrowsize=0.8]
+        T -> D [arrowsize=0.8]
+        T -> P [arrowsize=0.8]
     }

pyTMD/check_tide_points.py

@@ -68,8 +68,8 @@
 """
 from __future__ import print_function, annotations
 
+import logging
 import pathlib
-import warnings
 import numpy as np
 import scipy.interpolate
 
@@ -82,10 +82,7 @@
 try:
     import pyproj
 except (ImportError, ModuleNotFoundError) as exc:
-    warnings.filterwarnings("module")
-    warnings.warn("pyproj not available", ImportWarning)
-# ignore warnings
-warnings.filterwarnings("ignore")
+    logging.debug("pyproj not available")
 
 # PURPOSE: compute tides at points and times using tide model algorithms
 def check_tide_points(x: np.ndarray, y: np.ndarray,

pyTMD/compute_tide_corrections.py

@@ -101,8 +101,8 @@
 """
 from __future__ import print_function, annotations
 
+import logging
 import pathlib
-import warnings
 import numpy as np
 import scipy.interpolate
 import pyTMD.constants
@@ -118,10 +118,7 @@
 try:
     import pyproj
 except (ImportError, ModuleNotFoundError) as exc:
-    warnings.filterwarnings("module")
-    warnings.warn("pyproj not available", ImportWarning)
-# ignore warnings
-warnings.filterwarnings("ignore")
+    logging.critical("pyproj not available")
 
 # PURPOSE: wrapper function for computing corrections
 def compute_corrections(

pyTMD/convert_crs.py

@@ -47,17 +47,14 @@
 """
 from __future__ import annotations
 
-import warnings
+import logging
 import numpy as np
 
 # attempt imports
 try:
     import pyproj
 except (ImportError, ModuleNotFoundError) as exc:
-    warnings.filterwarnings("module")
-    warnings.warn("pyproj not available", ImportWarning)
-# ignore warnings
-warnings.filterwarnings("ignore")
+    logging.critical("pyproj not available")
 
 def convert_crs(
         i1: np.ndarray,

pyTMD/io/ATLAS.py

@@ -107,10 +107,7 @@
 try:
     import netCDF4
 except (ImportError, ModuleNotFoundError) as exc:
-    warnings.filterwarnings("module")
-    warnings.warn("netCDF4 not available", ImportWarning)
-# ignore warnings
-warnings.filterwarnings("ignore")
+    logging.critical("netCDF4 not available")
 
 # PURPOSE: extract harmonic constants from tide models at coordinates
 def extract_constants(

pyTMD/io/FES.py

@@ -107,10 +107,7 @@
 try:
     import netCDF4
 except (ImportError, ModuleNotFoundError) as exc:
-    warnings.filterwarnings("module")
-    warnings.warn("netCDF4 not available", ImportWarning)
-# ignore warnings
-warnings.filterwarnings("ignore")
+    logging.critical("netCDF4 not available")
 
 # PURPOSE: extract harmonic constants from tide models at coordinates
 def extract_constants(

pyTMD/io/GOT.py

@@ -98,10 +98,7 @@
 try:
     import netCDF4
 except (ImportError, ModuleNotFoundError) as exc:
-    warnings.filterwarnings("module")
-    warnings.warn("netCDF4 not available", ImportWarning)
-# ignore warnings
-warnings.filterwarnings("ignore")
+    logging.debug("netCDF4 not available")
 
 # PURPOSE: extract harmonic constants from tide models at coordinates
 def extract_constants(

pyTMD/io/OTIS.py

@@ -112,6 +112,7 @@
 
 import copy
 import struct
+import logging
 import pathlib
 import warnings
 import numpy as np
@@ -124,10 +125,7 @@
 try:
     import netCDF4
 except (ImportError, ModuleNotFoundError) as exc:
-    warnings.filterwarnings("module")
-    warnings.warn("netCDF4 not available", ImportWarning)
-# ignore warnings
-warnings.filterwarnings("ignore")
+    logging.debug("netCDF4 not available")
 
 # PURPOSE: extract harmonic constants from tide models at coordinates
 def extract_constants(

pyTMD/spatial.py

@@ -54,7 +54,7 @@
     Updated 07/2021: added function for determining input variable type
     Updated 03/2021: added polar stereographic area scale calculation
         add routines for converting to and from cartesian coordinates
-        eplaced numpy bool/int to prevent deprecation warnings
+        replaced numpy bool/int to prevent deprecation warnings
     Updated 01/2021: add streaming from bytes for ascii, netCDF4, HDF5, geotiff
         set default time for geotiff files to 0
     Updated 12/2020: added module for converting ellipsoids
@@ -73,7 +73,6 @@
 import logging
 import pathlib
 import datetime
-import warnings
 import numpy as np
 import pyTMD.time
 from pyTMD.constants import constants
@@ -82,20 +81,15 @@
 try:
     import osgeo.gdal, osgeo.osr, osgeo.gdalconst
 except (ImportError, ModuleNotFoundError) as exc:
-    warnings.filterwarnings("module")
-    warnings.warn("GDAL not available", ImportWarning)
+    logging.debug("GDAL not available")
 try:
     import h5py
 except (ImportError, ModuleNotFoundError) as exc:
-    warnings.filterwarnings("module")
-    warnings.warn("h5py not available", ImportWarning)
+    logging.debug("h5py not available")
 try:
     import netCDF4
 except (ImportError, ModuleNotFoundError) as exc:
-    warnings.filterwarnings("module")
-    warnings.warn("netCDF4 not available", ImportWarning)
-# ignore warnings
-warnings.filterwarnings("ignore")
+    logging.debug("netCDF4 not available")
 
 def case_insensitive_filename(filename: str | pathlib.Path):
     """
@@ -1604,8 +1598,8 @@ def _zhu_closed_form(
 
 def scale_areas(
         lat: np.ndarray,
-        flat: float=_wgs84.flat,
-        ref: float=70.0
+        flat: float = _wgs84.flat,
+        ref: float = 70.0
     ):
     """
     Calculates area scaling factors for a polar stereographic projection

pyTMD/time.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 u"""
 time.py
-Written by Tyler Sutterley (05/2023)
+Written by Tyler Sutterley (06/2023)
 Utilities for calculating time operations
 
 PYTHON DEPENDENCIES:
@@ -16,6 +16,7 @@
     utilities.py: download and management utilities for syncing files
 
 UPDATE HISTORY:
+    Updated 06/2023: improve conversion of timescale to datetime arrays
     Updated 05/2023: add timescale class for converting between time scales
         added timescale to_datetime function to create datetime arrays
         allow epoch arguments to be numpy datetime64 variables or strings
@@ -135,7 +136,7 @@ def parse_date_string(date_string: str):
         # return the epoch (as list)
         return (datetime_to_list(epoch), 0.0)
     # split the date string into units and epoch
-    units,epoch = split_date_string(date_string)
+    units, epoch = split_date_string(date_string)
     if units not in _to_sec.keys():
         raise ValueError(f'Invalid units: {units}')
     # return the epoch (as list) and the time unit conversion factors
@@ -193,7 +194,7 @@ def calendar_days(year: int | float | np.ndarray) -> np.ndarray:
 
     Returns
     -------
-    dpm: list
+    dpm: np.ndarray
         number of days for each month
     """
     # Rules in the Gregorian calendar for a year to be a leap year:
@@ -255,9 +256,9 @@ def convert_delta_time(
     ----------
     delta_time: np.ndarray
         seconds since epoch1
-    epoch1: tuple or NoneType, default None
+    epoch1: str, tuple, list or NoneType, default None
         epoch for input ``delta_time``
-    epoch2: tuple or NoneType, default None
+    epoch2: str, tuple, list or NoneType, default None
         epoch for output ``delta_time``
     scale: float, default 1.0
         scaling factor for converting time to output units
@@ -289,7 +290,7 @@ def convert_calendar_dates(
         scale: float = 1.0
     ) -> np.ndarray:
     """
-    Calculate the time in time units since ``epoch`` from calendar dates
+    Calculate the time in units since ``epoch`` from calendar dates
 
     Parameters
     ----------
@@ -759,7 +760,7 @@ def to_datetime(self):
         # use nanoseconds to keep as much precision as possible
         delta_time = np.atleast_1d(self.MJD*self.day*1e9).astype(np.int64)
         # return the datetime array
-        return np.array([epoch + np.timedelta64(s, 'ns') for s in delta_time])
+        return np.array(epoch + delta_time.astype('timedelta64[ns]'))
 
     # PURPOSE: calculate the sum of a polynomial function of time
     def polynomial_sum(self, coefficients: list | np.ndarray, t: np.ndarray):

scripts/compute_LPET_elevations.py

@@ -88,7 +88,6 @@
 import sys
 import logging
 import pathlib
-import warnings
 import argparse
 import numpy as np
 import pyTMD
@@ -97,10 +96,7 @@
 try:
     import pyproj
 except (ImportError, ModuleNotFoundError) as exc:
-    warnings.filterwarnings("module")
-    warnings.warn("pyproj not available", ImportWarning)
-# ignore warnings
-warnings.filterwarnings("ignore")
+    logging.critical("pyproj not available")
 
 # PURPOSE: try to get the projection information for the input file
 def get_projection(attributes, PROJECTION):