fix: scaling factors for TPXO9-atlas currents for #241 (#243)

* refactor: renamed tidal ellipse function
* refactor: renamed constituent parameters function
* refactor: renamed check tide model points function
* fix: output ATLAS netCDFs as `nx`, `ny` to match original files

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/ATLAS.py

@@ -911,11 +911,11 @@ def output_netcdf_grid(
     nc['lat_u'] = fileID.createVariable('lat_u', lat_u.dtype, ('ny',))
     nc['lon_v'] = fileID.createVariable('lon_v', lon_v.dtype, ('nx',))
     nc['lat_v'] = fileID.createVariable('lat_v', lat_v.dtype, ('ny',))
-    nc['hz'] = fileID.createVariable('hz', hz.dtype, ('ny','nx',),
+    nc['hz'] = fileID.createVariable('hz', hz.dtype, ('nx','ny',),
         fill_value=0, zlib=True)
-    nc['hu'] = fileID.createVariable('hu', hu.dtype, ('ny','nx',),
+    nc['hu'] = fileID.createVariable('hu', hu.dtype, ('nx','ny',),
         fill_value=0, zlib=True)
-    nc['hv'] = fileID.createVariable('hv', hv.dtype, ('ny','nx',),
+    nc['hv'] = fileID.createVariable('hv', hv.dtype, ('nx','ny',),
         fill_value=0, zlib=True)
     # filling the NetCDF variables
     nc['lon_z'][:] = lon_z[:]
@@ -924,9 +924,9 @@ def output_netcdf_grid(
     nc['lat_u'][:] = lat_u[:]
     nc['lon_v'][:] = lon_v[:]
     nc['lat_v'][:] = lat_v[:]
-    nc['hz'][:] = hz[:]
-    nc['hu'][:] = hu[:]
-    nc['hv'][:] = hv[:]
+    nc['hz'][:] = hz[:].T
+    nc['hu'][:] = hu[:].T
+    nc['hv'][:] = hv[:].T
     # define variable attributes
     for TYPE in ('z','u','v'):
         # set variable attributes for coordinates
@@ -992,15 +992,15 @@ def output_netcdf_elevation(
     nc = {}
     nc['lon_z'] = fileID.createVariable('lon_z', lon_z.dtype, ('nx',))
     nc['lat_z'] = fileID.createVariable('lat_z', lat_z.dtype, ('ny',))
-    nc['hRe'] = fileID.createVariable('hRe', h.real.dtype, ('ny','nx',),
+    nc['hRe'] = fileID.createVariable('hRe', h.real.dtype, ('nx','ny',),
         fill_value=0, zlib=True)
-    nc['hIm'] = fileID.createVariable('hIm', h.imag.dtype, ('ny','nx',),
+    nc['hIm'] = fileID.createVariable('hIm', h.imag.dtype, ('nx','ny',),
         fill_value=0, zlib=True)
     # filling the NetCDF variables
     nc['lon_z'][:] = lon_z[:]
     nc['lat_z'][:] = lat_z[:]
-    nc['hRe'][:] = h.real[:]
-    nc['hIm'][:] = h.imag[:]
+    nc['hRe'][:] = h.real[:].T
+    nc['hIm'][:] = h.imag[:].T
     # define variable attributes
     complexpart = dict(Re='Real part', Im='Imag part')
     # set variable attributes for coordinates
@@ -1087,23 +1087,23 @@ def output_netcdf_transport(
     nc['lat_u'] = fileID.createVariable('lat_u', lat_u.dtype, ('ny',))
     nc['lon_v'] = fileID.createVariable('lon_v', lon_v.dtype, ('nx',))
     nc['lat_v'] = fileID.createVariable('lat_v', lat_v.dtype, ('ny',))
-    nc['uRe'] = fileID.createVariable('uRe', u.real.dtype, ('ny','nx',),
+    nc['uRe'] = fileID.createVariable('uRe', u.real.dtype, ('nx','ny',),
         fill_value=0, zlib=True)
-    nc['uIm'] = fileID.createVariable('uIm', u.imag.dtype, ('ny','nx',),
+    nc['uIm'] = fileID.createVariable('uIm', u.imag.dtype, ('nx','ny',),
         fill_value=0, zlib=True)
-    nc['vRe'] = fileID.createVariable('vRe', v.real.dtype, ('ny','nx',),
+    nc['vRe'] = fileID.createVariable('vRe', v.real.dtype, ('nx','ny',),
         fill_value=0, zlib=True)
-    nc['vIm'] = fileID.createVariable('vIm', v.imag.dtype, ('ny','nx',),
+    nc['vIm'] = fileID.createVariable('vIm', v.imag.dtype, ('nx','ny',),
         fill_value=0, zlib=True)
     # filling the NetCDF variables
     nc['lon_u'][:] = lon_u[:]
     nc['lat_u'][:] = lat_u[:]
     nc['lon_v'][:] = lon_v[:]
     nc['lat_v'][:] = lat_v[:]
-    nc['uRe'][:] = u.real[:]
-    nc['uIm'][:] = u.imag[:]
-    nc['vRe'][:] = v.real[:]
-    nc['vIm'][:] = v.imag[:]
+    nc['uRe'][:] = u.real[:].T
+    nc['uIm'][:] = u.imag[:].T
+    nc['vRe'][:] = v.real[:].T
+    nc['vIm'][:] = v.imag[:].T
     # define variable attributes
     direction = dict(u='WE', v='SN')
     complexpart = dict(Re='Real part', Im='Imag part')

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'