34 What-If Templates - What-If Editor

The new What-If functionality was introduced in version 2021.01, with the intention to replace the outdated What-If functionality by 2024. This new What-If functionality uses WhatIfTemplates, which can be populated in the What-If Editor, i.e. the display to create whatif-instances that can be applied to a workflow. In Delft-FEWS 2021.01 and 2021.02, the new What-If functionality only works in Stand-Alone. From version 2022.01 and onwards,  the features also work in live systems (OCs).

		<explorerTask name="WhatIf">
			<predefinedDisplay>what if editor</predefinedDisplay>
			<toolbarTask>true</toolbarTask>
			<menubarTask>true</menubarTask>
			<loadAtStartup>true</loadAtStartup>
		</explorerTask>

The connection between WhatIfs-instances and workflows is (as of 2022.01) established via the WorkflowDescriptors, where a <whatIfTemplateId> can be defined (one of the last elements).

Note: this is a non-backward compatible change from 2021.02 and earlier releases, where the connection between workflows and WhatIfTemplates was defined in Topology.xml.

	<workflowDescriptor id="Test_WhatIfSettings" name="Test_WhatIfSettings" forecast="true" visible="true" autoApprove="true">
		...
		<whatIfTemplateId>test_whatif</whatIfTemplateId>
	</workflowDescriptor>

What-ifs are, by default, non-approved runs, unless the user puts a check in the approve checkbox of the GUI.

You can use the IFD-config option <enableAutoApprove> to bring the auto approve button to the attention of the user.

        <node id="run_whatif_properties" name="wf1 t1 Properties">
            <workflowId>Test_WhatIfSettings</workflowId>
			<enableAutoApprove>false</enableAutoApprove>

The WhatIf Editor uses the whatifTemplates.xsd schema. This schema allows the configuration of a whatif-template, which is used in the WhatifEditor GUI to allow the specification of properties and modifiers to be applied in a whatif-instance. Multiple whatIfTemplate.xml files are supported as long as their prefix is WhatIfTemplates_....xml and no duplicate identifiers are used across the files. Identifiers defined in one xml-file can be used in another xml-file.

Properties can be specified directly (string, int, double, boolean), by selecting from an enumeration, or by selecting from a configuration file (e.g. moduledataset, module parameter file). 
Note: if a whatif-property is used as a key in a timeSeriesSet, this timeSeriesSet has to be simulated forecasting.

Modifiers can be specified per modifierType. The actual behaviour of the modifier depends on the setting of <whatIfModifierType> element for this modifierType, as explained in detail in the ModifierTypes.xml:

1. always apply in workflow (default)
2. apply according to creation method (since 2022.02)
3. apply modifier if referenced in a what-if workflow
4. never apply in a what-if workflow (i.e. always apply unless running a workflow with a whatif attached)
   
   

    <timeSeriesModifier id="modify_timeseries_only_applied_in_whatif" name="Modify time series (only applied in whatif)">
        <whatIfModifierType>apply if referenced in what-if workflow</whatIfModifierType>
        <timeSeries>....

The whatIfTemplates-schema

<?xml version="1.0" encoding="UTF-8"?>
<whatIfTemplates 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/whatIfTemplates.xsd">
</whatIfTemplates>

The whatifTemplates-schema contains two main sections:

• valueTypes: to specify property types and their limits (e.g. min/max values)
• whatifTemplates: to define which properties and modifiers can be specified in the template. whatifTemplates can be nested (but not unlimited in the GUI)

valueTypes

valueTypes define the type of properties that can be used in a whatIfTemplate. Each valueType has a number of attributes with at least an id (required) and an optional default value. Additional attributes depend on the valueType. By allowing multiple instances of the same valueTypes, different display behaviour can be accommodated (e.g. different min/max ranges for numeric properties).

Attribute id the the identifier used to refer to this valueType when defining a new property in a whatIfTemplate.

Optional attribute default is the default value associated with the valueType, which will be used in the whatIf-instance and shown in the GUI (where a user can then change it).

enumeration

The valueType enumeration results in a string-property value. Using this valueType will list the items available in the enumeration in a dropdown box in the WhatIfEditor.

Required attribute code refers to the value which is stored when this option is chosen.

Optional attribute label specifies how this value is captioned in the display.

If no default is defined, the first item in the enumeration will be selected in the display.

configFile

The valueType configFile results in a string-property value referring to a ModuleDataSetFile, a ModuleParameterFile, or a ColdStateFile. Based on the search pattern, the configuration (either available in the database or the file system) will be queried for items to populate a dropdown box in the WhatIfEditor.

Attribute type specifies the type of config file (i.e. module dataset, module parameter, cold state).

Attribute pattern specifies the search pattern to apply. The result will be a list of configuration files that meet this search pattern and are shown in a drop-down menu.

