07 Correlation Module - EOL in 2023

Correlation Module Configuration

The Correlation Module is used to estimate a level at a downstream location through correlation of historical levels and discharges at specific upstream locations. This utility is provided through an interactive interface available on the operator client as well as for running automatically using a fixed correlation in the Forecasting Shell Server. The module may employ data from historical events at different locations as available in the central database

The module can be used in two ways:

As an automatic forecasting module. The module is then run through a preconfigured workflow with all required inputs being retrieved from those available in the database. Results are returned to the database. These results are then available for later viewing through for example a suitably configured report. In this mode a module Instance of the correlation module is defined as described below.
In interactive mode. In this mode the module is used through the CorrelationDisplay available on the operator client. In this mode no results are returned to the database. A module instance does not need to be created in this mode, all required configuration settings are selected through appropriate options in the dialogue.

The correlation module uses two associated configuration items to establish correlations, these are the CorrelationEventSets and the TravelTimes.

When available as configuration on the file system, the name of the XML file for configuring an instance of the correlation module called for example Correlation_Severn_Forecast may be:

Correlation_Severn_Forecast 1.00 default.xml

Correlation_Severn_Forecast	File name for the Correlation_Severn_Forecast configuration.
1.00	Version number
default	Flag to indicate the version is the default configuration (otherwise omitted).

Figure 82 Elements of the correlationSets configuration

correlationSet

Root element for defining a correlation to be applied..

inputTimeSeriesSet

Time series set to be used as input for the correlation. This time series set can either be a complete hydrograph (e.g. equidistant time series). It may also be a non-equidistant series of peaks sampled using a transformation module defined previously in the workflow.

outputTimeSerieSet

Time series set to be used as input for the correlation. Values are returned for the same time step as the input series.

correlation

Root element for the definition of a correlation

forecastLocationId

LocationId for the forecast location. This is the location to be defined in the output time series set.

equationType

Definition of the equation type to be applied in determining the correlation.

Attributes;

equationType . Selection of equation type. Enumeration of options include
polynomial
simple_linear
exponential_divide
exponential_multiply
power
logarithmic
hyperbolic
polynomialOrder : Integer value for value of polynomial order. Applies only if polynomial equation is selected.
eventSetsDescriptorId
Id of the event sets to be used. A suitable CorrelationEventSets configuration must be available (see below).
travelTimesDescriptorId
Id of the event sets to be used. A suitable CorrelationEventSets configuration must be available (see below).
eventSelectionType
Method to be used in matching events. Events at the support and forecast location can be paired either on the basis of common EventId's, or on the basis of a selection on travel time, where events at the upstream and downstream location are paired if these are found to belong to the same hydrological event as defined using travel time criteria defined in the TravelTimes Configuration. Enumeration of options includes;
eventid
traveltime
Comment
Optional comment for correlation configuration. Used for reference purposes only.
selectionCriteria
Selection criteria used in defining events to be used in establishing correlations.

Figure 83 Elements of the selectionCriteria configuration
period
Root element for defining selection of events based on dates.
startDate
Start date of time span to be used in selection (yyyy-MM-dd).
endDate
End date of time span to be used in selection (yyyy-MM-dd).
startTime
Optional start time of time span to be used in selection (HH:mm:ss)
endTime
Optional end time of time span to be used in selection (HH:mm:ss)
selectInsidePeriod
Boolean to indicate if events are to be selected that fall in the time span defined, or that fall outside the time span defined.
thresholds
Root element for defining selection of events that fall above or below a threshold. The threshold is applied to events selected at the forecast location.
thresholdLimit
Value of the threshold to use in selecting events.
selectAboveLimit
Boolean to indicate if events are to be selected that fall above the threshold if true. Events are selected below the threshold if false.
tags
Root element for defining selection of events on tags defined in the eventSets
tag
Definition of tag to use in event selection. Multiple tags may be defined.
include
Boolean to define if events with given tag are to be included or excluded in selection.
CorrelationEventSets
This configuration file is related to the Correlation module, and is used to define the events used in establishing a correlation. The configuration file is in the CorrelationEventSets (table or directory). Each configuration defined is referenced using a CorrelationEventSetsId as defined in the Regional Configuration.

Figure 84 Elements for defining correlationEventSets

comment

Optional comment for correlation event sets configuration. Used for reference purposes only.

correlationEventSet

Root element for defining set of events at a location to be used in establishing correlations.

locationId

LocationId for which events are defined

parameterId

ParameterId for which events are defined.

event

Definition of events at the specified location for the specified parameter.

Attributes;

eventId : String ID for the event (may be used in matching events)
value : value of the event
date : event data (yyyy-MM-dd).
time : event time (hh:mm:ss).
tag : optional tag for event (may be used in event selection)

Location Attribute Based Events

Since 2019.01 it is possible to define correlation events based on (multivalued) location attributes.

The advantage to this is the possibility to store the events in csv format

