What | ThresholdValueSets.xml |
---|---|
Required | no |
Description | definition of threshold values for all locations and data types |
schema location | http://fews.wldelft.nl/schemas/version1.0/thresholdValueSets.xsd |
Complementary to the definition of the types of thresholds identified, the values of the thresholds are defined in the ThresholdValueSets configuration (ThresholdValueSets.xml on a local filesystem).
A thresholdValueSet is build up out of:
- The values and what type each value is
- (Optional) Stage/Discharge conversions
- The timeSeries a thresholdValueSet is associated with
When thresholds are crossed, a log entry will be made. It is common practice to use this logging to initiate an action by the Master Controller when using thresholds in a live forecasting system. EventTypeIds (otherwise known as EventCodes) are used as a prefix in logging messages for the MC to identify which threshold is crossed.
What are the different value types?
There are 3 types of thresholdValues:
- levelThresholdValues
- rateThresholdValues
- maxThresholdValues (also known as peakThresholdValues)
levelThresholdValues are compared with single values from a timeSeries. It is crossed if a timeSeries value is bigger and the previous timeSeries value is smaller then the levelThresholdValue. i.a.w. the first time a timeSeries value is bigger. This means that the values in the timeSeries will first have to become smaller then the levelThresholdValues before it can be crossed again. Even tho the name "level" is asociated with water levels, it can be used for any parameter type (i.e. temperature, rainfall, wind).
rateThresholdValues are compared with a rate of change. To calculate this, each value in a timeSeries is matched with a value in the future that is exactly "timespan" away. The threshold is crossed if the difference between these two values is greater then the rateThresholdValue.
maxThresholdValues are compared with single values from a timeSeries. But only peak values are considered. A peak value has a previous and next value that are both lower. The threshold is crossed if a peak value is above the maxThresholdValue. If two crossings are within the timeSpan, only the first crossing will actually occur.
Figure 39 Elements of the ThresholdValueSets configuration.
thresholdValueSet
Root element for defining a set of thresholds. For each time series or time series set for which a threshold event is to be tested new element is required.
Attributes;
- Id: Id of the thresholdValueSet defined.
- Name: optional name, for reference purposes only
description
Optional description for the ThresholdValueSet. Used for reference purposes only
unit
Specify when the unit given for the values is not the same as the (internally stored) unit of the parameter it applies to. When specified it is required to also specify configUnitConversionsId in Parameters.xml. In those unit conversions the conversion from the specified unit to the (internal) unit should be available
levelThresholdValue
Definition of values for level thresholds.
rateThresholdValue
Definition of values for rate thresholds.
maxThreshold
Definition of values fro peak event thresholds.
forecastAvailableThresholdValue
If a threshold crossing event is measured for a given observed parameter, then the thresholdEventCrossing module logs whether or not there is a forecastrun available for the corresponding forecast parameter, within a given relative time period. This information is used in the ThresholdSkillScoreDisplay
timeSeriesSet
Definition of the time series set for which the thresholds are to be tested.
ratingCurve
Convert this threshold level value to a discharge level threshold value using the ratingcurve defined here
Defining level thresholds
Figure 40 Elements of the Level Threshold configuration of the ThresholdValueSets configuration
levelThresholdId
Id of the level threshold. This Id must refer to a threshold type defined in the Thresholds definition (see previous paragraph).
value
Value of the threshold.
valueFunction
Function alternatives may also be used instead of the value itself (see: Location and attributes defined in Shape-DBF files).
upActionLogEventTypeId
Event code to be generated on the up-crossing of the threshold. This event code can be used to initiate for example enhanced forecasting. The event code need not be unique. Multiple threshold crossings may generate the same event code. Note that event codes will only be generated for runs which have an a-priori approved status. This is normally the scheduled forecast run.
downActionLogEventTypeId
Event code to be generated on the down-crossing of the threshold. This event code can be used to initiate for example enhanced forecasting. The event code need not be unique. Multiple threshold crossings may generate the same event code. Note that event codes will only be generated for runs which have an a-priori approved status. This is normally the scheduled forecast run.
Defining rate thresholds
Figure 41 Elements of the Rate Threshold configuration of the ThresholdValueSets configuration
rateThresholdId
Id of the rate threshold. This Id must refer to a threshold type defined in the Thresholds definition (see previous paragraph).
value
Value of the rate threshold that must be exceeded in timeSpan.
timeSpan
Time span to use to establish the rate.
rainRate
Boolean indicator to identify thresholds in rain rates where the threshold is defined as the average rainRate over the timeSpan exceeding the threshold, and a rate in for example a level where the rate is determined as the value divided by the time span.
upActionLogEventTypeId
Event code to be generated on the up-crossing of the threshold. This event code can be used to initiate for example enhanced forecasting. The event code need not be unique. Multiple threshold crossings may generate the same event code. Note that event codes will only be generated for runs which have an a-priori approved status. This is normally the scheduled forecast run.
downActionLogEventTypeId
Event code to be generated on the down-crossing of the threshold. This event code can be used to initiate for example enhanced forecasting. The event code need not be unique. Multiple threshold crossings may generate the same event code. Note that event codes will only be generated for runs which have an a-priori approved status. This is normally the scheduled forecast run.
Defining peak event thresholds
Figure 42 Elements of the maxThreshold configuration of the ThresholdValueSets configuration
maxThresholdId
Id of the max threshold. This Id must refer to a threshold type defined in the Thresholds definition (see previous paragraph).
value
The value item is used here as a selection of peaks. The peak must exceed this value to be deemed significant (peaks over threshold)..
timeSpan
The timeSpan is used to establish independence of peaks. Peaks within timeSpan of each other are considered as being of the same event as a message will only be issued for the highest.
actionLogEventTypeId
Event code to be generated on the threshold occurring. This event code can be used to initiate for example enhanced forecasting. The event code need not be unique. Multiple threshold crossings may generate the same event code. Note that event codes will only be generated for runs which have an a-priori approved status. This is normally the scheduled forecast run.