Computed tags

Create computed tags

Computed tags allow users to calculate functions based on other tags within the DATAlake.

To create new computed tags:

To create a computed tag, first, it is is necessary to create a New Tag.

To create a new tag:

1. Click Manage > Tags in the menu.
2. Select the Folder.
3. Put Tag name. Example: Profit_h
4. Select the new tag Type: Numeric or Symbolic.  

It is obligatory to put the folder, tag name and tag type. Choose a folder which has access to all tags needed for the calculation of the computed tag.

1. Put the Title (optional).
2. Put the Description (optional).
3. Put the Unit (optional). Example: m3/h
4. Click Create.

After the creation of the shell ID it is necessary to create the computed tag.

To Add Computed tags:

From this menu, create jobs for computed tags or exports to DATAmaestro analytics. 

1. Click Manage > Jobs  in the menu.  
2. Click + New job button on top right.
3. Choose a New Job Type: ComputedTagTask 
4. Click Create. 

On General tab: 

1. Enter Job id. Note: The job must be in a folder that has access to the necessary data to be executed. 
   1. Click + New Folder 
   2. Select Base Folder. Choose the same Base Folder as the tags used for the computed tag executing. 
   3. Enter New Folder name. Example: computed. 
1. Create a New Folder to put all computed tags in the same folder. 
2. Example of Job Id: /Site A/Line 1/computed/Delta (predict - real)
2. Select Scheduling.
   1. Enter At time (hours) : (minutes) 
1. Standard:  Job will be executed a first time after the initial delay and then execution will occur at regular intervals. This regular interval is defined by the period.
2. Every day:  Job will be executed every day at the same time.
3. If scheduling Standard, enter Initial delay, if the initial delay is equal to zero the job starts as soon as the Save button is clicked.
4. Enter Period, frequency of the job. Important remark: it is necessary to put the units, example, for each 10 minutes : 10m. 
5. Class name indicates the type of job. This field is  automatically filled. 
   1. Computed tags: be.pepite.pepito.data.historian.tm.jobs.ComputedTags

On Properties tab: 

1. It is compulsory to create a +New Tag before creating a Computed Tag. 
1. Click + New Tag button. 
2. Enter Folder, path is automatically filled. 
3. Enter tag Name. 
4. Enter Title, if required.  
5. Enter Type, Numeric or Symbolic. 
6. Enter Unit, if required. 
7. Enter Description, if required. 
8. Click Save. 
2. Select Computed Tag. Note: You can only select tags in the folder or sub folders of the job. 
3. Select Input tags. Note: You can only select tags in the folder or sub folders of the job. 
4. Compute latest values checkbox is deactivated by default. Lake allows the insertion of several values at a same timestamp. By default, the computed tag is not going to calculate a new value for the last input since it is not sure whether there is going to have another value at the same timestamp. Therefore the computed tag can have one value late. If Compute latest values is activated it is possible to indicate to the computed tag that it can calculate the last input even if there is a new value at the same timestamp that can be inserted later. 
5. Write the script. 
6. Click Save. 
7. Click Truncate to remove data for a selection of tags from a particular date onwards. 

On Advanced properties tab: 

In this tab it is possible to edit all the properties of the job in a JSON format. For computed tags the properties that can be edited are: 

• output tags
• input tags
• script function
• is Optimistic = true or false (Compute latest values) 

function (values) {
        return values["Tag 1"] * values["Tag 2"];
}

function (values) {
        if (values["Tag 1"] <= 10.0) {
                return values["Tag 1"];
        } else {
                return 10.0
        }
}

function (values, time) {
        var d = new Date(time);
        var w;
        if (d.getDay() == 0 || d.getDay() == 6) {
                w = "WEEK-END";
        } else {
                w = "WEEK";
        }
        return w;
}

Edit computed tags

To edit computed tags:

A computed tag can be updated at any point after creation. The changes may be applied to the entire history or only from the date of change onwards.

1. Click Manage > Jobs in the menu.  
2. Click Edit icon on the list. 
3. Make required changes.
4. Click Save, the changes of the computed tags will operate onwards, it is saved from this period of time. The historical data of the computed tag, before editing, is not modified.
5. Optional - Click Truncate. Truncate recalculates the whole history for the computed tag, not just the future calculations of the computed tag.

Understanding Compute latest values

Example: Calculate the sum of  two tags (Tag1 and Tag2).

In the current implementation, for each different combination of tag values, one value of the ComputedTag is calculated. The ComputedTag calculation adopts the precautionary principle, it checks the dates associated with the input tag’s values and it stops at the tag value with the earliest (oldest) date. The main reason for that, is that there is no indication that the last value is with certainty the last one for a while or if another value will be coming soon. Moreover, Tag1 or Tag2 can themselves be computed tags. 

Let’s give an example: 

-          Tag1 corresponds to an index in thousands of m3 of gas. At 10h00 the value is equal to 151.000 m3.

-          Tag2 corresponds to an index in units of m3 of gas. At 10h00 the value is equal to 271 m3.

-          The  ComputedTag adds the values of Tag1 and Tag2.

Now let's assume that at 10h00, both tags Tag1 and Tag2 get a new value. The dates are the same, the calculation is launched and provides a value to the ComputedTag (151.271 m3). At 10h04, the Tag2 gets a new value (272 m3). A simple rule of combination could launch the calculation of the ComputedTag taking into account the new value of Tag2 and it could search for a more recent value of Tag1 (151.000 m3). The calculated value would be 151.272 m3. At 10h09, there is a new value for Tag2 (273 m3) that could be combined with the most recent value of Tag1 (151.000 m3) to calculate the next ComputedTag (151.273 m3).

As the calculation of the ComputedTag, in DM Lake, uses the precautionary principle, it grants the earliest (oldest) tag date. Therefore, in the example presented, at 10h04, Tag2 gets a new value but the last value for Tag1 is at 10h00 (earliest date).  Therefore, no calculated value is launched for the ComputedTag despite the fact there is a new value of Tag2 at 10h04. The same happens at 10h09, even though there is a new value for Tag2. 

The use of the precautionary principle can be explained by the fact that the tag values are not pushed to DM Lake individually (one at the time), but in packages. The DM Collector works in a buffer mode. Moreover, the data can come from different sources and can have different time delays.  Therefore, if we use a simple combination of the tag values Tag1 and Tag2, there is a risk that the ComputedTag values can be incorrect and must be recalculated. 

If, for example, Tag1 is stored within a certain delay (in green in the figure below, the pair value/ timestamp 152.000/10h06). If at the moment the Tag2 gets a new value, at 10h09, the computed tag is calculated by a simple combination of Tag1 and Tag2, the new value of Tag1 is stored with a certain delay, the value of the computed tag becomes incorrect.

In summary, the calculation of a computed tag in DM Lake is based on the precautionary principle instead of a simple combination of the tag values. No new value is calculated beyond the earliest date in which the tags were stored, even if certain tags propose more recent values (more recent dates). The most recent date of the calculated tag is the oldest date of the tags.