Add vector data analysis tutorial by Valyrian-Code · Pull Request #136 · OSGeo/grass-tutorials

Valyrian-Code · 2026-07-04T19:01:35Z

Adds a new beginner/intermediate tutorial on vector data analysis — the tutorial
set currently has no dedicated vector-focused tutorial, so this fills that gap and
covers the operations users reach for most often.

What it covers

Using the North Carolina schools_wake (points), roadsmajor (lines), and
zipcodes_wake (areas), it works through a single "school accessibility" example:

Exploring features and attributes — v.info, v.db.select
Selecting by attribute — v.extract (the 95 elementary schools)
Buffering — v.buffer (a 500 m road corridor)
Selecting by location — v.select (the 15 elementary schools within the corridor)
Overlay — v.overlay (road corridor intersected with ZIP areas)
Counting per area — v.vect.stats + a d.vect.thematic choropleth of schools per ZIP

Details

Uses the standard North Carolina sample dataset and the grass.tools API (GRASS 8.5), consistent with the recent NumPy/Landlab tutorial.
All code was run against GRASS 8.5; the figures are real outputs of the workflow, and the tutorial renders cleanly with Quarto (eval: false).
Categories: vector, beginner, intermediate, Python.
Cross-links to the Thematic Maps and Terrain/DEMs tutorials.

Feedback on scope, the choice of example, or wording is very welcome.

New beginner/intermediate tutorial covering the core vector toolkit: - exploring features and attributes (v.info, v.db.select) - selecting by attribute (v.extract) and by location (v.select) - buffering (v.buffer) and overlaying (v.overlay) layers - counting features per area (v.vect.stats) for a thematic map Worked example uses the North Carolina schools, roads, and ZIP codes, and the grass.tools API (GRASS 8.5). Categories: vector, beginner, intermediate, Python.

Copilot

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

veroandreo

The content is ok for an intro tutorial on basic vector operations. All images need to be fixed, though. Black background does not look nice and they are too big. See other suggestions below.

veroandreo · 2026-07-12T10:32:19Z

