add Arctic AOTIM-5-2018 matlab-python test

add download utilties for CATS and Arctic models

update documentation for setting up model directories

update documentation for new and updated programs

.github/workflows/python-package.yml

@@ -27,6 +27,7 @@ jobs:
     - name: Install dependencies for Linux
       if: matrix.os == 'ubuntu-20.04'
       run: |
+        sudo apt-get update
         sudo apt-get install libproj-dev proj-data proj-bin libgeos-dev octave
         sudo apt-get install libhdf5-dev libnetcdf-dev
         pip install --upgrade pip

.github/workflows/python-request.yml

@@ -24,6 +24,7 @@ jobs:
     - name: Install dependencies for Linux
       if: matrix.os == 'ubuntu-20.04'
       run: |
+        sudo apt-get update
         sudo apt-get install libproj-dev proj-data proj-bin libgeos-dev octave
         sudo apt-get install libhdf5-dev libnetcdf-dev
         pip install --upgrade pip

Plot Antarctic Tide Range.ipynb

@@ -285,7 +285,7 @@
     "    #-- list of minor constituents\n",
     "    minor = ['2q1','sigma1','rho1','m1','m1','chi1','pi1','phi1','theta1',\n",
     "        'j1','oo1','2n2','mu2','nu2','lambda2','l2','l2','t2']\n",
-    "    #-- only add minor consituents that are not on the list of major values\n",
+    "    #-- only add minor constituents that are not on the list of major values\n",
     "    minor_flag = [m not in constituents for m in minor]\n",
     "    #-- estimate minor constituents\n",
     "    zmin = np.zeros((npts,18))\n",

doc/source/conf.py

@@ -22,7 +22,7 @@
 author = 'Tyler C. Sutterley'
 
 # The full version, including alpha/beta/rc tags
-release = '1.0.2.7'
+release = '1.0.2.8'
 
 
 # -- General configuration ---------------------------------------------------

doc/source/getting_started/Getting-Started.md

