fix: latest TMD3 current variable names for #370

feat: add tidal aliasing period function
fix: add latitude and longitude as potential dimension names

doc/source/api_reference/arguments.rst

@@ -30,6 +30,8 @@ Calling Sequence
 
 .. autofunction:: pyTMD.arguments.frequency
 
+.. autofunction:: pyTMD.arguments.aliasing_period
+
 .. autofunction:: pyTMD.arguments._arguments_table
 
 .. autofunction:: pyTMD.arguments._minor_table

doc/source/api_reference/math.rst

@@ -22,6 +22,8 @@ Calling Sequence
 
 .. autofunction:: pyTMD.math.rotate
 
+.. autofunction:: pyTMD.math.aliasing
+
 .. autofunction:: pyTMD.math.legendre
 
 .. autofunction:: pyTMD.math.sph_harm

doc/source/user_guide/Examples.rst

@@ -70,7 +70,6 @@ The available examples include:
       :link: ../notebooks/Plot-Ocean-Pole-Tide-Map.html
       :link-alt: Plots maps of the real and imaginary geocentric pole tide admittance functions
 
-
     .. grid-item-card::  Plot Ross Ice Shelf Map
       :text-align: center
       :img-top: ../_assets/ross_ice_shelf_map.png
@@ -83,14 +82,17 @@ The available examples include:
       :text-align: center
       :img-top: ../_assets/tide_forecasts.png
       :link: ../notebooks/Plot-Tide-Forecasts.html
+      :link-alt: Plots a weekly forecast of tidal displacements at a given location
 
     .. grid-item-card::  Plot Tide Form Factor
       :text-align: center
       :img-top: ../_assets/tide_form_factor.png
       :link: ../notebooks/Plot-Tide-Form-Factor.html
+      :link-alt: Plots maps of the dominant tidal species
 
     .. grid-item-card::  Solve Synthetic Tides
       :text-align: center
       :img-top: ../_assets/solve_synthetic_tides.png
       :link: ../notebooks/Solve-Synthetic-Tides.html
+      :link-alt: Solves for the amplitude and phase of harmonic constituents at a given location
 

pyTMD/arguments.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 u"""
 arguments.py
-Written by Tyler Sutterley (11/2024)
+Written by Tyler Sutterley (12/2024)
 Calculates the nodal corrections for tidal constituents
 Modification of ARGUMENTS fortran subroutine by Richard Ray 03/1999
 
@@ -27,6 +27,7 @@
 
 PROGRAM DEPENDENCIES:
     astro.py: computes the basic astronomical mean longitudes
+    math.py: Special functions of mathematical physics
 
 REFERENCES:
     A. T. Doodson and H. Warburg, "Admiralty Manual of Tides", HMSO, (1941).
@@ -38,6 +39,7 @@
         Ocean Tides", Journal of Atmospheric and Oceanic Technology, (2002).
 
 UPDATE HISTORY:
+    Updated 12/2024: added function to calculate tidal aliasing periods
     Updated 11/2024: allow variable case for Doodson number formalisms
         fix species in constituent parameters for complex tides
         move body tide Love/Shida numbers from predict module
@@ -91,6 +93,7 @@
     "doodson_number",
     "nodal",
     "frequency",
+    "aliasing_period",
     "_arguments_table",
     "_minor_table",
     "_constituent_parameters",
@@ -1287,6 +1290,45 @@ def frequency(
     omega = 2.0*np.pi*fd/360.0
     return omega
 
+def aliasing_period(
+        constituents: list | np.ndarray,
+        sampling: float | np.ndarray,
+        **kwargs
+    ):
+    """
+    Calculates the tidal aliasing for a repeat period
+
+    Parameters
+    ----------
+    constituents: list
+        tidal constituent IDs
+    sampling: float
+        sampling repeat period in seconds
+    corrections: str, default 'OTIS'
+        use nodal corrections from OTIS, FES or GOT models
+    M1: str, default 'perth5'
+        coefficients to use for M1 tides
+
+                - ``'Doodson'``
+                - ``'Ray'``
+                - ``'perth5'``
+
+    Returns
+    -------
+    period: np.ndarray
+        tidal aliasing period in seconds
+    """
+    # get the angular frequency for tidal constituents
+    omega = frequency(constituents, **kwargs)
+    # convert to cycles per second
+    f = omega/(2.0*np.pi)
+    # calculate the sampling frequency
+    fs = 1.0/sampling
+    # calculate the aliasing period
+    period = 1.0/pyTMD.math.aliasing(f, fs)
+    # reutrn the aliasing period
+    return period
+
 def _arguments_table(**kwargs):
     """
     Arguments table for tidal constituents [1]_ [2]_