<?xml version="1.0" encoding="UTF-8"?>
<correlationEventSets xsi:schemaLocation="http://www.wldelft.nl/fews  https://fewsdocs.deltares.nl/schemas/version1.0/correlationEventSets.xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xmlns="http://www.wldelft.nl/fews">
   <timeZone>GMT</timeZone>
   <correlationEventSet>
      <locationSetId>MultiValuedAttributePeakHeights</locationSetId>
      <eventIdAttributeId>EVENT_ID</eventIdAttributeId>
      <eventParameterLocationAttributeId>PEAK_HEIGHT_PAR</eventParameterLocationAttributeId>
      <eventTimeLocationAttributeId>PEAK_HEIGHT_TIME</eventTimeLocationAttributeId>
      <eventValueLocationAttributeId>PEAK_HEIGHT_VALUE</eventValueLocationAttributeId>
   </correlationEventSet>
</correlationEventSets>

<?xml version="1.0" encoding="UTF-8"?>
<locationSets xmlns="http://www.wldelft.nl/fews"
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:schemaLocation="http://www.wldelft.nl/fews https://fewsdocs.deltares.nl/schemas/version1.0/locationSets.xsd" version="1.1">
   <locationSet id="MultiValuedAttributePeakHeights">
      <csvFile>
         <file>MultiValuedAttributePeakHeightsLocations.csv</file>
         <geoDatum>WGS 1984</geoDatum>
         <id>%ID%</id>
         <name>%NAME%</name>
         <x>%X%</x>
         <y>%Y%</y>
         <z>0</z>
         <attributeFile>
            <csvFile>MultiValuedAttributePeakHeightsLocationAttributes.csv</csvFile>
            <id>%ID%</id>
            <dateTimePattern>dd-MM-yyyy</dateTimePattern>
            <attribute id="EVENT_ID">
               <text>%PAR%%VALUE%%TIME%</text>
            </attribute>
            <attribute id="PEAK_HEIGHT_PAR">
               <text>%PAR%</text>
            </attribute>
            <attribute id="PEAK_HEIGHT_TIME">
               <dateTime>%TIME%</dateTime>
            </attribute>
            <attribute id="PEAK_HEIGHT_VALUE">
               <number>%VALUE%</number>
            </attribute>
         </attributeFile>
      </csvFile>
   </locationSet>
</locationSets>

MultiValuedAttributePeakHeightsLocationAttributes.csv

ID,PAR,VALUE,TIME,ACTIVE
PH_locA,H.m,0.1,01-01-2001,true
PH_locA,H.m,0.2,02-02-2002,false
PH_locA,H.m,0.3,03-03-2003,true
PH_locA,H.sim,0.4,04-04-2004,false
PH_locA,H.sim,0.5,05-05-2005,true
PH_locA,H.sim,0.6,06-06-2006,true
PH_locB,H.m,1.1,11-10-2011,true
PH_locB,H.m,1.2,12-10-2012,false
PH_locB,H.m,1.3,13-10-2013,true
PH_locB,H.m,1.4,14-10-2014,false
PH_locB,H.sim,1.5,15-10-2015,true
PH_locB,H.sim,1.6,16-10-2016,false
PH_locB,H.sim,1.7,17-10-2017,false
PH_locB,H.sim,1.8,18-10-2018,true

TravelTimes

This configuration file is related to the Correlation module, and is used to define the travel time between locations. These travel times may be used in matching events. The configuration file is in the TravelTimes (table or directory). Each configuration defined is referenced using a TravelTimes Id as defined in the Regional Configuration.

Figure 85 Elements of the TravelTimes configuration

travelTime

Root element for defining a set of travel times. Multiple entries may exist.

downstreamLocation

LocationId of the downstream (forecast) location

Attributes;

id : Id of the location
name : name of the location (for reference purposes only)
upstreamLocation
LocationId of the upstream (support) location. Multiple entries may exist.

Attributes;

id : Id of the location
name : name of the location (for reference purposes only)
travelTime
Definition of the travel time between the location (average)

Attributes;

unit unit of time (enumeration of: second, minute, hour, day, week)
multiplier defines the number of units given above in a time step.**
divider same function as the multiplier, but defines fraction of units in time step.**
validPeriod
Window around travel time for determining validity of event to be matched.

unit unit of time (enumeration of: second, minute, hour, day, week)
start : start of validity period
end : start of validity period

Page tree

07 Correlation Module - EOL in 2023

Correlation Module Configuration

correlationSet

inputTimeSeriesSet

outputTimeSerieSet

correlation

forecastLocationId

equationType

eventSetsDescriptorId

travelTimesDescriptorId

eventSelectionType

Comment

selectionCriteria

period

startDate

endDate

startTime

endTime

selectInsidePeriod

thresholds

thresholdLimit

selectAboveLimit

tags

tag

include

CorrelationEventSets

comment

correlationEventSet

locationId

parameterId

event

Location Attribute Based Events

TravelTimes

travelTime

downstreamLocation

upstreamLocation

travelTime

validPeriod