10 ThresholdValueSets

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

TimeSeriesSet Association

ThresholdValues are associated with all timeSeriesSets that are defined in the same thresholdValueSetSequence (With some extra associations for Stage/Discharge conversions). When the unit of the threshold values do not correspond with the internal unit, the unit element can be used to define the unit of the threshold values.

Stage/Discharge conversions

Rating Curves are used in fews to convert between stage (water level) and discharge (water flow) values. The optional stage and discharge elements in the thresholdValueSet should only and always be used if a rating curve is used in combination with thresholds.

A timeSeriesSet is put in the stage or discharge element based on what parameter is has. So putting a timeSeriesSet in the stage element says that this timeSeriesSet has a stage parameter. Putting the thresholds in the stage element is very similar to the timeSeriesSets in that it shows that these thresholds are a stage threshold. This indirectly shows what unit the threshold values are in.

A rating curve is normally associated to a timeSeriesSet by its locationId. So when leaving out any ratingCurve related config in the thresholdValueSet, ratingCurves are searched for in this way. When a different ratingCurve is needed, it can be specified with use of the ratingCurveLocationId and ratingCurveQualifierId elements.

After all these definitions it is clear:

• What thresholds are stage and discharge
• What timeseries are stage and discharge
• What ratingCurves need to be used and consequently how to convert between stage and discharge values

Now the stage thresholds will be converted to discharge thresholds and vice versa after which they are assigned to the timeSeriesSet. So the stage and converted discharge thresholds will be assigned to the timeSeriesSets that were placed in the stage element. And similarly, the discharge and converted stage thresholds will be assigned to the timeSeriesSets in the discharge element.

Schemas

ThresholdValueSet

contains level- and/or rate- and/or max-thresholds set for a given time series

description

Optional description for the ThresholdValueSet. Used for reference purposes only.

stage

Threshold values and time series that are in units of stage.

discharge

Threshold values and time series that are in units of discharge.

forecastAvailableThresholdValue

If a threshold crossing event is measured for a given observed parameter, then the thresholdEventCrossing module logs whether or not there is a forecast run available for the corresponding forecast parameter, within a given relative time period. This information is used in the ThresholdSkillScoreDisplay.

timeSeriesSet

Define one or more time series sets for which the threshold values in this thresholdValueSet will be used.

ratingCurveLocationId

When specified the rating curve available at this location is used instead of the location from the time series set.

ratingCurveQualifierId

One or more qualifier ids the used rating curve should have all

ThresholdValueSetSequence

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 this unit conversions the conversion from the specified unit to the (internal) unit should be available

levelThresholdValue

Specific values for level thresholds.

aggregationLevelThresholdValues

Specific values for level thresholds. This contains one or more level threshold values for different aggregation periods.

rateThresholdValue

Specific values for rate thresholds.

maxThresholdValue

Specific values for max thresholds.

levelThresholdValue

levelThresholdId

ID of the level threshold type, as it is specified in the file thresholds

value

level threshold value

valueFunction

Location dependent threshold value by using a function with location attributes. eg. @FLOOD_WATCH@. When an attribute is missing for a location the threshold value is invisible/ignored for that location.

label

Optional label.

labelFunction

Optional location dependent label that is specified by a function, e.g. "@FLOOD_WATCH@", in which tags between "@" signs refer to location attributes that are defined in the locationSets config file. The tags are replaced by actual attribute values. These attribute values can be different for different locations. If an attribute is missing for a location, then the label is ignored for that location.

warningArea

One or more warnings that correspond to this threshold for the configured timeSeriesSet(s). These warningAreas are e.g. used in the ThresholdOverviewDisplay threshold crossing counts tabs.

upActionLogEventTypeId

ID of the action message (=additional log.message) that must be logged if a threshold value is crossed UP. This id has to contain a dot, because the action event is only visible to the master controller if this id contains a dot, e.g. "Threshold_Name.Up". The event code need not be unique.

downActionLogEventTypeId

ID of the action message (=additional log.message) that must be logged if a threshold value is crossed DOWN. This id has to contain a dot, because the action event is only visible to the master controller if this id contains a dot, e.g. "Threshold_Name.Down". The event code need not be unique.

aggregationLevelThresholdValues

levelThresholdId

ID of the level threshold type, as it is specified in the file thresholds

timeSpanValue

One or more level threshold values for different aggregation periods. If this threshold value set is used for a time series without an aggregation period, then the timeStep of that time series is used as aggregation period. If a value for the aggregation period of a time series is not configured here, then these threshold values are ignored for that time series.

timeSpanValueFunction

