Merge pull request #78 from StagPython/plates-refactor

Refactor plates module and expose a public API

This PR is a full refactoring of the plates module to make it easier to
maintain, expand, and use in a user script. The main improvements are:

* `detect_plates` and `detect_plates_vzcheck` are merged in one routine
  `detect_plates`.
* New command line arguments `--vzratio`, `+-distribution` and `+-nbplates`
  allow the user to switch on the use of `vzabs` when detecting plate limits,
  plotting of plate size distribution, and plotting of number of plates as a
  function of time.
* the new `+-continents` argument switches the detection of continents and the
  related decorations on plots.
* `-o/--plot` now works in a similar way to eponym options of `field`, `rprof`,
  and `time` subcommands. The `plates` subcommand plots the requested surface
  diagnostics. The later can be surface fields, fields, or `"dv2"` (which is
  `d(vphi)/dphi`).
* the public api of the plates module (`detect_plates` and two plotting
  routines `plot_at_surface` and `plot_scalar_field`) is documented and
  available in user scripts.

Author: amorison

docs/sources/apiref/phyvars.rst

@@ -85,19 +85,6 @@ phyvars
       Dictionary of time series that StagPy can compute. Keys are the variable
       names, values are :class:`Vart` instances.
 
-   .. class:: Varp
-
-      :class:`collections.namedtuple` whose instances hold metadata of
-      plate variables. It defines the following fields:
-
-      - **description** (*str*): short description of the variable.
-
-   .. data:: PLATES
-      :annotation: = {platevar: Varp()}
-
-      Dictionary of plate variables output by StagYY. Keys are the variable
-      names, values are :class:`Varp` instances.
-
    .. data:: SCALES
       :annotation: = {dimstr: func}
 

docs/sources/apiref/plates.rst

@@ -2,4 +2,4 @@ plates
 ======
 
 .. automodule:: stagpy.plates
-   :members: cmd
+   :members:

stagpy/commands.py

@@ -142,9 +142,6 @@ def var_cmd():
         print('refstate:')
         _layout(phyvars.REFSTATE, {})
         print()
-    if print_all or conf.var.plates:
-        print('plates:')
-        _layout(phyvars.PLATES, {})
 
 
 def version_cmd():

stagpy/config.py

@@ -179,38 +179,27 @@ def _index_collection(arg):
 
 CONF_DEF['plates'] = OrderedDict((
     ('plot',
-        Conf('c,eta,sc', True, 'o',
-             {'nargs': '?', 'const': '', 'type': str},
-             True, 'variables to plot (see stagpy var)')),
-    ('vzcheck', switch_opt(False, None,
-                           'activate Colin\'s version with vz checking')),
-    ('timeprofile', switch_opt(False, None,
-                               'nb of plates as function of time')),
+        Conf('c.T.v2-v2.dv2-v2.topo_top', True, 'o',
+             {'nargs': '?', 'const': '', 'type': str}, True,
+             'variables to plot, can be a surface field, field, or dv2')),
+    ('field',
+        Conf('eta', True, None, {},
+             True, 'field variable to plot with plates info')),
+    ('stress', switch_opt(
+        False, None,
+        'Plot deviatoric stress instead of velocity on field plots')),
+    ('continents', switch_opt(True, None,
+                              'Whether to shade continents on plots')),
+    ('vzratio',
+        Conf(0., True, None, {}, True,
+             'Ratio of mean vzabs used as threshold for plates limits')),
+    ('nbplates', switch_opt(False, None,
+                            'Plot number of plates as function of time')),
+    ('distribution', switch_opt(False, None,
+                                'Plot plate size distribution')),
     ('zoom',
         Conf(None, True, None, {'type': float},
              False, 'zoom around surface')),
-    ('topomin', Conf(-40, False, None, {},
-                     True, 'min topography in plots')),
-    ('topomax', Conf(100, False, None, {},
-                     True, 'max topography in plots')),
-    ('agemin', Conf(-50, False, None, {},
-                    True, 'min age in plots')),
-    ('agemax', Conf(500, False, None, {},
-                    True, 'max age in plots')),
-    ('vmin', Conf(-5000, False, None, {},
-                  True, 'min velocity in plots')),
-    ('vmax', Conf(5000, False, None, {},
-                  True, 'max velocity in plots')),
-    ('dvmin', Conf(-250000, False, None, {},
-                   True, 'min velocity derivative in plots')),
-    ('dvmax', Conf(150000, False, None, {},
-                   True, 'max velocity derivative in plots')),
-    ('stressmin', Conf(0, False, None, {},
-                       True, 'min stress in plots')),
-    ('stressmax', Conf(800, False, None, {},
-                       True, 'max stress in plots')),
-    ('lstressmax', Conf(50, False, None, {},
-                        True, 'max lithospheric stress in plots')),
 ))
 
 CONF_DEF['info'] = OrderedDict((
@@ -229,8 +218,6 @@ def _index_collection(arg):
                   False, 'print time variables')),
     ('refstate', Conf(None, True, None, {'action': 'store_true'},
                       False, 'print refstate variables')),
-    ('plates', Conf(None, True, None, {'action': 'store_true'},
-                    False, 'print plates variables')),
 ))
 
 CONF_DEF['config'] = config_conf_section()

stagpy/error.py

@@ -163,23 +163,6 @@ def __init__(self, zoom):
         super().__init__(f'Zoom angle should be in [0,360] (received {zoom})')
 
 
-class StagnantLidError(StagpyError):
-    """Raised when unexpected stagnant lid regime is found.
-
-    Args:
-        sdat (:class:`~stagpy.stagyydata.StagyyData`): the StagyyData
-            instance for which a stagnant lid regime was found.
-
-    Attributes:
-        sdat (:class:`~stagpy.stagyydata.StagyyData`): the StagyyData
-            instance for which a stagnant lid regime was found.
-    """
-
-    def __init__(self, sdat):
-        self.sdat = sdat
-        super().__init__(f'Stagnant lid regime for {sdat}')
-
-
 class MissingDataError(StagpyError, KeyError):
     """Raised when requested data is not present in output."""
 

stagpy/phyvars.py

@@ -262,17 +262,6 @@
     ('grav', Varr('Gravity', 'Gravity', 'm/s2')),
 ))
 
-Varp = namedtuple('Varp', ['description'])
-PLATES = OrderedDict((
-    ('c', Varp('Composition')),
-    ('eta', Varp('Viscosity')),
-    ('sc', Varp('Topography')),
-    ('age', Varp('Age')),
-    ('str', Varp('Stress')),
-    ('sx', Varp('Principal deviatoric stress')),
-    ('ed', Varp('Strain rate')),
-))
-
 SCALES = {
     'm': attrgetter('length'),
     'kg/m3': attrgetter('density'),