feat: expose buffer distance to crop tide model data for #367

pyTMD/arguments.py

@@ -39,6 +39,7 @@
 
 UPDATE HISTORY:
     Updated 11/2024: allow variable case for Doodson number formalisms
+        fix species in constituent parameters for complex tides
     Updated 10/2024: can convert Doodson numbers formatted as strings
         update Doodson number conversions to follow Cartwright X=10 convention
         add function to parse Cartwright/Tayler/Edden tables
@@ -1408,7 +1409,7 @@ def _constituent_parameters(c: str, **kwargs):
         'msf', 'sa', 'mt', '2q1']
     # species type (spherical harmonic dependence of quadrupole potential)
     _species = np.array([2, 2, 1, 1, 2, 1, 2, 1, 2, 2, 2, 2, 2, 1, 1,
-        1, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1])
+        1, 1, 0, 0, 0, 4, 4, 4, 6, 8, 3, 6, 2, 3, 0, 0, 0, 1])
     # Load Love numbers
     # alpha = correction factor for first order load tides
     _alpha = np.array([0.693, 0.693, 0.736, 0.695, 0.693, 0.706, 0.693,

pyTMD/compute.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 u"""
 compute.py
-Written by Tyler Sutterley (10/2024)
+Written by Tyler Sutterley (11/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 11/2024: expose buffer distance for cropping tide model data
     Updated 10/2024: compute delta times based on corrections type
         simplify by using wrapper functions to read and interpolate constants
         added option to append equilibrium amplitudes for node tides
@@ -216,6 +217,7 @@ def tide_elevations(
         DEFINITION_FILE: str | pathlib.Path | IOBase | None = None,
         CROP: bool = False,
         BOUNDS: list | np.ndarray | None = None,
+        BUFFER: int | float | None = None,
         EPSG: str | int = 3031,
         EPOCH: list | tuple = (2000, 1, 1, 0, 0, 0),
         TYPE: str | None = 'drift',
@@ -255,6 +257,8 @@ def tide_elevations(
         Crop tide model data to (buffered) bounds
     BOUNDS: list, np.ndarray or NoneType, default None
         Boundaries for cropping tide model data
+    BUFFER: int, float or NoneType, default None
+        Buffer distance for cropping tide model data
     EPSG: int, default: 3031 (Polar Stereographic South, WGS84)
         Input coordinate system
     EPOCH: tuple, default (2000,1,1,0,0,0)
@@ -359,7 +363,7 @@ def tide_elevations(
 
     # read tidal constants and interpolate to grid points
     amp, ph, c = model.extract_constants(lon, lat, type=model.type,
-        crop=CROP, bounds=BOUNDS, method=METHOD,
+        crop=CROP, bounds=BOUNDS, buffer=BUFFER, method=METHOD,
         extrapolate=EXTRAPOLATE, cutoff=CUTOFF,
         append_node=APPEND_NODE, apply_flexure=APPLY_FLEXURE)
     # calculate complex phase in radians for Euler's
@@ -441,6 +445,7 @@ def tide_currents(
         DEFINITION_FILE: str | pathlib.Path | IOBase | None = None,
         CROP: bool = False,
         BOUNDS: list | np.ndarray | None = None,
+        BUFFER: int | float | None = None,
         EPSG: str | int = 3031,
         EPOCH: list | tuple = (2000, 1, 1, 0, 0, 0),
         TYPE: str | None = 'drift',
@@ -478,6 +483,8 @@ def tide_currents(
         Crop tide model data to (buffered) bounds
     BOUNDS: list, np.ndarray or NoneType, default None
         Boundaries for cropping tide model data
+    BUFFER: int, float or NoneType, default None
+        Buffer distance for cropping tide model data
     EPSG: int, default: 3031 (Polar Stereographic South, WGS84)
         Input coordinate system
     EPOCH: tuple, default (2000,1,1,0,0,0)
@@ -580,7 +587,7 @@ def tide_currents(
     for t in model.type:
         # read tidal constants and interpolate to grid points
         amp, ph, c = model.extract_constants(lon, lat, type=t,
-            crop=CROP, bounds=BOUNDS, method=METHOD,
+            crop=CROP, bounds=BOUNDS, buffer=BUFFER, method=METHOD,
             extrapolate=EXTRAPOLATE, cutoff=CUTOFF)
         # calculate complex phase in radians for Euler's
         cph = -1j*ph*np.pi/180.0

pyTMD/io/ATLAS.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 u"""
 ATLAS.py
-Written by Tyler Sutterley (10/2024)
+Written by Tyler Sutterley (11/2024)
 
 Reads files for a tidal model and makes initial calculations to run tide program
 Includes functions to extract tidal harmonic constants from OTIS tide models for
@@ -55,6 +55,7 @@
     interpolate.py: interpolation routines for spatial data
 
 UPDATE HISTORY:
+    Updated 11/2024: expose buffer distance for cropping tide model data
     Updated 10/2024: fix error when using default bounds in extract_constants
     Updated 07/2024: added crop and bounds keywords for trimming model data
     Updated 02/2024: changed variable for setting global grid flag to is_global
@@ -164,6 +165,8 @@ def extract_constants(
         Crop tide model data to (buffered) bounds
     bounds: list or NoneType, default None
         Boundaries for cropping tide model data
+    buffer: int, float or NoneType, default None
+        Buffer angle for cropping tide model data
     method: str, default 'spline'
         Interpolation method
 
@@ -196,6 +199,7 @@ def extract_constants(
     kwargs.setdefault('type', 'z')
     kwargs.setdefault('crop', False)
     kwargs.setdefault('bounds', None)
+    kwargs.setdefault('buffer', None)
     kwargs.setdefault('method', 'spline')
     kwargs.setdefault('extrapolate', False)
     kwargs.setdefault('cutoff', 10.0)
@@ -235,6 +239,8 @@ def extract_constants(
     bounds = kwargs['bounds'] or [xmin, xmax, ymin, ymax]
     # grid step size of tide model
     dlon = lon[1] - lon[0]
+    # default buffer if cropping data
+    buffer = kwargs['buffer'] or 4*dlon
     # if global: extend limits
     is_global = False
 
@@ -244,7 +250,7 @@ def extract_constants(
         mlon, mlat = np.copy(lon), np.copy(lat)
         bathymetry, lon, lat = _crop(bathymetry, mlon, mlat,
             bounds=bounds,
-            buffer=4*dlon
+            buffer=buffer
         )
     elif (np.min(ilon) < 0.0) & (np.max(lon) > 180.0):
         # input points convention (-180:180)
@@ -320,7 +326,7 @@ def extract_constants(
         if kwargs['crop'] and np.any(bounds):
             hc, _, _ = _crop(hc, mlon, mlat,
                 bounds=bounds,
-                buffer=4*dlon
+                buffer=buffer
             )
         # replace original values with extend matrices
         if is_global:
@@ -412,6 +418,8 @@ def read_constants(
         Crop tide model data to (buffered) bounds
     bounds: list or NoneType, default None
         Boundaries for cropping tide model data
+    buffer: int or float, default 0
+        Buffer angle for cropping tide model data
 
     Returns
     -------
@@ -423,6 +431,7 @@ def read_constants(
     kwargs.setdefault('compressed', True)
     kwargs.setdefault('crop', False)
     kwargs.setdefault('bounds', None)
+    kwargs.setdefault('buffer', 0)
 
     # raise warning if model files are entered as a string or path
     if isinstance(model_files, (str, pathlib.Path)):
@@ -444,6 +453,7 @@ def read_constants(
         mlon, mlat = np.copy(lon), np.copy(lat)
         bathymetry, lon, lat = _crop(bathymetry, mlon, mlat,
             bounds=kwargs['bounds'],
+            buffer=kwargs['buffer'],
         )
     # grid step size of tide model
     dlon = lon[1] - lon[0]
@@ -473,6 +483,7 @@ def read_constants(
         if kwargs['crop'] and np.any(kwargs['bounds']):
             hc, lon, lat = _crop(hc, mlon, mlat,
                 bounds=kwargs['bounds'],
+                buffer=kwargs['buffer'],
             )
         # replace original values with extend matrices
         if is_global:

pyTMD/io/FES.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 u"""
 FES.py
-Written by Tyler Sutterley (10/2024)
+Written by Tyler Sutterley (11/2024)
 
 Reads files for a tidal model and makes initial calculations to run tide program
 Includes functions to extract tidal harmonic constants from the
@@ -57,6 +57,7 @@
     interpolate.py: interpolation routines for spatial data
 
 UPDATE HISTORY:
+    Updated 11/2024: expose buffer distance for cropping tide model data
     Updated 10/2024: fix error when using default bounds in extract_constants
     Updated 07/2024: added new FES2022 to available known model versions
         FES2022 have masked longitudes, only extract longitude data
@@ -175,6 +176,8 @@ def extract_constants(
         Crop tide model data to (buffered) bounds
     bounds: list or NoneType, default None
         Boundaries for cropping tide model data
+    buffer: float or NoneType, default None
+        Buffer angle for cropping tide model data
     method: str, default 'spline'
         Interpolation method
 
@@ -203,6 +206,7 @@ def extract_constants(
     kwargs.setdefault('compressed', False)
     kwargs.setdefault('crop', False)
     kwargs.setdefault('bounds', None)
+    kwargs.setdefault('buffer', None)
     kwargs.setdefault('method', 'spline')
     kwargs.setdefault('extrapolate', False)
     kwargs.setdefault('cutoff', 10.0)
@@ -255,12 +259,14 @@ def extract_constants(
             hc, lon, lat = read_netcdf_file(model_file, **kwargs)
         # grid step size of tide model
         dlon = lon[1] - lon[0]
+        # default buffer if cropping data
+        buffer = kwargs['buffer'] or 4*dlon
         # crop tide model data to (buffered) bounds
         # or adjust longitudinal convention to fit tide model
         if kwargs['crop'] and np.any(bounds):
             hc, lon, lat = _crop(hc, lon, lat,
                 bounds=bounds,
-                buffer=4*dlon
+                buffer=buffer,
             )
         elif (np.min(ilon) < 0.0) & (np.max(lon) > 180.0):
             # input points convention (-180:180)
@@ -372,6 +378,8 @@ def read_constants(
         Crop tide model data to (buffered) bounds
     bounds: list or NoneType, default None
         Boundaries for cropping tide model data
+    buffer: int or float, default 0
+        Buffer angle for cropping tide model data
 
     Returns
     -------
@@ -384,6 +392,7 @@ def read_constants(
     kwargs.setdefault('compressed', False)
     kwargs.setdefault('crop', False)
     kwargs.setdefault('bounds', None)
+    kwargs.setdefault('buffer', 0)
 
     # raise warning if model files are entered as a string or path
     if isinstance(model_files, (str, pathlib.Path)):
@@ -414,6 +423,7 @@ def read_constants(
         if kwargs['crop'] and np.any(kwargs['bounds']):
             hc, lon, lat = _crop(hc, lon, lat,
                 bounds=kwargs['bounds'],
+                buffer=kwargs['buffer'],
             )
         # grid step size of tide model
         dlon = lon[1] - lon[0]

pyTMD/io/GOT.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 u"""
 GOT.py
-Written by Tyler Sutterley (10/2024)
+Written by Tyler Sutterley (11/2024)
 
 Reads files for Richard Ray's Global Ocean Tide (GOT) models and makes initial
     calculations to run the tide program
@@ -42,6 +42,7 @@
     interpolate.py: interpolation routines for spatial data
 
 UPDATE HISTORY:
+    Updated 11/2024: expose buffer distance for cropping tide model data
     Updated 10/2024: fix error when using default bounds in extract_constants
     Updated 07/2024: added crop and bounds keywords for trimming model data
         use parse function from constituents class to extract names
@@ -147,6 +148,8 @@ def extract_constants(
         Crop tide model data to (buffered) bounds
     bounds: list or NoneType, default None
         Boundaries for cropping tide model data
+    buffer: int or float, default None
+        Buffer angle for cropping tide model data
     method: str, default 'spline'
         Interpolation method
 
@@ -176,6 +179,7 @@ def extract_constants(
     kwargs.setdefault('compressed', False)
     kwargs.setdefault('crop', False)
     kwargs.setdefault('bounds', None)
+    kwargs.setdefault('buffer', None)
     kwargs.setdefault('method', 'spline')
     kwargs.setdefault('extrapolate', False)
     kwargs.setdefault('cutoff', 10.0)
@@ -232,12 +236,14 @@ def extract_constants(
         constituents.append(cons)
         # grid step size of tide model
         dlon = np.abs(lon[1] - lon[0])
+        # default buffer if cropping data
+        buffer = kwargs['buffer'] or 4*dlon
         # crop tide model data to (buffered) bounds
         # or adjust longitudinal convention to fit tide model
         if kwargs['crop'] and np.any(bounds):
             hc, lon, lat = _crop(hc, lon, lat,
                 bounds=bounds,
-                buffer=4*dlon
+                buffer=buffer,
             )
         elif (np.min(ilon) < 0.0) & (np.max(lon) > 180.0):
             # input points convention (-180:180)
@@ -326,6 +332,8 @@ def read_constants(
         Crop tide model data to (buffered) bounds
     bounds: list or NoneType, default None
         Boundaries for cropping tide model data
+    buffer: int or float, default 0
+        Buffer angle for cropping tide model data
 
     Returns
     -------
@@ -337,6 +345,7 @@ def read_constants(
     kwargs.setdefault('compressed', False)
     kwargs.setdefault('crop', False)
     kwargs.setdefault('bounds', None)
+    kwargs.setdefault('buffer', 0)
 
     # raise warning if model files are entered as a string
     if isinstance(model_files, (str, pathlib.Path)):
@@ -362,6 +371,7 @@ def read_constants(
         if kwargs['crop'] and np.any(kwargs['bounds']):
             hc, lon, lat = _crop(hc, lon, lat,
                 bounds=kwargs['bounds'],
+                buffer=kwargs['buffer'],
             )
         # grid step size of tide model
         dlon = np.abs(lon[1] - lon[0])