One or more level threshold values for different aggregation periods. If this threshold value set is used for a time series without an aggregation period, then the timeStep of that time series is used as aggregation period. If a value for the aggregation period of a time series is not configured here, then these threshold values are ignored for that time series. Here the value elements can be function expressions, e.g. "@N@ / 1000", in which tags between "@" signs refer to location attributes that are defined in the locationSets config file. The expression is evaluated when the configuration is read, by replacing the tags with actual values. These values can be different for different locations. When an attribute is missing for a location the threshold value is invisible/ignored for that location.

label

Optional label.

labelFunction

Optional location dependent label that is specified by a function, e.g. "@FLOOD_WATCH@", in which tags between "@" signs refer to location attributes that are defined in the locationSets config file. The tags are replaced by actual attribute values. These attribute values can be different for different locations. If an attribute is missing for a location, then the label is ignored for that location.

warningArea

One or more warnings that correspond to this threshold for the configured timeSeriesSet(s). These warningAreas are e.g. used in the ThresholdOverviewDisplay threshold crossing counts tabs.

upActionLogEventTypeId

ID of the action message (=additional log.message) that must be logged if a threshold value is crossed UP. This id has to contain a dot, because the action event is only visible to the master controller if this id contains a dot, e.g. "Threshold_Name.Up". The event code need not be unique.

downActionLogEventTypeId

ID of the action message (=additional log.message) that must be logged if a threshold value is crossed DOWN. This id has to contain a dot, because the action event is only visible to the master controller if this id contains a dot, e.g. "Threshold_Name.Down". The event code need not be unique.

rateThresholdValue

rateThresholdId

ID of the rate threshold type, as it is specified in the file thresholds

value

Value of the rate threshold. This is the change within timeSpan where timeSpan is the timeSpan configured below. Rate of change = (change within timeSpan) / timeSpan.

valueFunction

Location dependent threshold value by using a function with location attributes. eg. @FLOOD_WATCH@. When an attribute is missing for a location the threshold value is invisible/ignored for that location

label

Optional label.

labelFunction

Optional location dependent label that is specified by a function, e.g. "@FLOOD_WATCH@", in which tags between "@" signs refer to location attributes that are defined in the locationSets config file. The tags are replaced by actual attribute values. These attribute values can be different for different locations. If an attribute is missing for a location, then the label is ignored for that location.

upActionLogEventTypeId

ID of the action message (=additional log.message) that must be logged if threshold value is crossed UP. This id has to contain a dot, because the action event is only visible to the master controller if this id contains a dot, e.g. "Threshold_Name.Up". The event code need not be unique.

downEventTypeId

ID of the action message (=additional log.message) that must be logged if threshold value is crossed DOWN. This id has to contain a dot, because the action event is only visible to the master controller if this id contains a dot, e.g. "Threshold_Name.Down". The event code need not be unique.

timeSpan

This time span will be used in the computation of the rate of change. Rate of change = (change within timeSpan) / timeSpan.

rainRate

If rainRate is true, then the input time series is accumulated before the rate of change is computed.

maxThresholdValue

maxThresholdId

ID of the max threshold type, as it is specified in the file thresholds

value

max threshold value

valueFunction

Location dependent threshold value by using a function with location attributes. eg. @FLOOD_WATCH@. When an attribute is missing for a location the threshold value is invisible/ignored for that location

label

Optional label.

labelFunction

Optional location dependent label that is specified by a function, e.g. "@FLOOD_WATCH@", in which tags between "@" signs refer to location attributes that are defined in the locationSets config file. The tags are replaced by actual attribute values. These attribute values can be different for different locations. If an attribute is missing for a location, then the label is ignored for that location.

actionLogEventTypeId

ID of the action message (=additional log.message) that must be logged if threshold value is exceeded. This id has to contain a dot, because the action event is only visible to the master controller if this id contains a dot, e.g. "Threshold_Name.Max". The event code need not be unique.

timeSpan

If two peaks fall have a distance that is less then the defined timeSpan, only the first peak will be reported.

forecastAvailableThresholdValue

is used to log the info that the related forecast run was available within a certain time window when the observed threshold has been crossed.

deprecatedConversionChoice

stageDischargeConversion

since 2010.01, for NEW style rating curve types. Used when stages are specified for the threshold levels and there are discharges in (some of) the specified time series sets.

dischargeParameterId

Discharge parameters for which the threshold values should be converted from stage to discharge.

dischargeStageConversion

since 2010.01, for NEW style rating curve types. Used when discharges are specified for the threshold levels and there are stages in (some of) the specified time series sets.

stageParameterId

Stage parameters for which the threshold values should be converted from discharge to stage

ratingCurve

For OLD style rating curve types. Convert the threshold levels from stage to discharge or vice versa using the rating curve defined here.

id

Rating curve id to use for threshold mapping.

ratingCurveType

Type of rating curve

parameterId

Parameter ids of the time series sets for which the conversion should take place.