Page History

...

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
editing a 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. 

At On an OC the modifier is made final when a workflow in which the modifier is used is scheduled to run at on the server. At an 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 which 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 3 types of modifiersdifferent modifier types:

• location Location attribute modifiers,
• module Module parameter modifiers,
• time Time series modifiers.

These 3 The different types will be explained in more detail in the upcoming 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.

...

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

...

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.

...

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

...

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.

...

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.

...

Below a screenshot of the display.

In  In the examples above only one modifiableGroup was defined. It is also possible to define a location attribute modifier with multiple modifiableGroups. 

Below  Below a config example.

<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>
				<attribute id="QO_Avg_Min_Week_constraintType_RT">
					<selection>
						<predefined>
							<option>hard</option>
							<option>soft</option>
						</predefined>
					</selection>
					<comment>Original value: @QO_Avg_Min_Week_constraintType_RT@</comment>
				</attribute>
				<tabularLayout>
					<showOriginalValues>false</showOriginalValues>
					<locationOrientation>row</locationOrientation>
				</tabularLayout>
			</modifiableGroup>
			<modifiableGroup name="exampleGroupB">
				<locationSetId>MODIFIABLE_PROJECTS_QO_Avg_Min</locationSetId>
				<attribute id="wQO_Avg_Min_Week_RT"/>
			</modifiableGroup>
</locationAttributeModifier>

Because  Because there are two modifiable groups defined in the config, the display will show two tabs instead of only one.

...

This element can be used define a default value for a date/time attribute. If this option is selected the initial value is set to the system time. When this option is used a checkbox will be shown after the date/time selection box. If this checkbox is selected then a modifier will be created for this attribute with the current value of the date/time box. When an existing modifier is selected and there is a modified value for the attribute in this modifier then the checkbox will also be selected.

...

This option is similar to the option useSystemTimeAsDefaultValue, but instead of setting the default value to the system time the default time will be derived from a time series. A time series set can be configured for this option. The first time of the time series array for which a reliable value is available will be used.

...

The element <selection> can be used to predefine the list of options which are available for a certain attribute. The  The predefined list op options can be defined by:

...

<attributeModifiers>
		<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>
				<attribute id="QO_Avg_Min_Week_constraintType_RT">
					<selection>
						<predefined>
							<option>hard</option>
							<option>soft</option>
						</predefined>
					</selection>
					<comment>Original value: @QO_Avg_Min_Week_constraintType_RT@</comment>
				</attribute>
				<tabularLayout>
					<showOriginalValues>false</showOriginalValues>
					<locationOrientation>row</locationOrientation>
				</tabularLayout>
			</modifiableGroup>
			<modifiableGroup name="exampleGroupB">
				<locationSetId>MODIFIABLE_PROJECTS_QO_Avg_Min</locationSetId>
				<attribute id="wQO_Avg_Min_Week_RT"/>
			</modifiableGroup>
</locationAttributeModifier>

The  The display will look like the example below.

 Conditional selection

The conditional selection can be used to disable other attributes depending on which option is selected for an attribute. For example if option A is selected for a certain attribute X then attribute Y should be disabled and attribute Z should be enabled. If option B is selected then attribute Z should be disabled and attribute Y should be enabled. Below an example.

<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>
				<attribute id="QO_Avg_Min_Week_constraintType_RT">
					<conditionalSelection>
						<option value="hard">
							<disabledAttributeId>wQO_Avg_Req_Day_RT</disabledAttributeId>
						</option>
						<option value="soft">
							<disabledAttributeId>wQO_Avg_Min_Day_RT</disabledAttributeId>
						</option>
					</conditionalSelection>
					<comment>Original value: @QO_Avg_Min_Week_constraintType_RT@</comment>
				</attribute>
				<tabularLayout>
					<showOriginalValues>false</showOriginalValues>
					<locationOrientation>row</locationOrientation>
				</tabularLayout>
			</modifiableGroup>
</locationAttributeModifier>

If the option hard is selected, the attribute wQO_Avg_Req_Day_RT should be disabled. If the second option is selected the attribute wQO_Avg_Min_Day_RT should be disabled. Below an example of the display

...

The bottom line of the display shows the comment for each attribute. The comment can be defined by using this element. It is possible to use location attribute in the comment. The unmodified value of the defined attribute will be used in the comment. Below an example.

<attribute id="QO_Avg_Min_Week_constraintType_RT">
					<conditionalSelection>
						<option value="hard">
							<disabledAttributeId>wQO_Avg_Req_Day_RT</disabledAttributeId>
						</option>
						<option value="soft">
							<disabledAttributeId>wQO_Avg_Min_Day_RT</disabledAttributeId>
						</option>
					</conditionalSelection>
					<comment>Original value: @QO_Avg_Min_Week_constraintType_RT@</comment>
</attribute>

...

When the first two options are used the set of modifiable locations is determined in the following way;. After selecting a topology node the module config quick scanner will determine which locations are available in the workflow of the selected node. The intersection of the locations which are found for the selected node and the configured locations (by either a location set or a list of locations) is the set of modifiable locations for the selected node.

