guide Selecting Capsules within a Condition

[John Cox]

In some cases you may want to do a calculation (such as an average) for a specific capsule within a condition. In Seeq Formula, the toGroup() function can be used to get a group of capsules from a condition (over a user-specified time period). The pick() function can then be used to select a specific capsule from the group. The Formula example below illustrates calculating an average temperature for a specific capsule in a high temperature condition. 

// Calculate the average temperature during a user selected capsule of a high temperature
// condition. (The high temperature condition ($HighT) was created using the Value Search tool.)
//
// To prevent an unbounded search for the capsules, must define the search start/end to use in toGroup().
// Here, $capsule simply defines a search time period and does not refer to any specific capsules in the $HighT condition.
$capsule = capsule('2019-06-19T09:00Z','2019-07-07T12:00Z')
 
// Pick the 3rd capsule of the $HighT condition during the $capsule time period.
// We must specify capsule boundary behavior (Intersect, EnclosedBy, etc.) to 
// define which $HighTcapsules are used and what their boundaries are (see 
// CapsuleBoundary documentation within the Formula tool for more information). 
$SelectedCapsule = $HighT.toGroup($capsule,CapsuleBoundary.EnclosedBy).pick(3)
 
// Calculate the temperature average during the selected capsule.
$Temperature.average($SelectedCapsule)

The above example shows how to select and perform analysis on one specific capsule in a given time range. If instead you wanted to select a certain capsule of one condition within the capsule of a second condition, you can use the .transform() function. In this example, the user want to pick the first capsule from condition 2 within condition 1.

Use formula tool:

$condition1
.removeLongerThan(1d)
.transform($c -> 
           $condition2.removeLongerThan(1d).toGroup($c).pick(1))

The output:

 

Content Verified DEC2023

Edited December 1, 2023 by Mark Pietryka
Consolidating Information for tips & tricks post

[Wouter]

The above examples were helpful to select the capsule of A when there are multiple A capsules intersecting with B:

A + first B after A:

$md = 10d
$a.join($b, $md, false)

A when first B starts before end of A:

$nodata = '2000-01-01T00:00:00Z'
$bafa.removeLongerThan($md).transform($capsule ->
    $a.removeLongerThan($md).toGroup($capsule, CAPSULEBOUNDARY.INTERSECT)
        .pick(1,  // if there are multiple capsules, grab the first
              capsule($nodata, $nodata))  // otherwise a default capsule
)

B could be offline samples of the A process.

@John Cox suppose B has properties. How can they be added to (other properties of) A when first B starts before end of A ?

Edited November 30, 2022 by Wouter
Add question

[John Cox]

Depending on the details of the use case, adding properties from one condition to another (during a join or some type of combination of the 2 conditions) can be achieved with at least 2 approaches:

1. The mergeProperties() Formula function, introduced in Seeq R56 can be used. You can look up example uses of mergeProperties() in Seeq Formula's documentation. Also note that mergeProperties() has functionality for quantitatively merging numerical property values (max, average, etc.) if the 2 conditions have conflicting values for the same property. 
2. The setProperty() Formula function can be used to add property values from one condition to another. It may be necessary to use getProperty() in conjunction with setProperty(): please see the highlighted sections in the screenshot below, which is included here only to show an example of using setProperty() inside of a transform(). Another alternative with setProperty(): you may also consider converting a property value (to be retained from the second condition) to a signal with $condition.toSignal(propertyName), and then use the signal result with setProperty(). You can see examples of adding a signal aggregation as a capsule property in Seeq's Formula documentation for setProperty().

I think one of these approaches should help with your use case.