.. highlight:: rst

.. _autosigma:

#########
autosigma
#########

**Strong event parameter processing**


Description
===========

AUTOSIGMA is an automatic module to compute and visualize ground motion
parameters based on :term:`SeisComP events <event>`. The computed parameters are
stored as :term:`incidents <incident>` in the SIGMA database.



Module Configuration
====================

| :file:`etc/defaults/global.cfg`
| :file:`etc/defaults/autosigma.cfg`
| :file:`etc/global.cfg`
| :file:`etc/autosigma.cfg`
| :file:`~/.seiscomp/global.cfg`
| :file:`~/.seiscomp/autosigma.cfg`

autosigma inherits :ref:`global options<global-configuration>`.

.. note::

   Modules/plugins may require a license file. The default path to license
   files is :file:`@DATADIR@/licenses/` which can be overridden by global
   configuration of the parameter :confval:`gempa.licensePath`. Example: ::

      gempa.licensePath = @CONFIGDIR@/licenses



.. confval:: magnitudeFilterTable

   Type: *list:string*

   Magnitude\-dependent filter table. The format is
   \"mag1:fmin1;fmax1, mag2:fmin2;fmax2, mag3:fmin3;fmax3\".
   If a magnitude falls between two configured magnitudes, the filter
   of the lower magnitude is used. No interpolation takes place.
   Magnitude outside the configured range are clipped to the
   lowest\/highest value.
   Frequency values are given as simple positive doubles \(Hz is assumed\)
   or with suffix \"fNyquist\" which is then multiplied by the
   Nyquist frequency of the data to get the final corner frequency.
   
   The final frequency values are used as a replacement for
   the profile filter.loFreq and filter.hiFreq parameters unless
   the table is empty.


.. confval:: profiles

   Type: *list:string*

   A list of profiles defining event and region criteria with processing.
   Provide at least one profile.


.. note::

   **cron.\***
   *Timing parameters controlling the automatic event processing.*


.. confval:: cron.wakeupInterval

   Default: ``10``

   Unit: *s*

   Type: *int*

   Time interval to test for new events.


.. confval:: cron.eventKeep

   Default: ``3600``

   Unit: *s*

   Type: *int*

   The time interval to keep events in the buffer. During this
   interval events are available for processing.


.. confval:: cron.delayTimes

   Unit: *s*

   Type: *list:int*

   List of time intervals to delay the processing of new events.
   The delayTimes are added to the originTime.
   delayTimes > 0 s allow to load complete waveforms within the
   requested time windows. Provide a comma\-separated list to repeat
   the data processing of new events allowing for more complete
   data from stations with longer data delay or larger epicentral
   distances.


.. confval:: cron.updateDelay

   Default: ``60``

   Unit: *s*

   Type: *int*

   Time delay to test for event updates of already loaded events.


.. note::

   **acquisition.\***
   *Control parameters for waveform data acquisition.*


.. confval:: acquisition.maximumEpicentralDistance

   Default: ``400``

   Unit: *km*

   Type: *double*

   Maximum epicentral distance for considering stations.


.. confval:: acquisition.magnitudeDistanceTable

   Type: *list:string*

   Magnitude dependent maximum epicentral distance table. The format is
   
   mag1:km1, mag2:km2, mag3:km
   
   The distance value is given in km. If a magnitude falls between
   two configured magnitudes, the distance of the lower magnitude is
   used then. No interpolation is performed. Magnitude outside the
   configured range are clipped to the lowest\/highest value.
   
   The final value is used as a replacement for
   acquisition.maximumEpicentralDistance unless the table is empty.
   Example: 3:400, 4:450, 5:500


.. confval:: acquisition.initialTimeout

   Default: ``30``

   Unit: *s*

   Type: *int*

   


.. confval:: acquisition.runningTimeout

   Default: ``2``

   Unit: *s*

   Type: *int*

   


