gempa GmbH

Table Of Contents

This Page

shard

SHARD application suite

Description

SHARD is a web based application to monitor the structural health. PSAs calculated in real-time are compared with response spectra given in design codes as the EC, NEHRP or DIN codes. Exceedance is checked and warning incidents are issued. In addition to the spectral comparison also data qualit as delay and variance are tracked and quality incidents are generated. The built-in incident browser allows a quick and easy access to the history showing data quality, exceedance and earthquake occurance. Incidents are displayed in heat maps giving an instant overview.

The SHARD application suite consists of a backend that is running continuously in the background and processes the sensor data and two web frontends (dashboard and incident browser) that are available in an Internet browser.

When the shard daemon has been started it accepts by default connections on port 8080. The URL http://localhost:8080/index.html would bring up the following landing page:

_images/page_index.png

Architecture

The application follows the client-server-model. The server gathers the waveform data and aggregates them. In detail that means all calculations are done in the backend.

_images/homes_data_flow.png

Installation

  • Unpack archive(s):
    • gempa-shard-server-[vmaj.vmin]-jakarta-[year].[day]-[os].tar.gz
    • gempa-shard-frontends-[vmaj.vmin]-jakarta-[year].[day]-any-noarch.tar.gz
    • gempa-shard-[vmaj.vmin]-jakarta-[year].[day]-doc.tar.gz

Building configuration

SHARD needs to know how stations are deployed in buildings. The inventory that is used to describe stations and instruments is not sufficient for that task. Until more formal schema extensions are available SHARD uses its own configuration.

Buildings can be configured with scconfig or directly in shard.cfg. The entry point is buildings. This variable holds a list of building ids that shall be used. Each building id points to additional entries in the configuration. An example:

# Configure two buildings, A and B
buildings = A,B

Now only two building ids are requested but they are not yet configured. That is done with the building prefix, as shown below:

# Configure building A
building.A.name = "A building"
building.A.description = "Description of building A"
building.A.latlon = 1,2
building.A.picture = ../pics/A.png

That piece just configured the meta data of the building itself. The next step is to configure the sensors that are placed in the building.

# Building A has two sensors, top and bottom. These are just ids and are
# not used anywhere else.
building.A.sensors = top, bottom

Analogous to the building configuration sensors are configured via ids:

# Name that is shown in the frontend
building.A.sensor.top.name = "Top Sensor"
building.A.sensor.top.id = AB.STA01
building.A.sensor.top.type = acceleration
building.A.sensor.top.imgpos = 100, 200
building.A.sensor.top.channels = HLZ,HLN,HLE

That step has to be repeated for sensor bottom as well. The channels are appended to the sensor id to form a full waveform channel id. In the example above the resulting channel ids are AB.STA01..HLZ, AB.STA01..HLN and AB.STA01..HLE.

If the channels should have a location code then this must be added to the sensor id:

building.A.sensor.top.id = AB.STA01.00

Then the resulting channel ids are AB.STA01.00.HLZ, AB.STA01.00.HLN and AB.STA01.00.HLE.

Dashboard

The default URL http://localhost:8080/dashboard/ launches the SHARD dashboard:

_images/page_dashboard.png

The dashboard visualizes the actual information regarding pseudo response spectra, waveforms and station quality. It shows the location and shape of the building and position of sensors as well. This information is visualized in bar charts, bar diagram, photo and interactive map.

