fix: scaling factors for TPXO9-atlas currents for #241

refactor: renamed tidal ellipse function
refactor: renamed constituent parameters function
refactor: renamed check tide model points function

doc/source/api_reference/check_tide_points.rst → doc/source/api_reference/check_points.rst

@@ -1,6 +1,6 @@
-=================
-check_tide_points
-=================
+============
+check_points
+============
 
 - Check if points are within a tide model domain
 - Can check OTIS format tidal solutions provided by Ohio State University and ESR
@@ -12,12 +12,11 @@ Calling Sequence
 
 .. code-block:: python
 
-    from pyTMD.check_tide_points import check_tide_points
-    valid = check_tide_points(x, y, DIRECTORY=DIRECTORY,
-        MODEL=MODEL, EPSG=3031)
+    import pyTMD
+    valid = pyTMD.check_points(x, y, DIRECTORY=DIRECTORY, MODEL=MODEL, EPSG=3031)
 
 `Source code`__
 
-.. __: https://github.com/tsutterley/pyTMD/blob/main/pyTMD/check_tide_points.py
+.. __: https://github.com/tsutterley/pyTMD/blob/main/pyTMD/check_points.py
 
-.. autofunction:: pyTMD.check_tide_points
+.. autofunction:: pyTMD.check_points

doc/source/api_reference/compute_tide_corrections.rst

@@ -19,9 +19,10 @@ Calling Sequence
 
 .. code-block:: python
 
-    from pyTMD.compute_tide_corrections import compute_tide_corrections
-    tide = compute_tide_corrections(x, y, delta_time, DIRECTORY=DIRECTORY,
-        MODEL=MODEL, EPOCH=(2000,1,1,0,0,0), EPSG=3031, TYPE='drift')
+    import pyTMD
+    tide = pyTMD.compute_tide_corrections(x, y, delta_time,
+        DIRECTORY=DIRECTORY, MODEL=MODEL, EPOCH=(2000,1,1,0,0,0),
+        EPSG=3031, TYPE='drift')
 
 `Source code`__
 

doc/source/api_reference/tidal_ellipse.rst → doc/source/api_reference/ellipse.rst

@@ -1,6 +1,6 @@
-=============
-tidal_ellipse
-=============
+=======
+ellipse
+=======
 
 - Expresses the amplitudes and phases for the `u` and `v` components in terms of four ellipse parameters using `Foreman's formula <https://www.sciencedirect.com/science/article/pii/0309170889900171>`_
 
@@ -9,11 +9,11 @@ Calling Sequence
 
 .. code-block:: python
 
-    from pyTMD.tidal_ellipse import tidal_ellipse
-    umajor,uminor,uincl,uphase = tidal_ellipse(u,v)
+    import pyTMD
+    umajor,uminor,uincl,uphase = pyTMD.ellipse(u,v)
 
 `Source code`__
 
-.. __: https://github.com/tsutterley/pyTMD/blob/main/pyTMD/tidal_ellipse.py
+.. __: https://github.com/tsutterley/pyTMD/blob/main/pyTMD/ellipse.py
 
-.. autofunction:: pyTMD.tidal_ellipse
+.. autofunction:: pyTMD.ellipse

doc/source/api_reference/predict.rst

@@ -36,6 +36,8 @@ Calling Sequence
 
 .. autofunction:: pyTMD.predict.solid_earth_tide
 
+.. autofunction:: pyTMD.predict._constituent_parameters
+
 .. autofunction:: pyTMD.predict._out_of_phase_diurnal
 
 .. autofunction:: pyTMD.predict._out_of_phase_semidiurnal

doc/source/index.rst

@@ -31,10 +31,11 @@ ocean, load, solid Earth and pole tides
 
     api_reference/arguments.rst
     api_reference/astro.rst
-    api_reference/check_tide_points.rst
+    api_reference/check_points.rst
     api_reference/compute_tide_corrections.rst
     api_reference/constants.rst
     api_reference/convert_crs.rst
+    api_reference/ellipse.rst
     api_reference/eop.rst
     api_reference/interpolate.rst
     api_reference/io/ATLAS.rst
@@ -44,10 +45,8 @@ ocean, load, solid Earth and pole tides
     api_reference/io/constituents.rst
     api_reference/io/model.rst
     api_reference/io/ocean_pole_tide.rst
-    api_reference/load_constituent.rst
     api_reference/predict.rst
     api_reference/spatial.rst