.. confval:: acquisition.streams.whitelist

   Type: *list:string*

   A list of streams considered for processing.
   If set, no other streams will be used.


.. confval:: acquisition.streams.blacklist

   Type: *list:string*

   A list of streams excluded from processing.
   The listed streams will be ignored.


.. note::

   **gmpe.\***
   *Vs30 grid and definition of external GMPEs.*


.. confval:: gmpe.vs30grid

   Type: *path*

   The path to a Vs30 GeoTIFF or grid file, e.g.
   the global_vs30.tif GeoTIFF file provided by USGS. Grid files
   must be in a modified Surfer6 format where dimX and
   dimY are integers rather than shorts. The magic first 4 bytes
   contain \"GGBB\". The GeoTIFF reader is
   activated if the file extension is \".tif\".


.. note::

   **gmpe.py.\***
   *Adds configuration for processing based on Python2 GMPE models.*
   *Refer to as "py2gmpe" for the provider configured in profile.$name.*


.. confval:: gmpe.py.models

   Type: *list:string*

   The PyGMPE models available and their corresponding python filename.
   The format of each list entry is \"modelname;filename\". If
   the semicolon is omitted then the item is expected to be the
   modelname and a file with the same name and extension .py will
   be searched for.


.. confval:: gmpe.py.basePath

   Default: ``@CONFIGDIR@/pygmpe/``

   Type: *path*

   The base path for all python model implementations.


.. note::

   **gmpe.py3.\***
   *Adds configuration for processing based on Python3 GMPE models.*
   *Refer to as "py3gmpe" for the provider configured in profile.$name.*


.. confval:: gmpe.py3.models

   Type: *list:string*

   The Py3GMPE models available and their corresponding python filename.
   The format of each list entry is \"modelname;filename\". If
   the semicolon is omitted then the item is expected to be the
   modelname and a file with the same name and extension .py will
   be searched for.


.. confval:: gmpe.py3.basePath

   Default: ``@CONFIGDIR@/pygmpe/``

   Type: *path*

   The base path for all python model implementations.


.. note::

   **output.\***
   *Parameters controlling the output of processing products.*


.. confval:: output.database

   Type: *string*

   Configures the URI of the output database containing the SIGMA tables.
   If nothing is configured, the SeisComP database will be used.


.. confval:: output.exportPath

   Default: ``@LOGDIR@/autosigma``

   Type: *path*

   The path where all result files are saved.


.. confval:: output.exportScript

   Type: *path*

   The script that will be called when an incident is
   exported. Please ensure that the script is executable.
   3 parameters are passed: The eventID, an internal
   eventID and the export path where all files are
   stored.
   
   Provided example script: \@DATADIR\@\/sigma\/scripts\/export\-autosigma.sh


.. confval:: output.exportTimeout

   Default: ``60``

   Unit: *s*

   Type: *int*

   Timeout in seconds for the export script before it will be
   killed.


.. confval:: output.logfile

   Type: *path*

   Name of the logfile containing the processing logs.


.. confval:: output.mmi

   Default: ``true``

   Type: *boolean*

   Export MMI grids and images.


.. confval:: output.pga

   Default: ``true``

   Type: *boolean*

   Export PGA grids and images.


.. confval:: output.pgv

   Default: ``false``

   Type: *boolean*

   Export PGV grids and images.


.. note::

   **profile.\***
   *Profiles for customized regions and event criteria with specific*
   *GMPEs and processing.*
   *Internally defined models ("cppgmpe/CEA2014" and*
   *"cppgmpe/BEA2014") and external GMPEs, e.g.*
   *"py3gmpe/AbrahamsonEtAl2014" can be used.*
   *External GMPEs are defined in the gmpe section of the configuration.*


