See schema at https://fewsdocs.deltares.nl/schemas/version1.0/stateEditor.xsd
Several operational forecasting systems utilise conceptual hydrological models for calculating the response of a catchment to rainfall. These models typically contain a number of parameters and state variables. A common requirement within the forecast process is the updating of state variables so that the results of the models is closer to the observed behaviour. The updating of states on the basis of observed errors is often referred to as data assimilation.
There are methods available that allow for the updating of states algorithmically, including for example Kalman Filters, empirical state correction methods etc. Another approach is the direct updating of state variables through manual intervention.
The approach taken in that state variables are considered as time series of variables and FEWS handles these as it does any other time series. The evolution of state variables can then be easily plotted against time as can for example the time series of resulting discharge. When a state variable needs to be amended, the changed values are saved as non-equidistant values at the time of the change. When running the model these values are imported into the model and at the time indicated used to overrule the value calculated internally.
To be able to use the state modifiers functionality, the adapter to the model for which the states are to be modified must have the ability to take in the time series of amended values and overrule those used in the internal state. Additionally the model and its adapter should be able to export the values of calculated state variables as a time series. The figure below illustrates the exchange of time series of model inputs & state values to the external model, as well as the return of model outputs and state values.
The State editor display supports the user in amending time series of state variables. The amended data are then passed to the model through the model adapter to allow insertion into the state and subsequent change of response on running the model.
The state editor display is in principle independent of the DELFT-FEWS system, and has been developed as a web service client. Exchange of data with the DELFT-FEWS database makes use of a web service data exchange protocol. To the normal user, however, the display appears as an integrated part of the system.
The state editor display contains four main sections
• In the main window a graph is shown of the selected state variable and the response of the model. Only one variable is shown at a time for simplicity. The arrows on the bottom right can be used to navigate to the other variables.
• The panel below the main window shows each of the state variables. For each a slider control is available which allows the user to set the desired value. The slider controls include reference values of the climatology maximum and minimum (red lines), average (green lines) and the original values (blue line).
• A tree view on the left showing all the models for which states are available.
• A panel on the bottom left showing times at which states are available in the database for the selected model.
To select the model for which the state is to be edited, identify the group which contains the desired model, open the tree if required by double-clicking on the folder icon and select the desired model.
Once a model has been selected, the available state times for that model will be displayed, and the values of the slider controls and time series will be updated to show the values in the time series of state variables at the time of the state selected.
Before entering the values for the new state, the time at which these are to be defined need to be set. There are three options to set the time. This can be done by selection of the time at which there is a state for that model in the database, it can be done by entering a time in the available input field Enter new state date/time or it can be done by selecting the appropriate time on the graph.
Select the variable to be set. If this is not displayed, use the arrow keys on the bottom right to navigate to the desired variable. If there are more than six variables, keep scrolling to the right to reveal those that are not displayed.
The variable can be amended using the slider control. A small triangle on the display will indicate the new value at the selected time.
Once the values of selected variables have been set, the state can be saved by selecting the Save button. Note that this will save a complete set of state variables. In other words, if there are six state variables, and only one has been amended, then the saved set will contain all six variables. The amended value, as well as the other five with the value of the variable at the selected time.
Once a set of state variables has been defined these cannot be deleted.
The values of the state variables displayed are only those from the historical run. Values from the forecast
The PI-Service provides an interface through which data can be exchanged with the FEWS Web Service. To avoid the external web service client, referred to as the PI-Client having to contain intelligence on how data is stored in internally in the FEWS Database, the Pi-Service configuration allows the setting up of objects to be exchanged by assigning an external ID to be used by the PI-client to an internal object.
Four FEWS objects are available for exchange
• Time series data
• Module Parameter sets
• Module datasets
• Module states
Several definitions are given in the general block. The exchange of data through the web service is similar to that through the General Adapter.
If the option to exchange data using an intermediate persistent layer is selected (see option writeToFile) then this specifies the directory the service imports data from.
Specifies the Id Map to translate external identifiers for locations and parameters to internal identifiers for locations and parameters on import.
Specifies the unit conversion table to translate external units to internal units on import.
If the option to exchange data using an intermediate persistent layer is selected (see option writeToFile) then this specifies the directory the service imports data to.
Specifies the Id Map to translate external identifiers for locations and parameters to internal identifiers for locations and parameters on export.
Specifies the unit conversion table to translate external units to internal units on export.
Boolean option to exchange data through a persistent layer or to only exchange data in memory. When set to true the persistent layer is used.
Defines the time zone to which data is to be exported to and from which it should be imported.
Definition of the time series objects available for exchange
Optional description for this time series object
Identifier of the object to be used in exchanging through the web service
Boolean option. When set to true the data is exported as a bin file (or byte stream) while the headers use the PI-XML format. When false all data and headers are included in XML format.
Definition of the FEWS time series set. Not that the use of locationSets etc is supported, meaning that any object may contain multiple time series.
Boolean option. When true the exported arrays will not include missing values. When false (default) missing values will be included using the specified missing value indicator.
Identifier for missing values. If not defined missing values will be defined as NaN.
Boolean option. When true the values in the exported arrays will be transformed by the datum to provide the data at global data. This applies only for those parameter groups that this applies to.
Definition of module dataset objects available for exchange. Note that these are exchanged as zip files (streamed).
Identifier of the object to be used in exchanging through the web service.
Identifier of the module dataset in the FEWS database using its moduleInstanceId.
Definition of module parameter set objects available for exchange. Elements to be defined are the same as in the moduleDataSet.
Definition of module state set objects available for exchange. Elements to be defined are the same as in the moduleDataSet.
The state editor display is an external display to Delft FEWS. It exchanges data with the main FEWS database using the PI-Web Service exchange interface (see also Configuration of the FEWS Pi-Service).
Configuration of the State Editor requires configuration of several items;
• A general section defining the name of the display etc.
• A definition for the grouping of models for which states are handled
• A definition of all the models for which states are handled
• A definition of the grouping of state parameters
• A definition of the state parameter group which describes which parameters are contained in each model, and the properties of these parameters.
• A definition of additional time series to be displayed (e.g. result series and observed series)
• A definition of how time series are displayed.
Definition of general settings for the display
Name of the display to be shown in the title bar
time Zone to display all data in
Definition of the grouping of models
Definition of the a group of models. This will appear as a folder in the treeview. The attributes are;
id Identifier for the group for later reference
name Name of the group to be displayed in the tree view
list of identifiers of models included in this group (one or more)
list of identifiers of model groups included in this group (one or more). This allows recursive definition so that a complete tree can be formed. Obviously circular references are not supported.
definition of the models for which state variables/parameters are available for editing.
id Identifier for the model for later reference
name Name of the model to be displayed in the tree view (id is used if not defined).
Location identifier associated to this model. This is used for matching time series to the this model.
Identifier of the group of parameters considered in this model state. The parameters and their properties are defined in the stateParameterGroup element.
Identifier of the result time series. The locationId is used in matching a model to a time series.
Definition of the groups of parameters. For each model type a group needs to be defined. Different calibrated of the same model may allow different sets of parameters to be edited.
id Identifier for the parameter group for later reference
List of identifiers of the parameters included in the group. The properties of the parameters are defined in the stateParameter section.
Definition of a time series to be shown in the lower plot of the display. This time series should be associated to the model response to give guidance on the changes made to the state parameters.
id Identifier for the group of time series. This is for reference
name Name of the group of time series.
Definition of a time series. This definition is related to the definition of time series in the PI-Web Service. The identifiers used in this series groups there, must be related to identifiers to time series objects in the definition of the PI-Service.
id Identifier for the time series object as defined in the PI-Web Service configuration.
locationId Identifier for the location of the time series. If this is a group of time series then the key word $ANY$ should be used. The locationId associated to a model selection will then be filled run-time
parameterId Identifier of the parameter of the time series. This is the same parameter uses as externalParameter in the configuration of the idMapping.
Qualifier for the time series. This may be min, max or mean. Used only for displaying parameter climatology.
Definition of the parameters in a state. These can then be referenced in a stateParameterGroup.
id Identifier for the parameter for later reference
name Name of the parameter to be displayed (id is used if not defined).
Range of the parameter
min Minimum parameter value
max Maximum parameter value
Input data series for displaying as the time series of this parameter. This should relate to the time series for the current parameter. There is no explicit check if this is the case. See definition of series
Output data series to write the amended values of the state to. This should relate to the time series for the current parameter, and typically is a non equidistant time series. There is no explicit check if this is the case. See definition of series.
Definition of the climatology as a time series within this configuration. This is defined as eventData, with a given max, min and mean.
Definition of the climatology as a time series obtained from the FEWS database (preferred option). A series can to be defined for the min, max and mean at each location. The qualifier can be used to assign a series to each of these.
To run the State Editor display, this needs to be configured as a task. This should be defined as a call to the appropriate class of the external web service client. The arguments are
• Name of the configuration of the PI-Web Service Client and the PI Web Service itself. These names should be the same.
• The IP address of the computer on which the Pi-Service is run. Typically this will be on the local machine and the keyword %HOSTNAME% can be defined.
• The port on the computer on which the Pi-Service is run. Again this is typically defined by FEWS itself when running on the local machine and need only be specified when running remotely. When used locally the key word %PORT% should be used.
<explorerTask name="SAC SMA State Editor"> <iconFile>""</iconFile> <mnemonic>C</mnemonic> <arguments>SACSMA_StateModifiers %HOSTNAME% %PORT%</arguments> <taskClass>nl.wldelft.piclients.statemodifiers.StateEditor</taskClass> <toolbarTask>false</toolbarTask> <menubarTask>true</menubarTask> </explorerTask> |