Adding and Using Capsule Properties

[Lindsey.Wilcox]

Background:

A property can be added to capsules for further filtering and aggregation through Seeq tools, including Histogram.  All properties on a condition are stored as string values.  This post examines how to add a property to a condition and then how those properties may be used.

Adding Properties to a Condition

Capsule properties may be used to store important information such as, Product Codes, Batch IDs, and Recipes. There are three functions in Seeq Formula which can add properties to the capsules in a condition:

• toCondition()  - Dedicated function to transform a signal into a condition which contains a capsule for each value change in the input signal.  The value of the signal is stored as a property of the capsule
• toCapsules() - Dedicated function to transform a signal into a condition which contains a capsule for each valid sample in the input signal.  The value of the signal is stored as a property of the capsule.

• setProperty() - Flexible function which is used to assign properties to each capsule in a condition.   It is most commonly used in SQL queries to attach transactional information from a data source to a capsule in a condition.

toCondition()

This function creates a capsule for every value change in a signal. This may be useful on a Batch ID signal or operating mode signal. The toCondition() function creates a new capsule for each value change and automatically assigns the signal value to a capsule property called 'Value'.

Using the toCondition() operator on the Compressor Stage example data creates a capsule for each distinct value in the signal.

The following image shows the condition created from performing toCondition() on the Compressor Stage Example Data. A capsule is created for each distinct value in the signal.   This property may be viewed by adding the Value property to the Capsules Pane.

The .toCapsules() operator works similiarly, but instead creates a new condition with a capsule for each sample point (regardless of whether the value has changed).

setProperties()

This flexible function is used to assign properties to a condition. Users must assign both a property name and value. 

The following syntax is an example of how the .setProperties() operator can be used in Formula to assign properties to the capsules in a condition.  This example assigns a property of "Batch" with a value of '23' to each capsule in a condition.

$condition.transform($capsule->
     $capsule.setProperty('Batch',23))

In the next example, a High Power condition was created using Value Search tool (power >25).  The following syntax can be used to assign a property called "averagePower" to each capsule in the High Power condition.  The value of this property is calculated as the average Compressor Power during each High Power condition.

Executing this Formula results in a new condition that contains the averagePower property for each capsule.

Using Condition Properties

Condition properties can be used in different ways, such as to filter the capsules in a Condition or to aggregate the data in Histogram

Condition Filtering

Capsule properties can be displayed in the Capsule Pane by adding a column to the table.  These property columns may also be sorted in ascending or descending order.

Once capsules within a condition have properties assigned, the filter() operator may be used in Formula to create new conditions containing only a subset of the original capsules.  For example, the following syntax generates a new condition that only has the capsules where the Value property is equal to OFF.

$condition.filter($capsule->
     $capsule.getProperty('Value').isEqualTo('OFF'))

Histogram

Within the Histogram tool, users can select Condition as the aggregation type to create bins using capsule properties.

The following example creates a Histogram based upon the Value property in the toCondition() condition.  The output is a Histogram with a count of the number of capsules with a Value equal to each of the four stages of operation:

 

[Lindsey.Wilcox]

Capsule properties may also be used as column headers in Scorecard.  More information on this can be found in this post: 

 

[Lindsey.Wilcox]

Seeq Version R22.0.46 introduces the .keep() Formula operator for filtering a condition based on capsule properties.  In the original post, the following Formula was used to generate a new condition that only has capsules where the Value property is equal to OFF:

Prior to R22.0.46:

$condition.filter($capsule->
      $capsule.getProperty('Value').isEqualTo('OFF')

With Seeq Version 22.0.46, the same result is achieved using the simpler keep() function syntax:

Version R22.0.46 and later

$condition.keep('Value', isEqualTo('Stage 1'))

[Sean T]

Often when using capsule properties that have operational data, like alarm data, batch data, operator input comments, etc. Capsule properties are read in with multiple lines. In Seeq, we can easily leverage the capsule property and the keep function that Lindsey explained above to filter for specific key words and extract more exact information out of the properties!

To do this, i will need to use Regex searching to find my keywords. (To learn more about regular expressions or validate that your search is will work as expected, check out https://regex101.com/ ). 

toSignal() Property

We start with some capsule properties, in this case i have made a string signal out of my capsule properties using the $condition.toSignal('Value') function in formula, where 'Value' is the name of the capsule property of interest. I have an example of my condition with properties and my signal shown below so we can see the text I will be searching on.

When we view multi-line propeties in trend view in Seeq, it is not immediately apparent that they have multiple lines, This is done to allow them to better fit in the Capsules pane. To verify my multi-line comment, i have made a Scorecard out of the signal where we can see the multiple lines:

 

Regex Searching on Capsule Properties

When filtering capsule properties, like my commented property shown above in Seeq, we can utilize regex searching to be more exact in our search methodology. To do this, we use a regular expressing in place of our usual search strings:

$condition.keep('Value', isMatch('/.*Com.*/')

Which will keep any property that has the exact string 'Com' somewhere in the first line of the property. Any other regex search can be input in place of the '.*Com.*' string. The contains() operator can also be used in place of the isMatch() operator

To perform regex searching on multiple lines, a (?s) or (?si) needs to be tacked on to the front of the regex search. The (?s) will perform a case sensitive multi-line regex search and (?si) will allow the multi-line search to not be case sensitive. This way we can search for any specific keyword (or words) in a multi line capsule property:

$condition.keep('Value', isMatch('/(?s).*keyword.*/') or $condition.keep('Value', isMatch('/(?si).*keyword.*/')

Results in a new filtered condition that only contains capsules whose 'Value' property contains our 'keyword':

 

[Bharat Marwaha]

How can I use assigned numerical batch capsule property to multiply that numerical property with a signal from condition derived for that batch capsule.

[Emilio Conde]

Note that the below statement, $condition.keep(...) OR $condition.keep(...), will no longer maintain capsule properties as of version R57.

On 6/26/2020 at 1:46 PM, Sean T said:

$condition.keep('Value', isMatch('/(?s).*keyword.*/') or $condition.keep('Value', isMatch('/(?si).*keyword.*/')

Results in a new filtered condition that only contains capsules whose 'Value' property contains our 'keyword':

 

 

Capsule properties persisting when using an OR statement was actually unintended behavior, i.e. a bug. The behavior after R57 is now aligned with expected behavior.

An OR statement in Seeq is equivalent to the union() function. In the search documentation, you can see that it explicitly states "Capsule properties are not preserved in the output capsules“, even in versions before R57. See screenshots from R55 and R56 formula documentation demonstrating this.

 

There are many other methods available to achieve similar behavior, such as mergeProperties() or using combineWith(). See example below when using an OR vs CombineWith() in R57.

Edited November 17, 2022 by Emilio Conde