.. note::

   **profile.$name.\***
   *GMPE, event, image and grid parameters (mandatory).*
   $name is a placeholder for the name to be used and needs to be added to :confval:`profiles` to become active.

   .. code-block:: sh

      profiles = a,b
      profile.a.value1 = ...
      profile.b.value1 = ...
      # c is not active because it has not been added
      # to the list of profiles
      profile.c.value1 = ...


.. confval:: profile.$name.gmpe

   Type: *string*

   Defines the GMPE model to be used. The format is
   <provider>\/<model>, analogue to SIGMA,e.g.
   \"cppgmpe\/CEA2014\" or \"py3gmpe\/AbrahamsonEtAl2014\".


.. confval:: profile.$name.region

   Type: *string*

   The region name of a configured region \(e.g. with BNA
   files in \@DATADIR\@\/bna or \~\/.seiscomp\/bna\) for which the
   processing parameters are valid. Considered events must
   lie within the region.


.. confval:: profile.$name.rect

   Type: *list:double*

   Configures an alternative region filter with a
   rectangle. The 4 expected values are latMin, lonMin,
   latMax, lonMax. The region parameter takes priority
   over the rect parameter.


.. confval:: profile.$name.minimumMagnitude

   Type: *double*

   Defines the minimum magnitude that must be reached to start
   processing. By default this check is disabled.


.. confval:: profile.$name.deltaMagnitude

   Default: ``0.5``

   Type: *double*

   Trigger re\-processing when changes in event magnitude exceed deltaMagnitude.


.. confval:: profile.$name.deltaLocation

   Default: ``10``

   Unit: *km*

   Type: *double*

   Trigger re\-processing when changes in hypocenter location exceed deltaLocation.


.. note::

   **profile.$name.capture.\***
   *Parameters controlling the image capturing.*


.. confval:: profile.$name.capture.region

   Unit: *degrees*

   Type: *string*

   Defines the region rectangle of the plotted map.
   
   Formats:
   
   +lat0+lon0+lat1+lon1 : region rectangle by minimum and
   maximum latitude and longitude.
   
   [lat_dim]x[lon_dim]+lat0+lon0 : dimension + origin coordinate.


.. confval:: profile.$name.capture.dim.x

   Default: ``512``

   Unit: *px*

   Type: *int*

   Defines the X resolution of the output map images in pixels.


.. confval:: profile.$name.capture.dim.y

   Default: ``512``

   Unit: *px*

   Type: *int*

   Defines the Y resolution of the output map images in pixels.


.. note::

   **profile.$name.grid.\***
   *Parameters controlling the generation of grids for plotting on maps.*


.. confval:: profile.$name.grid.extent.lat

   Default: ``5``

   Unit: *deg*

   Type: *double*

   Defines the latitudinal extent of the processing grid for
   GMPEs.


.. confval:: profile.$name.grid.extent.lon

   Default: ``5``

   Unit: *deg*

   Type: *double*

   Defines the longitudinal extent of the processing grid for
   GMPEs.


.. confval:: profile.$name.grid.dim.x

   Default: ``512``

   Unit: *cnt*

   Type: *int*

   Defines the X \(longitude\) resolution of the processing grid.


.. confval:: profile.$name.grid.dim.y

   Default: ``512``

   Unit: *cnt*

   Type: *int*

   Defines the Y \(latitude\) resolution of the processing grid.


.. note::

   **profile.$name.processing.\***
   *Processing parameters.*


.. confval:: profile.$name.processing.targetDistricts

   Type: *list:string*

   A list of Shapefile paths used as target districts for GMPE\/intensity
   computation used for GeoJSON export.


.. confval:: profile.$name.processing.preEventWindowLength

   Default: ``60``

   Unit: *s*

   Type: *int*

   The pre event time window length in seconds.


.. confval:: profile.$name.processing.postEventWindowLength

   Default: ``(0.36*d)+60``

   Unit: *s*

   Type: *string*

   Default value of time window length after the event onset in seconds. This
   value is an numerical expression and can include four symbols: d \(distance in km\),
   D \(distance in degree\), az \(azimuth clockwise from North\) and M \(magnitude value\).