The visible screen ist seperated in two columns:

  1. The left side shows a column consisting of three widgets:

    1. The map showing all buildings and recorded events of a certain time period configured with apps.events.timeSpan.

      _images/slippy_map.png
    2. A configurable photo of the currently selected monitored building. Sensors can placed (drawn as a circle) within the photo.

      _images/photo_widget.png
    3. A table with the last 100 incidents for the currently selected building.

      _images/incident_table.png
  2. The right side shows a column with two main areas:

    1. The latest event information with respect to the currently selected building. The right part show two time values. The one with red background is the relative origin time (time ago) and the one with green background is the estimated arrival time at the building.

      _images/latest_event.png
    2. The Fourier spectra, pseudo acceleration response spectra and waveforms the the currently selected sensor.

      _images/channel_boxes.png

      Each box represents a single channel of the selected sensor. The pseudo acceleration response spectrum values for the configured frequencies and the maximum value of the last n hours which is configurable with avd.prsMaxTimeSpan are plotted in logarithmic scales and shown on the left side of a channel box. The waveforms (possibly converted to acceleration) are shown on the right side along with the configured warning and alert thresholds.

Usage

To switch between buildings or sensors click on either symbol in the map or the photo. The channel boxes will update immediately according to the new selection. If a warning or alert is reported the respective building and sensor symbol will turn yellow or red.

i18n-Support

Language files are stored in the folder i18n. It holds a map of translated items. To adjust your preferences, first click Languages in Chrome settings and input settings (Mac & Linux: Language settings) to open the "Languages" dialog. Add or remove languages from the list, and drag to order them based on your preference. It is important to arrange the order of the available languages.

Incident browser

The default URL http://localhost:8080/browser/ launches the SHARD incident browser:

_images/page_browser.png

The incident browser lists SHARD incidents created from analyzing the waveform data such as response spectra exceedance as well as reported earthquakes.

Report generation

The incident browser allows to generate earthquake reports for a selected sensor. Click on an event and a popup will open.

_images/event_details.png

By default the report button is disabled because a sensor is required for which the report will be created. Select a sensor from the "Sensor for report" dropdown and the report button will be activated. Reports are named shard-report-[eventid].pfg and can be found in the download folder of the browser, usually $HOME/Downloads. An example report shard-report-gfz2016ajxe.pdf is attached to this documentation. Note that the example is just an arbitrary example and does not reflect a real setup of a structure.

Configuration

etc/defaults/global.cfg
etc/defaults/shard.cfg
etc/global.cfg
etc/shard.cfg
~/.seiscomp3/global.cfg
~/.seiscomp3/shard.cfg

shard inherits global options.

bind

Type: list:string

Set the adress and port for incoming connections. Default is 127.0.0.1:8080. Default is 127.0.0.1:8080.

mediaDirectory

Type: list:string

Set the path where to look for your web application. Default ${share directory}/shard/apps/ Default is @DATADIR@/shard/apps.

tileDB

Type: path

Configured the MBTiles tile database if shard should serve tiles itself. If mapURI is configured with a remote tile server, this is not required. Default is @DATADIR@/gaps/zoom12.mbtiles.

bufferSize

Type: int

Unit: byte

Set the buffer size for each request. Default are 65536 bytes. Default is 65536.

maximumThreads

Type: int

Set the maxmial amount of record threads. Default is 10. Default is 10.

requestTimeout

Type: int

Unit: s

Set the thread timeout. Default is 10s. Default is 10.

reportRecordStreamURI

Type: string

Sets the recordstream URI for report generation. It is important to note that this URI should be an archive source that does not block if data are not available such as Seedlink. In connection with CAPS the option "arch" should be used, e.g. "caps://localhost:18002?arch".

Type: string

The QuakeLink event request URI that is called from the SHARD server itself. It can be an internal URI but must start with either http:// or https://. The default value is taken from apps.quakelink.

reportUseCentiUnits

Type: boolean

Whether to use cm/s**2 or g, default is g. Default is false.

reportClipPSAToReferenceSpectrum

Type: boolean

Should the period domain for the PSA spectrum clipped with with reference spectrum or not. If yes then the minimum and maximum period of the computed PSA spectrum is inside the minimum and maximum periods of the given reference spectrum. Default is false.

reportTimeShift

Type: int

Unit: s

Shifts all timestamps occuring in the report by n seconds. Default is 0.

reportUseLocalTime

Type: boolean

Whether to use UTC or local time, default is UTC. Default is false.

