Page History

UserSimple

Input

It is possible to define embedded variables in this transformation. In the expression both embedded variables and variables defined at the start of the transformations configuration file can be used. If an embedded variable and a variable defined at the start of the transformations configuration file have the same variableId, then the embedded variable will be used.

In FEWS 2014.01 a new feature was added to the UserSimple transformation making it possible to embed variables containing a LocationSet. This can be done by creating the element ‘inputVariableDefinition’ where:

• variableId is the identifier of this variable. This variableId must be used in the expression.
• templateVariableId templateVariableId  refers to the variable defined at the start of the transformation configuration file. Note that in the example this variable contains a LocationSet.locationId is used to define a specific timeseries when the embedded variable (templateVariableId) contains multiple locationsThis variable should have a time series set definition, which will be used as a template. The time series set will be filtered using the filter location.
• locationId filter location. The time series set of the template variable will be filtered using this location and the resulting time series set will be stored in configured variableId.
• variableId The variable used in the expression.  It will store the time series set from the  template variable, after filtering for the filter location. This variable does not need to be explicitly defined at the start of the transformation configuration file.

In the example below Location_A is part of the locationSet Test_Locations:

...

The following operators can be used in the expression: +, -, /, *, ^ as well as the logical operators for 'or' || and 'and' && .

Functions

Furthermore the following functions can be used in the expression: sin, cos, tan, asin, acos, atan, sinh, cosh, tanh, asinh, acosh, atanh, log, ln, exp, sqrt, abs, pow, max, min, max, min, sum, average, qnorm, pgamma. Note that the trigonometric functions assume that the argument is in radians.

isMissing Function 

...

Furthermore "pi" in lowercase letters is recognised as the standard mathematical constant π. This means that the user cannot use variables or coefficients with id "pi". 

Since stable build 2013.02 it is also possible to use the calculated output value of the previous time step, by using "PREVIOUS_OUTPUT_VALUE" in uppercase letters in the expression (can be used multiple times). For each calculation time step "PREVIOUS_OUTPUT_VALUE" is replaced with the previous output value from the output time series. For the first calculation time step in the run period, the previous output value from before the start of the run period is read from the existing output time series in the database (e.g. from a previous run), if present. If for a given calculation time step the previous output value is not present or is unreliable, then "PREVIOUS_OUTPUT_VALUE" is replaced with NaN (missing value).

To write a missing value (NaN) in the expression, you can should use "0/0". Also note that an expression of "1/0" results in positive infinity, which is later replaced with NaN by the transformation module framework. However, "1/0" cannot be used in all cases to get an NaN value, since e.g. the expression "1 / (1/0)" gives 0 as a result, as expected. 

Furthermore it is possible to use "if statements" in the expression. This can e.g. be used to get one output value if X is greater than 3 and get another output value if X is equal to or less than 3. For instance in the expression

...

the if statement will be replaced with 10.5 or -2, depending on the value of the variable 'X'. In this case if X is greater than 3, then the if statement is replaced with 10.5. If X is equal to or less than 3, then the if statement is replaced with -2. The following symbols can be used (without the quotes) in an if statement:

 >  

 >= 

 <  

 <= 

 '==' 

 '!=' 

If statements can also be nested, e.g.

...

1. output: result of the evaluated expression.
   If comments are provided in the input variables being used in the expression, then the comments are appended for each time step in the output.

Description

Function specified by a custom free format expression and coefficients. Any number of input variables and coefficients can be used in the free format expression. The expression may contain general mathematical operators. A function parser is used to evaluate the expression. For each time step in the output time series the expression is evaluated and the result is written to the output time series.

...

<variable>
	<variableId>X</variableId>
	<timeSeriesSet>
		<moduleInstanceId>UserSimpleWithCoefficientSetFunctionsTest</moduleInstanceId>
		<valueType>scalar</valueType>
		<parameterId>Q.m</parameterId>
		<locationId>locationWithAttributes4</locationId>
		<timeSeriesType>external historical</timeSeriesType>
		<timeStep unit="day"/>
		<relativeViewPeriod unit="day" start="0" end="9"/>
		<readWriteMode>editing visible to all future task runs</readWriteMode>
	</timeSeriesSet>
</variable>
<variable>
	<variableId>Y</variableId>
	<timeSeriesSet>
		<moduleInstanceId>UserSimpleWithCoefficientSetFunctionsTest</moduleInstanceId>
		<valueType>scalar</valueType>
		<parameterId>Q.tra</parameterId>
		<locationId>locationWithAttributes4</locationId>
		<timeSeriesType>external historical</timeSeriesType>
		<timeStep unit="day"/>
		<relativeViewPeriod unit="day" start="0" end="9"/>
		<readWriteMode>add originals</readWriteMode>
	</timeSeriesSet>
</variable>
<transformation id="user simple with coefficient set functions test">
	<user>
		<simple>
			<expression>a*(X^2) + b*X + c</expression>
			<coefficientSetFunctions>
				<coefficient id="a" value="@coef_a@"/>
				<coefficient id="b" value="@coef_b@"/>
				<coefficient id="c" value="@coef_c@"/>
			</coefficientSetFunctions>
			<outputVariable>
				<variableId>Y</variableId>
			</outputVariable>
		</simple>
	</user>
</transformation>

The example below enables the use of string comparison in a coefficient, which may be usefull in combination with modifiable attributes. If you have for example your modifier attribute OPTION_TYPE that can be "hard" or "soft" you make a coefficient that as a boolean checks which type you are using. The numerical value of the boolean coefficient can then be used in the expression. The below example will be resolved as:

...

<variable>
	<variableId>X</variableId>
    ....
</variable>
<variable>
	<variableId>Y</variableId>
    ....
</variable>
<transformation id="user simple with boolean coefficient test">
	<user>
		<simple>
            <expression>IF(COEF_OPTION == 1, X, Y)</expression>
            <coefficientSetFunctions>
               <coefficient id="COEF_OPTION" value="@OPTION_TYPE@==&quot;hard&quot;"/>
            <coefficientSetFunctions></coefficientSetFunctions>
    	    <outputVariable>
		        <variableId>Y</variableId>
		    </outputVariable>
		</simple>
	</user>
</transformation>

You can use an attribute of a related location by using this format: @<relationID>:<attribute>@.