03 Parameters

Overview

All time series data in DELFT-FEWS must be defined to be of one of the parameters supported. This configuration file defines the list of supported parameters, including the unit of the parameter.

Parameters are organised into ParameterGroups. All parameters within a group should have the same properties and the same units. Only parameters of the same group may be displayed in a single (sub) plot in the time series display, though this can be overruled if requested using a display template.

When available on the file system, the name of the XML file is for example:

Parameters 1.00 default.xml

Parameters                                 Fixed file name for the Parameters configuration

1.00                                            Version number

default                                       Flag to indicate the version is the default configuration (otherwise omitted).

Configuration

displayUnitConversionId

The unit conversions id to convert from the (internal) units to the display units. This id should be available in the UnitConversionsDescriptors. Only required when a displayUnit is specified for a parameter group

configUnitConversionId

The unit conversions id to convert from the units specified in config files to the internal units for this parameter. This id should be available in the UnitConversionsDescriptors. Only required when a user unit is specified for a thresholdValuesSet, validationRuleSet or ratingCurve

ratingCurveStageParameterId

This parameter is used to resolve the internal stage unit and display stage unit and the name (label) that is used for the rating curve stage axis/column in the user interface

ratingCurveDischargeParameterId

This parameter is used to resolve the internal discharge unit and display discharge unit and the name (label) that is used for the rating curve discharge axis/column in the user interface

parameterGroup

Root element of each definition of a parameter group. Multiple entries may exist.

Attributes;

• id: Id of the parameter group. The ID must be unique.
• name: optional name for the parameter group. Used for reference only.

Figure 26 Elements of the ParameterGroup configuration in the parameter definition

description

Optional description of the parameter group. Used for reference purposes only.

parameterType

Definition of the parameters in the group if these are "instantaneous" parameters, "accumulative" parameters or "mean" parameters.

dimension

Optional. The dimension of the parameter used to indicate what quantity the values for this parameter represent. For example: time, mass, velocity, acceleration, discharge etc.

For certain features the dimension is checked to ensure the calculation performed by FEWS will make sense. For example, the calculate budget option in the spatial display.

The following dimensions are recognized by FEWS:

<dimension name="length" length="1"/>
<dimension name="mass" mass="1"/>
<dimension name="time" time="1"/>
<dimension name="temperature" temperature="1"/>
<dimension name="electricCurrent" electricCurrent="1"/>
<dimension name="amountOfSubstance" amountOfSubstance="1"/>
<dimension name="luminousIntensity" luminousIntensity="1"/>


<dimension name="velocity" length="1" time="-1"/>
<dimension name="frequency" time="-1"/>
<dimension name="acceleration" length="1" time="-2"/>
<dimension name="discharge" length="3" time="-1"/>
<dimension name="momentum" mass="1" length="1" time="-1"/>
<dimension name="force" mass="1" length="1" time="-2"/>
<dimension name="pressure" mass="1" length="-1" time="-2"/>
<dimension name="mass flux" mass="1" length="-2" time="-1"/>
<dimension name="volumetric flux" length="1" time="-1"/>
<dimension name="energy flux" mass="1" time="-3"/>
<dimension name="surface tension" mass="1" time="-2"/>
<dimension name="energy" mass="1" length="2" time="-2"/>
<dimension name="power" mass="1" length="2" time="-3"/>
<dimension name="mass density" mass="1" length="-3"/>
<dimension name="viscosity" mass="1" length="-1" time="-1"/>
<dimension name="area" length="2"/>
<dimension name="volume" length="3"/>
<dimension name="entropy" mass="1" length="2" time="-2" temperature="-1"/>
<dimension name="electric charge" electricCurrent="1" time="1"/>
<dimension name="electric field" mass="1" length="1" time="-3" electricCurrent="-1"/>
<dimension name="magnetic field" mass="1" time="-2" electricCurrent="-1"/>


<dimension name="dimensionless"/>

unit

Unit of the parameters defined in the group. The unit may be selected from a list of units supported by DELFT-FEWS. These are generally SI units. For an enumeration of supported units see Appendix B.

displayUnit

Specify when the unit seen by the user is not the same as the unit of the values internally stored in the data store. Also specify displayUnitConversionsId above. In this unit conversions the conversion from (internal) unit to display unit should be available

valueResolution