reportUseRelativeTime

Type: boolean

Whether to use absolute or relative time in ruler. Default is false.

reportDefaultLocale

Type: string

The default language of automatic generated reports. The default language is "en" (English). Other supported languages are "es" (Spanish) and "de" (German). Default is en.

reportMinimumIntensity

Type: double

The minimum intensity (GMPE) at the building for automatic reporting. Default is 3.

reportMinimumDelay

Type: double

Unit: s

The minimum time delay after origin time for automatic reporting. Default is 180.

GDS

Type: string

The GDS dissemination address. Format is "host:port/queue", e.g. "localhost:20000/shard". Note that the queue must be configured in GDS.

buildings

Type: list:string

List of configured buildings. Each building listed here is the name of a parameter structure which has to be configured with "building.[name].*".

map.location

Type: path

Alternative configuration parameter for @tileDB. Default is @DATADIR@/gaps/zoom12.mbtiles.

Note

building.$name.* $name is a placeholder for the name to be used and needs to be added to buildings to become active.

buildings = a,b
building.a.value1 = ...
building.b.value1 = ...
# c is not active because it has not been added
# to the list of buildings
building.c.value1 = ...
building.$name.name

Type: string

Name of the building as shown in the frontend.

building.$name.description

Type: string

Optional building description to be used in e.g. tooltips.

building.$name.latlon

Type: list:double

Latitude and Longitude as two item list, e.g. 52.23456, 13.23456.

building.$name.type

Type: string

Optional building type that is used to generate a corresponding icon on the map. The type name corresponds to the filename of the icon to be used. This icon must exist in "$SEISCOMP_ROOT/share/shard/apps/share/css/icons/structure/[type].png". If the icon can not be found just a shadow is plotted onto the map at the position of the building/structure. Default is building.

building.$name.picture

Type: string

Path to your building picture relative to a path of a web application. This path is actually a URI and not a file path. It can be used as absolute path starting with "https://". Every locator that a browser supports is possible.

building.$name.recordBufferSize

Type: integer

Size of record buffer. It corresponds to the length of the data time window shown in the dashboard. Default is 1200.

building.$name.sensors

Type: list:string

List of sensors. Each sensor listed here is the name of a parameter structure which has to be configured with "building.[name].sensor.[sensor].*".

Note

building.$name.sensor.$name.* $name is a placeholder for the name to be used.

building.$name.sensor.$name.name

Type: string

The name of the sensor. The name is shown in the frontend.

building.$name.sensor.$name.type

Type: string

The type of the sensor. Types "acceleration", "velocity" and "displacement" are supported. If the type is velocity or displacement then data are differentiated to acceleration in the frontend.

building.$name.sensor.$name.id

Type: string

The sensor id. The id is composed of network-, station- and locationcode, e.g. "XX.ABCD". This will take the sensor location at station XX.ABCD with empty location code. A non-empty location code may be added to the station code, e.g. "XX.ABCD.00".

building.$name.sensor.$name.imgpos

Type: list:int

The position in the provided station picture of the sensor as two item list, e.g. 123, 456.

building.$name.sensor.$name.channels

Type: list:string

The list of channel codes for each component to be shown in the frontend.

building.$name.sensor.$name.displacementChannels

Type: list:string

The list of displacement channel codes for each component to be shown in the frontend if displacement traces are selected.

building.$name.sensor.$name.driftChannels

Type: list:string

The list of drift channel codes for each component to be shown in the frontend if drift traces are selected.

building.$name.sensor.$name.f1Channels

Type: list:string

The list of fundamental frequency channel codes for each component to be shown in the frontend if fundamental frequency traces are selected.

incidents.database

Type: string

Path to the SQLite3 database file. If a database server (e.g. MYSQL) should be used, provide a database URI as with any SeisComP3 application, e.g. "mysql://sysop:sysop@localhost/shard". Default is @ROOTDIR@/var/lib/shard/archive.db.

Note

