How to add a custom transformation to my FEWS system?
Adding a custom transformation involves several steps which will be explained in detail in the upcoming section:
- writing the code for the custom tranformation.
- configuring the custom tranformation,
How to write a custom transformation?
First step is to write the actual code for the tranformation. Running and debugging the actual transformation can be done by writing unit tests.
Lets say we want to write a simple transformation that calculates the output value by using the following formula:
output = input1 x correctionFactor1 + input2 x correctionFactor2
The code needed for such a transformation would be quite basic and is given below:
package example; import nl.wldelft.fews.openapi.transformationmodule.Calculation; import nl.wldelft.fews.openapi.transformationmodule.Input; import nl.wldelft.fews.openapi.transformationmodule.Output; import nl.wldelft.util.timeseries.Variable; import org.apache.log4j.Logger; public class Example1 implements Calculation { private static final Logger log = Logger.getLogger(Example1.class.getName()); @Input float option1; @Input float option2; @Input Variable input1 = null; @Input Variable input2 = null; @Output Variable output = null; @Override public void calculate() throws Exception { if (Float.isNaN(input1.value) || Float.isNaN(input2.value)) return; log.info("Input is " + input1.value + " and " + input2.value); output.value = (input1.value * option1 + input2.value * option2) / 2; log.info("Output is " + output.value); } }
Now the code above will explained step by step to understand the details. First note that tranformation implements the interface Calculation.
The interface Calculation has one method void calculate().
package nl.wldelft.fews.openapi.transformationmodule; import nl.wldelft.util.Initializable; import nl.wldelft.util.TimeZeroConsumer; public interface Calculation extends Function { /** * This method is called by the framework to do the actual calculations. * The implementing class should get the input from its InputVariable * fields and put the calculation output in its OutputVariable fields. * The framework will initialize the InputVariable and OutputVariable * fields and set the input values in the InputVariables before calling * this method and get the output values out of the OutputVariables * afterwards. * * @throws Exception */ void calculate() throws Exception; }
The method calculate will contain the actual code for the transformation. The FEWS Transformation framework will automaticly invoke this method.
Once the workflow containing the custom transformation is executed. The java code in the calculate method is self explaining will not be explained in more detail here.
Next step is to explain the correctionfactors and the input values used in the calculate-method.
They are both defined as fields in the java-class.
@Input float option1; @Input float option2; @Input Variable input1 = null; @Input Variable input2 = null;
The fields option1 and option2 however dont have any values assigned! How can they have a value during runtime?
The answer is that the FEWS Transformation will inject the values at runtime in these variables. The actual values
are described in the configuration. In the upcoming section, the configuration will be explained in detail.
The input timeseries are defined as input1 and input2. They are marked as being input timeseries by the annotation @Input.
It is important to note that input timeseries can be defined as a:
- Variable (as is done in the example above)
- TimSeriesArray
Variable[]
TimeSeriesArray[]
The major difference between the use of the class Variable and TimeSeriesArray is that Variable is used when the output is only dependend on input values
of the same timestep. For example when the transformation is calculating the discharge from the stage by using a rating curve than the output is only dependend of
the input value at the same time step. However when a transformation is calculating the aggregation of the input time series over a certain period than the output
is dependend on other values at other time steps in the input time series. In this case one should use the TimeSeriesArray.
The same logic applies to the cases when a Variable[] or TimeSeriesArray[] is used. The difference between a Variable and a Variable[] is that when in the configuration several
timeseries are defined in the timeseriesset config a Variable[] is used. For example by configuring a locationSet in the timeSeriesSet. When the timeseriesset only defines a single
timeseries than a Variable is used.
In our example the output is calculated from the input values at the same time step. Therefore we define the input time series as Variable.
@Output Variable output = null;