Skip to content

Add vector data analysis tutorial - #136

Merged
veroandreo merged 17 commits into
OSGeo:mainfrom
Valyrian-Code:add-vector-analysis-tutorial
Sep 15, 2026
Merged

veroandreo merged 17 commits into
OSGeo:mainfrom
Valyrian-Code:add-vector-analysis-tutorial

Conversation

@Valyrian-Code

Copy link
Copy Markdown
Contributor

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:

  1. Exploring features and attributes — v.info, v.db.select
  2. Selecting by attributev.extract (the 95 elementary schools)
  3. Bufferingv.buffer (a 500 m road corridor)
  4. Selecting by locationv.select (the 15 elementary schools within the corridor)
  5. Overlayv.overlay (road corridor intersected with ZIP areas)
  6. Counting per areav.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 AI review requested due to automatic review settings July 4, 2026 19:01

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

@veroandreo veroandreo left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Comment thread content/tutorials/vector_analysis/vector_analysis.qmd Outdated
Comment thread content/tutorials/vector_analysis/vector_analysis.qmd Outdated
Comment thread content/tutorials/vector_analysis/vector_analysis.qmd Outdated
Comment thread content/tutorials/vector_analysis/vector_analysis.qmd Outdated
Comment thread content/tutorials/vector_analysis/vector_analysis.qmd Outdated
Comment thread content/tutorials/vector_analysis/vector_analysis.qmd Outdated
Comment thread content/tutorials/vector_analysis/vector_analysis.qmd Outdated
Comment thread content/tutorials/vector_analysis/vector_analysis.qmd Outdated
Comment thread content/tutorials/vector_analysis/vector_analysis.qmd Outdated
Comment thread content/tutorials/vector_analysis/vector_analysis.qmd Outdated
- 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

Copy link
Copy Markdown
Contributor Author

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 veroandreo left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Comment thread content/tutorials/vector_analysis/vector_analysis.qmd Outdated
Comment thread content/tutorials/vector_analysis/vector_analysis.qmd Outdated
Comment thread content/tutorials/vector_analysis/vector_analysis.qmd Outdated
Comment thread content/tutorials/vector_analysis/vector_analysis.qmd Outdated
Comment thread content/tutorials/vector_analysis/vector_analysis.qmd Outdated
Comment thread content/tutorials/vector_analysis/vector_analysis.qmd Outdated
Comment thread content/tutorials/vector_analysis/vector_analysis.qmd
Comment thread content/tutorials/vector_analysis/vector_analysis.qmd Outdated
Valyrian-Code and others added 8 commits July 16, 2026 00:55
Co-authored-by: Veronica Andreo <veroandreo@gmail.com>
Co-authored-by: Veronica Andreo <veroandreo@gmail.com>
Co-authored-by: Veronica Andreo <veroandreo@gmail.com>
Co-authored-by: Veronica Andreo <veroandreo@gmail.com>
Co-authored-by: Veronica Andreo <veroandreo@gmail.com>
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

Copy link
Copy Markdown
Contributor Author

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.

Comment thread content/tutorials/vector_analysis/vector_analysis.qmd Outdated
Comment thread content/tutorials/vector_analysis/vector_analysis.qmd Outdated
Comment thread content/tutorials/vector_analysis/vector_analysis.qmd Outdated
Comment thread content/tutorials/vector_analysis/vector_analysis.qmd Outdated
Comment thread content/tutorials/vector_analysis/vector_analysis.qmd Outdated
- 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

Copy link
Copy Markdown
Contributor Author

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).

Comment thread content/tutorials/vector_analysis/vector_analysis.qmd Outdated
Co-authored-by: Anna Petrasova <kratochanna@gmail.com>
Comment thread content/tutorials/vector_analysis/images/buffer.webp
Raise the scale bar so the bar, label, and north arrow sit fully inside
the frame in every figure.
@Valyrian-Code

Copy link
Copy Markdown
Contributor Author

Fixed, thanks for catching it. Raised the scale bar so the bar, label, and north arrow now sit fully inside the frame in all figures.

@Valyrian-Code

Copy link
Copy Markdown
Contributor Author

Friendly ping on this one. All the review points from @veroandreo and @petrasovaa are addressed (Tools API cleanup, the two table extracts, and the scale bars fixed so nothing is cropped), and GitHub shows it mergeable with CI passing. It has been open a while, so happy to rebase on the latest main if it has gone stale. Let me know if anything else is needed to get it in.

Comment thread content/tutorials/vector_analysis/vector_analysis.qmd Outdated
Comment thread content/tutorials/vector_analysis/vector_analysis.qmd
Co-authored-by: Anna Petrasova <kratochanna@gmail.com>

@petrasovaa petrasovaa left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, sorry for the delay. Just FYI, we would like to migrate relevant tutorials to an updated dataset (https://grass.osgeo.org/sampledata/raleigh_northcarolina_usa_epsg6542.zip).The layers are different so some the choice of layers and extent will be different. But I will merge this as is.

@veroandreo
veroandreo merged commit 63da927 into OSGeo:main Sep 15, 2026
1 check passed
@Valyrian-Code
Valyrian-Code deleted the add-vector-analysis-tutorial branch September 17, 2026 04:32
@Valyrian-Code

Valyrian-Code commented Sep 17, 2026

Copy link
Copy Markdown
Contributor Author

Thanks @petrasovaa and @veroandreo for the careful reviews and for getting this in.

On the new Raleigh dataset, the layers line up well for this tutorial (schools, roads, and zipcodes all have direct analogs), so I am happy to handle the migration for the vector tutorial, and the viewshed one too if useful, whenever you have decided which tutorials are in scope.

Just point me at the timing and I will pick it up.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants