...

DELFT-FEWS supports checking of time series against thresholds. When thresholds are crossed, appropriate messages may be issued. Thresholds are defined in two files: thresholds.xml (described here) and thresholdValueSets.xml (described here). The first file contains definitions of threshold groups with thresholds and the types of threshold. There are three types of thresholds: level crossing thresholds, rate of rise and fall thresholds and max value thresholds. For a given threshold the options that are independent of location and parameter are defined.  Additional threshold options for specific locations and parameters are defined in the thresholdValueSets configuration file.  It is possible to configure one or more threshold groups.

...

Similar to the Id's used, a warning level integer can be assigned to threshold crossings. This warning level is resolved to either an icon (for display in the main FEWS GUI), or a colour (for use in reports or schematic status displays). Warning levels need not be unique. If not specified this id will be generated automatically. Internally DELFT-FEWS maintains threshold events as a non-equidistant time series, where the crossings are identified by an integer. For each threshold two unique integer Id's need to be assigned. One ID is used to identify the upcrossing of the threshold, the other Id is assigned to identify the downcrossing. The exception to this is the peak threshold where only a single Id needs to be assigned to identify the occurrence of the peak event. Note: in the new thresholds configuration approach (thresholdGroups) these ids are optional and will be generated when not specified in configuration.

...

See level thresholds for more information about the up and down ids.

Event Threshold

An event threshold is similar to a level threshold, only it has the possibility to be based on correlation events.

...

<thresholdValueSet id="EventThresholds" name="EventThresholds">
   <eventThresholdValues>
      <eventThresholdId>LevelWarn</eventThresholdId>
      <valueFunction>@PEAK_HEIGHT_VALUE@</valueFunction>
      <labelFunction>@PEAK_HEIGHT_TIME@</labelFunction>
      <parameterIdFunction>@PEAK_HEIGHT_PAR@</parameterIdFunction>
      <enabledFunction>@PEAK_HEIGHT_ENABLED@</enabledFunction>
   </eventThresholdValues>
   <timeSeriesSet>
      <moduleInstanceId>ThresholdCheck</moduleInstanceId>
      <valueType>scalar</valueType>
      <parameterId>H.m</parameterId>
      <locationSetId>MultiValuedAttributeThresholds</locationSetId>
      <timeSeriesType>external historical</timeSeriesType>
      <timeStep unit="hour" divider="1" multiplier="1"/>
      <readWriteMode>add originals</readWriteMode>
   </timeSeriesSet>
</thresholdValueSet>

Schema Thresholds.xsd

Level Threshold definition

...

Rate Threshold definition

Max Threshold definition

ThresholdWarningLevels

Different threshold warning levels can be defined. They need to be in order of increasing severity. First level defined is always the no-threshold-cross level.

...

<thresholdWarningLevels xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://www.wldelft.nl/fews" xsi:schemaLocation="http://www.wldelft.nl/fews httphttps://fewsfewsdocs.wldelftdeltares.nl/schemas/version1.0/thresholdWarningLevels.xsd">
   <missingDataThreshold id="noData">
      <color>blue</color>
      <iconName>nodata.gif</iconName>
      <historicOverlayIconName>historicnodata.gif</historicOverlayIconName>
      <forecastOverlayIconName>forecastnodata.gif</forecastOverlayIconName>
   </missingDataThreshold>
   <thresholdWarningLevel id="allClear" name="No threshold exceeded">
      <color>green</color>
      <iconName>warninglevel1.gif</iconName>
      <historicOverlayIconName>historicwarninglevel1.gif</historicOverlayIconName>
      <forecastOverlayIconName>forecastwarninglevel1.gif</forecastOverlayIconName>
   </thresholdWarningLevel>
   <thresholdWarningLevel id="warningLevel2" name="Enhance">
      <color>yellow</color>
      <iconName>warninglevel2.gif</iconName>
      <historicOverlayIconName>historicwarninglevel2.gif</historicOverlayIconName>
      <forecastOverlayIconName>forecastwarninglevel2.gif</forecastOverlayIconName>
   </thresholdWarningLevel>
   <thresholdWarningLevel id="warningLevel3" name="Flood Warning">
      <color>red</color>
      <iconName>warninglevel3.gif</iconName>
      <historicOverlayIconName>historicwarninglevel3.gif</historicOverlayIconName>
      <forecastOverlayIconName>forecastwarninglevel3.gif</forecastOverlayIconName>
   </thresholdWarningLevel></thresholdWarningLevels>

...

Explanation how threshold configuration is linked together

...

Firstly to trigger the threshold crossing module, it is necessary to configure include the predefinedActivity "threshold even event crossing" in a workflow. When the threshold crossing module runs it will look at the configured timeseriesset in the ThresholdValueSets file and check if any data was written to these timeseries. Timeseries are only checked for threshold crossings if the data values have changed. For external timeseries it is possible to skip the check for changes and always check for threshold crossings. This can be configured with option 'onlyCheckThresholdsOfChangedSeries' in the workflow descriptor file.

