Distance between features

Calculating the distance between features (points, polygons, lines) is a common GIS task. In this tutorial I will calculate the nearest sighting of mountain lions to Minnesota in GRASS GIS. tags: GIS, spatial analysis, GeoPython

Introduction

Calculating the distance between features (points, polygons, lines) is a common GIS task. Here I will use it to calculate the nearest sighting of mountain lions to Minnesota according to the Global Biodiversity Information Facility (GBIF) database. If you want to try this out, I have downloaded the GBIF data (Gbif.Org 2021), and the state boundaries of Minnesota from the Global Administrative Areas (GADM).

The data

The data is included in this GRASS GIS database. Download it and unzip it, and open the database (how to). Go to the data tab and open the mapset puma. Double click the layer PumaGBIF to display the layer. Next, open the layers Minnesota_boundary and CONUS.

Find the nearest sightning

Add a column

To compute the distance of each puma record to the state boundary, you first need to add the column to the attribute table. The distance between the points and the boundary of Minnesota will be written to this column. Figure 1 and Figure 2 show you how to add the column using the v.db.addcolumn function.

Figure 1: Find the ‘Add columns’ function in the Database > Vector database connections menu.

Figure 2: The ’Add columns menu. Note that GRASS GIS provides the code as well; a convenient way to find out the code and relevant parameters of a function.

You can also add a column using the attribute table manager. See the note for a short explanation how to do this .

Compute the distance

Next, run v.distance function, which you can find in the Vector menu > Nearest feature (v.distance). In the From tab (see below) fill in the name of the layer with the features you want to calculate the distance from 1. You can leave the default settings for Feature type 2, select the minimum distance to nearest feature 3, and select the column to which the distances should be written 4. Note that you can upload multiple values at once. If you do, make sure to provide the respective column names to which these values need to be uploaded.

Figure 3: The v.distance menu, ‘From’ tab.

In the ‘To’ tab (see below), you fill in the name of the feature layer to which you want to calculate the distances To 5. For the other fields, keep the default values.

Figure 4: The v.distance menu, ‘To’ tab.

Find the minimum distance

The last step is to identify the distance between the nearest sighting of the mountain lion and the Minnesota border. Open the attribute table again. Next, right click on the name of the column with the distances, and select the Statistics option in the context menu. The result will tell you that the nearest GBIF record for the mountain lion is 255 km away from Minnesota.

Figure 5: Get basic statistics about the values in the dist2minnesota1 column.

Conclusion

According to the Minnesota Department of Natural Resources, there have been more than 30 confirmed sightings in Minnesota in the last 30 years (map), most likely from transient animals from the Western Dakotas (MDNR, n.d.). Clearly, these records have not found their way to the GBIF database yet, as the nearest GBIF record is from 255 km away.

Automating the task

You can also use the command line or even write a Python script. Especially if you are new, finding out the right syntax can be tricky though. The help files are pretty good, but if you are a more visually inclined persons, it might help to first run the function using the GUI, as shown above. The great thing about GRASS is that each time you run a function, you can simply copy the corresponding code using the copy button.

So for example, to carry out the steps above from the command line, you can run the two lines of code below from the command line.

# Add a new column to the point data set. 
v.db.addcolumn map=PumaGBIF columns="dist2minnesota double precision" 
v.distance from=PumaGBIF from_type=point \
           to=Minnesota_boundary upload=dist \
           column=dist2minnesota

Running the code from the command line can be a convenient and quick way to run one or more functions. However, to automate your code, you better use Python. You can run Python code in the Python tab in GRASS GUI. Alternatively, you can open the simple python editor and run the code from there. In the example below, the wrapper code is used.

import grass.script as gs
gs.run_command("v.db.addcolumn", map="PumaGBIF",
               columns="dist2minnesota double precision")
gs.run_command("v.distance", from="PumaGBIF", from_type="point", 
               to="Minnesota_boundary", upload="dist",
               column="dist2minnesota")

The v.distance fuctions has a number of other handy options, which you certainly should explore. And, if you are working with raster layers, check out the r.distance function. As a note to QGIS users. GRASS GIS functions are also available from the processing toolbox in QGIS, or via the GRASS GIS add-on. So instead of using the GRASS GIS interface, you can run this in QGIS if you like.

×

To add columns to an attribute table, open the attribute table. Make sure to select the layer first, and then hit the Show attribute table button.

Open the attribute table

Next, select the Manage tables tab 1 and fill in the name of the new column 2. Furthermore, select the right data type 3 and click the Add button 4.

Add a column to the attribute table

×

grass.script api

The grass.script package offers a wrapper code to run the same code you would run on the command line. You first need to import the package. In de code below, it is imported under the name gs. Next, you can run the functions you have seen above, using the run_command(). The general syntax is:

gs.run_command('module.name', option1=value1, option2=..., flags='flagletters')

For example, you can use the following code to print the region settings (extent, resolution) and save it under the name 'myregion'.

import grass.script as gs
gs.run_command('g.region', flags='p', save="myregion")

There are also other functions besides run_command(), including read_command(), write_command() and parse_command(). Read more about the Python interface to scripting in the manual.

References

Gbif.Org. 2021. “Occurrence Download Puma Concolor.” Darwin. The Global Biodiversity Information Facility. https://doi.org/10.15468/DL.6RTAUV.

MDNR. n.d. “Cougars in Minnesota.” Minnesota Department of Natural Resources. https://www.dnr.state.mn.us/mammals/cougar/index.html.