.. confval:: profile.$name.processing.eventCutOff

   Default: ``true``

   Type: *boolean*

   Enables\/disables pre event cut\-off. A hardcoded sta\/lta algorithm
   \(with sta\=0.1s, lta\=2s, sta\/lta threshold\=1.2\) is run on the time
   window defined by \(expected_P_arrival_time \- 15 s\). The pre event
   window is hence defined as
   [t\(sta\/lta \=1.2\) \- 15.5s, t\(sta\/lta \=1.2\) \- 0.5s].


.. confval:: profile.$name.processing.afterShockRemoval

   Default: ``true``

   Type: *boolean*

   Enables\/disables aftershock removal \(Figini, 2006; Paolucci et al., 2008\)


.. confval:: profile.$name.processing.durationScale

   Default: ``1.5``

   Type: *double*

   Defines the factor applied to the signigicant duration to define the
   processing spetra time window. If that value is <\= 0,
   the totalTimeWindowLength is used.


.. confval:: profile.$name.processing.STAlength

   Default: ``1``

   Unit: *s*

   Type: *double*

   The STA length in seconds of the applied STA\/LTA check.


.. confval:: profile.$name.processing.LTAlength

   Default: ``60``

   Unit: *s*

   Type: *double*

   The LTA length in seconds of the applied STA\/LTA check.


.. confval:: profile.$name.processing.STALTAratio

   Default: ``3``

   Type: *double*

   The minimum STALTA ratio to be reached to further process
   a station.


.. confval:: profile.$name.processing.STALTAmargin

   Default: ``5``

   Unit: *s*

   Type: *double*

   The number of seconds around P to be used to check the STA\/LTA ratio.


.. note::

   **profile.$name.processing.filter.\***
   *Parameters of the 1st stage filter.*


.. confval:: profile.$name.processing.filter.order

   Default: ``4``

   Type: *int*

   The order of the 1st stage filter.


.. confval:: profile.$name.processing.filter.loFreq

   Default: ``0.025``

   Unit: *Hz*

   Type: *double*

   Specifies the frequency of the 1st stage hi\-pass filter. If this
   parameter is equal to 0 the hi\-pass filter is not used.
   If negative, then the absolute value is multiplied
   by the Nyquist frequency of the data to get the final corner
   frequency of the filter.


.. confval:: profile.$name.processing.filter.hiFreq

   Default: ``40``

   Unit: *Hz*

   Type: *double*

   Specifies the frequency of the 1st stage lo\-pass filter. If this
   parameter is equal to 0 the lo\-pass filter is not used.
   If negative, then the absolute value is multiplied
   by the Nyquist frequency of the data to get the final corner
   frequency of the filter.


.. note::

   **profile.$name.processing.spectra.\***
   *Parameters controlling the calculation of Fourier spectra.*


.. confval:: profile.$name.processing.spectra.taperLength

   Default: ``-1``

   Unit: *s*

   Type: *double*

   Defines the cosine taper length in seconds if non\-causal filters
   are activated applied on either side of the waveform. If a
   negative length is given 10 percent of the pre event window length
   is used on either side of the waveform.


.. confval:: profile.$name.processing.spectra.padLength

   Default: ``-1``

   Unit: *s*

   Type: *double*

   The length of the zero padding window in seconds applied on either
   side of the waveform. If negative, it is computed following
   Boore \(2005\) as 1.5\*order\/corner_freq and applied half at the
   beginning and half at the end of the waveform.


.. note::

   **profile.$name.processing.prs.\***
   *Parameters controlling the calculation of Pseudo Response Spectra.*


.. confval:: profile.$name.processing.prs.damping

   Default: ``5``

   Unit: *%*

   Type: *double*

   The damping value \(in percent\) for computation
   of the pseudo absolute acceleration elastic response
   spectrum.