-    api_reference/tidal_ellipse.rst
     api_reference/time.rst
     api_reference/utilities.rst
 

notebooks/Plot Antarctic Tidal Currents.ipynb

@@ -31,7 +31,6 @@
     "- `arguments.py`: load the nodal corrections for tidal constituents  \n",
     "- `astro.py`: computes the basic astronomical mean longitudes  \n",
     "- `convert_crs.py`: convert points to and from Coordinates Reference Systems  \n",
-    "- `load_constituent.py`: loads parameters for a given tidal constituent  \n",
     "- `io.model.py`: retrieves tide model parameters for named tide models\n",
     "- `io.OTIS.py`: extract tidal harmonic constants from OTIS tide models  \n",
     "- `io.ATLAS.py`: extract tidal harmonic constants from ATLAS netcdf models  \n",

notebooks/Plot Arctic Ocean Map.ipynb

@@ -33,7 +33,6 @@
     "- `arguments.py`: load the nodal corrections for tidal constituents  \n",
     "- `astro.py`: computes the basic astronomical mean longitudes  \n",
     "- `convert_crs.py`: convert points to and from Coordinates Reference Systems  \n",
-    "- `load_constituent.py`: loads parameters for a given tidal constituent  \n",
     "- `io.model.py`: retrieves tide model parameters for named tide models  \n",
     "- `io.OTIS.py`: extract tidal harmonic constants from OTIS tide models  \n",
     "- `io.ATLAS.py`: extract tidal harmonic constants from ATLAS netcdf models  \n",

notebooks/Plot Ross Ice Shelf Map.ipynb

@@ -33,7 +33,6 @@
     "- `arguments.py`: load the nodal corrections for tidal constituents  \n",
     "- `astro.py`: computes the basic astronomical mean longitudes  \n",
     "- `convert_crs.py`: convert points to and from Coordinates Reference Systems  \n",
-    "- `load_constituent.py`: loads parameters for a given tidal constituent  \n",
     "- `io.model.py`: retrieves tide model parameters for named tide models\n",
     "- `io.OTIS.py`: extract tidal harmonic constants from OTIS tide models  \n",
     "- `io.ATLAS.py`: extract tidal harmonic constants from ATLAS netcdf models  \n",

notebooks/Plot Tide Forecasts.ipynb

@@ -33,7 +33,6 @@
     "- `arguments.py`: load the nodal corrections for tidal constituents  \n",
     "- `astro.py`: computes the basic astronomical mean longitudes  \n",
     "- `convert_crs.py`: convert points to and from Coordinates Reference Systems  \n",
-    "- `load_constituent.py`: loads parameters for a given tidal constituent  \n",
     "- `io.model.py`: retrieves tide model parameters for named tide models\n",
     "- `io.OTIS.py`: extract tidal harmonic constants from OTIS tide models  \n",
     "- `io.ATLAS.py`: extract tidal harmonic constants from ATLAS netCDF4 tide models  \n",

pyTMD/__init__.py

@@ -22,7 +22,7 @@
 import pyTMD.version
 from pyTMD import io
 from pyTMD.arguments import arguments
-from pyTMD.check_tide_points import check_tide_points
+from pyTMD.check_points import check_points
 from pyTMD.compute_tide_corrections import (
     compute_corrections,
     compute_tide_corrections,
@@ -36,8 +36,7 @@
     _ellipsoids
 )
 from pyTMD.convert_crs import convert_crs
-from pyTMD.load_constituent import load_constituent
-from pyTMD.tidal_ellipse import tidal_ellipse
+from pyTMD.ellipse import ellipse
 
 # Deprecated functions
 from pyTMD.calc_astrol_longitudes import calc_astrol_longitudes

pyTMD/check_tide_points.py → pyTMD/check_points.py

@@ -1,6 +1,6 @@
 #!/usr/bin/env python
 u"""
-check_tide_points.py
+check_points.py
 Written by Tyler Sutterley (04/2023)
 Check if points are within a tide model domain
 
@@ -86,7 +86,7 @@
     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,
+def check_points(x: np.ndarray, y: np.ndarray,
         DIRECTORY: str | pathlib.Path | None = None,
         MODEL: str | None = None,
         ATLAS_FORMAT: str = 'netcdf',

pyTMD/compute_tide_corrections.py

@@ -50,7 +50,6 @@
     arguments.py: load the nodal corrections for tidal constituents
     astro.py: computes the basic astronomical mean longitudes
     convert_crs.py: convert points to and from Coordinates Reference Systems
-    load_constituent.py: loads parameters for a given tidal constituent
     predict.py: predict tide values using harmonic constants
     io/model.py: retrieves tide model parameters for named tide models
     io/OTIS.py: extract tidal harmonic constants from OTIS tide models

pyTMD/tidal_ellipse.py → pyTMD/ellipse.py

@@ -1,11 +1,11 @@
 #!/usr/bin/env python
 u"""
