requake 0.5__tar.gz → 0.6__tar.gz

{requake-0.5 → requake-0.6}/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 Copyright (c) 2021-2024 Claudio Satriano <satriano@ipgp.fr>
 
+## v0.6 - 2024-05-04
+
+Note: you might want to run `requake update_config` to update your config file
+to the latest version.
+
+- Verb `plot_slip` renamed to `plot_cumulative`. This new verb has new options
+  to plot cumulative slip, cumulative moment, and cumulative number of events,
+  and to make the plot logarithmic.
+- New verb `print_catalog`: print the event catalog to screen
+- New verb `print_pairs`: print the event pairs to screen
+- `print_families`: also print minimum and maximum family magnitudes
+- Additional models to convert magnitude to slip. Currently supported models
+  are: Nadeau and Johnson (1998), Beeler et al. (2001), Eshelby (1957).
+  Model selection is done using the `mag_to_slip_model` config parameter.
+- New verb `update_config`: update an existing config file to the latest
+  version
+
 ## v0.5 - 2024-04-23
 
 - New config options: `station_metadata_path` and `waveform_data_path` to

{requake-0.5 → requake-0.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: requake
-Version: 0.5
+Version: 0.6
 Summary: Repeating earthquakes search and analysis
 Home-page: https://requake.seismicsource.org
 Author: Claudio Satriano
@@ -33,7 +33,7 @@ Requires-Dist: argcomplete
 Requires-Dist: tqdm
 Requires-Dist: tabulate
 
-<img src="imgs/Requake_logo.svg" width="400">
+<img src="https://cdn.jsdelivr.net/gh/SeismicSource/requake@dc9a6e6fd818e57e0c0d74f9c16f2bfc6d4d148c/imgs/Requake_logo.svg" width="400">
 
 # Requake
 
@@ -122,33 +122,34 @@ To get help, use:
 
     requake -h
 
-The different running modes are specified as "verbs" (positional arguments).
-Currently supported verbs are:
+Different commands are available:
 
     sample_config       write sample config file to current directory and exit
+    update_config       update an existing config file to the latest version
     read_catalog        read an event catalog from web services or from a file
+    print_catalog       print the event catalog to screen
     scan_catalog        scan an existing catalog for earthquake pairs
+    print_pairs         print pairs to screen
     plot_pair           plot traces for a given event pair
     build_families      build families of repeating earthquakes from a catalog
                         of pairs
     print_families      print families to screen
     plot_families       plot traces for one ore more event families
     plot_timespans      plot family timespans
-    plot_slip           plot cumulative slip for one or more families
+    plot_cumulative     cumulative plot for one or more families
     map_families        plot families on a map
     flag_family         flag a family of repeating earthquakes as valid or not
-                        valid. Note that all families are valid by default
-                        when first created
+                        valid.
     build_templates     build waveform templates for one or more event
                         families
     scan_templates      scan a continuous waveform stream using one or more
                         templates
 
-Certain running modes (e.g., `plot_pair`) require further arguments (use, e.g.,
+Certain commands (e.g., `plot_pair`) require further arguments (use, e.g.,
 `requake plot_pair -h` to get help).
 
-Requake supports command line tab completion for arguments, thanks to
-[argcomplete](https://kislyuk.github.io/argcomplete/).
+Requake supports command line tab completion for commands and arguments, thanks
+to [argcomplete](https://kislyuk.github.io/argcomplete/).
 To enable command line tab completion, add the following line to your `.bashrc`
 or `.zshrc`:
 

{requake-0.5 → requake-0.6}/README.md

@@ -87,33 +87,34 @@ To get help, use:
 
     requake -h
 
-The different running modes are specified as "verbs" (positional arguments).
-Currently supported verbs are:
+Different commands are available:
 
     sample_config       write sample config file to current directory and exit
+    update_config       update an existing config file to the latest version
     read_catalog        read an event catalog from web services or from a file
+    print_catalog       print the event catalog to screen
     scan_catalog        scan an existing catalog for earthquake pairs
+    print_pairs         print pairs to screen
     plot_pair           plot traces for a given event pair
     build_families      build families of repeating earthquakes from a catalog
                         of pairs
     print_families      print families to screen
     plot_families       plot traces for one ore more event families
     plot_timespans      plot family timespans
-    plot_slip           plot cumulative slip for one or more families
+    plot_cumulative     cumulative plot for one or more families
     map_families        plot families on a map
     flag_family         flag a family of repeating earthquakes as valid or not
-                        valid. Note that all families are valid by default
-                        when first created
+                        valid.
     build_templates     build waveform templates for one or more event
                         families
     scan_templates      scan a continuous waveform stream using one or more
                         templates
 
-Certain running modes (e.g., `plot_pair`) require further arguments (use, e.g.,
+Certain commands (e.g., `plot_pair`) require further arguments (use, e.g.,
 `requake plot_pair -h` to get help).
 
-Requake supports command line tab completion for arguments, thanks to
-[argcomplete](https://kislyuk.github.io/argcomplete/).
+Requake supports command line tab completion for commands and arguments, thanks
+to [argcomplete](https://kislyuk.github.io/argcomplete/).
 To enable command line tab completion, add the following line to your `.bashrc`
 or `.zshrc`:
 

{requake-0.5 → requake-0.6}/requake/_version.py

@@ -8,11 +8,11 @@ import json
 
 version_json = '''
 {
- "date": "2024-04-23T09:52:34+0200",
+ "date": "2024-05-04T17:23:20+0200",
  "dirty": false,
  "error": null,
- "full-revisionid": "5223a069ca428a69bba654b59dc8bc7b8860cbdd",
- "version": "0.5"
+ "full-revisionid": "dc9a6e6fd818e57e0c0d74f9c16f2bfc6d4d148c",
+ "version": "0.6"
 }
 '''  # END VERSION_JSON
 

{requake-0.5 → requake-0.6}/requake/catalog/__init__.py

@@ -10,3 +10,4 @@ Functions and data structures for managing earthquake catalogs.
     (https://www.gnu.org/licenses/gpl-3.0-standalone.html)
 """
 from .read_catalog import read_catalog  # noqa
+from .print_catalog import print_catalog  # noqa

{requake-0.5 → requake-0.6}/requake/catalog/catalog.py

@@ -264,10 +264,13 @@ def read_stored_catalog(config):
     try:
         cat = RequakeCatalog()
         cat.read(config.scan_catalog_file)
+        cat.sort()
+        if not cat:
+            raise ValueError('Empty catalog')
         return cat
     except ValueError as m:
         raise ValueError(
-            f'Error reading catalog file {config.scan_catalog_file}'
+            f'Error reading catalog file {config.scan_catalog_file}: {m}'
         ) from m
     except FileNotFoundError as m:
         raise FileNotFoundError(

requake-0.6/requake/catalog/print_catalog.py

@@ -0,0 +1,53 @@
+# -*- coding: utf8 -*-
+# SPDX-License-Identifier: GPL-3.0-or-later
+"""
+Print the event catalog to screen.
+
+:copyright:
+    2021-2024 Claudio Satriano <satriano@ipgp.fr>
+:license:
+    GNU General Public License v3.0 or later
+    (https://www.gnu.org/licenses/gpl-3.0-standalone.html)
+"""
+import logging
+from .catalog import read_stored_catalog
+from ..config.generic_printer import generic_printer
+from ..config.rq_setup import rq_exit
+logger = logging.getLogger(__name__.rsplit('.', maxsplit=1)[-1])
+
+
+def print_catalog(config):
+    """
+    Print the event catalog to screen.
+
+    :param config: Configuration object.
+    :type config: config.Config
+    """
+    try:
+        catalog = read_stored_catalog(config)
+    except (ValueError, FileNotFoundError) as m:
+        logger.error(m)
+        rq_exit(1)
+
+    headers_fmt = [
+        ('evid', None),
+        ('origin time', None),
+        ('longitude', '.4f'),
+        ('latitude', '.4f'),
+        ('depth\n(km)', '.3f'),
+        ('mag\ntype', None),
+        ('mag', '.1f')
+    ]
+    rows = [
+        [
+            ev.evid,
+            ev.orig_time,
+            ev.lon,
+            ev.lat,
+            ev.depth,
+            ev.mag_type,
+            ev.mag
+        ]
+        for ev in catalog
+    ]
+    generic_printer(config, rows, headers_fmt)

{requake-0.5 → requake-0.6}/requake/config/configspec.conf

@@ -128,3 +128,19 @@ distance_from_lat = float(default=None)
 ## Normalization will produce an average trace which is more representative
 ## of the family, but will be less effective in reducing noise.
 normalize_traces_before_averaging = boolean(default=False)
+
+#### Post-processing parameters
+## Estimation of fault slip (in cm) from repetater's magnitude
+## Choose between:
+##  NJ1998 : Nadeau and Johnson (1998)
+##  B2001 : Beeler et al. (2001)
+##  E1957 : Eshelby (1957), circular crack model
+## See Uchida (2019, https://doi.org/10.1186/s40645-019-0284-z) for details
+## on the models.
+mag_to_slip_model = string(default='NJ1998')
+## Static stress drop value for B2001 and E1957 models (MPa)
+static_stress_drop = float(default=10.0)
+## Rigidity value for B2001 and E1957 models (GPa)
+rigidity = float(default=30.0)
+## Strain hardening coefficient for B2001 model (MPa/cm)
+strain_hardening = float(default=0.5)

requake-0.6/requake/config/generic_printer.py

@@ -0,0 +1,66 @@
+# -*- coding: utf8 -*-
+# SPDX-License-Identifier: GPL-3.0-or-later
+"""
+Generic printer functions for Requake.
+
+:copyright:
+    2021-2024 Claudio Satriano <satriano@ipgp.fr>
+:license:
+    GNU General Public License v3.0 or later
+    (https://www.gnu.org/licenses/gpl-3.0-standalone.html)
+"""
+import sys
+import os
+import csv
+import contextlib
+import logging
+from tabulate import tabulate
+logger = logging.getLogger(__name__.rsplit('.', maxsplit=1)[-1])
+
+
+def generic_printer(config, rows, headers_fmt, print_headers=True):
+    """
+    A generic printer function for Requake.
+
+    :param config: Configuration object.
+    :type config: config.Config
+    :param rows: Rows to print.
+    :type rows: list of rows
+    :param headers_fmt: Headers and format strings.
+    :type headers_fmt: list of tuples of str
+    """
+    headers = [h[0] for h in headers_fmt]
+    floatfmt = [h[1] for h in headers_fmt]
+    tablefmt = config.args.format
+    if tablefmt == 'csv':
+        writer = csv.writer(sys.stdout)
+        if print_headers:
+            # replace newlines with spaces in headers
+            headers = [h.replace('\n', ' ') for h in headers]
+            writer.writerow(headers)
+    elif tablefmt == 'markdown':
+        headers = [h.replace('\n', '<br>') for h in headers]
+    if tablefmt == 'csv':
+        try:
+            writer.writerows(rows)
+        except BrokenPipeError:
+            # Redirect remaining output to devnull to avoid another
+            # BrokenPipeError at shutdown
+            devnull = os.open(os.devnull, os.O_WRONLY)
+            os.dup2(devnull, sys.stdout.fileno())
+    else:
+        format_dict = {
+            'simple': 'simple',
+            'markdown': 'github'
+        }
+        tablefmt = format_dict[config.args.format]
+        with contextlib.suppress(BrokenPipeError):
+            kwargs = {
+                'headers': headers,
+                'floatfmt': floatfmt,
+                'tablefmt': tablefmt
+            }
+            line = tabulate(rows, **kwargs)
+            if not print_headers:
+                line = line.rsplit('\n', maxsplit=1)[-1]
+            print(line)

{requake-0.5 → requake-0.6}/requake/config/parse_arguments.py

@@ -34,6 +34,22 @@ class NewlineHelpFormatter(argparse.HelpFormatter):
         return lines
 
 
+class SubcommandHelpFormatter(argparse.RawDescriptionHelpFormatter):
+    """
+    Custom help formatter that removes the list of subcommands from the help
+    message.
+
+    See: https://stackoverflow.com/a/13429281/2021880
+    """
+    def _format_action(self, action):
+        parts = super(
+            argparse.RawDescriptionHelpFormatter, self
+        )._format_action(action)
+        if action.nargs == argparse.PARSER:
+            parts = '\n'.join(parts.split('\n')[1:])
+        return parts
+
+
 def parse_arguments(progname='requake'):
     """
     Parse command line arguments.
@@ -44,9 +60,14 @@ def parse_arguments(progname='requake'):
     :rtype: argparse.Namespace
     """
     parser = argparse.ArgumentParser(
-        description=f'{progname}: Repeating earthquakes search and analysis.'
-    )
-    subparser = parser.add_subparsers(dest='action')
+        description=f'{progname}: Repeating earthquakes search and analysis.',
+        epilog='Use "%(prog)s <command> -h" for help on a specific command\n'
+               '(example: "%(prog)s read_catalog -h").\n'
+               '\nFull documentation at https://requake.readthedocs.io',
+        formatter_class=SubcommandHelpFormatter
+    )
+    subparser = parser.add_subparsers(dest='action', title='commands')
+    subparser.metavar = '<command> [options]'
     parser.add_argument(
         '-c',
         '--configfile',
@@ -73,6 +94,16 @@ def parse_arguments(progname='requake'):
         help='write sample config file to current directory and exit'
     )
     # ---
+    # --- update_config
+    updateconfig = subparser.add_parser(
+        'update_config',
+        help='update an existing config file to the latest version'
+    )
+    updateconfig.add_argument(
+        'config_file', default='requake.conf', nargs='?',
+        help='config file to be updated (default: %(default)s)'
+    )
+    # ---
     # --- read catalog
     readcatalog = subparser.add_parser(
         'read_catalog',
@@ -103,6 +134,22 @@ def parse_arguments(progname='requake'):
         '-a', '--append', action='store_true',
         help='append events to existing catalog'
     )
+    # --- printformat
+    #     a parent parser for the "format" option,
+    #     used by the "print" subparsers
+    printformat = argparse.ArgumentParser(add_help=False)
+    printformat.add_argument(
+        '-f', '--format', type=str, default='simple',
+        choices=['simple', 'markdown', 'csv'],
+        help='format for the output table (default: %(default)s)'
+    )
+    # ---
+    # --- print_catalog
+    subparser.add_parser(
+        'print_catalog',
+        parents=[printformat],
+        help='print the event catalog to screen'
+    )
     # ---
     # --- scan_catalog
     subparser.add_parser(
@@ -110,6 +157,23 @@ def parse_arguments(progname='requake'):
         help='scan an existing catalog for earthquake pairs'
     )
     # ---
+    # --- print_pairs
+    printpairs = subparser.add_parser(
+        'print_pairs',
+        parents=[printformat],
+        help='print pairs to screen'
+    )
+    printpairs.add_argument(
+        '-c', '--cc_min',
+        type=float, default=None,
+        help='minimum cross-correlation coefficient (default: %(default)s)'
+    )
+    printpairs.add_argument(
+        '-C', '--cc_max',
+        type=float, default=None,
+        help='maximum cross-correlation coefficient (default: %(default)s)'
+    )
+    # ---
     # --- plot_pair
     plotpair = subparser.add_parser(
         'plot_pair',
@@ -166,16 +230,11 @@ def parse_arguments(progname='requake'):
     )
     # ---
     # --- print_families
-    printfamilies = subparser.add_parser(
+    subparser.add_parser(
         'print_families',
-        parents=[longerthan, minevents, familynumbers],
+        parents=[longerthan, minevents, familynumbers, printformat],
         help='print families to screen'
     )
-    printfamilies.add_argument(
-        '-f', '--format', type=str, default='simple',
-        choices=['simple', 'markdown', 'csv'],
-        help='format for the output table (default: %(default)s)'
-    )
     # ---
     # --- plot_families
     plotfamilies = subparser.add_parser(
@@ -207,11 +266,20 @@ def parse_arguments(progname='requake'):
         help='quantity to sort families by on y-axis (default: %(default)s)'
     )
     # ---
-    # --- plot_slip
-    subparser.add_parser(
-        'plot_slip',
+    # --- plot_cumulative
+    plotcumulative = subparser.add_parser(
+        'plot_cumulative',
         parents=[longerthan, minevents, familynumbers],
-        help='plot cumulative slip for one or more families'
+        help='cumulative plot for one or more families'
+    )
+    plotcumulative.add_argument(
+        '-q', '--quantity', type=str, default='slip',
+        choices=['slip', 'moment', 'number'],
+        help='cumulative quantity to plot on y-axis (default: %(default)s)'
+    )
+    plotcumulative.add_argument(
+        '-L', '--logscale', action='store_true',
+        help='use log scale for y-axis'
     )
     # ---
     # --- map_families
@@ -242,8 +310,7 @@ def parse_arguments(progname='requake'):
     # --- flag_family
     flagfamily = subparser.add_parser(
         'flag_family',
-        help='flag a family of repeating earthquakes as valid or not valid. '
-             'Note that all families are valid by default when first created'
+        help='flag a family of repeating earthquakes as valid or not valid'
     )
     flagfamily.add_argument('family_number')
     flagfamily.add_argument(

{requake-0.5 → requake-0.6}/requake/config/rq_setup.py

@@ -25,7 +25,7 @@ from .._version import get_versions
 from .config import Config
 from .utils import (
     parse_configspec, read_config, validate_config, write_sample_config,
-    write_ok
+    update_config_file, write_ok
 )
 # pylint: disable=global-statement,import-outside-toplevel
 
@@ -50,6 +50,20 @@ def _check_library_versions():
     OBSPY_VERSION_STR = obspy.__version__
 
 
+def _make_outdir(outdir):
+    """Create the output directory if it doesn't exist."""
+    if not os.path.exists(outdir):
+        os.makedirs(outdir)
+    readme = os.path.join(outdir, 'README.txt')
+    if not os.path.exists(readme):
+        with open(readme, 'w', encoding='utf8') as fp:
+            fp.write('This is the Requake output directory.\n\n')
+            fp.write('''\
+Do not manually edit the files in this directory, unless you know what you
+are doing.
+''')
+
+
 def _setup_logging(config, progname, action_name):
     """Set up the logging infrastructure."""
     global logger
@@ -68,8 +82,7 @@ def _setup_logging(config, progname, action_name):
         'build_families'
     ]
     if action_name in logging_actions:
-        if not os.path.exists(config.args.outdir):
-            os.makedirs(config.args.outdir)
+        _make_outdir(config.args.outdir)
         logfile = os.path.join(
             config.args.outdir, f'{progname}.{action_name}.log')
         filehand = logging.FileHandler(filename=logfile, mode='a')
@@ -190,6 +203,9 @@ def configure(args):
     if args.action == 'sample_config':
         write_sample_config(configspec, 'requake')
         sys.exit(0)
+    if args.action == 'update_config':
+        update_config_file(args.configfile, configspec)
+        sys.exit(0)
     config_obj = read_config(args.configfile, configspec)
     # Set to None all the 'None' strings
     for key, value in config_obj.dict().items():
@@ -261,8 +277,9 @@ def rq_exit(retval=0, abort=False, progname='requake'):
     """Exit as gracefully as possible."""
     if abort:
         print('\nAborting.')
-        logger.debug(f'{progname} ABORTED\n\n')
-    else:
+        if logger is not None:
+            logger.debug(f'{progname} ABORTED\n\n')
+    elif logger is not None:
         logger.debug(f'{progname} END\n\n')
     logging.shutdown()
     sys.exit(retval)

{requake-0.5 → requake-0.6}/requake/config/utils.py

@@ -12,8 +12,8 @@ Utility functions for Requake.
 import os
 import sys
 import locale
-import traceback
-from .. import __version__
+import shutil
+from datetime import datetime
 from .configobj import ConfigObj
 from .configobj.validate import Validator
 locale.setlocale(locale.LC_ALL, '')
@@ -133,6 +133,53 @@ def validate_config(config_obj):
         err_exit('No configuration value present!')
 
 
+def update_config_file(config_file, configspec):
+    """
+    Update a configuration file to the latest version.
+
+    :param config_file: Configuration file.
+    :type config_file: str
+    :param configspec: Configuration specification file.
+    :type configspec: str
+    """
+    config_obj = read_config(config_file, configspec)
+    val = Validator()
+    config_obj.validate(val)
+    mod_time = datetime.fromtimestamp(os.path.getmtime(config_file))
+    mod_time_str = mod_time.strftime('%Y%m%d_%H%M%S')
+    config_file_old = f'{config_file}.{mod_time_str}'
+    ans = input(
+        f'Ok to update {config_file}? [y/N]\n'
+        f'(Old file will be saved as {config_file_old}) '
+    )
+    if ans not in ['y', 'Y']:
+        sys.exit(0)
+    config_new = ConfigObj(configspec=configspec, default_encoding='utf8')
+    config_new = read_config(None, configspec)
+    config_new.validate(val)
+    config_new.defaults = []
+    config_new.comments = configspec.comments
+    config_new.initial_comment = config_obj.initial_comment
+    config_new.final_comment = configspec.final_comment
+    for k, v in config_obj.items():
+        if k not in config_new:
+            continue
+        # Fix for force_list(default=None)
+        if v == ['None', ]:
+            v = None
+        config_new[k] = v
+    migrate_options = {
+        # 'old_option': 'new_option'
+    }
+    for old_opt, new_opt in migrate_options.items():
+        if old_opt in config_obj and config_obj[old_opt] != 'None':
+            config_new[new_opt] = config_obj[old_opt]
+    shutil.copyfile(config_file, config_file_old)
+    with open(config_file, 'wb') as fp:
+        config_new.write(fp)
+        print(f'{config_file}: updated')
+
+
 def manage_uncaught_exception(exception):
     """
     Manage an uncaught exception.
@@ -140,6 +187,13 @@ def manage_uncaught_exception(exception):
     :param exception: Exception object.
     :type exception: Exception
     """
+    # pylint: disable=import-outside-toplevel
+    from .. import __version__
+    import traceback
+    import numpy as np
+    import scipy as sp
+    import obspy
+    import matplotlib
     sys.stderr.write("""
 # BEGIN TRACEBACK #############################################################
 """)
@@ -160,6 +214,10 @@ Include the following information in your report:
 """)
     sys.stderr.write(f'  Requake version: {__version__}\n')
     sys.stderr.write(f'  Python version: {sys.version}\n')
+    sys.stderr.write(f'  NumPy version: {np.__version__}\n')
+    sys.stderr.write(f'  SciPy version: {sp.__version__}\n')
+    sys.stderr.write(f'  ObsPy version: {obspy.__version__}\n')
+    sys.stderr.write(f'  Matplotlib version: {matplotlib.__version__}\n')
     sys.stderr.write(f'  Platform: {sys.platform}\n')
     sys.stderr.write(f'  Command line: {" ".join(sys.argv)}\n')
     sys.stderr.write(f'  Error message: {str(exception)}\n')

{requake-0.5 → requake-0.6}/requake/families/__init__.py

@@ -10,6 +10,7 @@ earthquakes.
     GNU General Public License v3.0 or later
     (https://www.gnu.org/licenses/gpl-3.0-standalone.html)
 """
+from .print_pairs import print_pairs  # noqa
 from .build_families import build_families  # noqa
 from .print_families import print_families  # noqa
 from .flag_family import flag_family  # noqa