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 quality 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 occurrence. 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:

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.

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:

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

      

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

      

   3. A table with the last 100 incidents for the currently selected building.

      

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.

      

   2. The Fourier spectra, pseudo acceleration response spectra and waveforms the the currently selected sensor.

      

      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:

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.

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” drop-down 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.

Module Configuration

etc/defaults/global.cfg

etc/defaults/shard.cfg

etc/global.cfg

etc/shard.cfg

~/.seiscomp/global.cfg

~/.seiscomp/shard.cfg

shard inherits global options.

Note

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

gempa.licensePath = @CONFIGDIR@/licenses

bind

Default: 127.0.0.1:8080

Type: list:string

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

mediaDirectory

Default: @DATADIR@/shard/apps

Type: list:string

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

tileDB

Default: @DATADIR@/gaps/zoom12.mbtiles

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.

bufferSize

Default: 65536

Unit: byte

Type: int

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

maximumThreads

Default: 10

Type: int

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

requestTimeout

Default: 10

Unit: s

Type: int

Set the thread timeout. Default is 10s.

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

reportQuakelink

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

Default: false

Type: boolean

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

reportClipPSAToReferenceSpectrum

Default: false

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.

reportTimeShift

Default: 0

Unit: s

Type: int

Shifts all timestamps occuring in the report by n seconds.

reportUseLocalTime

Default: false

Type: boolean

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

reportUseRelativeTime

Default: false

Type: boolean

Whether to use absolute or relative time in ruler.

reportUseRelativeEta

Default: false

Type: boolean

Whether to use absolute or relative time for the estimated arrival field.

reportDefaultLocale

Default: en

Type: string

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

reportMinimumIntensity

Default: 3

Type: double

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

reportMinimumDelay

Default: 180

Unit: s

Type: double

The minimum time delay after origin time for automatic reporting.

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

Default: @DATADIR@/gaps/zoom12.mbtiles

Type: path

Alternative configuration parameter for @tileDB.

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

Default: building

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.

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

Default: 1200

Type: integer

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

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

Default: @ROOTDIR@/var/lib/shard/archive.db

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

Note

apps.* Web app specific configurations.

apps.serverAPI

Default: ../

Type: string

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

apps.mapURI

Default: http://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png

Type: string

Full URL for tiles.

apps.mapZoom

Default: 18

Type: int

The initial zoom of the map.

apps.minTraceScale

Default: 2e-4

Type: double

The minimum trace scale in sensor units of trace data in e.g. the dashboard.

apps.quakelink

Default: http://localhost:18080/events/query

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.

apps.events.timeSpan

Default: 12

Unit: hours

Type: double

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

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

Unit: km

Type: double

The maximum depth in km.

apps.events.lat.min

Unit: deg

Type: double

The minimum latitude in degree.

apps.events.lat.max

Unit: deg

Type: double

The maximum latitude in degree.

apps.events.lon.min

Unit: deg

Type: double

The minimum longitude in degree.

apps.events.lon.max

Unit: deg

Type: double

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

Default: -1

Unit: sensor units squared

Type: double

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.

avd.delayThreshold

Default: -1

Unit: s

Type: double

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.

avd.pgaWatch

Default: -1

Unit: m/s/s

Type: double

Defines a global default PGA threshold used to issue an information if exceeded.

avd.pgaWarning

Default: -1

Unit: m/s/s

Type: double

Defines a global default PGA threshold used to issue a warning if exceeded.

avd.pgaAlert

Default: -1

Unit: m/s/s

Type: double

Defines a global default PGA threshold used to issue an alert if exceeded.

avd.pgaWatchIntensity

Default: -1

Unit: MMI

Type: double

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

avd.pgaWarningIntensity

Default: -1

Unit: MMI

Type: double

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

avd.pgaAlertIntensity

Default: -1

Unit: MMI

Type: double

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

avd.incidentsMaxTimeSpan

Default: 3600

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.

avd.prsMaxTimeSpan

Default: 60

Unit: s

Type: double

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.

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

Default: -1

Unit: sensor units squared

Type: double

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.

avd.bindings.$name.delayThreshold

Default: -1

Unit: s

Type: double

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

avd.bindings.$name.pgaWatch

Default: -1

Unit: m/s/s

Type: double

PGA threshold used to issue an information if exceeded.

avd.bindings.$name.pgaWarning

Default: -1

Unit: m/s/s

Type: double

PGA threshold used to issue a warning if exceeded.

avd.bindings.$name.pgaAlert

Default: -1

Unit: m/s/s

Type: double

PGA threshold used to issue an alert if exceeded.

avd.bindings.$name.pgaWatchIntensity

Default: -1

Unit: MMI

Type: double

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

avd.bindings.$name.pgaWarningIntensity

Default: -1

Unit: MMI

Type: double

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

avd.bindings.$name.pgaAlertIntensity

Default: -1

Unit: MMI

Type: double

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

Note

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

avd.spec.length

Default: 20

Unit: s

Type: double

Defines the trace length in seconds to compute the spectra from.

avd.spec.overlap

Default: 0.5

Type: double

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

Command-Line Options

Generic

Verbosity

Database

--db-disable

Do not use the database at all

Records