| scrollbar |
|---|
...
What
...
ModifierTypes.xml
...
Required
...
no
...
Description
...
Definition of modifiers in an IFD environment
...
schema location
...
http://fews.wldelft.nl/schemas/version1.0/modifierTypes.xsd
Contents
| Table of Contents |
|---|
Introduction
The chapter describes the configuration options of the modifiers.xml. The modifiers.xml is used to define which modifier types are available within a Delft-FEWS configuration. The modifiers can be created in the modifiers panel. TimeValue-modifiers can also be created in the plot display by graphically modifying a time series or by changing values in the table.
Modifier Concept
Modifiers play an important role in the concept of interactive forecasting. By using modifiers a forecaster can manually change time series, module parameters or location attributes. After creating one or more modifiers the forecaster can run a workflow locally in IFD mode to verify the effect of the modifiers. When a modifier is created it is initially only visible for the user who created the modifier. In this case the modifier is always colored red.
On an OC the modifier is made final when a workflow in which the modifier is used is scheduled to run on the server. On a SA the modifier is made final when a regular workflow is started in which the modifier is used. When a modifier is made final the modifier will be colored green. A modifier that is outside of the forecast period is colored grey. The forecast period is defined by the start of the selected state in the IFD and the selected forecast length.
Within Delft-FEWS there are different modifier types:
- Location attribute modifiers,
- Module parameter modifiers,
- Time series modifiers
The different types will be explained in more detail in the sections below. The modifierTypes.xml is the configuration file that can be used to define which modifier types are available in a FEWS system. It is for example possible to define that all time series which have parameter id X can be modified by using modifier A. If a topology node is selected in the forecast tree the module config quick scanner will determine which time series, locations and module parameter files are used in the workflow of the topology node. The time series which are used in the workflow and which have a parameter X can be modified in the modifiers panel by using modifier A.
Below an overview of all the modifiers in FEWS.
Modifier
...
The user can select an option from a pre-defined list of options. For each option a value will be defined which will stored in the time series.
This modifier is usually applied to an empty time series.
...
With this modifier it is possible to disable the adjustQ transformation
...
Assigning modifiers to whatifs
By default, modifiers are always applied to the workflow
With the introduction of the new WhatIf Templates/WhatIf Editor functionality in 2021.01, one can configure the system to allow modifiers to be created in the What-If Editor and only to be applied in a whatif.
This behavior is specified in element <whatIfModifierType> available in each modifierType, which offers four options:
- always apply in workflow (default)
- apply according to creation method (since 2022.02)
- apply modifier if referenced in a what-if workflow
- never apply in a what-if workflow (i.e. always apply unless running a workflow with a whatif attached)
ModifierTypes configured with case 1 (always apply in workflow) represent the default behaviour. The associated Modifiers can be created in the ModifiersDisplay or in the TimeSeriesDisplay. These modifiers can not be created in the WhatIf Editor.
ModifierTypes configured with case 2 (apply according to creation method) can be created in the ModifiersDisplay or in the WhatIf Editor. When created in the ModifiersDisplay the modifier will apply in the regular forecast workflow, but will never be applied in a what-if forecast workflow. When created in the WhatIf Editor, theyare tied to a specific what-if and will only be applied in the associated what-if forecast workflow.
ModifierTypes configured with case 3 (apply modifier if referenced in a whatif workflow) can only be created in the WhatIf Editor. The created modifier is directly associated with the whatif-instance and will only be applide in a whatif workflow. The created modifier will never be applied in a regular workflow.
ModifierTypes configured with case 4 (never apply in a what-if workflow) allows creation of modifiers in the ModifiersDisplay or in the TimeSeriesDisplay. These modifiers can not be created in the WhatIf Editor.the created modifier will only apply in a regular forecast and not in a what-if forecast.
Modifiers can become part of a what-if by referencing the modifierType in the whatifTemplates.
Location attribute modifiers
Currently there is only one type of modifier, the locationAttributeModifier, available to modify location attributes. This type has however a lot of configuration options so it can be used in a lot of different ways.
Location Attribute Modifier
This type is the only type available to modify location attributes. The section will explain the available configuration options in detail.
Basic examples
Although this modifier type offers a lot of configuration options, it is possible to configure a basic location attribute modifier without much effort.
Below an example.
...
Location attribute modifiers are used to change the value of a location attribute. When a modifier is applied to a location attribute the original value of the attribute will not change. When the value of location attribute is retrieved from the data store, the original value will be retrieved first. After that FEWS will apply the available modifiers to the location attribute. The available and active modifiers will applied from old to new. This means that only the newest active location attribute modifier which changes a certain attribute will be effective.
Module parameter modifiers
Module parameter modifiers are used to modify module parameter files. It is possible to create multiple module parameter modifiers for a single module parameter file. Module parameter modifiers can be applied in two ways:
- by overwriting the original values in the module parameter files,
- by adding an additional group to the module parameter file which contains the modified parameters.
The advantage of the first option is that the model adapter doesn't have to be changed to use module parameters. The model receives a single set of module parameters in which the modifiers are already applied. In the second case the model parameter files contains the original values plus
one or more groups with the modified values. The model adapter has to create the modified set of module parameter values from this file. The original set of module parameter values are always in the first group. This group always has the attribute modified set to false. The additional groups contain the modified values and always have the attribute modified set to true. Below an example of a modified module parameter file.
| Code Block | ||
|---|---|---|
| ||
<?xml version="1.0" encoding="UTF-8"?>
<parameters xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://www.wldelft.nl/fews/PI" xsi:schemaLocation="http://www.wldelft.nl/fews/PI http://fews.wldelft.nl/schemas/version1.0/pi-schemas/pi_modelparameters.xsd" version="1.5">
<group id="default" readonly="false" modified="false">
<parameter id="UHG_DURATION" name="UHG_DURATION">
<intValue>6</intValue>
</parameter>
<parameter id="UNIT" name="UNIT">
<stringValue>ENGLISH</stringValue>
</parameter>
<parameter id="UHG_INTERVAL" name="UHG_INTERVAL">
<intValue>6</intValue>
</parameter>
<parameter id="DRAINAGE_AREA" name="DRAINAGE_AREA">
<dblValue>3103.0</dblValue>
</parameter>
<parameter id="CONSTANT_BASE_FLOW" name="CONSTANT_BASE_FLOW">
<dblValue>111.0</dblValue>
</parameter>
<parameter id="UHG_ORDINATES" name="UHG_ORDINATES">
<table>
<columnTypes A="double"/>
<row A="7499.0"/>
<row A="16872.0"/>
<row A="29370.0"/>
<row A="39993.0"/>
<row A="48116.0"/>
<row A="43742.0"/>
<row A="38118.0"/>
<row A="31869.0"/>
<row A="24995.0"/>
<row A="18747.0"/>
<row A="13123.0"/>
<row A="8123.0"/>
<row A="5436.0"/>
<row A="3874.0"/>
<row A="2625.0"/>
<row A="1687.0"/>
<row A="1000.0"/>
<row A="500.0"/>
<row A="250.0"/>
<row A="62.0"/>
<row A="0.0"/>
<row A="0.0"/>
<row A="0.0"/>
<row A="0.0"/>
<row A="0.0"/>
<row A="0.0"/>
<row A="0.0"/>
<row A="0.0"/>
</table>
</parameter>
</group>
<group id="default" readonly="false" modified="true">
<validPeriod>
<timeZone>0.0</timeZone>
<startDate date="2012-09-09" time="12:00:00"/>
<endDate date="2012-09-27" time="12:00:00"/>
</validPeriod>
<parameter id="UHG_DURATION" name="UHG_DURATION">
<intValue>6</intValue>
</parameter>
<parameter id="UNIT" name="UNIT">
<stringValue>ENGLISH</stringValue>
</parameter>
<parameter id="UHG_INTERVAL" name="UHG_INTERVAL">
<intValue>6</intValue>
</parameter>
<parameter id="DRAINAGE_AREA" name="DRAINAGE_AREA">
<dblValue>3103.0</dblValue>
</parameter>
<parameter id="CONSTANT_BASE_FLOW" name="CONSTANT_BASE_FLOW">
<dblValue>0.0</dblValue>
</parameter>
<parameter id="UHG_ORDINATES" name="UHG_ORDINATES">
<table>
<columnTypes A="double"/>
<row A="8666.18"/>
<row A="19498.05"/>
<row A="33941.3"/>
<row A="46217.72"/>
<row A="24331.23"/>
<row A="50550.24"/>
<row A="23027.725"/>
<row A="36829.26"/>
<row A="28885.35"/>
<row A="21664.88"/>
<row A="15165.53"/>
<row A="9387.31"/>
<row A="6282.09"/>
<row A="4476.97"/>
<row A="3033.57"/>
<row A="1949.57"/>
<row A="1155.65"/>
<row A="577.82"/>
<row A="288.91"/>
<row A="71.65"/>
<row A="0.0"/>
<row A="0.0"/>
<row A="0.0"/>
<row A="0.0"/>
<row A="0.0"/>
<row A="0.0"/>
<row A="0.0"/>
<row A="0.0"/>
</table>
</parameter>
</group>
</parameters> |
Time series modifiers
Time series modifiers modify time series. It is possible to apply more than 1 modifier to a single time series. A single time series modifier can be applied to multiple time series. The original time series will always be left unchanged in the database. When a time series is retrieved from the database first the original time series will be retrieved. After retrieving the time series from the database the modifiers will be applied to the time series. The modifiers will be applied from old to new. Rating curves can also be modified in FEWS. Since rating curves are considered to be a form of time series, rating curve modifiers are a special type of time series modifiers. Time series modifiers can be created by using the modifiers panel or by modifying a time series directly in the time series plot or time series table.
Config options which apply to all modifiers
The following config options apply to all modifier types.
restoreModifiersWhenApprovingForecastRun
In the forecast manager it is possible to approve a forecast. If this option is enabled the modifiers which were applied in this run will restored.
rollbackOverlappingModifiers
If an OC detects that another user committed new modifiers which overlap with local non-finalized modifiers then these local modifiers will be rolled back.
autoCommit
By default, local modifiers are committed when the user starts a server run in which these modifiers are used. When this option is enabled the modifiers will be committed directly after the moment they are changed.
Assigning modifiers to whatifs
By default, modifiers are always applied to the workflow
With the introduction of the new WhatIf Templates/WhatIf Editor functionality in 2021.01, one can configure the system to allow modifiers to be created in the What-If Editor and only to be applied in a whatif.
This behavior is specified in element <whatIfModifierType> available in each modifierType, which offers four options:
- always apply in workflow (default)
- apply according to creation method (since 2022.02)
- apply modifier if referenced in a what-if workflow
- never apply in a what-if workflow (i.e. always apply unless running a workflow with a whatif attached)
ModifierTypes configured with case 1 (always apply in workflow) represent the default behaviour. The associated Modifiers can be created in the ModifiersDisplay or in the TimeSeriesDisplay. These modifiers can not be created in the WhatIf Editor.
ModifierTypes configured with case 2 (apply according to creation method) can be created in the ModifiersDisplay or in the WhatIf Editor. When created in the ModifiersDisplay the modifier will apply in the regular forecast workflow, but will never be applied in a what-if forecast workflow. When created in the WhatIf Editor, theyare tied to a specific what-if and will only be applied in the associated what-if forecast workflow.
ModifierTypes configured with case 3 (apply modifier if referenced in a whatif workflow) can only be created in the WhatIf Editor. The created modifier is directly associated with the whatif-instance and will only be applide in a whatif workflow. The created modifier will never be applied in a regular workflow.
ModifierTypes configured with case 4 (never apply in a what-if workflow) allows creation of modifiers in the ModifiersDisplay or in the TimeSeriesDisplay. These modifiers can not be created in the WhatIf Editor.the created modifier will only apply in a regular forecast and not in a what-if forecast.
Modifiers can become part of a what-if by referencing the modifierType in the whatifTemplates.
Location attribute modifiers
Currently there is only one type of modifier, the locationAttributeModifier, available to modify location attributes. This type has however a lot of configuration options so it can be used in a lot of different ways.
Location Attribute Modifier
This type is the only type available to modify location attributes. The section will explain the available configuration options in detail.
Basic examples
Although this modifier type offers a lot of configuration options, it is possible to configure a basic location attribute modifier without much effort.
Below an example.
| Code Block | ||||
|---|---|---|---|---|
| ||||
<locationAttributeModifier id="example" name="example"> <modifiableGroup name="exampleGroupA"> <locationSetId>MODIFIABLE_PROJECTS_QO_Avg_Min</locationSetId> <attribute id="wQO_Avg_Req_Day_RT"> <comment>Original value: @wQO_Avg_Req_Day_RT@</comment> </attribute> <attribute id="wQO_Avg_Min_Day_RT"> <comment>Original value: @wQO_Avg_Min_Day_RT@</comment> </attribute> </modifiableGroup> </locationAttributeModifier> |
...
| Code Block | ||
|---|---|---|
| ||
<attributeModifiers> <shiftDateTimeModifier id="shiftDateTimeModifier" name="shiftDateTimeModifier"> <attributeId>wMarketChoice_RT</attributeId> <locationId>BPA</locationId> <defaultModifierTime> <offset unit="day"/> <timeStep unit="day"/> </defaultModifierTime> <customLabel>My custom label text</customLabel> <editablePeriodTimeSeries> <moduleInstanceId>Publish_RT</moduleInstanceId> <valueType>scalar</valueType> <parameterId>GN_Sim</parameterId> <locationId>BPA</locationId> <timeSeriesType>simulated forecasting</timeSeriesType> <timeStep unit="hour"/> <relativeViewPeriod unit="day" start="0" startOverrulable="false" end="24" endOverrulable="false"/> <readWriteMode>read only</readWriteMode> </editablePeriodTimeSeries> <offsetValidTime unit="day"/> </shiftDateTimeModifier> </attributeModifiers> |
Module parameter modifiers
Module parameter modifiers can be used to modify module parameters. The most common usage is to modify the module parameters of a model directly but it is also possible to modify transformations with this modifier.
To modify the parameters of a transformation the transformation must have a module parameter file configured.
Module parameter modifiers
Module parameter modifiers are used to modify module parameter file which are used by a model. Currently there are two types available:
...
| Code Block | ||
|---|---|---|
| ||
<ratingCurveModifiers> <shiftMultiplyRatingCurveModifier id="qpcshift" name="qpcshift"> <defaultStartTime>start run</defaultStartTime> <defaultEndTime>end run</defaultEndTime> <offsetDefaultEndTime unit="day" multiplier="3"/> </shiftMultiplyRatingCurveModifier> </ratingCurveModifiers>" multiplier="3"/> </shiftMultiplyRatingCurveModifier> </ratingCurveModifiers> |
defaultStartTime
The default start time of the modifier. The available options are startrun and time zero. It corresponds to the same fields in the modifier display. This is only a default value, which can be changed by the user.
offsetDefaultStartTime
The offset start time compared to the option defined in defaultStartTime. For example when an offset of 1 day is configured in this option and the defaultStartTime is set to timezero than the default starttime of the modifier will be set to time zero plus 1 day. It corresponds to the same fields in the modifier display. This is only a default value, which can be changed by the user.
defaultEndTime
The default end defaultStartTime
The default start time of the modifier. The available options are startrun and time zero and end run. It corresponds to the same fields in the modifier display. This is only a default value, which can be changed by the user.
offsetDefaultEndTimeoffsetDefaultStartTime
The offset start of the end time compared to the option defined in defaultStartTime. For example when an offset of 1 day is configured in this option and the defaultStartTime is set to timezero than the default starttime of the modifier will be set to time zero plus 1 day. It corresponds to the same fields in the modifier display. This is only a default value, which can be changed by the user.
defaultEndTime
The default end time of the modifier. The available options are time zero and end run. It corresponds to the same fields in the modifier display. This is only a default value, which can be changed by the user.
offsetDefaultEndTime
The offset of the end time compared to the option defined in defaultEndTime. It corresponds to the same fields in the modifier display. This is only a default value, which can be changed by the user.
expiryTime
This element can be used to overrule the default expiry time. The expiryTime is not related to the display (and is thus hidden from the user) and can be used to maximize the period a rating table modifier can be applied. This expiryTime is related to the period to which the modifier is applied, it does not indicate the period after which the rating table will be removed by the rollingBarrel. By using this option, you can overrule the default expiryTime.
expiryTimeDeletedModifiers
The expiryTimeDeletedModifiers is related to the rollingBarrel. When a modifier is deleted by the user (in the GUI) it will not be deleted but only set to invisible, so that it can be restored. However, when the expiryTimeDeletedModifiers has passed, the modifier will be removed from the database and the modifier can no longer be restored. So if the expiry time is 50 years, the modifier remains 50 years in the database, visible or invisible.
Time series modifiers
There are several options which apply to all types of time series modifiers.
applyToDeterministicRun
If this option is set to true then the modifier will only apply to deterministic runs.
applyToEnsemble
in defaultEndTime. It corresponds to the same fields in the modifier display. This is only a default value, which can be changed by the user.
expiryTime
This element can be used to overrule the default expiry time. The expiryTime is not related to the display (and is thus hidden from the user) and can be used to maximize the period a rating table modifier can be applied. This expiryTime is related to the period to which the modifier is applied, it does not indicate the period after which the rating table will be removed by the rollingBarrel. By using this option, you can overrule the default expiryTime.
expiryTimeDeletedModifiers
The expiryTimeDeletedModifiers is related to the rollingBarrel. When a modifier is deleted by the user (in the GUI) it will not be deleted but only set to invisible, so that it can be restored. However, when the expiryTimeDeletedModifiers has passed, the modifier will be removed from the database and the modifier can no longer be restored. So if the expiry time is 50 years, the modifier remains 50 years in the database, visible or invisible.
Time series modifiers
There are several options which apply to all types of time series modifiers.
applyToDeterministicRun
If this option is set to true then the modifier will only apply to deterministic runs.
applyToEnsemble
If you have configured ensemble ids in this section, the modifier will only apply to the configured ensemble ids.
Valid time
The behaviour of the valid time for simulated time series and external historical time series is as follows:
When modifiers are defined in the period before valid time, they will always be valid.
The situation changes when modified values are placed in the future. When the valid time is on or after time zero, all modified values are valid and will be used.
Later, when time has proceeded and valid time is before time zero, the modified values AFTER valid time are not valid anymore.
The behaviour of the valid time for external forecasting time series is as follows:
If a modifier has a valid time then it will only be applied if the external forecast time is the same as the valid time. If a modifier doesn't have a valid time then it will always be validIf you have configured ensemble ids in this section, the modifier will only apply to the configured ensemble ids.
Single value modifiers
A single value modifier is a modifier which modifies only one value at one time step in a time series. The forecaster can define a single value modifier in the modifier panel by selecting a date and a value. The combination of the selected time and value is the definition of the single value modifier.
...
Below an example of the display for an enumeration modifier.
Configuration example
| Code Block | ||
|---|---|---|
| ||
<enumerationModifier id="rainsnow" name="rainsnow">
<timeSeries>
<parameterId>RAINSNOW</parameterId>
</timeSeries>
<descriptionEnumeration>choose precipitation:</descriptionEnumeration>
<enumeration>
<item text="rain" value="1"/>
<item text="snow" value="2"/>
</enumeration>
<defaultStartTime>start run</defaultStartTime>
<defaultEndTime>end run</defaultEndTime>
</enumerationModifier> |
timeseries
The user can define a timeseries filter in this element.
descriptionEnumeration
Define the text value in the display which is shown before the dropdown list
enumeration
Define the list of options available in the drop down list and its associated value which will be placed into the time series.
defaultstarttime
The default start time of the modifier can be defined here. It corresponds to the same fields in the modifier display. This is only a default value, which can be changed by the user.
Possible options are: "start run" or "time zero"
defaultendtime
The default end time of the modifier can be defined here. It corresponds to the same fields in the modifier display. This is only a default value, which can be changed by the user.
Possible options are: "time zero" or "end run"
Time series modifier
The time series modifier is a modifier which allows the forecaster to modify a timeseries by selecting points in a graph (graphical appointment of modifiers, aka GAM, see below) or by changing values in a modifier table. In most applications of this modifier the forecaster is directly modifying a time series that is used by trasnformations or external models. It might, for example, be used to directly modify a precipitation time series. This is contrary to how for example the single value modifier WECHNG is used. This modifier modifies an empty time series that is used by a snow17-model for modifying its state based on the input from this modifier. A time series modifier has the following characteristics:
- The time series modifier has always a start- and end date.
- The time series modifier can (Optionally, if configured) have a valid time.
When a valid time is used the behaviour is different for time series types:
an enumeration modifier.
Configuration example
| Code Block | ||
|---|---|---|
| ||
<enumerationModifier id="rainsnow" name="rainsnow">
<timeSeries>
<parameterId>RAINSNOW</parameterId>
</timeSeries>
<descriptionEnumeration>choose precipitation:</descriptionEnumeration>
<enumeration>
<item text="rain" value="1"/>
<item text="snow" value="2"/>
</enumeration>
<defaultStartTime>start run</defaultStartTime>
<defaultEndTime>end run</defaultEndTime>
</enumerationModifier> |
timeseries
The user can define a timeseries filter in this element.
descriptionEnumeration
Define the text value in the display which is shown before the dropdown list
enumeration
Define the list of options available in the drop down list and its associated value which will be placed into the time series.
defaultstarttime
The default start time of the modifier can be defined here. It corresponds to the same fields in the modifier display. This is only a default value, which can be changed by the user.
Possible options are: "start run" or "time zero"
defaultendtime
The default end time of the modifier can be defined here. It corresponds to the same fields in the modifier display. This is only a default value, which can be changed by the user.
Possible options are: "time zero" or "end run"
Time series modifier
The time series modifier is a modifier which allows the forecaster to modify a timeseries by selecting points in a graph (graphical appointment of modifiers, aka GAM, see below) or by changing values in a modifier table. In most applications of this modifier the forecaster is directly modifying a time series that is used by trasnformations or external models. It might, for example, be used to directly modify a precipitation time series. This is contrary to how for example the single value modifier WECHNG is used. This modifier modifies an empty time series that is used by a snow17-model for modifying its state based on the input from this modifier. A time series modifier has the following characteristics:
- The time series modifier has always a start- and end date.
- The time series modifier can (Optionally, if configured) have a valid time
- When a modified time series is a simulated forecast time series or an external historical time series and the valid time is equal to time zero (or later) then the entire modifier will be applied, otherwise the modifier will only be applied up to the valid time. When a modifier is created the valid time will be equal to the system time. In this situation the entire modifier will be applied. When the modifier is still available and used in later runs with a later time zero then the modifier will only be partly applied up to the valid time. This functionality was developed for the following situation. When the data of a simulated time series before time zero is a copy of the observed data this part of the simulation is not likely to change in simulations which are executed at a later time. So the part of the modifier before time zero (valid time) is still valid in later runs. However the part of the modifier after time zero is likely to be invalid because this part of the time series more likely to change in later runs.
- When a modified time series is an external forecast time series, and no valid time is configured, the modifier is valid for all external forecast times.
- When a modified time series is an external forecast time series, and a valid time is configured, the modifier is valid for the valid time only.
The forecaster can modify time series by making changes in table or in the graph. The changes in the graph are made by clicking in the graph.
...