guide A Guide to Working with Capsule Properties

[Joe Reckamp]

Capsules can have properties or information attached to the event. By default, all capsules contain information on time context such as the capsule’s start time, end time, and duration. However, one can assign additional capsule properties based on other signals’ values during the capsules. Datasources can also bring in conditions with capsule properties already added. This guide will walk through some common workflows to visualize, add, and work with capsule properties.

How can I visualize capsule properties?

Capsule Properties can be added to the Capsules Pane in the bottom right hand corner of Seeq Workbench with the black grid icon. Any capsule properties beyond start, end, duration, and similarity that are created with the formulas that follow or come in automatically through the datasource connection can be found by clicking the “Add Column” option and selecting the desired property in the modal.

In the capsule pane, you can filter on capsule properties by clicking on the three dots next to a column.

 

In Trend View, you can Capsule Property labels inside the capsules by selecting the property from the labels modal.

In Capsule Time, the signals can be colored by Capsule Properties by turning on the coloring to rainbow or gradient. The selection for which property is performing the coloring is done by sorting by the capsule property in the Capsule Pane in the bottom right corner. Therefore, if Batch ID is sorted by as selected below, the legend shown on the chart will show the Batch ID values.

When working with Condition Table, you can add capsule properties as columns or as headers

How do I create a capsule for every (unique) value of a signal?

The Condition with Properties tool allows you take one or more step signals and turn them into a condition with a capsule per value change. The signal values will be added as properties on the capsules. For instance, if we have a BatchID and an Operation signal, we can use this tool to generate a capsule per Operation.

 

In formula this would be done using the toCondition() operator:

$batchID.toCondition('Batch ID')

Where Batch ID is the name of the resulting property on the condition.

How do I assign a capsule property?

Option 1: Assigning a constant value to all capsules within a condition

$condition.setProperty('Property Name', 'Property Value')

Note that it is important to know whether you would like the property stored as a string or numeric value. If the desired property value is a string, make sure that the ‘Property Value’ is in single quotes to represent a string like the above formula. If the desired value is numeric, you should not use the single quotes.

Option 2: Assigning a property based on another signal value during the capsule

For these operations, you can also use the setProperty operator. For example, you may want the first value of a signal within a capsule or the average value of a signal during the capsule. Below are some examples of options you have and how you would set these values to capsule properties.

$condition.setProperty('Property Name', $signal, aggregationMethod())

A full list of aggregation methods can be found under the Signal Value Statistics and Condition Value Statistics pages in the formula documentation, but common aggregation methods include:

• startValue()
• endValue()
• max()
• average()
• count()
• totalDuration()

Option 3: Moving properties between conditions (e.g. parent to child conditions)

In batch processing, there is often a parent/child relationship of conditions in an S88 (or ISA-88) tree hierarchy where the batch is made up of smaller operations, which is then made up of smaller phases. Some events databases may only set properties on particular capsules within that hierarchy, but you may want to move the properties to higher or lower levels of that hierarchy. You can accomplish this using mergeProperties() 

$conditionWithoutProperty.mergeProperties($conditionWithProperty)

 

How do I filter a condition by capsule properties?

Conditions are filtered by capsule properties using the keep() operator. Some examples of this are listed below:

Option 1: Keep exact match to property

$condition.keep('Property Name', isEqualTo('Property Value'))

Note that it is important to know whether the property is stored as a string or numeric value. If the property value is a string, make sure that the ‘Property Value’ is in single quotes to represent a string like the above formula. If the value is numeric, you should not use the single quotes.

Option 2: Keep regular expression string match

$condition.keep('Property Name', isMatch('B*'))

$condition.keep('Property Name', isNotMatch('B*'))

You can specify to keep either matches or not matches to partial string signals. In the above formulas, I’m specifying to either keep all capsules where the capsule property starts with a B or in the second equation, the ones that do not start with a B. If you need additional information on regular expressions, please see our Knowledge Base article.

Option 3: Other keep operators for numeric properties

Using the same format of Option 1 above, you can replace the isEqualTo operator with any of the following operators for comparison functions on numeric properties:

isGreaterThan	isGreaterThanOrEqualTo
isLessThan	isLessThanOrEqualTo
isBetween	isNotBetween
isNotEqualTo

 

Option 4: Keep capsules where capsule property exists

$condition.keep('Property Name', isValid())

In this case, any capsules that have a value for the property specified will be retained, but all capsules without a value for the specified property will be removed from the condition.

How do I turn a capsule property into a signal?

A capsule property can be turned into a signal by using the toSignal() operator. The properties can be placed at either the start timestamp of the capsule (startKey), the end timestamp of the capsule (endKey), or the entire duration of the capsule (durationKey). For most use cases the default of durationKey is the most appropriate.

$condition.toSignal('Property Name') // will default to durationKey

$condition.toSignal('Property Name', startKey())

$condition.toSignal('Property Name', endKey())

Using startKey or endKey will result in a discrete signal. If you would like to turn the discrete signal into a continuous signal connecting the data points, you can do so by adding a toStep or toLinear operator at the end to either add step or linear interpolation to the signal. Inside the parentheses for the interpolation operators, you will need to add a maximum interpolation time that represent the maximum time distance between points that you would want to interpolate. For example, a desired step interpolation of capsules may look like the following formula:

$condition.toSignal('Batch ID', startKey()).toStep(40h)

How do I rename capsule properties?

Properties can be swapped to new names by using the renameProperty operator:

$condition.renameProperty('Current Property Name', 'New Property Name')

A complex example of using capsule properties:

What if you had upstream and downstream processes where the Batch ID (or other property) could link the data between an upstream and downstream capsule that do not touch and are not in a specific order? In this case, you would want to be able to search a particular range of time for a matching property value and to transfer another property between the capsules. This can be explained with the following equation:

$upstreamCondition.move(0, 7d).mergeProperties($downstreamCondition, 'Batch ID').move(0, -7d)

Let's walk through what this is doing step by step. First, it's important to start with the condition that you want to add the property to, in this case the upstream condition. Then we move the condition by a certain amount to be able to find the matching capsule value. In this case, we are moving just the end of each capsule 7 days into the future to search for a matching property value and then at the end of the formula, we move the end of the capsule back 7 days to return the capsule to its original state. After moving the capsules, we merge properties with the downstream condition, only bringing properties from overlapping downstream capsules with the same Batch ID as the upstream condition.

Using capsule properties in histogram

You can create bins using capsule properties in the histogram tool by selecting the 'Condition' aggregation type.

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:

Content Verified DEC2023

 

[Annie]

This has been very helpful!  How would i string together multiple setProperties to add in more attributes associated with the capsules?    For example:  

$o2.removeLongerThan(40h).setProperty('OpeName', $o, startvalue())

I want to repeat this process on the same capsule for "Batch".

thanks!

[Joe Reckamp]

Hi Annie,

You can simply string the setProperty operator along to add multiple properties:

$o2.removeLongerThan(40h).setProperty('OpeName', $o, startvalue()).setProperty('Batch', $b, startvalue())

 

[Annie]

Great!  That worked!