From 7d71495040bf8d64c77e7a0be045b6c2c13852d5 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Fr=C3=A9d=C3=A9ric=20BRIOL?= <fbriol@gmail.com>
Date: Mon, 16 Dec 2024 17:49:28 +0100
Subject: [PATCH] Add Quality class and update tide evaluation documentation

---
 docs/source/api.rst          | 40 ++++++++++++++++++++++++++++++++++
 src/python/pyfes/__init__.py | 42 +++++++++++++++++++++++++-----------
 2 files changed, 69 insertions(+), 13 deletions(-)

diff --git a/docs/source/api.rst b/docs/source/api.rst
index 9565dfd..66c42f1 100644
--- a/docs/source/api.rst
+++ b/docs/source/api.rst
@@ -14,6 +14,46 @@ units as the tidal model.
 
 .. autofunction:: pyfes.evaluate_tide
 
+Quality
+-------
+
+The quality flag is used to indicate the quality of the interpolated value from
+the tidal model.
+
+.. class:: pyfes.Quality
+
+   .. py:attribute:: kUndefined
+
+      The tidal model is undefined at the given location. The corresponding
+      value is ``0``.
+
+   .. py:attribute:: kExtrapolated1
+
+      The tidal model is extrapolated with one data point. The corresponding
+      value is ``1``.
+
+   .. py:attribute:: kExtrapolated2
+
+      The tidal model is extrapolated with two data points. The corresponding
+      value is ``2``.
+
+   .. py:attribute:: kExtrapolated3
+
+      The tidal model is extrapolated with three data points. The corresponding
+      value is ``3``.
+
+   .. py:attribute:: kInterpolated
+
+      The tidal model is interpolated. The corresponding value is ``4``.
+
+   .. py:method:: value() -> int
+
+      Returns the integer value of the quality flag.
+
+   .. py:method:: name() -> str
+
+      Returns the name of the quality flag.
+
 Configuration file
 ------------------
 
diff --git a/src/python/pyfes/__init__.py b/src/python/pyfes/__init__.py
index ad35c64..78c3637 100644
--- a/src/python/pyfes/__init__.py
+++ b/src/python/pyfes/__init__.py
@@ -8,7 +8,7 @@
 from . import core
 from .astronomic_angle import AstronomicAngle
 from .config import load as load_config
-from .core import Constituent, Formulae, constituents
+from .core import Constituent, Formulae, Quality, constituents
 from .leap_seconds import get_leap_seconds
 from .typing import VectorDateTime64, VectorFloat64, VectorInt8
 from .version import __version__
@@ -20,6 +20,7 @@
     'AstronomicAngle',
     'Constituent',
     'Formulae',
+    'Quality',
     'load_config',
     'WaveDict',
     'WaveTable',
@@ -104,21 +105,36 @@ def evaluate_tide(
         * A flag indicating if the tide is correctly estimated or not. Possible
           values are
 
-            ======  ==========================================================
-            1       The tide is correctly estimated.
-            2       The tide is extrapolated with the nearest mesh point.
-            4       The tide is extrapolated using a linear interpolation
-                    with two surrounding grid points.
-            8       The tide is extrapolated using a linear interpolation
-                    with three surrounding grid points.
-            16      The tide is undefined because the position is outside the
-                    domain of the tidal model or the numerical model is
-                    undefined for the requested spatial position.
-            ======  ==========================================================
+          .. list-table:: Flag values
+              :header-rows: 1
+
+              * - Flag
+                - Description
+              * - ``0``
+                - The tide is undefined because the position is outside the
+                  domain of the tidal model or the numerical model is
+                  undefined for the requested spatial position. This value
+                  corresponds to the :py:attr:`pyfes.Quality.kUndefined`
+                  quality flag.
+              * - ``1``
+                - The tide is extrapolated with the nearest mesh point. This
+                  value corresponds to the
+                  :py:attr:`pyfes.Quality.kExtrapolated1` quality flag.
+              * - ``2``
+                - The tide is extrapolated using a linear interpolation with
+                  two surrounding grid points. This value corresponds to the
+                  :py:attr:`pyfes.Quality.kExtrapolated2` quality flag.
+              * - ``3``
+                - The tide is extrapolated using a linear interpolation with
+                  three surrounding grid points. This value corresponds to the
+                  :py:attr:`pyfes.Quality.kExtrapolated3` quality flag.
+              * - ``4``
+                - The tide is correctly estimated. This value corresponds to
+                  the :py:attr:`pyfes.Quality.kInterpolated` quality flag.
 
         .. note::
 
-            The flag value ``2``, ``4`` or ``8`` are only possible if the
+            The flag value ``2`` or ``3`` are only possible if the
             tidal model used is a Cartesian grid.
     """
     return core.evaluate_tide(