.. confval:: profile.$name.processing.prs.periods

   Default: ``0.3,1,3``

   Unit: *s*

   Type: *list:double*

   The natural periods for computation of the
   pseudo absolute acceleration elastic response spectrum.


.. confval:: profile.$name.processing.prs.Tmin

   Default: ``-1``

   Unit: *s*

   Type: *double*

   The lower bound of the period range to compute response spectra for.
   A negative value disables the range and only the list of
   periods is used.


.. confval:: profile.$name.processing.prs.Tmax

   Default: ``-1``

   Unit: *s*

   Type: *double*

   The upper bound of the period range to compute response spectra for.
   A negative value disables the range and only the list of
   periods is used.


.. confval:: profile.$name.processing.prs.naturalPeriods

   Default: ``0``

   Type: *int*

   The number of natural periods that are created with linear
   spacing between Tmin and Tmax.


.. note::

   **capture.\***
   *Parameters controlling the image capturing. They are overridden*
   *if defined in profiles.*


.. confval:: capture.region

   Unit: *degrees*

   Type: *string*

   Defines the region rectangle of the plotted map.
   
   Formats:
   
   +lat0+lon0+lat1+lon1 : region rectangle by minimum and
   maximum latitude and longitude.
   
   [lat_dim]x[lon_dim]+lat0+lon0 : dimension + origin coordinate.


.. confval:: capture.dim.x

   Default: ``512``

   Unit: *px*

   Type: *int*

   Defines the X resolution of the output map images in pixels.


.. confval:: capture.dim.y

   Default: ``512``

   Unit: *px*

   Type: *int*

   Defines the Y resolution of the output map images in pixels.


.. note::

   **grid.\***
   *Parameters controlling the generation of grids for plotting on maps.*
   *They are overridden if defined in profiles.*


.. confval:: grid.extent.lat

   Default: ``5``

   Unit: *deg*

   Type: *double*

   Defines the latitudinal extent of the processing grid for
   GMPEs.


.. confval:: grid.extent.lon

   Default: ``5``

   Unit: *deg*

   Type: *double*

   Defines the longitudinal extent of the processing grid for
   GMPEs.


.. confval:: grid.dim.x

   Default: ``512``

   Unit: *cnt*

   Type: *int*

   Defines the X \(longitude\) resolution of the processing grid.


.. confval:: grid.dim.y

   Default: ``512``

   Unit: *cnt*

   Type: *int*

   Defines the Y \(latitude\) resolution of the processing grid.


.. note::

   **map.\***
   *Parameters controlling the map features.*


.. confval:: map.grayscale

   Default: ``false``

   Type: *boolean*

   Whether to render the map grayscale or coloured.


.. confval:: map.grid.composition

   Default: ``default``

   Type: *string*

   Sets the mode of the GMPE grid map overlay. Possible
   values are: default, src, src\-over, xor, plus, multiply.


.. confval:: map.grid.triangle

   Default: ``false``

   Type: *boolean*

   If enabled then station symbols are being rendered
   as triangles. Otherwise a diamond shape is being used.


.. confval:: map.station.annotation

   Default: ``true``

   Type: *boolean*

   Whether to show station annotations \(codes\) or not.


.. confval:: map.station.triangle

   Default: ``false``

   Type: *boolean*

   If enabled then station symbols are being rendered
   as triangles. Otherwise a diamond shape is being used.


.. confval:: map.event.legend

   Default: ``false``

   Type: *boolean*

   Whether to show the event legend or not.


.. note::

   **scheme.colors.\***
   *Define colors.*


.. confval:: scheme.colors.sigma.intensity

   Type: *gradient*

   The intensity color gradient for ground motion values.
   This gradient will be used without normalization.


.. confval:: scheme.colors.sigma.gradient

   Type: *gradient*

   The base color gradient for ground motion values.
   This gradient will be scaled to the final value range
   unless absolute scale is enabled in sigma.


