What's New in Formula

New functions

reduceUnits()

This function reduces complex units that can result from complicated computations combining non-identical units, such as m*h/s or hPa/mbar. It can also be used to breakdown alternate names, such as in 1N.reduceUnits() == 1kg*m/s^2. Units are based on our fundamental unit for a dimension which mostly derives from SI base units.

mergeProperties()

This new function takes a condition, and while preserving its capsule intervals, merges capsule properties of another condition’s capsules that overlap with the first condition’s capsules. The overlap behavior can be refined by using the optional matchProperty argument, in which case only overlapping capsules that both have the provided property with matching values, are paired together for property merge. Since capsule properties are single values, conflicts are resolved using the provided propertyRule. By default, all properties are preserved with an implicit keepProperties() rule. For this function, property value conflicts will give precedence to the original condition (whose capsule intervals are taken) and then by time sequence of the other condition.

New Capabilities

Capsule matching by property

Many functions that work with multiple conditions use time to match up capsules across the two conditions. For example, join() creates capsules that span the each capsule in a “start” condition with the next capsule in the “end” condition.

In this release, several of these functions now take an optional matchProperty parameter. When specified, only capsule that have the same value of that property will be matched. This capability is very useful for analysis of batches, when a given condition has lots of intermingled capsules that a discriminated by a batch ID.

Functions that support a matchProperty include join(), encloses(), inside(), and touches()

Behavior changes

join()

The join() function changed its behavior slightly, but only when useEarliestStart=false and there are multiple overlapping start capsules for a given end capsule. Previously, a capsule would be produced from the last start's start to the end capsule's end, without regard to when the end capsule started. Now the capsule goes from the last start before the end's start.

countOverlaps()

The countOverlaps() logic was improved and the first argument samplePeriod is no longer needed for accuracy (although it might still be useful for controlling the sample period for visualization or for chaining calculations that need a fixed sample frequency period). The main issue with the previous logic for this function is that samplePeriod had to be small enough (1 second or less) to capture the changes when they occurred, which yields a large number of samples.

This can be visualized in the graph below. The signal at the bottom counts the active compressors with the formula logic of previous versions, which defaulted to 1 second sample period and yielded 259,200 samples for a 3-day period. The signal right above it is the one produced by the new countOverlaps logic, which accurately captures the count of overlapping conditions and only produces 22 samples (a sample for each instant when there is a change in the count).