@@ -0,0 +1,45 @@
+Getting Started
+===============
+
+#### Tide Model Formats
+OTIS and ATLAS formatted data use a single binary file to store all the constituents for either heights (`z`) or transports (`u`, `v`).
+Arctic Ocean models can be downloaded from the NSF ArcticData server using the [`arcticdata_tides.py`](https://github.com/tsutterley/pyTMD/blob/master/scripts/arcticdata_tides.py) program.
+CATS2008 can be downloaded from the US Antarctic Program (USAP) using the [`usap_cats_tides.py`](https://github.com/tsutterley/pyTMD/blob/master/scripts/usap_cats_tides.py) program.
+ATLAS netCDF formatted data use netCDF4 files for each constituent and variable type (`z`, `u`, `v`).
+GOT formatted data use ascii files for each height constituent (`z`).
+FES formatted data use either ascii (1999, 2004) or netCDF4 (2012, 2014) files for each constituent and variable type (`z`, `u`, `v`).
+The FES models can be downloaded using the [`aviso_fes_tides.py`](https://github.com/tsutterley/pyTMD/blob/master/scripts/aviso_fes_tides.py) program for users registered with AVISO.
+
+#### Directories
+pyTMD uses a tree structure for storing the tidal constituent data.
+This structure was chosen based on the different formats of each tide model.
+
+- Circum-Antarctic Tidal Simulations
+    * CATS0201: `<path_to_tide_models>/cats0201_tmd/`
+    * [CATS2008](https://www.usap-dc.org/view/dataset/601235): `<path_to_tide_models>/CATS2008/`
+    * CATS2008_load: `<path_to_tide_models>/CATS2008a_SPOTL_Load/`
+
+- Arctic Ocean Tidal Simulations
+    * [AODTM-5](https://arcticdata.io/catalog/view/doi:10.18739/A2901ZG3N): `<path_to_tide_models>/aodtm5_tmd/`
+    * [AOTIM-5](https://arcticdata.io/catalog/view/doi:10.18739/A2S17SS80): `<path_to_tide_models>/aotim5_tmd/`
+    * [AOTIM-5-2018](https://arcticdata.io/catalog/view/doi:10.18739/A21R6N14K): `<path_to_tide_models>/Arc5km2018/`
+
+- TOPEX/POSEIDON global tide models
+    * [TPXO9-atlas](https://www.tpxo.net/tpxo-products-and-registration): `<path_to_tide_models>/TPXO9_atlas/`
+    * [TPXO9-atlas-v2](https://www.tpxo.net/tpxo-products-and-registration): `<path_to_tide_models>/TPXO9_atlas_v2/`
+    * [TPXO9.1](https://www.tpxo.net/tpxo-products-and-registration): `<path_to_tide_models>/TPXO9.1/DATA/`
+    * [TPXO8-atlas](https://www.tpxo.net/tpxo-products-and-registration): `<path_to_tide_models>/tpxo8_atlas/`
+    * TPXO7.2: `<path_to_tide_models>/TPXO7.2_tmd/`
+    * TPXO7.2_load: `<path_to_tide_models>/TPXO7.2_load/`
+
+- Global Ocean Tide models
+    * GOT4.7: `<path_to_tide_models>/GOT4.7/grids_oceantide/`
+    * GOT4.7_load: `<path_to_tide_models>/GOT4.7/grids_loadtide/`
+    * GOT4.8: `<path_to_tide_models>/got4.8/grids_oceantide/`
+    * GOT4.8_load: `<path_to_tide_models>/got4.8/grids_loadtide/`
+    * GOT4.10: `<path_to_tide_models>/GOT4.10c/grids_oceantide/`
+    * GOT4.10_load: `<path_to_tide_models>/GOT4.10c/grids_loadtide/`
+
+- Finite Element Solution tide models
+    * [FES2014](https://www.aviso.altimetry.fr/data/products/auxiliary-products/global-tide-fes.html): `<path_to_tide_models>/fes2014/ocean_tide/`
+    * [FES2014_load](https://www.aviso.altimetry.fr/data/products/auxiliary-products/global-tide-fes.html): `<path_to_tide_models>/fes2014/load_tide/`

doc/source/index.rst

@@ -26,13 +26,15 @@ calculating radial pole tide displacements
     :caption: Getting Started:
 
     getting_started/Install.md
+    getting_started/Getting-Started.md
     getting_started/Resources.md
     getting_started/Citations.md
 
 .. toctree::
     :maxdepth: 1
     :caption: User Guide:
 
+    user_guide/arcticdata_tides.md
     user_guide/aviso_fes_tides.md
     user_guide/bilinear_interp.md
     user_guide/calc_astrol_longitudes.md
@@ -70,4 +72,5 @@ calculating radial pole tide displacements
     user_guide/reduce_OTIS_files.md
     user_guide/tidal_ellipse.md
     user_guide/time.rst
+    user_guide/usap_cats_tides.md
     user_guide/utilities.rst

doc/source/user_guide/arcticdata_tides.md

@@ -0,0 +1,21 @@
+arcticdata_tides.py
+===================
+
+ - Download Arctic Ocean Tide Models from the [NSF ArcticData](https://arcticdata.io) archive
+ - [AODTM-5](https://arcticdata.io/catalog/view/doi:10.18739/A2901ZG3N)
+ - [AOTIM-5](https://arcticdata.io/catalog/view/doi:10.18739/A2S17SS80)
+ - [AOTIM-5-2018](https://arcticdata.io/catalog/view/doi:10.18739/A21R6N14K)
+
+#### Calling Sequence
+```bash
+python arcticdata_tides.py --directory=<path_to_tide_directory> --tide=AOTIM-5-2018
+```
+[Source code](https://github.com/tsutterley/pyTMD/blob/master/scripts/arcticdata_tides.py)
+
+#### Command Line Options
+ - `-D X`, `--directory=X`: Working Data Directory
+ - `--tide=X`: Arctic Ocean tide model to download
+    * AODTM-5
+    * AOTIM-5
+    * AOTIM-5-2018
+ - `-M X`, `--mode=X`: Permission mode of files downloaded

doc/source/user_guide/usap_cats_tides.md

@@ -0,0 +1,17 @@
+usap_cats_tides.py
+==================
+
+ - Download Circum-Antarctic Tidal Simulations from the [US Antarctic Program](https://www.usap-dc.org)
+ - [CATS2008](https://www.usap-dc.org/view/dataset/601235)
+
+#### Calling Sequence
+```bash
+python usap_cats_tides.py --directory=<path_to_tide_directory> --tide=CATS2008
+```
+[Source code](https://github.com/tsutterley/pyTMD/blob/master/scripts/usap_cats_tides.py)
+
+#### Command Line Options
+ - `-D X`, `--directory=X`: Working Data Directory
+ - `--tide=X`: Circum-Antarctic Tidal Simulation to download
+    * CATS2008
+ - `-M X`, `--mode=X`: Permission mode of files downloaded

doc/source/user_guide/utilities.rst

@@ -105,6 +105,15 @@ General Methods
         `mode`: permissions mode of output local file
 
 
+.. method:: pyTMD.utilities.check_connection(HOST)
+
+    Check internet connection
+
+    Arguments:
+
+        `HOST`: remote http host
+
+
 .. method:: pyTMD.utilities.from_http(HOST,timeout=None,local=None,hash='',chunk=16384,verbose=False,mode=0o775)
 
     Download a file from a http host

pyTMD/convert_ll_xy.py

@@ -108,7 +108,7 @@ def xy_ll_EPSG3976(i1,i2,BF):
     #-- return the output variables
     return (o1,o2)
 
-#-- wrapper function for models in PSNorth projection
+#-- wrapper function for models in (idealized) PSNorth projection
 def xy_ll_PSNorth(i1,i2,BF):
     # #-- projections for converting from latitude/longitude
     # proj1 = pyproj.Proj("+init=EPSG:{0:d}".format(4326))

pyTMD/infer_minor_corrections.py

@@ -94,7 +94,7 @@ def infer_minor_corrections(time,zmajor,constituents,DELTAT=0.0,CORRECTIONS=''):
     #-- list of minor constituents
     minor = ['2q1','sigma1','rho1','m1','m1','chi1','pi1','phi1','theta1','j1',
         'oo1','2n2','mu2','nu2','lambda2','l2','l2','t2']
-    #-- only add minor consituents that are not on the list of major values
+    #-- only add minor constituents that are not on the list of major values
     minor_indices = [i for i,m in enumerate(minor) if m not in constituents]
 
     #-- relationship between major and minor constituent amplitude and phase

pyTMD/time.py

@@ -6,6 +6,7 @@
 
 PYTHON DEPENDENCIES:
     numpy: Scientific Computing Tools For Python (https://numpy.org)
+    lxml: processing XML and HTML in Python (https://pypi.python.org/pypi/lxml)
 
 PROGRAM DEPENDENCIES:
     convert_julian.py: returns the calendar date and time given a Julian date

pyTMD/utilities.py

@@ -3,6 +3,9 @@
 Written by Tyler Sutterley (08/2020)
 Download and management utilities for syncing time and auxiliary files
 
+PYTHON DEPENDENCIES:
+    lxml: processing XML and HTML in Python (https://pypi.python.org/pypi/lxml)
+
 UPDATE HISTORY:
     Updated 08/2020: add GSFC CDDIS opener, login and download functions
     Written 08/2020
@@ -24,9 +27,11 @@
 import lxml.etree
 import calendar,time
 if sys.version_info[0] == 2:
+    from urllib import quote_plus
     from cookielib import CookieJar
     import urllib2
 else:
+    from urllib.parse import quote_plus
     from http.cookiejar import CookieJar
     import urllib.request as urllib2
 
@@ -228,6 +233,23 @@ def from_ftp(HOST,timeout=None,local=None,hash='',chunk=16384,
         remote_buffer.seek(0)
         return remote_buffer
 
+#-- PURPOSE: check internet connection
+def check_connection(HOST):
+    """
+    Check internet connection
+
+    Arguments
+    ---------
+    HOST: remote http host
+    """
+    #-- attempt to connect to https host
+    try:
+        urllib2.urlopen(HOST,timeout=20,context=ssl.SSLContext())
+    except urllib2.URLError:
+        raise RuntimeError('Check internet connection')
+    else:
+        return True
+
 #-- PURPOSE: download a file from a http host
 def from_http(HOST,timeout=None,local=None,hash='',chunk=16384,
     verbose=False,mode=0o775):

scripts/arcticdata_tides.py

@@ -0,0 +1,119 @@
+#!/usr/bin/env python
+u"""
+arcticdata_tides.py
+Written by Tyler Sutterley (07/2020)
+Download Arctic Ocean Tide Models from the NSF ArcticData archive
+AODTM-5: https://arcticdata.io/catalog/view/doi:10.18739/A2901ZG3N
+AOTIM-5: https://arcticdata.io/catalog/view/doi:10.18739/A2S17SS80
+AOTIM-5-2018: https://arcticdata.io/catalog/view/doi:10.18739/A21R6N14K
+
+CALLING SEQUENCE:
+    python arcticdata_tides.py --tide=AOTIM-5-2018
+
+COMMAND LINE OPTIONS:
+    --help: list the command line options
+    --directory=X: working data directory
+    --tide=X: tide model to download
+        AODTM-5
+        AOTIM-5
+        AOTIM-5-2018
+    -M X, --mode=X: Local permissions mode of the files downloaded
+
+PYTHON DEPENDENCIES:
+    future: Compatibility layer between Python 2 and Python 3
+        https://python-future.org/
+
+PROGRAM DEPENDENCIES:
+    utilities: download and management utilities for syncing files
+
+UPDATE HISTORY:
+    Written 08/2020
+"""
+from __future__ import print_function
+
+import sys
+import os
+import re
+import time
+import getopt
+import zipfile
+import posixpath
+import pyTMD.utilities
+
+#-- PURPOSE: Download Arctic Ocean Tide Models from the NSF ArcticData archive
+def arcticdata_tides(MODEL,DIRECTORY=None,MODE=0o775):
+    #-- doi for each model
+    DOI = {}
+    DOI['AODTM-5'] = '10.18739/A2901ZG3N'
+    DOI['AOTIM-5'] = '10.18739/A2S17SS80'
+    DOI['AOTIM-5-2018'] = '10.18739/A21R6N14K'
+    #-- local subdirectory for each model
+    LOCAL = {}
+    LOCAL['AODTM-5'] = 'aodtm5_tmd'
+    LOCAL['AOTIM-5'] = 'aotim5_tmd'
+    LOCAL['AOTIM-5-2018'] = 'Arc5km2018'
+    #-- recursively create directories if non-existent
+    if not os.access(os.path.join(DIRECTORY,LOCAL[MODEL]), os.F_OK):
+        os.makedirs(os.path.join(DIRECTORY,LOCAL[MODEL]), MODE)
+
+    #-- build host url for model
+    resource_map_doi = 'resource_map_doi:{0}'.format(DOI[MODEL])
+    HOST = ['https://arcticdata.io','metacat','d1','mn','v2','packages',
+        pyTMD.utilities.quote_plus(posixpath.join('application','bagit-097')),
+        pyTMD.utilities.quote_plus(resource_map_doi)]
+    #-- download zipfile from host
+    zfile = zipfile.ZipFile(pyTMD.utilities.from_http(HOST))
+    print('{0} -->\n'.format(posixpath.join(*HOST)))
+    #-- find model files within zip file
+    rx = re.compile('(grid|h[0]?|UV[0]?|Model|xy)_(.*?)',re.VERBOSE)
+    members = [m for m in zfile.filelist if rx.search(m.filename)]
+    #-- extract each member
+    for m in members:
+        #-- strip directories from member filename
+        m.filename = posixpath.basename(m.filename)
+        print('\t{0}\n'.format(os.path.join(DIRECTORY,LOCAL[MODEL],m.filename)))
+        #-- extract file
+        zfile.extract(m, path=os.path.join(DIRECTORY,LOCAL[MODEL]))
+        #-- change permissions mode
+        os.chmod(os.path.join(DIRECTORY,LOCAL[MODEL],m.filename), MODE)
+    #-- close the zipfile object
+    zfile.close()
+
+#-- PURPOSE: help module to describe the optional input parameters
+def usage():
+    print('\nHelp: {}'.format(os.path.basename(sys.argv[0])))
+    print(' -D X, --directory=X\tWorking data directory')
+    print(' --tide=X\t\tArctic Ocean tide model to download')
+    print('\tAODTM-5\n\tAOTIM-5\n\tAOTIM-5-2018')
+    print(' -M X, --mode=X\t\tPermission mode of files downloaded\n')
+
+#-- Main program that calls arcticdata_tides()
+def main():
+    #-- Read the system arguments listed after the program
+    long_options = ['help','directory=','tide=','mode=']
+    optlist,arglist = getopt.getopt(sys.argv[1:],'hD:M:',long_options)
+
+    #-- command line parameters
+    DIRECTORY = os.getcwd()
+    MODELS = ['AOTIM-5-2018']
+    #-- permissions mode of the local directories and files (number in octal)
+    MODE = 0o775
+    for opt, arg in optlist:
+        if opt in ('-h','--help'):
+            usage()
+            sys.exit()
+        elif opt in ("-D","--directory"):
+            DIRECTORY = os.path.expanduser(arg)
+        elif opt in ("--tide",):
+            MODELS = arg.upper().split(',')
+        elif opt in ("-M","--mode"):
+            MODE = int(arg, 8)
+
+    #-- check internet connection before attempting to run program
+    if pyTMD.utilities.check_connection('https://arcticdata.io'):
+        for m in MODELS:
+            arcticdata_tides(m,DIRECTORY=DIRECTORY,MODE=MODE)
+
+#-- run main program
+if __name__ == '__main__':
+    main()