Optional. Default accuracy (smallest increment between two values) of the calculated or measured values for all parameters in this group. Value resolution can also be specified for a single parameter (since stable build 2011.01). By default the resolution is dynamic and the values are stored as a 32 bit floating point with 6 significant digits. Floating points don't compress very well and are slow to decode. It is far more efficient to store a value as an integer with a scale factor (= value resolution). When an 8, 16, 24 or 32 bits integer is not big enough to achieve the value resolution the default 32 bit floating point is used as a fallback. E.g. when the accuracy of a water level is half a centimeter, specify 0.005. When the accuracy of a discharge is 10 m3/s, specify 10. Although an 32 bits integer can hold 9 digits the total number of significant digits can not be larger than 7 due the limitation of the 32 bits float. The integer value is always converted to a float when loaded from the database.

usesDatum

Indicates if the parameters in the group are to be converted when toggling between local and global datum. Value is either true or false. If the value is true, the elevation defined in the location is added to the time series in the database on conversion. See Locations

parameter

Definition of each parameter in a parameter group. Multiple parameters may be defined per group.

Attributes;

• id: Id of the parameter. The ID must be unique.
• name: optional name for the parameter. Used for reference only.

shortName

Short name for the parameter. This name will be used in the time series display and reports.

description

Optional description of the parameter (tool tip).

simulatedHistoricalParameterId

Optional. Only required when different parameters are used for the forecast and historical period. The simulated historical update run, current at the moment the forecast is created, will be used for data before the start of the forecast. It is also required to configure the simulatedHistoricalModuleInstance for the forecast module instances. When configured, this parameter can only be used for simulated forecast time series.

standardName

Optional standard name defined by the netcdf CF convention. This is currently only used for export to netcdf files. The standard name has to be valid according to the list of standard names, version 18, see http://cfconventions.org/Data/cf-standard-names/18/build/cf-standard-name-table.html

standardNameModifier

Optional standard name modifier defined by the netcdf CF convention. This is currently only used for export to netcdf files. See http://cfconventions.org/Data/cf-conventions/cf-conventions-1.6/build/cf-conventions.html#standard-name

allowMissing

Option to indicate if a time series of this parameter type is allowed to contain missing values when being used by a model or a transformation. When omitted this value will default to 'true'. If this is used for a transformation, then it is also required to set the option checkMissing in the inputVariable of the transformation to true.

cellMethod

Optional cell method (for time dimension) as defined in the netcdf CF convention. This is currently only used for export to netcdf files. See http://cfconventions.org/Data/cf-conventions/cf-conventions-1.6/build/cf-conventions.html#cell-methods

Configuring a hierarchical tree view for parameters in Fews Explorer

As of Fews 2010_01 there is a second root node parameters available in the parameters.xsd schema. This new element facilitates configurations of the parameters to be displayed in Fews Explorer in the form of a hierarchical tree. The parameters node embeds the parameterGroups element described above. The element parameterRootNode is of type ParameterNodeComplexType and represents the top node of the hierarchical tree structure that is to be displayed. Other parameterNodes can be nested within each instance of ParameterNodeComplexType. Each node has an id field and can have a name and description and multiple parameterIds. The parameterIds from parameterGroups that are not included in the hierarchical tree specified by parameterRootNode are added automatically at the root level.

id

This attribute is used as the identifier label which is displayed when ids are made visible within Fews Explorer.

name

This element is used as the name label which is displayed when names are made visible within Fews Explorer.

description

This element is used as the description label which is displayed when descriptions are made visible within Fews Explorer.

parameterId

This element must refer to the identifier of one of the parameters defined within the parameterGroups section.

NB. Each parameterId can only be used once and has to be defined within one of the parameterGroups.

parameterNode

This element is of type ParameterNodeComplexType and can be used similar to parameterRootNode.