...

Anchor
thresholdeventcrossing thresholdeventcrossing

Run ThresholdEventCrossing module in workflow

Run Threshold Event Crossing module in workflow

The ThresholdEventCrossing module is replaced in 2013 by a predefined activity. This predefined activity has the same functionality as the old ThresholdEvent module. You can add the following predefined activity to your workflowDefine module in the ModuleDescriptors.xml file (obsolete since 2013.02):

<moduleDescriptor id="ThresholdChecks">
    <description>Module to check on threshold event crossings</description>
	<className>nl.wldelft.fews.system.plugin.threshold.ThresholdEventCrossingModule</className>
</moduleDescriptor>

<activity>
	<runIndependent>false</runIndependent>
	<predefinedActivity>threshold event crossing</predefinedActivity>
 </activity>	

 Do make sure to set the relativeViewPeriod correctly in ThresholdValueSets.xmlCreate entry in ModuleInstanceDescriptors.xml file:

<moduleInstanceDescriptor id="ThresholdChecks">
	<moduleId>ThresholdChecks</moduleId>
</moduleInstanceDescriptor>

Add module to the workflow. Please note:

...

<timeSeriesSet>
	<moduleInstanceId>ImportCSV</moduleInstanceId>
	<valueType>scalar</valueType>
	<parameterId>H.obs</parameterId>
	<locationId>Bhadra_Reservoir</locationId>
	<timeSeriesType>external historical</timeSeriesType>
	<timeStep id="daily0600"/>
	<relativeViewPeriod unit="day" start="-5" end="0"/>
	<readWriteMode>read only</readWriteMode>
</timeSeriesSet>

For the threshold event values to be visible in the ThresholdEvents display the view period needs to be set:

<eventTimeViewPeriod start="-365" end="48" unit="day"/>

If this is not done it will default to -10 day to +10 days. This does not have to be a problem because it is always possible to overrule the view period in the display itself by mean of filtering: double-click 'Event Time' column and a pop-up will appear where the user can set the period for viewing threshold events.

When the predefined activity is added to the workflow. Please note:

• The module will take all external time series into account (external historical and external forecast series created inside and outside the workflow) and only simulated (simulated historical, simulated forecasting) time series which are created within the same workflow.
• When the module should only check external time series changed within the current workflow, the attribute "onlyCheckThresholdsOfChangedSeries" in the workflow descriptor file need to be set to true. This need to be added to all workflowdescriptors that have the threshold crossing module included.
• The module needs to be added at the end of the workflow where the timeseries have been created (e.g. imported or by transformation).
• The relativeViewPeriod configured for the timeseriesSets in the ThresholdValueSets.xml determines the viewPeriod for which thresholdcrossings are determined. If the timeseries that has been imported or otherwise created is longer than the configured relative view period, the values outside this relativeViewPeriod will not be validated.
• As a result, the threshold crossing logs are written to the database, and can for example be used in eventActions and shown in the system wide threshold events display.
• When time series from within a threshold value set should not be taken into account, do not use a <relativeViewPeriod> for them and not a <readWriteMode> that says "read complete forecast".

...

<activity>
	<runIndependent>false</runIndependent>
	<predefinedActivity>threshold event crossing</predefinedActivity>
 </activity>	

(Before 2013.02)
<activity>
	<runIndependent>false</runIndependent>
	<predefinedActivity>threshold event crossing</predefinedActivity>
 </activity>	

 Set relativeViewPeriod correctly in ThresholdValueSets.xml

<timeSeriesSet>
	<moduleInstanceId>ImportCSV</moduleInstanceId>
	<valueType>scalar</valueType>
	<parameterId>H.obs</parameterId>
	<locationId>Bhadra_Reservoir</locationId>
	<timeSeriesType>external historical</timeSeriesType>
	<timeStep id="daily0600"/>
	<relativeViewPeriod unit="day" start="-365" end="0"/>
	<readWriteMode>add originals</readWriteMode>
</timeSeriesSet>

For the threshold event values to be visible in the ThresholdEvents display the view period needs to be set.

<eventTimeViewPeriod start="-365" end="48" unit="day"/>

If this is not done it will default to -10 day to +10 days. This does not have to be a problem because it is always possible to overrule the view period in the display itself by mean of filtering:

double-click 'Event Time' column and a pop-up will appear where the user can set the period for viewing threshold events.

Seasonal Thresholds

Since 2018.02 thresholds can be made seasonal if a threshold is only valid for part of a year. When not configured the threshold is valid for the entire year.

...

This is illustrated in the next picture where no warning overlay icon will be drawn:

 Grouping threshold labels (since 2020.02)

Since 2020.02 when multiple threshold labels belong to the same threshold id and have the same value, they will be grouped together and the threshold id plus the amount of thresholds will be shown between [ ].

Image Added