Attribute hidePattern (true/false) specifies whether the specified pattern should be removed from the values shown in the dropdown menu. By default this is false.

Attribute default specifies the default value to be shown in the dropdown menu. Be aware that the default value should account for the hidePattern option. When hidePattern is false, the default should include the full string including the search pattern. When hidePattern is true, the default value should include only the selected suffix.

    <valueTypes>
        <configFile hidePattern="false" id="select_moduleparfile" pattern="moduleparfile_fixed_*" type="module parameter" default="moduleparfile_fixed_base"/>
		<configFile hidePattern="true" id="select_moduledataset" pattern="moduledataset_*" type="module dataset" default="grid_A"/>
	</valueTypes>

If no default value is specified, the first item returned by the search will be shown as default value in the display.

string

The valueType string allows the user to specify any string value they like in a text field in the WhatIfEditor display.

If no default value is defined, the field is empty in the display.

int

The valueType int allows the user to specify any integer value they like in a numeric field.

Optional attribute min specifies the minimum value accepted in the display.

Optional attribute max specifies the maximum value accepted in the display.

If no default value is defined, the numeric field contains a 0 in the display.

double

The valueType double allows the user to specify any numeric value they like in a numeric field.

Optional attribute min specifies the minimum value accepted in the display.

Optional attribute max specifies the maximum value accepted in the display.

If no default value is defined, the numeric field contains a 0.0 in the display.

bool

The valueType bool allows the user to turn on/off a checkbox value.

whatIfTemplateId (since 2022.01)

The valueType whatIfTemplateId allows the user to specify that the input series to the whatif run being created needs to come from another (previous) whatif run. A typical use case is a situation where the user wants to choose from a set of computed hydrological inflow scenarios to select a specific (climate/weather) scenario as an input to a reservoir or water quality model to investigate various intervention strategies.

This is deviation of default Delft-FEWS behaviour, where a workflow always uses simulated series of the "Current" run. By referencing a whatif to be used as input, the timeseries of that (approved) whatif run will be used, ignoring the Current run. Please note that, due to code complexity, this feature is explicitly not intended to inherit other whatif content (i.e. property values and modifier values) from one whatif-template into another template.

dateTime

The valueType dateTime is not implemented yet.

whatIfTemplate

This section defines the actual whatIfTemplate shown in the WhatIfEditor display, where users can create new what-if scenarios by defining different property values.

Required attribute id is a unique identifier for the whatIfTemplate. This id can be referenced in the WorkflowDescriptors to make the connection with a workflow for which the whatifTemplate can be used.

Required attribute name specifies the template name (i.e. caption) used in the display.

whatIfExpiryTime (since 2022.01)

The expiry time of whatIf is the amount of time that the what-if scenario (created with the WhatIfEditor) remains in the Topology menu. The default expiry time of the whatIf can be overruled with a custom expiry time configured in whatIfTemplate with the element ‘whatIfExpiryTime’. This custom expiry time will be used also for the modifiers associated with the whatIf’s created using the whatIfTemplate. If no whatIfExpiryTime is specified, the default expiry time for the workflow will be used instead.

properties

This is a list of all properties that are shown in the WhatIfEditor display, either as text field or drop-down menu (dependending on the valueType), that need to be defined in each instance of the what-if scenario.

property

Required attribute id is the $PROPERTY$ as used in the workflow

Optional attribute name is the name/caption as shown in the WhatIfEditor display.

Required attribute valueTypeId specifies which of the previously specified valueTypes apply to the property.

Optional element description is text which will appear as tooltip in the editor when hovering over the property (since 2024.01).

modifierType

Identifies the modifierType for which all available committed modifier-instances will be shown in the dropdown menu. By default, no modifier is selected.

Note: By selecting a modifier-instance, a copy of this selected modifier is created which is tightly related to the whatif-instance. Value changes in the original modifier (resulting in a new modifier-instance) will therefore not be reflected in the whatif scenario. To incorporate changed modifier values, the modifier-instance should be reselected in the display to obtain a copy of this new modifier-instance.

whatIfTemplateId

This makes it possible to nest whatIfTemplate sections within one another, to allow for some structure in the WhatIfEditor display.

Final notes

1. WhatIfTemplates are stored as part of the whatif-instance, also when archived. Changing a whatIfTemplate (while maintaining the same whatIfTemplateId) may thus break retrieval of archived whatif scenarios.
2. The relation between modifiers and whatif scenarios is stored at the modifier side. Exported whatif scenarios are unaware of associated modifiers, although the exported zip-file will include both the whatif.xml and the modifiers.xml if needed.
3. As of 2022.01, a TypicalProfile modifier was introduced to enable full replacement of the legacy whatif-functionality.
4. This configuration example includes several examples of how to configure and use properties and modifiers in whatifs scenarios.