+- **select by attribute** with [v.extract](https://grass.osgeo.org/grass-stable/manuals/v.extract.html),
+- **buffer** features with [v.buffer](https://grass.osgeo.org/grass-stable/manuals/v.buffer.html),
+- **select by location** with [v.select](https://grass.osgeo.org/grass-stable/manuals/v.select.html),
+- combine layers with [v.overlay](https://grass.osgeo.org/grass-stable/manuals/v.overlay.html), and


v.overlay combines when we do the union; I would say "perform spatial operations with v.overlay", instead

veroandreo · 2026-07-12T10:35:35Z

+- combine layers with [v.overlay](https://grass.osgeo.org/grass-stable/manuals/v.overlay.html), and
+- count features per area with [v.vect.stats](https://grass.osgeo.org/grass-stable/manuals/v.vect.stats.html).
+
+![Number of schools per ZIP code area in Wake County, from few (light) to many (dark).](images/thumbnail.webp)


I'd remove this image from here as it is generated below.

veroandreo · 2026-07-12T13:30:06Z

+```
+
+```{python}
+attr_map = gj.Map(width=800)


Same comment as above regarding images. Also, consider enhancing the scale bar or placing it differently, so it does not overlap the map features.

veroandreo · 2026-07-12T13:41:15Z

+area maps with set operations. With `operator=and` we get the **intersection** — the
+part of the road corridor that falls within each ZIP code area. The output keeps the
+attributes of both inputs, so you could, for example, measure how much of each ZIP
+code is within reach of a major road.


Would be nice to actually show how to estimate how much area of each ZIP is within reach of a major road.

veroandreo · 2026-07-12T13:50:56Z

+A common summary is "how many points fall in each area?"
+[v.vect.stats](https://grass.osgeo.org/grass-stable/manuals/v.vect.stats.html) counts
+the points of one map within the areas of another and writes the result to the area
+map's attribute table. We first copy the ZIP codes with


Suggested change

map's attribute table. We first copy the ZIP codes with

map's attribute table. We first create a copy of the ZIP codes map with

veroandreo · 2026-07-12T13:52:50Z

+- **buffering** (`v.buffer`) and **overlaying** (`v.overlay`) layers, and
+- **counting** points per area (`v.vect.stats`) for a thematic map.
+
+These operations combine into most vector workflows. To turn results like the


Suggested change

These operations combine into most vector workflows. To turn results like the

The operations described here are common in most vector workflows. To turn results like the

veroandreo · 2026-07-12T13:55:45Z

+[Making Thematic Maps](../thematic_maps/thematic_maps.qmd). To bring raster terrain
+into the analysis, see
+[Visualizing and Modeling Terrain from DEMs in GRASS](../terrain_and_DEMs/GRASS_terrain.qmd).


Suggested change

[Making Thematic Maps](../thematic_maps/thematic_maps.qmd). To bring raster terrain

into the analysis, see

[Visualizing and Modeling Terrain from DEMs in GRASS](../terrain_and_DEMs/GRASS_terrain.qmd).

As there's no specific suggestion on how to connect this tutorial with the terrain one, I suggest to remove the sentence about raster terrain.

- regenerate figures with white background, smaller size (width 500), and a legible scale bar (white background box) - retitle to "Basic Vector Data Analysis with GRASS" - show the attribute table (v.db.select JSON -> pandas) before selecting on GLEVEL, so the selection is motivated - add an area-within-reach computation (v.to.db + grouped db.select) to the overlay section - reword the v.overlay intro bullet; move the GRASS-version callout below the setup code to avoid stacked callouts - fix the get-started link to the Python quick start - drop the unmotivated terrain cross-link; minor wording fixes

Valyrian-Code · 2026-07-12T15:09:04Z

Thanks for the thorough review, @veroandreo! I've pushed an update addressing all of it:

Images: the transparent areas were rendering as a black background — regenerated all figures composited onto white, at a smaller size (width=500), with the scale bar on a white background box so it stays legible and clear of the features.
Attribute table first: added v.db.select ... format=json read into a pandas table, so the GLEVEL selection is motivated by what's actually in the data (and it shows the handy JSON-to-table trick).
Overlay: added an area-within-reach computation (v.to.db + grouped db.select) reporting how much of each ZIP code lies within 500 m of a major road.
Retitled to "Basic Vector Data Analysis with GRASS", reworded the v.overlay bullet, moved the GRASS-version callout below the setup code, fixed the get-started link, removed the duplicate intro image and the terrain cross-link, and applied the wording suggestions.

Let me know if you'd like any further changes!

veroandreo

Thanks @Valyrian-Code! Looks much better now, I left some other minor suggestions here and there.

Co-authored-by: Veronica Andreo <veroandreo@gmail.com>

Add the two table outputs the review asked for: the schools attribute table (pandas from v.db.select JSON) and the reach-per-ZIP result (db.select also returns JSON, so the same pandas pattern is reused).

Valyrian-Code · 2026-07-15T19:37:42Z

Thanks @veroandreo! Pushed the follow-ups:

Both tables now show an actual extract: the schools attribute table, and the reach-per-ZIP result. Good call on db.select also having JSON output, so I reused the same pandas pattern there.
Applied all the wording suggestions.

Ready for another look when you have a moment.

petrasovaa · 2026-07-16T12:20:59Z

+records = json.loads(
+    tools.v_db_select(
+        map="schools_wake",
+        columns="NAMESHORT,GLEVEL,ADDRCITY,CORECAPACI",
+        format="json",
+    ).stdout
+)["records"]


pd.DataFrame(tools.v_db_select(...)["records"]).head()

- pass the full path as a single string to gj.init - use .text instead of .stdout for printed output - read JSON results by subscripting the ToolResult directly (tools.v_db_select(...)["records"]) instead of json.loads(...stdout) - move the scale bar to the bottom-right in every figure so it no longer overlays the map

Valyrian-Code · 2026-07-16T13:46:05Z

Thanks @petrasovaa! Applied the same cleanups here:

single-string path to gj.init
.text instead of .stdout for printed output
JSON read by subscripting the ToolResult directly (tools.v_db_select(...)["records"], same for db.select) instead of json.loads(...)
scale bar moved to the bottom-right in every figure so it no longer overlays the map

I also mirrored the Tools-API changes in the viewshed PR (#135).

Co-authored-by: Anna Petrasova <kratochanna@gmail.com>

Copilot AI review requested due to automatic review settings July 4, 2026 19:01

Copilot AI reviewed Jul 4, 2026

veroandreo requested changes Jul 12, 2026

View reviewed changes

veroandreo mentioned this pull request Jul 12, 2026

Add visibility analysis tutorial (r.viewshed) #135

Open

veroandreo requested changes Jul 15, 2026

View reviewed changes

Valyrian-Code and others added 8 commits July 16, 2026 00:55

Update content/tutorials/vector_analysis/vector_analysis.qmd

4d64256

Co-authored-by: Veronica Andreo <veroandreo@gmail.com>

Update content/tutorials/vector_analysis/vector_analysis.qmd

18aa6f9

Co-authored-by: Veronica Andreo <veroandreo@gmail.com>

Merge branch 'main' into add-vector-analysis-tutorial

59b1578

Update content/tutorials/vector_analysis/vector_analysis.qmd

7e8b287

Co-authored-by: Veronica Andreo <veroandreo@gmail.com>

Update content/tutorials/vector_analysis/vector_analysis.qmd

27e0c77

Co-authored-by: Veronica Andreo <veroandreo@gmail.com>

Update content/tutorials/vector_analysis/vector_analysis.qmd

0353b80

Co-authored-by: Veronica Andreo <veroandreo@gmail.com>

Update content/tutorials/vector_analysis/vector_analysis.qmd

f490d7b

Co-authored-by: Veronica Andreo <veroandreo@gmail.com>

Show table extracts for schools and reach-per-ZIP

06c12c7

Add the two table outputs the review asked for: the schools attribute table (pandas from v.db.select JSON) and the reach-per-ZIP result (db.select also returns JSON, so the same pandas pattern is reused).

petrasovaa reviewed Jul 16, 2026

View reviewed changes

Comment thread content/tutorials/vector_analysis/vector_analysis.qmd Outdated

Update content/tutorials/vector_analysis/vector_analysis.qmd

776fd28

Co-authored-by: Anna Petrasova <kratochanna@gmail.com>

	map's attribute table. We first copy the ZIP codes with
	map's attribute table. We first create a copy of the ZIP codes map with

	These operations combine into most vector workflows. To turn results like the
	The operations described here are common in most vector workflows. To turn results like the

	[Making Thematic Maps](../thematic_maps/thematic_maps.qmd). To bring raster terrain
	into the analysis, see
	[Visualizing and Modeling Terrain from DEMs in GRASS](../terrain_and_DEMs/GRASS_terrain.qmd).

Uh oh!

Conversation

Valyrian-Code commented Jul 4, 2026

What it covers

Details

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Uh oh!

veroandreo left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Valyrian-Code commented Jul 12, 2026

Uh oh!

veroandreo left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Valyrian-Code commented Jul 15, 2026

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Valyrian-Code commented Jul 16, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants