QueryString

class nimble.match.QueryString

A callable object for filtering in Nimble data objects.

Query strings are used when an object method iterates through the elements, points, or features of the object as a quick method to define a boolean function. Since queries can be elementwise or operate over points and features, the strings will differ slightly, but all follow the same rules. All queries require an operator. Valid operators are:

==  equal to
!=  not equal to
>=  greater than or equal to
>   greater than
<=  less than or equal to
<   less than
is  special value

For the “is” operator, the following value can be a function name from the nimble.match module (i.e. missing, negative, zero, etc.) or “True”, “False”, or “None”.

For an elementwise query string, only an operator and value are required. The “is” operator must be separated from the value by a single space, but the space is optional for the other operators. For example:

"==3"         elements equal to 3
"> 10"        elements greater than 10
"is missing"  elements that are missing values

For a points or features query, the point or feature name must be included prior to the operator. The operator must be separated from the name and the value by single space characters. For example:

"pt3 <= 1"     elements in pt3 that are less than or equal to 1
"ft1 == True"  elements in ft1 that are equal to the string "True"
"ft2 is False" elements in ft2 that are the python False object

The Examples below show how query strings interact with Nimble data object methods.

Note: Query strings do not work for every situation or sometimes cannot be parsed because another part of the string also contains an operator. All methods that accept query strings also accept a custom function that can handle more complex cases.

Parameters:

• string (str) – The string to parse. See above for string requirements.

• elementQuery (bool, None) – When set to True, identifies that the query is intended to be elementwise. When set to False, identifies that the query is specific to a point or feature. This can help eliminate ambiguity if the string contains multiple operators.

Examples

>>> lst = [[0, True, -1.0],
...        [-1, True, 2.0],
...        [2, True, -1.0],
...        [-1, False, 3.0]]
>>> fnames = ['ft1', 'ft2', 'ft3']
>>> toQuery = nimble.data(lst, featureNames=fnames)
>>> missing = toQuery.matchingElements("is nonZero")
>>> missing
<DataFrame 4pt x 3ft
      ft1    ft2   ft3
   ┌───────────────────
 0 │ False   True  True
 1 │  True   True  True
 2 │  True   True  True
 3 │  True  False  True
>
>>> toQuery.points.delete('ft3 == -1')
>>> toQuery
<DataFrame 2pt x 3ft
     ft1   ft2    ft3
   ┌──────────────────
 0 │  -1   True  2.000
 1 │  -1  False  3.000
>