The option timeSeries can be used to define a filter. First all the time series which are  used in the topology workflow are determined. Then the found time series are filtered by using the defined filter the locations of the resulting time series are the modifiable locations for a toplogy node.

Below a configuration example of the option <timeSeries>.

<modifiableGroup name="exampleGroupA">
				<timeSeries>
					<parameterId>QO</parameterId>
				</timeSeries>
				<attribute id="wQO_Avg_Req_Day_RT">
					<comment>Original value: @wQO_Avg_Req_Day_RT@</comment>
</attribute>

...

Export file

If this option is configured an additional button "export" will be shown in the modifiers display. It is possible to export the location attribute modifiers to dbf-format or csv-format. Each modifierGroup will be exported to a separate file. In addition a file called description.txt will be exported. This file will contain general information about the exported modifier. By default the data will be exported to dbf-format. Below an example of a location attribute modifier which is exported to csv-format.

Location id,URBS_LOSSTYPE,URBS_IL,URBS_CL,URBS_PR,URBS_IF,URBS_ILMX,URBS_RF,URBS_IFRF
tweed_eungella,ILCL,2.0,22.0,0.0,1.0E31,0.0,0.0,0.0

Below  Below an example.

<locationAttributeModifier id="example" name="example">
			<exportFile>
				<fileName>example</fileName>
				<exportAllAttributes>true</exportAllAttributes>
				<dataFormat>csv</dataFormat>
			</exportFile>
			<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>
				<tabularLayout>
					<showOriginalValues>false</showOriginalValues>
					<locationOrientation>row</locationOrientation>
				</tabularLayout>
			</modifiableGroup>
</locationAttributeModifier>

The element <fileName> is used to define the name of export file. The element <exportAllAttributes> can be used to define if only the visible attributes (exportAllAttributes=false) should be exported or all the attributes (exportAllAttributes=true). Currently two dataFormats are supported for the export function csv and dbf. The dataFormat can be configured by using the element <dataFormat>

. Below an example of a modifier with the element <exportFile> configured.

Summary function

The lower panel of the modifier display shows the details of the selected modifier. The upper section shows the list of modifiers for the selected topology node. Each modifier has a summary. By default Delft-FEWS will generate a summary based on the available information about the modifier. For the location attribute modifiers it is possible to configure a custom summary by using the element <summaryFunction>. In the <summaryFunction> element it is possible to include location attributes. When a summaryFunction element is added to the locationAttributeModifer, only the modifiers included in the summaryFunction will be shown. If a location attribute included in this summaryFunction is modified it will be coloured blue and bold to indicate that the value is modified. If a location attribute in the summaryFunction is not modifierd the value will be shown with original black font colour.

...

The option tabularLayout is used in the majority of the examples above, this option can be used to display the modifiable groups in a tab panel. Each modifiable group will have its own tab. The panel layout can be used to show the modifiable groups in a single panel.

...

The panel layout section defines two tableLayout sections. In the template section both table layouts are positioned on the panel. In the example the panels are placed in a grid with 1 row and 2 columns. Below an example of the display.

...

<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

...

To modify the parameters of a transformation the transformation must have a module parameter file configured. 

Module parameter modifiers

...

With the element <filter> can be identified which module parameter files can be modified.In  In the example above every module parameter file with the element CONSTANT_BASE_FLOW can be modified. The filter is also used to filter which part of the module parameter file can be modified. In the example below only the module parameters with id CONSTANT_BASE_FLOW are editable by this modifier. 

Multiple model parameter modifier

This type of modifier can also be used to modify module parameter files of models. The difference with the module parameter modifier type is that this type can be used to modify multiple parameter files with a single modifier. This type of modifier is mainly used for calibration purposes but it can also be used in an operational environment.

Below an basic example of this modifier.

...

The configuration above declares that all module parameter files which have parameter SCF can be modified with the modifier "example".

Below an example of the display of this modifier.

...

The display will show all the module parameter files of the selected segment which have a parameter SCF. In this case there are two module parameter files which have parameter SCF.

It  It is possible to define a minimum and/or a maximum value for the applied changes to a certain parameter. Below an example.

    <multipleModuleParameterModifier id="example" name="example">
        <numberParameter id="SCF">
            <minimumValue>0.1</minimumValue>
            <maximumValue>10</maximumValue>
        </numberParameter>
    </multipleModuleParameterModifier>

...

In addition it is also possible to keep the difference of the parameter value between models the same (interModelRelation = preserve difference) or keep the ratio of the values of a parameter the same between models (interModelRelation = preserve ration).

Below an configuration example.

...

If the user changes the value of the parameter SI of one of the module parameter files then the values of the SI parameter of the other module parameter will automatically be adjusted so that the difference between the values is still the same. In the example below the difference between the two values of SI is 550.

...

It is also possible to define a relation between parameter values of the same module parameter file. It is possible to keep the difference or the ratio between two different parameter values the same.

Below an configuration example.

...