Selecting features by attributes in Whitebox GAT

The latest released version of Whitebox GAT (3.1.3) has greatly improved feature selection capabilities, including feature selection by attributes built directly into the vector attributes table. The following post is a brief tutorial to guide you through the process of how this works.

To select features based on attributes contained with the attributes table, first be sure that the vector layer of interest is selected as the active map layer in the Layers tab. Now open the attribute table of the vector layer either by selecting the View Attribute Table icon located on the toolbar, or by selecting View Attribute Table from the Data Layers menu. Click on the Feature Selection tab (see below).

Selection by attribute

Example of selection by attribute

The first important feature of this tab pane is the Execute Code icon (green arrow) used to run a selection command. You will also notice a drop-down menu that can be used to specify the type of selection operation including the following four modes:

  • Create new selection
  • Add to current selection
  • Remove from current selection
  • Select from current selection

Each of the various modes differ in the way that the newly identified features are related to any features that are already selected. The default mode of Create new selection will simply ignore any existing selection and create a new selection set.

There is also a drop-down menu containing the names of each of the fields within the attribute table. If you select a field from the field name menu, the name will automatically be inserted into the selection script text area. The selection script text area has an auto-complete feature that allows users to press Control (Ctrl) and the space bar (or Command + space on a Mac) after having typed one or a few letters of the field name and a helpful pop-up window will appear from which you can select the correct field name. This auto-complete feature is also available to help identify all of the methods that are associated with fields containing strings (e.g. startsWith, toLowerCase, equals, contains, etc.). If the selected field is a text string or is a numeric integer value with fewer than 300 unique values within the table these values will appear listed in the ‘Unique Values’ drop-down value. Selecting a unique value will result in it being inserted into the selection script text area as well.

The operators drop-down menu provides a quick-link list to many of the commonly used operators. Importantly, the selection is based on Groovy-language scripting. Groovy is a super-set of the Java programming language and provides substantial power to the feature selection process. The common logical and comparison operators that are used in a selection script include:

  • & (logical AND operator)
  • | (logical OR operator)
  • == (equal-to comparison operator for numeric data types; for text strings use str1.equals(str2) method)
  • != (not-equal-to comparison operatorfor numeric data types; for text strings use !str1.equals(str2) method))
  • > (greater-than comparison operator)
  • >= (greater-than-equal-to comparison operator)
  • < (greater-than comparison operator)
  • <= (greater-than-equal-to comparison operator)

However, any valid Groovy code is allowable in the selection script. The selection script is typically a single line long, effectively a single command, although multiline scripts are accepted as well. Importantly, the last line of the script must evaluate to a Boolean (true or false) value. Each row in the attributes table will be evaluated and if the final line expression evaluates to ‘true‘, the corresponding feature will be selected. The values within each of the fields for a row are assigned to variables with the same name as the field (case sensitive). There is also an extra variable available within the script called ‘index‘ which is the row (feature) number. For example, the following selection script:

index < 100 

would select the first 100 features in the vector layer. More complex selections are also possible. For example,

 
NAME.startsWith("C") & POP2005 > 25000000 & LAT > 0.0

selects the features that have NAME starting with the letter U, POP2005 greater than 25,000,000 and LAT greater than 0.0. And,

CLASS.equals("agriculture") | CLASS.equals("forest")

selects all features that have an attribute CLASS value of either agriculture or forest.

After performing a selection, you will find that a filter has been applied to the attribute table such that only the selected features are displayed. The Options menu allows you to remove this filter, to copy the selected features to the clip board (they can then be pasted into a spreadsheet program as comma-separated values (CSV) text), or even save the features as a separate vector layer. The selected features will also be rendered on the map with a cyan coloured outline. That’s it. I think it’s rather straightforward and hopefully you do too. As always, best wishes and happy geoprocessing.