Skip to content

Add vector data analysis tutorial#136

Open
Valyrian-Code wants to merge 14 commits into
OSGeo:mainfrom
Valyrian-Code:add-vector-analysis-tutorial
Open

Add vector data analysis tutorial#136
Valyrian-Code wants to merge 14 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>

@veroandreo veroandreo Jul 17, 2026

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.

All scale bars are cropped in the lower border now. Fix all of them.

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.

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