apps.* Web app specific configurations.

apps.serverAPI

Type: string

Defines the pathe where to request your data. Default is: "../". Default is ../.

apps.mapURI

Type: string

Full URL for tiles. Default is http://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png.

apps.mapZoom

Type: int

The initial zoom of the map. Default is 18.

apps.minTraceScale

Type: double

The minimum trace scale in sensor units of trace data in e.g. the dashboard. Default is 2e-4.

Type: string

The QuakeLink event request URI that is called by the webbrowser that accesses the SHARD frontend. This URI must be public for the clients. Default is http://localhost:18080/events/query.

apps.events.timeSpan

Type: double

Unit: hours

Size of the event buffer in the browser. The default value shows e.g. the events of the last 12 hours in a map. Default is 12.

apps.events.filter

Type: string

In addition to the above filters this filter must contain a valid Quakelink WHERE statement which will be combined with the generated WHERE clause with AND. Don't set this option if you don't know what that really means.

apps.events.mag.min

Type: double

The minimum magnitude.

apps.events.mag.max

Type: double

The maximum magnitude.

apps.events.depth.min

Type: double

The minimum depth in km.

apps.events.depth.max

Type: double

Unit: km

The maximum depth in km.

apps.events.lat.min

Type: double

Unit: deg

The minimum latitude in degree.

apps.events.lat.max

Type: double

Unit: deg

The maximum latitude in degree.

apps.events.lon.min

Type: double

Unit: deg

The minimum longitude in degree.

apps.events.lon.max

Type: double

Unit: deg

The maximum longitude in degree.

Note

avd.* (A)cceleration, (V)elocity and (D)isplacement specific processing parameters.

avd.streams

Type: list:string

Defines a list of stream ids that can contain wildcards that should be processed. For each stream a real-time peak ground amplitude is computed.

avd.referenceSpectrum

Type: list:string

Defines a global default reference spectrum as a list of pairs frequency:magnitude, e.g. "0.5:1, 1:2, -1:3". -1 is a special frequency value that corresponds to the Nyquist frequency of the processed stream. If the reference spectrum is exceeded at at least one node an alert is issued.

avd.varianceThreshold

Type: double

Unit: sensor units squared

Defines a global default variance threshold. If the variance of the sensitivity corrected data used to compute a spectrum is below this threshold a warning is issued. Negative numbers disable warnings. Default is -1.

avd.delayThreshold

Type: double

Unit: s

Defines a global default delay threshold. If that threshold is exceeded per received record (receive time - record end time) a warning is issued. Negative numbers disable warnings. Default is -1.

avd.pgaWatch

Type: double

Unit: m/s/s

Defines a global default PGA threshold used to issue an information if exceeded. Default is -1.

avd.pgaWarning

Type: double

Unit: m/s/s

Defines a global default PGA threshold used to issue a warning if exceeded. Default is -1.

avd.pgaAlert

Type: double

Unit: m/s/s

Defines a global default PGA threshold used to issue an alert if exceeded. Default is -1.

avd.pgaWatchIntensity

Type: double

Unit: MMI

If not absolute pga watch threshold is configured it will be calculated according to the given MMI intensity according to Kaestli and Faeh (2006). Default is -1.

avd.pgaWarningIntensity

Type: double

Unit: MMI

If not absolute pga warning threshold is configured it will be calculated according to the given MMI intensity according to Kaestli and Faeh (2006). Default is -1.

avd.pgaAlertIntensity

Type: double

Unit: MMI

If not absolute pga alert threshold is configured it will be calculated according to the given MMI intensity according to Kaestli and Faeh (2006). Default is -1.

avd.incidentsMaxTimeSpan

Type: double

Defines the time span of incidents held in memory and sent to a client initially. Default is 1 hour. This buffer is a real time ring buffer and buffers the last configured time span of incidents. Default is 3600.

avd.prsMaxTimeSpan

Type: double

Unit: s

