feat: include inference of eps2 and eta2 with GOT models (#319)

* feat: add attribute for minor constituents to model object
* feat: allow inferring only specific minor constituents
* feat: allow searching over iterable glob strings in definition files for #318
* feat: add option to auto-detect definition file format for #318
* feat: add back nodal arguments from PERTH3 for backwards compatibility
* chore: trim trim trailing whitespace
* docs: add GOT5.5 to getting started

doc/source/getting_started/Getting-Started.rst

@@ -61,6 +61,8 @@ Presently, the following models and their directories parameterized within ``pyT
     * `GOT4.8_load <https://earth.gsfc.nasa.gov/sites/default/files/2022-07/got4.8.tar.gz>`_: ``<path_to_tide_models>/got4.8/grids_loadtide/``
     * `GOT4.10 <https://earth.gsfc.nasa.gov/sites/default/files/2022-07/got4.10c.tar.gz>`_: ``<path_to_tide_models>/GOT4.10c/grids_oceantide/``
     * `GOT4.10_load <https://earth.gsfc.nasa.gov/sites/default/files/2022-07/got4.10c.tar.gz>`_: ``<path_to_tide_models>/GOT4.10c/grids_loadtide/``
+    * `GOT5.5 <https://earth.gsfc.nasa.gov/sites/default/files/2024-07/GOT5.5.tar%201.gz>`_: ``<path_to_tide_models>/GOT5.5/ocean_tides/``
+    * `GOT5.5_load <https://earth.gsfc.nasa.gov/sites/default/files/2024-07/GOT5.5.tar%201.gz>`_: ``<path_to_tide_models>/GOT5.5/load_tides/``
 
 - Finite Element Solution tide models [Lyard2020]_
 

pyTMD/compute.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 u"""
 compute.py
-Written by Tyler Sutterley (07/2024)
+Written by Tyler Sutterley (08/2024)
 Calculates tidal elevations for correcting elevation or imagery data
 Calculates tidal currents at locations and times
 
@@ -60,6 +60,7 @@
     interpolate.py: interpolation routines for spatial data
 
 UPDATE HISTORY:
+    Updated 08/2024: allow inferring only specific minor constituents
     Updated 07/2024: assert that data type is a known value
         make number of days to convert JD to MJD a variable
         added option to crop tide models to the domain of the input data
@@ -191,7 +192,7 @@ def tide_elevations(
         ATLAS_FORMAT: str = 'ATLAS-netcdf',
         GZIP: bool = False,
         DEFINITION_FILE: str | pathlib.Path | IOBase | None = None,
-        DEFINITION_FORMAT: str = 'ascii',
+        DEFINITION_FORMAT: str = 'auto',
         CROP: bool = False,
         BOUNDS: list | np.ndarray | None = None,
         EPSG: str | int = 3031,
@@ -202,6 +203,7 @@ def tide_elevations(
         EXTRAPOLATE: bool = False,
         CUTOFF: int | float=10.0,
         INFER_MINOR: bool = True,
+        MINOR_CONSTITUENTS: list | None = None,
         APPLY_FLEXURE: bool = False,
         FILL_VALUE: float = np.nan,
         **kwargs
@@ -228,11 +230,12 @@ def tide_elevations(
         Tide model files are gzip compressed
     DEFINITION_FILE: str, pathlib.Path, io.IOBase or NoneType, default None
         Tide model definition file for use
-    DEFINITION_FORMAT: str, default 'ascii'
+    DEFINITION_FORMAT: str, default 'auto'
         Format for model definition file
 
             - ``'ascii'``: tab-delimited definition file
             - ``'json'``: JSON formatted definition file
+            - ``'auto'``: auto-detect the definition file format
     CROP: bool, default False
         Crop tide model data to (buffered) bounds
     BOUNDS: list, np.ndarray or NoneType, default None
@@ -271,6 +274,8 @@ def tide_elevations(
         Set to ``np.inf`` to extrapolate for all points
     INFER_MINOR: bool, default True
         Infer the height values for minor tidal constituents
+    MINOR_CONSTITUENTS: list or None, default None
+        Specify constituents to infer
     APPLY_FLEXURE: bool, default False
         Apply ice flexure scaling factor to height values
 
@@ -346,7 +351,7 @@ def tide_elevations(
         deltat = np.zeros((nt), dtype=np.float64)
     elif model.format in ('ATLAS-netcdf',):
         amp,ph,D,c = pyTMD.io.ATLAS.extract_constants(lon, lat, model.grid_file,
-            model.model_file, type=model.type, crop=CROP, bounds=BOUNDS, 
+            model.model_file, type=model.type, crop=CROP, bounds=BOUNDS,
             method=METHOD, extrapolate=EXTRAPOLATE, cutoff=CUTOFF,
             scale=model.scale, compressed=model.compressed)
         # use delta time at 2000.0 to match TMD outputs
@@ -374,6 +379,7 @@ def tide_elevations(
     hc = amp*np.exp(cph)
 
     # predict tidal elevations at time
+    minor_constituents = MINOR_CONSTITUENTS or model.minor
     if (TYPE.lower() == 'grid'):
         ny,nx = np.shape(x)
         tide = np.ma.zeros((ny,nx,nt),fill_value=FILL_VALUE)
@@ -384,7 +390,8 @@ def tide_elevations(
             # calculate values for minor constituents by inferrence
             if INFER_MINOR:
                 MINOR = pyTMD.predict.infer_minor(ts.tide[i], hc, c,
-                    deltat=deltat[i], corrections=corrections)
+                    deltat=deltat[i], corrections=corrections,
+                    minor=minor_constituents)
             else:
                 MINOR = np.ma.zeros_like(TIDE)
             # add major and minor components and reform grid
@@ -398,7 +405,8 @@ def tide_elevations(
         # calculate values for minor constituents by inferrence
         if INFER_MINOR:
             minor = pyTMD.predict.infer_minor(ts.tide, hc, c,
-                deltat=deltat, corrections=corrections)
+                deltat=deltat, corrections=corrections,
+                minor=minor_constituents)
             tide.data[:] += minor.data[:]
     elif (TYPE.lower() == 'time series'):
         nstation = len(x)
@@ -411,7 +419,8 @@ def tide_elevations(
             # calculate values for minor constituents by inferrence
             if INFER_MINOR:
                 MINOR = pyTMD.predict.infer_minor(ts.tide, HC, c,
-                    deltat=deltat, corrections=corrections)
+                    deltat=deltat, corrections=corrections,
+                    minor=minor_constituents)
             else:
                 MINOR = np.ma.zeros_like(TIDE)
             # add major and minor components
@@ -442,6 +451,7 @@ def tide_currents(
         EXTRAPOLATE: bool = False,
         CUTOFF: int | float=10.0,
         INFER_MINOR: bool = True,
+        MINOR_CONSTITUENTS: list | None = None,
         FILL_VALUE: float = np.nan,
         **kwargs
     ):
@@ -467,11 +477,12 @@ def tide_currents(
         Tide model files are gzip compressed
     DEFINITION_FILE: str, pathlib.Path, io.IOBase or NoneType, default None
         Tide model definition file for use
-    DEFINITION_FORMAT: str, default 'ascii'
+    DEFINITION_FORMAT: str, default 'auto'
         Format for model definition file
 
             - ``'ascii'``: tab-delimited definition file
             - ``'json'``: JSON formatted definition file
+            - ``'auto'``: auto-detect the definition file format
     CROP: bool, default False
         Crop tide model data to (buffered) bounds
     BOUNDS: list, np.ndarray or NoneType, default None
@@ -510,6 +521,8 @@ def tide_currents(
         Set to ``np.inf`` to extrapolate for all points
     INFER_MINOR: bool, default True
         Infer the height values for minor tidal constituents
+    MINOR_CONSTITUENTS: list or None, default None
+        Specify constituents to infer
     FILL_VALUE: float, default np.nan
         Output invalid value
 
@@ -585,14 +598,14 @@ def tide_currents(
             deltat = np.zeros((nt), dtype=np.float64)
         elif model.format in ('ATLAS-netcdf',):
             amp,ph,D,c = pyTMD.io.ATLAS.extract_constants(lon, lat, model.grid_file,
-                model.model_file[t], type=t, crop=CROP, bounds=BOUNDS, 
+                model.model_file[t], type=t, crop=CROP, bounds=BOUNDS,
                 method=METHOD, extrapolate=EXTRAPOLATE, cutoff=CUTOFF,
                 scale=model.scale, compressed=model.compressed)
             # use delta time at 2000.0 to match TMD outputs
             deltat = np.zeros((nt), dtype=np.float64)
         elif model.format in ('FES-ascii', 'FES-netcdf'):
             amp,ph = pyTMD.io.FES.extract_constants(lon, lat, model.model_file[t],
-                type=t, version=model.version, crop=CROP, bounds=BOUNDS, 
+                type=t, version=model.version, crop=CROP, bounds=BOUNDS,
                 method=METHOD, extrapolate=EXTRAPOLATE, cutoff=CUTOFF,
                 scale=model.scale, compressed=model.compressed)
             # available model constituents
@@ -606,6 +619,7 @@ def tide_currents(
         hc = amp*np.exp(cph)
 
         # predict tidal currents at time
+        minor_constituents = MINOR_CONSTITUENTS or model.minor
         if (TYPE.lower() == 'grid'):
             ny,nx = np.shape(x)
             tide[t] = np.ma.zeros((ny,nx,nt),fill_value=FILL_VALUE)
@@ -616,7 +630,8 @@ def tide_currents(
                 # calculate values for minor constituents by inferrence
                 if INFER_MINOR:
                     MINOR = pyTMD.predict.infer_minor(ts.tide[i], hc, c,
-                        deltat=deltat[i], corrections=corrections)
+                        deltat=deltat[i], corrections=corrections,
+                        minor=minor_constituents)
                 else:
                     MINOR = np.ma.zeros_like(TIDE)
                 # add major and minor components and reform grid
@@ -630,7 +645,8 @@ def tide_currents(
             # calculate values for minor constituents by inferrence
             if INFER_MINOR:
                 minor = pyTMD.predict.infer_minor(ts.tide, hc, c,
-                    deltat=deltat, corrections=corrections)
+                    deltat=deltat, corrections=corrections,
+                    minor=minor_constituents)
                 tide[t].data[:] += minor.data[:]
         elif (TYPE.lower() == 'time series'):
             nstation = len(x)
@@ -643,7 +659,8 @@ def tide_currents(
                 # calculate values for minor constituents by inferrence
                 if INFER_MINOR:
                     MINOR = pyTMD.predict.infer_minor(ts.tide, HC, c,
-                        deltat=deltat, corrections=corrections)
+                        deltat=deltat, corrections=corrections,
+                        minor=minor_constituents)
                 else:
                     MINOR = np.ma.zeros_like(TIDE)
                 # add major and minor components

pyTMD/io/constituents.py

@@ -260,7 +260,7 @@ def __next__(self):
         constituent = getattr(self, field)
         self.__index__ += 1
         return (field, constituent)
-    
+
     def __getitem__(self, key):
         return getattr(self, key)