feat: export database as dataclass for easier access (#337)

* chore: bump version to 2.1.6 feat: export database as ``dataclass`` docs: update getting started and ``README.rst`` * test: add test for reading model database * Update release-v2.1.6.rst
tsutterley · Sep 10, 2024 · 1f51f2a · 1f51f2a
1 parent 1a9bee3
commit 1f51f2a
Show file tree

Hide file tree

Showing 12 changed files with 142 additions and 163 deletions.
diff --git a/README.rst b/README.rst
@@ -33,25 +33,32 @@ pyTMD
 
 Python-based tidal prediction software for estimating ocean, load, solid Earth and pole tides
 
-Ocean and load tidal predictions using OTIS, GOT and FES formatted tidal solutions
-
-- `OSU Tidal Prediction Software (OTPS) <https://www.tpxo.net/otps>`_
-- `ESR Tide Model Driver (TMD) Matlab Toolbox <https://www.esr.org/research/polar-tide-models/tmd-software/>`_
-- `OSU Global and Regional Tide Models <https://www.tpxo.net>`_
-- `ESR Polar Tide Models <https://www.esr.org/research/polar-tide-models/list-of-polar-tide-models/>`_
-- `A Global Ocean Tide Model From TOPEX/POSEIDON Altimetry: GOT99.2 <https://ntrs.nasa.gov/citations/19990089548>`_
-- `Finite Element Solution (FES) tide models <https://www.aviso.altimetry.fr/en/data/products/auxiliary-products/global-tide-fes.html>`_
-- `Delta times from US Naval Observatory (USNO) Earth Orientation Products <http://maia.usno.navy.mil/ser7/deltat.data>`_
-- `Delta times from NASA Crustal Dynamics Data Information System (CDDIS) <ftp://cddis.nasa.gov/products/iers/deltat.data>`_
-
-Radial solid Earth and pole tide displacements following IERS conventions
-
-- `IERS Conventions (2010) <http://iers-conventions.obspm.fr/>`_
-- `IERS Mean Pole Location <https://hpiers.obspm.fr/iers/eop/eopc01/mean-pole.tab>`_
-- `IERS Pole Coordinates to Calculate Mean Pole <https://hpiers.obspm.fr/iers/eop/eopc01/eopc01.1900-now.dat>`_
-- `IERS Daily Earth Orientation Parameters (EOP) from USNO <http://www.usno.navy.mil/USNO/earth-orientation/eo-products/weekly>`_
-- `IERS Daily Earth Orientation Parameters (EOP) from NASA CDDIS <ftp://cddis.nasa.gov/products/iers/finals.all>`_
-- `IERS Ocean Pole Load Tide Coefficients Map <http://maia.usno.navy.mil/conventions/2010/2010_update/chapter7/additional_info/opoleloadcoefcmcor.txt.gz>`_
+For more information: see the documentation at `pytmd.readthedocs.io <https://pytmd.readthedocs.io/>`_
+
+Installation
+############
+
+From PyPI:
+
+.. code-block:: bash
+
+   python3 -m pip install pyTMD
+
+Using `conda` or `mamba` from conda-forge:
+
+.. code-block:: bash
+
+   conda install -c conda-forge pytmd
+
+.. code-block:: bash
+
+   mamba install -c conda-forge pytmd
+
+Development version from GitHub:
+
+.. code-block:: bash
+
+   python3 -m pip install git+https://github.com/tsutterley/pyTMD.git
 
 Dependencies
 ############
@@ -87,11 +94,11 @@ Download
 Alternative Software
 ####################
 
-| perth5 from NASA Goddard Space Flight Center is available at:
+| perth5 from NASA Goddard Space Flight Center:
 | https://codeberg.org/rray/perth5
-| Matlab Tide Model Driver from Earth & Space Research is available at:
+| Matlab Tide Model Driver from Earth & Space Research:
 | https://github.com/EarthAndSpaceResearch/TMD_Matlab_Toolbox_v2.5
-| Fortran OSU Tidal Prediction Software OTPS is available at:
+| Fortran OSU Tidal Prediction Software:
 | https://www.tpxo.net/otps
 
 Disclaimer
@@ -102,10 +109,15 @@ It is not sponsored or maintained by the Universities Space Research Association
 The software is provided here for your convenience but *with no guarantees whatsoever*.
 It should not be used for coastal navigation or any application that may risk life or property.
 
+Contributing
+############
+
+This project contains work and contributions from the `scientific community <./CONTRIBUTORS.rst>`_.
+If you would like to contribute to the project, please have a look at the `open issues <https://github.com/tsutterley/pyTMD/issues>`_ and the project `code of conduct <./CODE_OF_CONDUCT.rst>`_.
+
 Credits
 #######
 
-This project contains work and contributions from the `scientific community <./CONTRIBUTORS.rst>`_.
 The Tidal Model Driver (`TMD <https://github.com/EarthAndSpaceResearch/TMD_Matlab_Toolbox_v2.5>`_) Matlab Toolbox was developed by Laurie Padman, Lana Erofeeva and Susan Howard.
 An updated version of the TMD Matlab Toolbox (`TMD3 <https://github.com/chadagreene/Tide-Model-Driver>`_) was developed by Chad Greene.
 The OSU Tidal Inversion Software (OTIS) and OSU Tidal Prediction Software (`OTPS <https://www.tpxo.net/otps>`_) were developed by Lana Erofeeva and Gary Egbert (`copyright OSU <https://www.tpxo.net/tpxo-products-and-registration>`_, licensed for non-commercial use).

diff --git a/doc/source/getting_started/Getting-Started.rst b/doc/source/getting_started/Getting-Started.rst
@@ -19,12 +19,32 @@ 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/main/scripts/aviso_fes_tides.py>`_ program for users registered with AVISO.
 
+Model Database
+##############
+
+``pyTMD`` comes parameterized with models for the prediction of tidal elevations and currents.
+All presently available models are stored within a `JSON database <https://github.com/tsutterley/pyTMD/blob/main/pyTMD/data/database.json>`_:
+
+.. code-block:: python
+
+   >>> import pyTMD
+   >>> pyTMD.models.current.get('CATS2008')
+   {'format': 'OTIS', 'grid_file': 'CATS2008/grid_CATS2008',
+   'model_file': {'u': 'CATS2008/uv.CATS2008.out'}, 'name': 'CATS2008',
+   'projection': 'CATS2008', 'reference': 'https://doi.org/10.15784/601235',
+   'type': ['u', 'v']}
+   >>> pyTMD.models.elevation.get('CATS2008')
+   {'format': 'OTIS', 'grid_file': 'CATS2008/grid_CATS2008',
+   'model_file': 'CATS2008/hf.CATS2008.out', 'name': 'CATS2008',
+   'projection': 'CATS2008', 'reference': 'https://doi.org/10.15784/601235',
+   'type': 'z', 'variable': 'tide_ocean'}
+
 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.
-Presently, the following models and their directories are parameterized within ``pyTMD`` in a JSON database.
+Presently, the following models and their directories are parameterized within ``pyTMD``.
 
 - Circum-Antarctic Tidal Simulations [Padman2008]_
 
@@ -133,14 +153,14 @@ elevations or currents (zonal and meridional) for each point.
 Definition Files
 ################
 
-For models within the ``pyTMD`` database, the parameters can be set with a model definition file in JSON format.
+For models not currently within the ``pyTMD`` `database <./Getting-Started.html#model-database>`_, the model parameters can be set with a definition file in JSON format.
 The JSON definition files follow a similar structure as the main ``pyTMD`` database, but for individual entries.
 The JSON format directly maps the parameter names with their values stored in the appropriate data type (strings, lists, numbers, booleans, etc).
 For FES-type models of currents, the two lists of model files (``u`` and ``v``) are stored in a name-value pair objects (similar to a python dictionary).
 While still human readable, the JSON format is both interoperable and more easily machine readable.
 
-Each definition file regardless of the format should have ``name``, ``format`` and ``type`` parameters.
-Each model type also requires specific sets of parameters for the model reader.
+Each definition file should have ``name``, ``format`` and ``type`` parameters.
+Each model type may also require specific sets of parameters for the individual model reader.
 For models with multiple constituent files, the files can be found using a ``glob`` string to search a directory.
 
 - ``OTIS``, ``ATLAS-compact`` and ``TMD3``
@@ -154,7 +174,7 @@ For models with multiple constituent files, the files can be found using a ``glo
 
 - ``ATLAS-netcdf``
 
-    * ``compressed``: model files are gzip compressed
+    * ``compressed``: model files are ``gzip`` compressed
     * ``format``: ``ATLAS-netcdf``
     * ``grid_file``: path to model grid file
     * ``model_file``: path to model constituent files or a ``glob`` string
@@ -164,7 +184,7 @@ For models with multiple constituent files, the files can be found using a ``glo
 
 - ``GOT-ascii`` and ``GOT-netcdf``
 
-    * ``compressed``: model files are gzip compressed
+    * ``compressed``: model files are ``gzip`` compressed
     * ``format``: ``GOT-ascii`` or ``GOT-netcdf``
     * ``model_file``: path to model constituent files or a ``glob`` string
     * ``name``: tide model name
@@ -173,7 +193,7 @@ For models with multiple constituent files, the files can be found using a ``glo
 
 - ``FES-ascii`` and ``FES-netcdf``
 
-    * ``compressed``: model files are gzip compressed
+    * ``compressed``: model files are ``gzip`` compressed
     * ``format``: ``FES-ascii`` or ``FES-netcdf``
     * ``model_file``: path to model constituent files or a ``glob`` string
     * ``name``: tide model name

diff --git a/doc/source/getting_started/Install.rst b/doc/source/getting_started/Install.rst
@@ -52,13 +52,7 @@ To use the development repository, please fork ``pyTMD`` into your own account a
 
     git clone https://github.com/tsutterley/pyTMD.git
 
-``pyTMD`` can then be installed within the package directory using ``setuptools``:
-
-.. code-block:: bash
-
-    python3 setup.py install
-
-or ``pip``
+``pyTMD`` can then be installed within the package directory using ``pip``:
 
 .. code-block:: bash
 

diff --git a/doc/source/release_notes/release-v2.1.6.rst b/doc/source/release_notes/release-v2.1.6.rst
@@ -0,0 +1,27 @@
+##################
+`Release v2.1.6`__
+##################
+
+* ``refactor``: use JSON database for known model parameters for `#328 <https://github.com/tsutterley/pyTMD/issues/328>`_ (`#329 <https://github.com/tsutterley/pyTMD/pull/329>`_)
+* ``feat``: added new ``TPXO10-atlas-v2`` to list of models (`#329 <https://github.com/tsutterley/pyTMD/pull/329>`_)
+* ``feat``: generalize hash function to use any available algorithm (`#329 <https://github.com/tsutterley/pyTMD/pull/329>`_)
+* ``fix``: use model name in default output filename for definition file case (`#329 <https://github.com/tsutterley/pyTMD/pull/329>`_)
+* ``refactor``: create database from providers (`#329 <https://github.com/tsutterley/pyTMD/pull/329>`_)
+* ``refactor``: drop support for the ascii definition file format (`#329 <https://github.com/tsutterley/pyTMD/pull/329>`_)
+* ``docs``: add model providers section to contributions (`#329 <https://github.com/tsutterley/pyTMD/pull/329>`_)
+* ``ci``: add GitHub Action to update ``database.json`` (`#330 <https://github.com/tsutterley/pyTMD/pull/330>`_)
+* ``feat``: Add additional models to provider JSON (`#331 <https://github.com/tsutterley/pyTMD/pull/331>`_)
+* ``fix``: add parse constituents back to model load (`#331 <https://github.com/tsutterley/pyTMD/pull/331>`_)
+* ``fix``: drop constituents from database (`#331 <https://github.com/tsutterley/pyTMD/pull/331>`_)
+* ``ci``: only run ``pytest`` action if secrets are accessible (`#331 <https://github.com/tsutterley/pyTMD/pull/331>`_)
+* ``refactor``: use idealized Azimuthal equidistant for Arctic models (`#332 <https://github.com/tsutterley/pyTMD/pull/332>`_)
+* ``fix``: deprecation in case where an array is output to scalars (`#332 <https://github.com/tsutterley/pyTMD/pull/332>`_)
+* ``fix``: j1 and theta for FES type models for `#335 <https://github.com/tsutterley/pyTMD/issues/335>`_ (`#336 <https://github.com/tsutterley/pyTMD/pull/336>`_)
+* ``fix``: nodal corrections for ``eps2`` and ``eta2`` when inferring for GOT5.5 (`#336 <https://github.com/tsutterley/pyTMD/pull/336>`_)
+* ``feat``: use model class attributes for file format and corrections (`#336 <https://github.com/tsutterley/pyTMD/pull/336>`_)
+* ``feat``: add option to select nodal corrections type (`#336 <https://github.com/tsutterley/pyTMD/pull/336>`_)
+* ``feat``: export database as ``dataclass`` (`#337 <https://github.com/tsutterley/pyTMD/pull/337>`_)
+* ``docs``: update getting started and ``README.rst`` (`#337 <https://github.com/tsutterley/pyTMD/pull/337>`_)
+* ``test``: add test for reading model database (`#337 <https://github.com/tsutterley/pyTMD/pull/337>`_)
+
+.. __: https://github.com/tsutterley/pyTMD/releases/tag/2.1.6
diff --git a/providers/ESR.json b/providers/ESR.json
@@ -80,6 +80,7 @@
             },
             "name": "CATS2008",
             "projection": "CATS2008",