Defines the time span to compute the maximum value for each configured pseude elastic response spectrum frequency (node in the reference spectrum). A value <= 0 disables it. Default is 60.

avd.bindings

Type: list:string

Define a list of channel profiles to be used. The profiles are evaluated in the given order and each match updates the previous match.

Note

avd.bindings.$name.* $name is a placeholder for the name to be used.

avd.bindings.$name.patterns

Type: list:string

A list of stream id patterns that activate the profile a channel where its id matches at least one item of the pattern list. Each item can contain wildcards and network-, station-, location- and channel codes are separated with a dot.

avd.bindings.$name.referenceSpectrum

Type: list:string

The reference spectrum as a list of pairs (frequency:magnitude), e.g. "0.5:1, 1:2, -1:3". -1 is a special frequency value that corresponds to the Nyquist frequency of the processed stream. If the reference spectrum is exceeded at at least one node an alert is issued.

avd.bindings.$name.varianceThreshold

Type: double

Unit: sensor units squared

The variance threshold. If that threshold is exceeded with the variance of the sensitivity corrected raw data used to compute a spectrum a warning is issued. Negative numbers disable warnings. Default is -1.

avd.bindings.$name.delayThreshold

Type: double

Unit: s

The delay threshold. If that threshold is exceeded per received record (receive time - record end time) a warning is issued. Negative numbers disable warnings. Default is -1.

avd.bindings.$name.pgaWatch

Type: double

Unit: m/s/s

PGA threshold used to issue an information if exceeded. Default is -1.

avd.bindings.$name.pgaWarning

Type: double

Unit: m/s/s

PGA threshold used to issue a warning if exceeded. Default is -1.

avd.bindings.$name.pgaAlert

Type: double

Unit: m/s/s

PGA threshold used to issue an alert if exceeded. Default is -1.

avd.bindings.$name.pgaWatchIntensity

Type: double

Unit: MMI

If not absolute pga watch threshold is configured it will be calculated according to the given MMI intensity according to Kaestli and Faeh (2006). Default is -1.

avd.bindings.$name.pgaWarningIntensity

Type: double

Unit: MMI

If not absolute pga warning threshold is configured it will be calculated according to the given MMI intensity according to Kaestli and Faeh (2006). Default is -1.

avd.bindings.$name.pgaAlertIntensity

Type: double

Unit: MMI

If not absolute pga alert threshold is configured it will be calculated according to the given MMI intensity according to Kaestli and Faeh (2006). Default is -1.

Note

avd.spec.* If a reference spectrum is specified this parameters are in effect to configure the spectra computation.

avd.spec.length

Type: double

Unit: s

Defines the trace length in seconds to compute the spectra from. Default is 20.

avd.spec.overlap

Type: double

Defines the overlap ratio of the time windows used for the running spectra computation. The overlap in seconds is then length*overlap. Default is 0.5.

Command-line

Generic

-h, --help

show help message.

-V, --version

show version information

--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, eg scautopick -> scautopick2.

--plugins arg

Load given plugins.

-D, --daemon

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

Verbosity

--verbosity arg

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

-v, --v

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

-q, --quiet

Quiet mode: no logging output

--print-component arg

For each log entry print the component right after the log level. By default the component output is enabled for file output but disabled for console output.

--component arg

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

-s, --syslog

Use syslog logging back end. The output usually goes to /var/lib/messages.

-l, --lockfile arg

Path to lock file.

--console arg

Send log output to stdout.

--debug

Debug mode: --verbosity=4 --console=1

--trace

Trace mode: --verbosity=4 --console=1 --print-component=1 --print-context=1

--log-file arg

Use alternative log file.

Database

--db-driver-list

List all supported database drivers.

-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".

--config-module arg

The configmodule to use.

--inventory-db arg

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

--db-disable

Do not use the database at all

Records

--record-driver-list

List all supported record stream drivers

-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.

--record-file arg

Specify a file as record source.

--record-type arg

Specify a type for the records being read.