-tidal_ellipse.py (03/2023)
+ellipse.py (03/2023)
 Expresses the amplitudes and phases for the u and v components in terms of
     four ellipse parameters using Foreman's formula
 
 CALLING SEQUENCE:
-    umajor,uminor,uincl,uphase = tidal_ellipse(u,v)
+    umajor,uminor,uincl,uphase = ellipse(u,v)
 
 INPUTS:
     u: zonal current (EW)
@@ -24,6 +24,7 @@
         https://doi.org/10.1016/0309-1708(89)90017-1
 
 UPDATE HISTORY:
+    Updated 09/2023: renamed to ellipse.py (from tidal_ellipse.py)
     Updated 03/2023: add basic variable typing to function inputs
     Updated 04/2022: updated docstrings to numpy documentation format
     Written 07/2020
@@ -32,7 +33,7 @@
 
 import numpy as np
 
-def tidal_ellipse(u: np.ndarray, v: np.ndarray):
+def ellipse(u: np.ndarray, v: np.ndarray):
     """
     Expresses the amplitudes and phases for the u and v components in terms of
     four ellipse parameters using Foreman's formula [1]_

pyTMD/interpolate.py

@@ -107,7 +107,6 @@ def bilinear(
     # return interpolated values
     return data
 
-
 def spline(
         ilon: np.ndarray,
         ilat: np.ndarray,

pyTMD/io/model.py

@@ -1,11 +1,12 @@
 #!/usr/bin/env python
 u"""
 model.py
-Written by Tyler Sutterley (08/2023)
+Written by Tyler Sutterley (09/2023)
 Retrieves tide model parameters for named tide models and
     from model definition files
 
 UPDATE HISTORY:
+    Updated 09/2023: fix scale values for TPXO9-atlas currents
     Updated 08/2023: changed ESR netCDF4 format to TMD3 format
         updated filenames for CATS2008-v2023 to final version
     Updated 06/2023: remap FES2012 e2 constituent to eps2
@@ -726,7 +727,7 @@ def current(self, m: str):
             self.model_file = dict(u=self.pathfinder(model_files),
                                    v=self.pathfinder(model_files))
             self.projection = '4326'
