close

Function Repository Resource:

BoolEval

Source Notebook

Fast vectorized evaluation of array inequalities

Contributed by: Szabolcs Horvát

ResourceFunction["BoolEval"][array>value]

replaces elements of array which are greater than value with 1 and the rest with 0.

ResourceFunction["BoolEval"][condition]

takes a condition expressed in terms of >,,<,,, and logical operators, and evaluates it for each element of the arrays appearing in the condition, returning a Boolean array of 1s and 0s.

Details and Options

ResourceFunction["BoolEval"] is intended for use with numerical arrays.
The arrays appearing in the conditions must have compatible sizes.
ResourceFunction["BoolEval"] has attribute HoldAll, and only processes operators that appear literally in the input.
The primary purpose of ResourceFunction["BoolEval"] is to achieve maximum performance, therefore it does not check its input for correctness. This is left to the programmer.
Effectively, ResourceFunction["BoolEval"][x>a] is equivalent to Boole@Thread[x>a].
Internally, ResourceFunction["BoolEval"] converts inequalities to expressions in terms of UnitStep and logical operators to arithmetic ones.
The BoolEval package contains the same function (BoolEval) as well as related utilities and documentation.

Examples

Basic Examples (2) 

Identify elements of an array that are larger than 5:

In[1]:=
ResourceFunction["BoolEval"][Range[10] > 5]
Out[1]=
Image

Identify elements that are greater than or equal to 3 but less than 7:

In[2]:=
ResourceFunction["BoolEval"][3 <= Range[10] < 7]
Out[3]=
Image

Scope (5) 

Higher dimensional arrays are supported:

In[4]:=
ResourceFunction["BoolEval"][( {
    {1, 2},
    {3, 4}
   } ) != 3]
Out[4]=
Image

Compare each row of a matrix with a different constant:

In[5]:=
ResourceFunction["BoolEval"][{{1, 2}, {3, 4}} <= {2, 3}]
Out[1]=
Image

Compare two arrays:

In[6]:=
ResourceFunction["BoolEval"][Range[5] == Range[5, 1, -1]]
Out[6]=
Image

BoolEval supports any expression that works with arithmetic and basic numerical operations:

In[7]:=
ResourceFunction["BoolEval"][<|"a" -> 10, "b" -> 3|> < 5]
Out[7]=
Image

BoolEval works with images:

In[8]:=
(* Evaluate this cell to get the example input *) CloudGet["https://www.wolframcloud.com/obj/cfbccf45-4474-44ec-b78c-032a54519709"]
Out[8]=
Image

Applications (3) 

Count the number of array elements that are greater than 0.3:

In[9]:=
array = RandomReal[1, 100];
Total@ResourceFunction["BoolEval"][array > 0.3]
Out[10]=
Image

Pick non-positive elements of an array:

In[11]:=
array = RandomVariate[NormalDistribution[], 10];
Pick[array, ResourceFunction["BoolEval"][array <= 0], 1]
Out[12]=
Image

Process an array much faster than it would be possible using Select or Cases:

In[13]:=
array = RandomReal[1, 1000000];
result1 = Pick[array, ResourceFunction["BoolEval"][array > 0.5], 1]; // RepeatedTiming
Out[4]=
Image
In[14]:=
result2 = Select[array, # > 0.5 &]; // RepeatedTiming
Out[14]=
Image
In[15]:=
result3 = Cases[array, x_ /; x > 0.5]; // RepeatedTiming
Out[15]=
Image
In[16]:=
result1 === result2 === result3
Out[16]=
Image

Properties and Relations (3) 

BoolEval effectively threads comparisons over arrays, then converts truth values to 0 or 1:

In[17]:=
ResourceFunction["BoolEval"][Range[5] < 3]
Out[17]=
Image
In[18]:=
Boole[Thread[Range[5] < 3]]
Out[18]=
Image

Literal truth values are also converted to 0s and 1s:

In[19]:=
ResourceFunction["BoolEval"][{True, False}]
Out[19]=
Image

Passing symbolic input to BoolEval reveals how it translates inequalities to UnitStep and logical operators to arithmetic ones:

In[20]:=
ResourceFunction["BoolEval"][a <= 3]
Out[20]=
Image
In[21]:=
ResourceFunction["BoolEval"][a > 3]
Out[21]=
Image
In[22]:=
ResourceFunction["BoolEval"][a && b && ! c]
Out[22]=
Image

Possible Issues (4) 

Only those operators are processed which appear literally in the argument of BoolEval:

In[23]:=
f[arr_] := arr > 3
ResourceFunction["BoolEval"][f[Range[5]]]
Out[24]=
Image
In[25]:=
ResourceFunction["BoolEval"][Range[5] > 3]
Out[25]=
Image

Evaluate the argument explicitly using the Evaluate function to allow BoolEval to see the operators:

In[26]:=
f[arr_] := arr > 3
ResourceFunction["BoolEval"][f[Range[5]] // Evaluate]
Out[27]=
Image

BoolEval is optimized for performance, and does not check its arguments for correctness:

In[28]:=
ResourceFunction["BoolEval"][{1, 2, 3} < {2, 3}]
Image
Out[28]=
Image

The arrays in the argument must be numeric:

In[29]:=
ResourceFunction["BoolEval"][{"a", "b", "c"} < "b"]
Out[29]=
Image

Neat Examples (1) 

Estimate the value of π using Monte Carlo integration:

In[30]:=
With[{n = 1000000},
 4 N@Total@ResourceFunction["BoolEval"][
      Total[RandomReal[{-1, 1}, {2, n}]^2] < 1
      ]/n
 ]
Out[30]=
Image

Publisher

Szabolcs Horvat

Version History

  • 1.0.0 – 31 July 2019

Author Notes

This resource function serves as a preview to the BoolEval package, and implements the package’s core functionality. The package contains additional utility functions, additional documentation, a tutorial and it is compatible Mathematica version 10.0 or later.

License Information