Lookup Tables

Currently Lookup Tables are Experimental. See Experimental Functions for full details, including how to submit feedback.

Description

Lookup Tables allow you specify two columns of data and transform a scalar or a signal by substituting its value or values from one column with the value from the same row in the other column. For example, using the Lookup Table below we can transform 3m to 2m/s, or 0m/s to 10m. These transformations happen to each sample in a signal, with customizable interpolation options.

Distance	Velocity
3m	2m/s
5m	5m/s
10m	0m/s

Written in Formula this would be:

CODE

$meterSignal = ...
$table = experimental_lookupTable(
"[
  [3m, 2m/s],
  [5, 5],
  [10, 0]
]", InterpolationMethod.linear)
$table.experimental_lookup($meterSignal, 'B')

Using a lookup table has two parts.

1. Specifying the Lookup Table

The experimental_lookupTable function is used to create a lookup table. It takes two inputs.

tableDescription, a string scalar that defines the data of the table. It is a string containing a matched set of brackets [], where each row of the table is entered as a pair of brackets containing comma separated scalar values. Rows are separated by commas.
- The table can be entered on a single line or in multiple lines, whatever is easiest for the user.
- The first row defines the units of the columns. All other units must match the first row in their respective column. Units can be left off of subsequent rows and will be coerced to match.
- Strings are valid scalar inputs. They must be placed in quotes. If the entire table string is enclosed in double quotes, strings inside must be in single quotes and vice versa. The following tables would function identically.
  CODE
```
"[[3m, 'Three Meters'], [500cm, 'Five Meters']]" 
```
  A single line tableDescription with units fully specified. Uses double quotes for the entire table string, and double quotes for internal strings.
  CODE
```
'[                        
[3m, "Three Meters"],
[5, "Five Meters"]
]'
```
  A multi-line tableDescription with units in the first row. Uses single quotes for the entire table string and double quotes for internal strings.
interpolationMethod, the interpolation method used for non-exact matches of the table. The possible options are
- Linear or PILinear: linearly interpolated using the nearest keys and their values.
- Discrete: no interpolation is used. Keys that have no match in the table will return an invalid sample.
- Step: the value of the nearest smallest key will be used.
- Note that if a table contains strings it must use either Discrete or Step as an interpolation method.
- Note that no extrapolation will ever be performed (if the key is greater than or smaller than all values in the table, the returned value will be invalid).
- No interpolation will be performed if the table is not already sorted in ascending or descending order by the column with the values to be interpolated between. Instead, an error will be returned.

Scalars within the key column must be unique (the target column is allowed to have duplicate values). The key column is the one in which the provided key is being looked up.

2. Lookup a scalar using the table.

The experimental_lookup function is used to perform the lookup. It takes 3 inputs.

table: the table created in step 1.
key: the scalar being looked up. Must match the units of the opposite column to targetColumn.
targetColumn: a string specifying which column has the desired output. Either ‘A’ or ‘B’, indicating lookup in the first or second column respectively. Lookup can be performed against either column A or B (the key scalar would need to match units with the other column).

CODE

$table.experimental_lookup($keys, 'A')

The experimental_lookup function will look up the scalar’s value in the appropriate column of the table. If a match is found, the matching value in the other column will be returned. If the scalar is invalid, the function returns an invalid scalar. If the scalar value is not found in the table, but is between values in the table, it will be interpolated according to the table’s interpolation method by finding the nearest values in the sorted column.

3. Lookup a signal using the table.

The experimental_lookup function is used to perform the lookup. It takes 3 inputs.

table: the table created in step 1.
keys: the signal being looked up. Must match the units of the opposite column to targetColumn.
targetColumn: a string specifying which column has the desired output. Either ‘A’ or ‘B’, indicating lookup in the first or second column respectively. Lookup can be performed against either column A or B (the key signal would need to match units with the other column).

CODE

$table.experimental_lookup($keys, 'A')

The experimental_lookup function will check every sample in the signal against the table. For each signal sample, its value will be looked up in the appropriate column of the table. If a match is found, the matching value in the other column will be added as a sample in the return signal. If the signal sample is invalid, an invalid sample will be added to the return signal. If the signal sample value is not found in the table, but is between values in the table, it will be interpolated according to the table’s interpolation method by finding the nearest values in the sorted column.

Reusing Lookup Tables

We can define the table string in a separate Formula, and use it as a variable in future Lookup. This lets us avoid having the string copied into every formula that uses it.

Current Limitations

Scalars within the key column must be unique (key column being the one in which values are to be looked up).
String values cannot contain commas.
Only two columns are allowed.
targetColumn and tableStringmust be Locally Constant Values.
- At this time, the LookupTable itself cannot be exported as a variable for use elsewhere, only the tableString can.
It is not possible to assign particular keys an invalid value.
Extrapolation results in invalids.
Columns on which interpolation is expected must contain values already sorted in ascending or descending order (must be monotonic).