The vector calculator

The vector calculator is two operators that read the same scripts: vector.calc gives every feature new attributes computed from its others and from its geometry (the area in hectares, a class's name, a density), as QGIS's field calculator does; vector.filter keeps the features where a condition holds (the forest patches larger than 10 ha), as QGIS's Select by Expression or geopandas' query. Their language is the raster calculator's, with texts and the geometry's measures added. This page has a playground over real features, then the language, recipes and pitfalls.

Try it#

The playground computes over the 156 patches of Sibuyan Island's land use in 2011 (Philippines): each patch is a polygon of connected cells of one class, made by vector.polygonize, with these attributes:

The coordinates are in metres (UTM zone 51N), so geometry.area is in m² and geometry.x, geometry.y in metres. Switch between vector.calc and vector.filter at the top; a script of vector.calc gives its attributes with out, one of vector.filter ends with its condition.

The idea#

A vector layer is a table with a geometry in each row: one feature per row (a patch, a reserve, a road, a plot), its attributes in the columns. A script over features computes, as the raster calculator does over cells, for every feature at once: geometry.area / 10000 is the area of every patch, cover == "forest" is 1 for the forest patches and 0 for the others. So everything of the raster calculator holds, with "feature" for "cell" and "attribute" for "map": the operators, the functions, a if c else b, name[condition] = value, None, and the numbers of all the features (x.sum(), x.percentile(90)).

Three things are new:

vector.calc and vector.filter#

density = pop / geometry.area
out density
out dense = density > density.percentile(75)

area_ha = geometry.area / 10000
cover == "forest" and area_ha >= 10

Both give the features (vector) and their attributes as a table (table).

The language over features#

Attributes and inputs#

• An attribute by its name: elevation, cover. A name the features do not have is told with the attributes they have.
• feature, the number of the feature (1, 2, ...), unless an attribute has that name.
• The node's other inputs by their names: numbers and texts (cover == wanted, area_ha >= min_ha), connected to another node's output or to an input of the model; in the model file a number can also be written as it is (min_ha = 10), and a text comes from an input of the model (wanted = "$wanted", with [inputs.wanted], kind = "value", value = "forest"). Features and tables among the inputs are not read.
• An attribute that is not a valid name of the language is not reachable; rename it first (a name begins with a letter or _, and has letters, digits and _).

Texts#

A text is not a number: cover + "s", cover > 3, cover.mean() and abs(cover) are refused, each with the form to write. Texts are compared as they are written, capital letters and accents included: "Forest" is not "forest".

The geometry's measures#

They are in the units of the features' coordinates: square metres and metres in a projected system (UTM, an Albers or Lambert projection), square degrees in geographic coordinates (longitude and latitude), which mean nothing as an area. Reproject the features first (vector.reproject), or use vector.geometry with geodesic for areas in m² on the ellipsoid.

geometry alone is refused (it is read by its measures), and so is giving it a value.

Numbers of all the features#

x.sum(), x.mean(), x.sd(), x.median(), x.min(), x.max(), x.count() and x.percentile(p) are one number from every feature with a value, as over the cells of a map. They give shares (geometry.area / geometry.area.sum()), ranks of a kind (x >= x.percentile(90), the top tenth) and totals. A number given to an attribute with out is given to every feature (out total = people.sum()).

Missing values#

A feature without a value (None, an empty text) gives missing values in what is computed from it, as a missing cell does, and and or included: where cover is missing, cover == "forest" or elevation > 50 is missing, not 1. A filter leaves such features out; isnull(x) finds them and coalesce(x, y) fills them.

Recipes#

In the application, the model file and the assistant#

[[nodes]]
id = "patches"
op = "vector.read"
params = { path = "patches.gpkg" }

[[nodes]]
id = "attrs"
op = "vector.calc"
inputs = { vector = "patches.vector" }
params = { expression = """
out area_ha = geometry.area / 10000
out kind = "natural" if cover == "forest" else "farmed"
""" }

[[nodes]]
id = "large_forest"
op = "vector.filter"
inputs = { vector = "attrs.vector", min_ha = 10 }
params = { expression = 'kind == "natural" and area_ha >= min_ha' }

Common pitfalls#

• Texts in quotes. cover == forest reads an attribute or an input named forest; the text is cover == "forest".
• Capital letters and spaces count. "Forest", "forest " and "forest" are three texts. Look at the values in the table (or with cover.count() in the console) before you compare them.
• Areas in degrees. Features in longitude and latitude have areas in square degrees. Reproject them, or use vector.geometry with geodesic.
• area and geometry.area. An attribute called area is whatever the file holds (here the cells' area from vector.polygonize, equal to the geometry's); geometry.area is always measured from the geometry, after a clip or an overlay too.
• out in a filter, or none in a calculation. vector.filter takes a condition, not out; vector.calc without out needs its column.
• A missing value spreads, through and and or too: fill it with coalesce, or test it with isnull.
• round and % are not Python's for halves and negative numbers: round(2.5) is 3, -7 % 3 is -1.

Going further#

• The raster calculator: the language over maps, with stacks and neighbourhoods.
• Vector data: reading features, burning them into a grid, statistics of a map in each polygon, values at points.
• The operator reference: vector.calc, vector.filter, vector.geometry, vector.zonal, vector.polygonize, vector.spatial_join.