-            self.scale = 1.0/100.0
+            self.scale = 1e-4
             self.version = 'v1'
             # model description and references
             self.reference = ('http://volkov.oce.orst.edu/tides/'
@@ -743,7 +744,7 @@ def current(self, m: str):
             self.model_file = dict(u=self.pathfinder(model_files),
                                    v=self.pathfinder(model_files))
             self.projection = '4326'
-            self.scale = 1.0/100.0
+            self.scale = 1e-4
             self.version = 'v2'
             # model description and references
             self.reference = 'https://www.tpxo.net/global/tpxo9-atlas'
@@ -760,7 +761,7 @@ def current(self, m: str):
             self.model_file = dict(u=self.pathfinder(model_files),
                                    v=self.pathfinder(model_files))
             self.projection = '4326'
-            self.scale = 1.0/100.0
+            self.scale = 1e-4
             self.version = 'v3'
             # model description and references
             self.reference = 'https://www.tpxo.net/global/tpxo9-atlas'
@@ -777,7 +778,7 @@ def current(self, m: str):
             self.model_file = dict(u=self.pathfinder(model_files),
                                    v=self.pathfinder(model_files))
             self.projection = '4326'
-            self.scale = 1.0/100.0
+            self.scale = 1e-4
             self.version = 'v4'
             # model description and references
             self.reference = 'https://www.tpxo.net/global/tpxo9-atlas'
@@ -795,7 +796,7 @@ def current(self, m: str):
             self.model_file = dict(u=self.pathfinder(model_files),
                                    v=self.pathfinder(model_files))
             self.projection = '4326'
-            self.scale = 1.0/100.0
+            self.scale = 1e-4
             self.version = 'v5'
             # model description and references
             self.reference = 'https://www.tpxo.net/global/tpxo9-atlas'

pyTMD/load_constituent.py

@@ -1,6 +1,6 @@
 #!/usr/bin/env python
 u"""
-load_constituent.py (04/2022)
+load_constituent.py (09/2023)
 Loads parameters for a given tidal constituent
 
 CALLING SEQUENCE:
@@ -26,11 +26,13 @@
         https://numpy.org/doc/stable/user/numpy-for-matlab-users.html
 
 UPDATE HISTORY:
+    Updated 09/2023: deprecated in favor of pyTMD.predict function
     Updated 04/2022: updated docstrings to numpy documentation format
     Updated 07/2020: add more constituents from OTPSnc and function docstrings
     Updated 09/2017: Rewritten in Python
 """
-import numpy as np
+import warnings
+import pyTMD.predict
 
 def load_constituent(c):
     """
@@ -63,51 +65,8 @@ def load_constituent(c):
 
     .. __: https://doi.org/10.1175/1520-0426(2002)019<0183:EIMOBO>2.0.CO;2
     """
-    # constituents array that are included in tidal program
-    cindex = ['m2','s2','k1','o1','n2','p1','k2','q1','2n2','mu2','nu2','l2',
-        't2','j1','m1','oo1','rho1','mf','mm','ssa','m4','ms4','mn4','m6','m8',
-        'mk3','s6','2sm2','2mk3']
-    # species type (spherical harmonic dependence of quadrupole potential)
-    species_all = 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])
-    # loading love number
-    # alpha = correction factor for first order load tides
-    alpha_all = np.array([0.693,0.693,0.736,0.695,0.693,0.706,0.693,0.695,0.693,
-        0.693,0.693,0.693,0.693,0.695,0.695,0.695,0.695,0.693,0.693,0.693,
-        0.693,0.693,0.693,0.693,0.693,0.693,0.693,0.693,0.693])
-    # omega: angular frequency of constituent, in radians
-    omega_all = np.array([1.405189e-04,1.454441e-04,7.292117e-05,6.759774e-05,
-        1.378797e-04,7.252295e-05,1.458423e-04,6.495854e-05,1.352405e-04,
-        1.355937e-04,1.382329e-04,1.431581e-04,1.452450e-04,7.556036e-05,
-        7.028195e-05,7.824458e-05,6.531174e-05,0.053234e-04,0.026392e-04,
-        0.003982e-04,2.810377e-04,2.859630e-04,2.783984e-04,4.215566e-04,
-        5.620755e-04,2.134402e-04,4.363323e-04,1.503693e-04,2.081166e-04])
-    # Astronomical arguments (relative to t0 = 1 Jan 0:00 1992)
-    # phases for each constituent are referred to the time when the phase of
-    # the forcing for that constituent is zero on the Greenwich meridian
-    phase_all = np.array([1.731557546,0.000000000,0.173003674,1.558553872,
-        6.050721243,6.110181633,3.487600001,5.877717569,4.086699633,
-        3.463115091,5.427136701,0.553986502,0.052841931,2.137025284,
-        2.436575100,1.929046130,5.254133027,1.756042456,1.964021610,
-        3.487600001,3.463115091,1.731557546,1.499093481,5.194672637,
-        6.926230184,1.904561220,0.000000000,4.551627762,3.809122439])
-    # amplitudes of equilibrium tide in m
-    # amplitude_all = np.array([0.242334,0.112743,0.141565,0.100661,0.046397,
-    amplitude_all = np.array([0.2441,0.112743,0.141565,0.100661,0.046397,
-        0.046848,0.030684,0.019273,0.006141,0.007408,0.008811,0.006931,0.006608,
-        0.007915,0.007915,0.004338,0.003661,0.042041,0.022191,0.019567,0.,0.,0.,
-        0.,0.,0.,0.,0.,0.])
-
-    # map between input constituent and cindex
-    j = [j for j,val in enumerate(cindex) if (val == c.lower())]
-    # set the values for the constituent
-    if j:
-        amplitude, = amplitude_all[j]
-        phase, = phase_all[j]
-        omega, = omega_all[j]
-        alpha, = alpha_all[j]
-        species, = species_all[j]
-    else:
-        amplitude = 0.0; phase = 0.0; omega = 0.0; alpha = 0.0; species = 0
-    # return the values for the constituent
-    return (amplitude, phase, omega, alpha, species)
+    # raise warning for deprecated function call
+    warnings.warn("Deprecated. Please use pyTMD.predict instead",
+        DeprecationWarning)
+    # call updated function to not break current workflows
+    return pyTMD.predict._constituent_parameters(c)