.. confval:: scheme.colors.sigma.normalize

   Default: ``true``

   Type: *boolean*

   Whether to normalize the base color gradient to the
   current value range or not.



Bindings Parameters
===================


.. confval:: enable

   Default: ``true``

   Type: *boolean*

   Enables\/disables the station for strong motion processing.


.. confval:: channels

   Type: *list:string*

   Defines a list of preferred channels that are activated
   by default for that station. If this option is undefined,
   the highest sample rate channels for acceleration
   and velocity are used by default. If the list is empty
   \(which is a different state than undefined\), then no channels
   are selected by default.





Command-Line Options
====================


Generic
-------

.. option:: -h, --help

   Show help message.

.. option:: -V, --version

   Show version information.

.. option:: --config-file arg

   Use alternative configuration file. When this option is
   used the loading of all stages is disabled. Only the
   given configuration file is parsed and used. To use
   another name for the configuration create a symbolic
   link of the application or copy it. Example:
   scautopick \-> scautopick2.

.. option:: --plugins arg

   Load given plugins.

.. option:: -D, --daemon

   Run as daemon. This means the application will fork itself
   and doesn't need to be started with \&.

.. option:: --auto-shutdown arg

   Enable\/disable self\-shutdown because a master module shutdown.
   This only works when messaging is enabled and the master
   module sends a shutdown message \(enabled with \-\-start\-stop\-msg
   for the master module\).

.. option:: --shutdown-master-module arg

   Set the name of the master\-module used for auto\-shutdown.
   This is the application name of the module actually
   started. If symlinks are used, then it is the name of
   the symlinked application.

.. option:: --shutdown-master-username arg

   Set the name of the master\-username of the messaging
   used for auto\-shutdown. If \"shutdown\-master\-module\" is
   given as well, this parameter is ignored.


Verbosity
---------

.. option:: --verbosity arg

   Verbosity level [0..4]. 0:quiet, 1:error, 2:warning, 3:info,
   4:debug.

.. option:: -v, --v

   Increase verbosity level \(may be repeated, eg. \-vv\).

.. option:: -q, --quiet

   Quiet mode: no logging output.

.. option:: --component arg

   Limit the logging to a certain component. This option can
   be given more than once.

.. option:: -s, --syslog

   Use syslog logging backend. The output usually goes to
   \/var\/lib\/messages.

.. option:: -l, --lockfile arg

   Path to lock file.

.. option:: --console arg

   Send log output to stdout.

.. option:: --debug

   Execute in debug mode.
   Equivalent to \-\-verbosity\=4 \-\-console\=1 .

.. option:: --log-file arg

   Use alternative log file.


Database
--------

.. option:: --db-driver-list

   List all supported database drivers.

.. option:: -d, --database arg

   The database connection string, format:
   service:\/\/user:pwd\@host\/database.
   \"service\" is the name of the database driver which
   can be queried with \"\-\-db\-driver\-list\".

.. option:: --config-module arg

   The config module to use.

.. option:: --inventory-db arg

   Load the inventory from the given database or file, format:
   [service:\/\/]location .


Records
-------

.. option:: --record-driver-list

   List all supported record stream drivers.

.. option:: -I, --record-url arg

   The recordstream source URL, format:
   [service:\/\/]location[#type].
   \"service\" is the name of the recordstream driver
   which can be queried with \"\-\-record\-driver\-list\".
   If \"service\" is not given, \"file:\/\/\" is
   used.

.. option:: --record-file arg

   Specify a file as record source.

.. option:: --record-type arg

   Specify a type for the records being read.


Mode
----

.. option:: --offline

   Invoke AUTOSIGMA in offline mode without
   connecting to the SeisComP messaging system.

.. option:: -E, --event-ID

   ID of the event to be processed in offline mode.

.. option:: --dump-config

   Dump the configuration and exit.