...

DELFT-FEWS supports checking of time series against thresholds. When thresholds are crossed, appropriate messages may be issued. Thresholds are defined in two type of files: thresholds.xml (described here) and thresholdValueSets.xml (described 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. It is possible to configure threshold groups through several files. Note that the general configuration options should be either defined only once, or defined exactly in the same way in each file.

Contents

...

Firstly to trigger the threshold crossing module, it is necessary to include the predefinedActivity "threshold 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.

 Once Once a threshold crossing check has been triggered the threshold event is logged in the database. Depending on issue status and event coupling, a message will appear in the log panel at a certain log level. The logging process works as follows:

0) On initialization of the Threshold Crossing Module a subset of events is read from the ThresholdEventsTable. The number of records read is defined by the configuration parameter 'maxActionEventDuraion' times 10. Events older than this are considered irrelevant.

1) Check if  a if a newly logged event is already in the list of logged events retrieved from the database. For this check the following values are compared in the given order:

check threshold type
check threshold direction
check time series type 
check event time
check event value. Difference has aan allowed tolerance of 10% of value.
For forecasted timeseries check the taskrunid
check moduleInstanceId
check thresholdValueSetId
check thresholdId
check locationId
check parameterId
check eventActionId
check rateOfChange value

...

   At the end of this action we have a list of all currently active Action Events. Threshold crossings for which no Action Event is configured in a 'LocationThresholds.csv' will not appear at WARN level in the log panel.

5) Go over the 5) Go over the list of currently active Action Events and check if they have exceeded their max action duration time. This is the maximum time that an action event can be active. This value is configured in the Thresholds file with element 'maxActionEventDuration'. Default value is 1 Day. If an up action has expired then a corresponding down Action Event needs to be created and added to the issue list. Action Events of none approved forecast timeseries are skipped.

...

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):

Code Block
language xml title ModuleDescriptors.xml (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>
workflow.xml
<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:

Code Block
language xml title ModuleInstanceDescriptorsthresholdvaluesets.xml
<moduleInstanceDescriptor id="ThresholdChecks"><timeSeriesSet> <moduleId>ThresholdChecks</moduleId> </moduleInstanceDescriptor>

Add the module 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 also only check external time series changed within the current workflow, the attribute "onlyCheckThresholdsOfChangedSeries" in the workflow descriptor file need to be set to true.
• 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".

Run Threshold Event Crossing activity in workflow (2013.02 and later):

The ThresholdEventCrossing module is replaced 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 workflow:

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

 Do make sure to set the 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"/>

...

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

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.

...