+            "reference": "https://doi.org/10.15784/601235",
             "type": [
                 "u",
                 "v"

diff --git a/providers/README.rst b/providers/README.rst
@@ -8,4 +8,4 @@ The main database is created by merging the model provider JSON files
 - ``ESR``: `Earth and Space Research Polar Tide Models <https://www.esr.org/research/polar-tide-models/>`_
 - ``GSFC``: `NASA Goddard Space Flight Center Global Tide Models <https://earth.gsfc.nasa.gov/geo/data/ocean-tide-models>`_
 - ``TPXO``: `Oregon State University TPXO Tide Models <https://www.tpxo.net/home>`_
--  ``providers``: Additional or stand-alone model providers
+- ``providers``: Additional or stand-alone model providers
diff --git a/providers/providers.json b/providers/providers.json
@@ -8,23 +8,13 @@
             },
             "name": "CATS2008-v2023",
             "projection": "CATS2008",
+            "reference": "https://doi.org/10.15784/601772",
             "type": [
                 "u",
                 "v"
             ]
         },
         "HAMTIDE11": {
-            "constituents": [
-                "2n2",
-                "k1",
-                "k2",
-                "m2",
-                "n2",
-                "o1",
-                "p1",
-                "q1",
-                "s2"
-            ],
             "format": "FES-netcdf",
             "model_file": {
                 "u": [
@@ -67,30 +57,11 @@
             "model_file": "CATS2008_v2023/CATS2008_v2023.nc",
             "name": "CATS2008-v2023",
             "projection": "CATS2008",
-            "reference": "https://www.esr.org/research/polar-tide-models/list-of-polar-tide-models/cats2008/",
+            "reference": "https://doi.org/10.15784/601772",
             "type": "z",
             "variable": "tide_ocean"
         },
         "EOT20": {
-            "constituents": [
-                "2n2",
-                "j1",
-                "k1",
-                "k2",
-                "m2",
-                "m4",
-                "mf",
-                "mm",
-                "n2",
-                "o1",
-                "p1",
-                "q1",
-                "s1",
-                "s2",
-                "sa",
-                "ssa",
-                "t2"
-            ],
             "format": "FES-netcdf",
             "model_file": [
                 "EOT20/ocean_tides/2N2_ocean_eot20.nc",
@@ -119,25 +90,6 @@
             "version": "EOT20"
         },
         "EOT20_load": {
-            "constituents": [
-                "2n2",
-                "j1",
-                "k1",
-                "k2",
-                "m2",
-                "m4",
-                "mf",
-                "mm",
-                "n2",
-                "o1",
-                "p1",
-                "q1",
-                "s1",
-                "s2",
-                "sa",
-                "ssa",
-                "t2"
-            ],
             "format": "FES-netcdf",
             "model_file": [
                 "EOT20/load_tides/2N2_load_eot20.nc",
@@ -166,17 +118,6 @@
             "version": "EOT20"
         },
         "HAMTIDE11": {
-            "constituents": [
-                "2n2",
-                "k1",
-                "k2",
-                "m2",
-                "n2",
-                "o1",
-                "p1",
-                "q1",
-                "s2"
-            ],
             "format": "FES-netcdf",
             "model_file": [
                 "hamtide/2n.hamtide11a.nc",

diff --git a/pyTMD/__init__.py b/pyTMD/__init__.py
@@ -44,3 +44,5 @@
 
 # get semantic version from setuptools-scm
 __version__ = pyTMD.version.version
+# read model database
+models = io.load_database()