Templates
=========
Templates are the backbone of |appname|, they allow to create user-defined
reports. The latex templates make use of
`Jinja2 `_ which integrates Python into latex,
therefore the templates can recognize Python variables.
Contact `gempa `_ for assistance if needed.
Adding a new template
---------------------
To add a new template, either copy, rename and modify one of the provided
templates or create your own templates and move them into the directory
:file:`$SEISCOMP_ROOT/share/[shard|sigma]/templates/`. Only templates in this
directory can be used by |appname|.
.. note::
Be aware that any changes to the provided templates will be overwritten once
|appname| is updated.
.. _rgsm_variables:
Usage of variables in templates
-------------------------------
There are specific variables that can be used in the latex templates. They offer
the chance to use post-processed results in the report.
The list differs between |shard| and |sigma|. To use variables, put the variable
name inside of double curly brackets, e.g. **{{ magnitude }}**.
Use option :command:`--print-vars` to get the list of usable variables for your
current incident and template. This list might differ, depending on the used
template, used module and available content in the report directory.
For an exemplary |shard| incident, the variable *smParameters* and sub-variables
can be utilized in a template:
.. code-block:: latex
\begin{table}[h]
\begin{tabular}{|l|l|l|l|l|l|l|l|l|l|}
\hline
Net & Sta & Loc & max PGA & max PGV & max PGD & max EDA & max CAV & max T & max Tp\\
& & & [m/s\textsuperscript{2}] & [m/s] & [m] & [m/s\textsuperscript{2}] & [m/s] & [s] & [s]\\
\hline
{% for key, value in smParameters.items() %}
{{ value.networkCode }} & {{ value.stationCode }} & {{ value.locationCode }} & {{ value.valuePGA_max }} & {{ value.valuePGV_max }} & {{ value.valuePGD_max }} & {{ value.EDA_max }} & {{ value.CAV_max }} & {{ value.duration_max }} & {{ value.Tp_max }}\\ \hline
{% endfor %}
\end{tabular}
\end{table}
.. figure:: media/shard/sm_parameters_table.png
:width: 18cm
:align: center
Exemplary result of the latex code above
It is possible to show acceleration parameters in units of 'g'.
Further, for |shard| the table can be expanded to include the threshold of the
configurable pgaAlert, pgaWarning and pgaWatch (as each sensor can have its
own thresholds, the minimum and maximum per nslc is formed).
.. code-block:: latex
\begin{table}[h]
\begin{tabular}{|l|l|l|l|l|l|l|l|l|l|l|}
\hline
Net & Sta & Loc & max PGA & max PGV & max PGD & max EDA & max CAV & max T & max Tp & pgaAlert threshold\\
& & & [g] & [m/s] & [m] & [g] & [m/s] & [s] & [s] & [g]\\
\hline
{% for key, value in smParameters.items() %}
{{ value.networkCode }} & {{ value.stationCode }} & {{ value.locationCode }} & {{ value.valuePGA_g_max }} & {{ value.valuePGV_max }} & {{ value.valuePGD_max }} & {{ value.EDA_g_max }} & {{ value.CAV_max }} & {{ value.duration_max }} & {{ value.Tp_max }} & {{ structure.nslc[value.waveformID].pgaAlert_g_min }} \\ \hline
{% endfor %}
\end{tabular}
\end{table}
.. figure:: media/shard/sm_parameters_table_expanded.png
:width: 18cm
:align: center
Exemplary result of the latex code above
Times and time zones
^^^^^^^^^^^^^^^^^^^^
The variable **{{ originTime }}**, and derivatives,
refer to the origin time directly found in the incident.xml and therefore is
assumed to be given in UTC.
However, the variable **{{ originTimeLocal }}**, and derivatives,
refer to the time zone of the machine the report is created on. Usually this is
also UTC.
To convert a time to a specific time zone, use **convertToTimezone** (a
custom jinja2 filter). The initial input has to be string or an
internal variable containing a time, e.g.
**{{ originTime }}**. Time zone strings have to be supported by
`dateutil.tz `_.
Exemplary timezone values:
* "Europe/Berlin"
* "Asia/Dubai"
* "UTC+10"
* "CET"
The jinja filter supports specifying the output format using the argument
*form*. For example, showing only the date or time, rearranging
the time values and/or changing the separators in-between.
Visit `datetime docs `_
for a detailed description and possibilities of how to modify the time string.
A special value is "code" (similar to form="%z" or "%Z"),
this will return the code of the time zone, either relative to UTC or a known
time zone name.
Exemplary usage of the filter *convertToTimezone*:
.. code:: latex
{{ originTime }}
% 2019-07-06T03:19:53.0000Z
{{ originTime | convertToTimezone("Asia/Dubai") }}
% 2019-07-06 07:19:53
{{ originTime | convertToTimezone("Asia/Dubai", form="%Y/%m/%d") }}
% 2019/07/06
{{ originTime | convertToTimezone("Asia/Dubai", form="%H.%M.%S") }}
% 07.19.53
{{ originTime | convertToTimezone("Asia/Dubai", form="code") }}
% +04
Alert level
^^^^^^^^^^^
The variable **{{alertLevel}}** for |shard| is calculated based on the highest
exceed PGA-level of any sensor.
The variable **{{alertLevel}}** for |sigma| is calculated based on the highest
MMI found for any given :ref:`rgsm_poi`.
Display plots
-------------
|appname| can create waveform, reference- and spectrum plots based on the files
the modules, i.e. |shard| and |sigma|, provide. For that, the templates have to
contain the path to the files-to-create. Only if these specific path names are
found in the template, the corresponding plots will be created and displayed in
the report. This procedure reduces the creation time of reports in cases certain
plots are unwanted.
Per default, the content of the plots is displayed in English. To translate or
rephrase it there is the option to use a translation file
(see :ref:`rgsm_plot-trans`).
Waveform + Spectrum
^^^^^^^^^^^^^^^^^^^
To enable plotting the `waveform + spectrum`, the template needs to include
``[Unit]-1C-wav+spec``, whereas `unit` is one of *acc*, *vel* or *disp*. Only
the corresponding units will be plotted. E.g. if only *acc-1C-wav+spec* is found
the acceleration traces are plotted, if *acc-1C-wav+spec* and
*disp-1C-wav+spec* both are plotted.
Exemplary:
.. code:: latex
\section{Waveforms and Fourier spectra of station with peak values}
{% for key, value in smParameters.items() %}
{% for component in value.components %}
\begin{figure}[th]
\centering
\includegraphics[width=0.9\textwidth]{ {{inputPath}}/{{value.waveformIDmod}}{{component}}{{value.unit}}-acc-1C-wav+spec.pdf }
\end{figure}
{% endfor %}
{% endfor %}
.. figure:: media/shard/waveform+spectrum.png
:width: 18cm
:align: center
Waveform + spectrum plot of one station
Response Spectrum
^^^^^^^^^^^^^^^^^
Similar, to enable plotting the response spectra the template needs to include
``-resp.pdf``.
Exemplary:
.. code:: latex
{% for key, value in smParameters.items() %}
\begin{figure}[th]
\centering
\includegraphics[width=0.9\textwidth]{ {{inputPath}}/{{value.waveformIDmod}}-resp.pdf }
\end{figure}
{% endfor %}
In addition to the response spectrum, the design spectrum can be visualized as
well. |appname| checks the directory :file:`@DATADIR@/stations/design` if a
corresponding design spectrum for a displayed stations exists. As |shard| and
|sigma| use the same directory, usually station-specific design spectra should
exist already.
.. figure:: media/shard/response_spectrum.png
:width: 18cm
:align: center
Response and design spectrum of one station
Fragility curve
^^^^^^^^^^^^^^^
If the template includes ``fragility-curve.pdf``, a fragility curve per station
with its maximum measured ground motion value can be plotted.
Exemplary:
.. code:: latex
\section{Fragility curve}
{% for key, value in smParameters.items() %}
\begin{figure}[th]
\centering
\includegraphics[width=0.85\textwidth]{ {{inputPath}}/{{value.waveformIDmod}}-fragility-curve.pdf }
\end{figure}
{% endfor %}
|appname| checks the directory :file:`@DATADIR@/stations/fragility` if a
corresponding fragility curve for each station exists. As |shard| and |sigma|
use the same directory, usually station-specific fragility curve should exist
already. |appname| currently supports the fragility curve OpenQuake NRML format
versions 0.4 and 0.5 (see |shard| documentation).
.. figure:: media/shard/fragility-curve.png
:width: 18cm
:align: center
Exemplary fragility curve for PGA of 1g for a transformer.
Special functions in templates
------------------------------
There are some special and useful functions that can be used in the templates.
.. _rgsm_trans:
Translations (trans)
^^^^^^^^^^^^^^^^^^^^
The variable content is in English. Hence, latex templates can include custom
translations, using the `trans` function by providing a list of key values
pairs. Hereby, the keys are the values of Python variables
(see :ref:`rgsm_variables`).
The syntax is one line per word/phrase:
.. code-block:: latex
{# trans: "English word/phrase" = "translation" #}
*List of text-keys that can be translated, might not be complete*
.. code-block:: latex
{# trans: "Not felt" = "..." #}
{# trans: "None" = "..." #}
{# trans: "Weak" = "..." #}
{# trans: "Very light" = "..." #}
{# trans: "Light" = "..." #}
{# trans: "Slight" = "..." #}
{# trans: "Moderate" = "..." #}
{# trans: "Strong" = "..." #}
{# trans: "Very strong" = "..." #}
{# trans: "Severe" = "..." #}
{# trans: "Violent" = "..." #}
{# trans: "Extreme" = "..." #}
{# trans: "Moderate/Heavy" = "..." #}
{# trans: "Heavy" = "..." #}
{# trans: "Very heavy" = "..." #}
{# trans: "\textcolor{red}{ALERT ON}" = "\textcolor{red}{...}" #}
{# trans: "\textcolor{green}{NO ALERT}" = "\textcolor{green}{...}" #}
{# trans: "N" = "..." #}
{# trans: "E" = "..." #}
{# trans: "S" = "..." #}
{# trans: "W" = "..." #}
.. _rgsm_plot-trans:
Plot Translations
^^^^^^^^^^^^^^^^^
The default content of the generated plots is in English.
To translate or even rephrase titles, axes and/or labels of plots that are
created by |appname| a translation file can be defined.
This file needs to be stored in the template directory of the specific module,
:file:`seiscomp/share/rgsm/[shard|sigma]/templates`.
Further, to use a custom translation file, it must be specified in the used
template itself. Hereby the keyword has to be **{# plotTranslationFile: ... #}**,
filled by the translation file, i.e.:
.. code-block:: latex
{# plotTranslationFile: plot_translations_custom.json #}
The translation file needs to be in JSON format. The key-values pairs are stored
under the main key **"PLOT_TRANSLATIONS"**. Whereas the keys correspond to
specific segments of the plot. The values contain the text, which can be
modified as desired. Only the key-value pairs that should be modified need to
exist in the file, the rest is taken from the default file.
Additionally, some keys support 'variables' in their corresponding values,
e.g. *{waveformID}*. However, the variables only work for the specific key and
are, in general, limited.
The default file contains all (currently) available keys:
.. code-block:: json
{
"PLOT_TRANSLATIONS": {
"SEISMIC_TITLE": "Timeseries and spectrum for {waveformID} @ {startTime}",
"SEISMIC_LABEL_X": "Time (s)",
"SEISMIC_LABEL_Y": "Amplitude ({unit})",
"SEISMIC_LABEL_AMPLITUDE": "Amplitude",
"SEISMIC_LABEL_DURATION1": "Duration Ia05 to Ia95",
"SEISMIC_LABEL_DURATION2": "Duration Ia25 to Ia75",
"FREQUENCY_LABEL_X": "Frequency (Hz)",
"FREQUENCY_LABEL_Y": "dB",
"FREQUENCY_LABEL_SIGNAL": "Signal Spectrum",
"FREQUENCY_LABEL_NOISE": "Noise Spectrum",
"RESPONSE_TITLE": "Response spectra for {waveformID}",
"RESPONSE_LABEL_X": "Periods (s)",
"RESPONSE_LABEL_Y": "Amplitude (M/S**2)",
"RESPONSE_LABEL_DESIGN": "Design Spectrum",
"FRAGILITY_TITLE": "Fragility curve for {waveformID} \n {fragCurveDescription}",
"FRAGILITY_LABEL_X": "{imt} ({unit})",
"FRAGILITY_LABEL_Y": "Cumulative Probability of Failure (%)",
"FRAGILITY_LABEL_LINE": "Maximum measured {imt}={fragilityMaxValue}{unit}",
"DISTPLOT_TITLE": "Origin time: {originTime}\n Amplitude in {unit}",
"DISTPLOT_LABEL_X": "Time since Origin time (s)",
"DISTPLOT_LABEL_Y": "Distance (km)"
}
}
To use quotation marks (") in the text, use escape characters, e.g., \\".
.. _rgsm_fe-trans:
Translation of Flinn-Engdahl Regions
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Additionally, the Flinn-Engdahl regions can be translated.
One way is to translate each region manually as described in :ref:`rgsm_trans`,
or, which might be more convenient as is does not need to be defined in every
template, by putting a file named :file:`translation.map` in the corresponding
directory :file:`seiscomp/share/rgsm/[shard|sigma]`.
This file needs to have the following syntax:
.. code-block:: map
...
[Regions]
FE1=FE1_translation
FE2=FE2_translation
...
.. _rgsm_poi:
Point Of Interest (POI)
^^^^^^^^^^^^^^^^^^^^^^^
*Only used by* |sigma|
|sigma| generates a MMI grid based on the applied GMPE. In the template multiple
*point of interest* (POI) can be defined, e.g., cities or structures. For these
POIs the MMI is extracted and can be displayed in the report.
The syntax is one line per POI:
.. code-block:: latex
{# poi: NAME, LON, LAT #}
Exemplary, the following code uses the POIs to create a table:
.. code-block:: latex
\begin{tabular}{|l|c|c|c|c|}
\hline
\multicolumn{5}{|c|}{\textcolor{red}{Intensity at Main Cities}}\\
\hline
\textbf{City} & \textbf{Distance (km)} & \textbf{Intensity (MMI)} & \textbf{Perceived Shaking} & \textbf{Potential Effect/Damage} \\
\hline
{% for key, value in POI.items() %}
{% if key != "epicentre" %}
\hline
{{value.name}} & {{value.repi}} & {{value.intensity_roman}} & {{value.shaking}} & {{value.damage}} \\
{% endif %}
{% endfor %}
\hline
\end{tabular}
.. _rgsm_gis:
gempa Image Server (GIS) image integration
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
It is possible to create additional map images by using the
`gempa Image Server (GIS) `_.
In order to use GIS, provide its URL address plus query parameters.
There are specific placeholders for the query that might be used to customize
the map, i.e. the event location (#EVLAT#, #EVLON#), depth (#EVDEPTH) and
magnitude (#MAG#).
An example can be seen below. Multiple URLs can be declared and used as an
internal variable (**gislink_{NAME}**), whereas *NAME* needs to be given with
the URL. The output format has to be *png*.
The syntax is one Name-URL per line, with the importance of using *"*:
.. code-block:: latex
{# gis: "NAME" = "URL" #}
Exemplary, the following code defines GIS urls and uses them via the internal
variables.
.. code-block:: latex
{# gis: "smallmap" = "http://localhost:20001/map?reg=#EVLAT#,#EVLON#,1,1&dim=512,256&origin=#EVLAT#,#EVLON#,#EVDEPTH#&mag=#MAG#" #}
{# gis: "bigmap" = "http://localhost:20001/map?reg=#EVLAT#,#EVLON#,15,15&dim=512,256&origin=#EVLAT#,#EVLON#,#EVDEPTH#&mag=#MAG#" #}
\includegraphics[width=0.8\textwidth]{ {{gislink_smallmap}} }
\includegraphics[width=0.8\textwidth]{ {{gislink_bigmap}} }
Media
=====
The directory :file:`$SEISCOMP_ROOT/share/[shard|sigma]/media/` contains
pictures that |appname| can use. Although, latex templates are able to use
absolute paths to any directory or file, we suggest to put all static pictures
related to the report, e.g., agency logo, in this directory. Additionally, some
latex variables won't work if the files in this directory are not correctly
defined.
E.g., the latex variable **{{agencylink}}** corresponds to the file name
`$SEISCOMP_ROOT/share/[shard|sigma]/media/agency.png`. If it does not exists,
the file `agency_default.png` is used instead.