pyTMD/io/OTIS.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 u"""
 OTIS.py
-Written by Tyler Sutterley (11/2024)
+Written by Tyler Sutterley (12/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
@@ -58,6 +58,7 @@
     interpolate.py: interpolation routines for spatial data
 
 UPDATE HISTORY:
+    Updated 12/2024: released version of TMD3 has different variable names
     Updated 11/2024: expose buffer distance for cropping tide model data
     Updated 10/2024: save latitude and longitude to output constituent object
         fix error when using default bounds in extract_constants
@@ -1731,11 +1732,11 @@ def read_netcdf_file(
         hc.data.real[:,:] = fileID.variables['hRe'][ic,::-1,:]
         hc.data.imag[:,:] = -fileID.variables['hIm'][ic,::-1,:]
     elif variable in ('U','u'):
-        hc.data.real[:,:] = fileID.variables['uRe'][ic,::-1,:]
-        hc.data.imag[:,:] = -fileID.variables['uIm'][ic,::-1,:]
+        hc.data.real[:,:] = fileID.variables['URe'][ic,::-1,:]
+        hc.data.imag[:,:] = -fileID.variables['UIm'][ic,::-1,:]
     elif variable in ('V','v'):
-        hc.data.real[:,:] = fileID.variables['vRe'][ic,::-1,:]
-        hc.data.imag[:,:] = -fileID.variables['vIm'][ic,::-1,:]
+        hc.data.real[:,:] = fileID.variables['VRe'][ic,::-1,:]
+        hc.data.imag[:,:] = -fileID.variables['VIm'][ic,::-1,:]
     # close the file
     fileID.close()
     # return output variables

pyTMD/math.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 u"""
 math.py
-Written by Tyler Sutterley (11/2024)
+Written by Tyler Sutterley (12/2024)
 Special functions of mathematical physics
 
 PYTHON DEPENDENCIES:
@@ -12,6 +12,7 @@
         https://docs.scipy.org/doc/
 
 UPDATE HISTORY:
+    Updated 12/2024: added function to calculate an aliasing frequency
     Written 11/2024
 """
 import numpy as np
@@ -21,6 +22,7 @@
     "polynomial_sum",
     "normalize_angle",
     "rotate",
+    "aliasing",
     "legendre",
     "sph_harm"
 ]
@@ -109,6 +111,28 @@ def rotate(
     # return the rotation matrix
     return R
 
+def aliasing(
+        f: float,
+        fs: float
+    ) -> float:
+    """
+    Calculate the aliasing frequency of a signal
+
+    Parameters
+    ----------
+    f: float
+        Frequency of the signal
+    fs: float
+        Sampling frequency of the signal
+
+    Returns
+    -------
+    fa: float
+        Aliasing frequency of the signal
+    """
+    fa = np.abs(f - fs*np.round(f/fs))
+    return fa
+
 def legendre(
         l: int,
         x: np.ndarray,

pyTMD/spatial.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 u"""
 spatial.py
-Written by Tyler Sutterley (11/2024)
+Written by Tyler Sutterley (12/2024)
 
 Utilities for reading, writing and operating on spatial data
 
@@ -30,6 +30,7 @@
     crs.py: Coordinate Reference System (CRS) routines
 
 UPDATE HISTORY:
+    Updated 12/2024: add latitude and longitude as potential dimension names
     Updated 11/2024: added function to calculate the altitude and azimuth
     Updated 09/2024: deprecation fix case where an array is output to scalars
     Updated 08/2024: changed from 'geotiff' to 'GTiff' and 'cog' formats
@@ -979,7 +980,7 @@ def _grid_netCDF4(fileID, output: dict, attributes: dict, **kwargs):
         python dictionary of output attributes
     """
     # output data fields
-    dimensions = ['time', 'lon', 'lat', 't', 'x', 'y']
+    dimensions = ['t', 'time', 'lon', 'longitude', 'x', 'lat', 'latitude', 'y']
     crs = ['crs', 'crs_wkt', 'crs_proj4', 'projection']
     fields = sorted(set(output.keys()) - set(dimensions) - set(crs))
     # Defining the NetCDF dimensions
@@ -1029,7 +1030,7 @@ def _time_series_netCDF4(fileID, output: dict, attributes: dict, **kwargs):
         python dictionary of output attributes
     """
     # output data fields
-    dimensions = ['time', 'lon', 'lat', 't', 'x', 'y']
+    dimensions = ['t', 'time', 'lon', 'longitude', 'x', 'lat', 'latitude', 'y']
     crs = ['crs', 'crs_wkt', 'crs_proj4', 'projection']
     fields = sorted(set(output.keys()) - set(dimensions) - set(crs))
     # Defining the NetCDF dimensions
@@ -1249,7 +1250,7 @@ def to_parquet(
     if kwargs['geoparquet'] and (kwargs['geometry_encoding'] == 'WKB'):
         # get geometry columns
         primary_column = kwargs['primary_column']
-        geometries = ['lon', 'x', 'lat', 'y']
+        geometries = ['lon', 'longitude', 'x', 'lat', 'latitude', 'y']
         geom_vars = [v for v in geometries if v in output.keys()]
         # convert to shapely geometry
         points = shapely.points(df[geom_vars[0]], df[geom_vars[1]])