Sample xml for hierarchical parameters

 
<parameters version="1.0" xmlns="http://www.wldelft.nl/fews" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
         xsi:schemaLocation="http://www.wldelft.nl/fews http://fews.wldelft.nl/schemas/version1.0/parameters.xsd">
         <parameterGroups>
                <parameterGroup id="Discharge">
                     ...as before ...
                </parameterGroup>
         </parameterGroups>
         <parameterRootNode id="Parameters">
                <parameterNode id="Discharge">
                        <parameterId>Q.obs</parameterId>
                        <parameterId>Q.rated</parameterId>
                        <parameterId>Q.simulated</parameterId>
                        <parameterId>Q.simulated.historical</parameterId>
                        <parameterId>Q.simulated.forecast</parameterId>
                        <parameterId>Q.simulated.event</parameterId>
                        <parameterId>Q.updated</parameterId>
                        <parameterId>Q.correlated</parameterId>
                        <parameterId>Q.updated.historical</parameterId>
                        <parameterId>Q.updated.forecast</parameterId>
                        <parameterId>Q.generated</parameterId>
                        <parameterId>Q.merged</parameterId>
                        <parameterId>Q.profile</parameterId>
                        <parameterId>Q.target</parameterId>
                        <parameterId>Q.peak</parameterId>
                        <parameterId>Q.simulated.inflow</parameterId>
                </parameterNode>
                <parameterNode id="Water Level">
                        <name>Water level</name>
                        <parameterId>H.obs</parameterId>
                        <parameterId>H.obs.upstream</parameterId>
                        <parameterId>H.obs.downstream</parameterId>
                        <parameterId>H.obs.head</parameterId>
                        <parameterId>H.obs.tail</parameterId>
                        <parameterId>H.obs.crest</parameterId>
                        <parameterId>H.simulated</parameterId>
                        <parameterId>H.simulated.historical</parameterId>
                        <parameterId>H.simulated.forecast</parameterId>
                        <parameterId>H.simulated.event</parameterId>
...
                </parameterNode>	
         </parameterRootNode>
</parameters>

Sample parameters tree view in Fews Explorer

In case there is no timeseriesset for the combination of parameter and location, the nodes will be grayed out:

Enumerations

Parameters can also be defined as enumerations. Then there will be a set number of possible values with a specific label. The value will be stored in the database, the label will be shown in the GUI. 

<parameters version="1.0" xmlns="http://www.wldelft.nl/fews" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.wldelft.nl/fews http://fews.wldelft.nl/schemas/version1.0/parameters.xsd">
	<displayUnitConversionsId>ImportUnitConversions_IMmetingen</displayUnitConversionsId>
	<enumerations>
		<enumeration id="GATE">
			<value code="0" label="Closed"/>
			<value code="1" label="Half Open"/>
			<value code="2" label="Open"/>
		</enumeration>
		<enumeration id="SMELL">
			<value code="0" label="None"/>
			<value code="1" label="Weak"/>
			<value code="2" label="Strong"/>
		</enumeration>

Parameters in csv format

It is possible to define parameters in a csv file. By using %% can be referred to the content of the columns in the csv file. For example:

<?xml version="1.0" encoding="UTF-8"?>
<parameters version="1.0" xmlns="http://www.wldelft.nl/fews" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.wldelft.nl/fews http://fews.wldelft.nl/schemas/version1.0/parameters.xsd">
	<displayUnitConversionsId>ImportUnitConversions</displayUnitConversionsId>
	<ratingCurveStageParameterId>H.obs</ratingCurveStageParameterId>
	<ratingCurveDischargeParameterId>Q.rated</ratingCurveDischargeParameterId>
	<parametersCsvFile>
		<file>parametersALL.csv</file>
		<id>%ID%</id>
		<name>%NAME%</name>
		<shortName>%SHORT_NAME%</shortName>
		<group>%GROUP%</group>
    	<groupName>%GROUP_NAME%</groupName> <!--optional-->
	    <enumerationId>%ENUMERATION_ID%</enumerationId> <!--optional-->
		<parameterType>%TYPE%</parameterType>
		<unit>%UNIT%</unit>
		<valueResolution>%VALUE_RESOLUTION%</valueResolution>
		<allowMissing>%ALLOW_MISSING%</allowMissing> <!--optional-->
		<attribute id="InternalParameterId">
			<text>%ID%</text>
		</attribute>
	</parametersCsvFile>
</parameters>

parametersALL.csv located in MapLayerFiles config directory

ID;NAME;SHORT_NAME;GROUP;TYPE;UNIT;VALUE_RESOLUTION;ALLOW_MISSING
WATHTE;Waterhoogte;;Hoogte;instantaneous;m;0.001;TRUE
WATDTE;Waterdiepte;;Hoogte;instantaneous;m;0.001;TRUE
pH;Zuurgraad;;Dimensieloos;instantaneous;-;0.001;TRUE
OLE;Olie;Olie;Dimensieloos;instantaneous;-;0.001;TRUE
SO4;Sulfaat;Sulfaat;Concentratie mg/l;instantaneous;mg/l;;TRUE
Cl;Chloride;Chloride;Concentratie mg/l;instantaneous;mg/l;;TRUE