Skip to content

doc: Migrate notebooks to grass.tools API #7360

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
wenzeslaus merged 7 commits into from
May 8, 2026
Merged

doc: Migrate notebooks to grass.tools API #7360

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
aacc852
doc: Migrate notebooks to grass.tools API
wenzeslaus May 2, 2026
cf40daa
Set, but don't always read computational region, update intros
wenzeslaus May 6, 2026
d409976
Use JSON to get zones (much simpler)
wenzeslaus May 6, 2026
191ddda
Remove old code
wenzeslaus May 6, 2026
dcfd7b5
Indent and unicode by reviewdog
wenzeslaus May 6, 2026
428056b
Removed unnecessary imports
wenzeslaus May 6, 2026
02814ee
Fix wrong project name
wenzeslaus May 6, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
74 changes: 28 additions & 46 deletions doc/examples/notebooks/hydrology.ipynb
View file
Open in desktop
Comment thread
wenzeslaus marked this conversation as resolved.
Comment thread
wenzeslaus marked this conversation as resolved.
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@
"source": [
"# Hydrology with GRASS\n",
"\n",
"This is a short introduction to common hydrologic workflows in *GRASS* in *Jupyter Notebook*. In addition to common *Python* packages, it demonstrates the usage of `grass.script`, the *Python* API for GRASS, and `grass.jupyter`, an experimental *Jupyter Notebook* specific package that helps with the launch of *GRASS* and with displaying maps.\n",
"This is a short introduction to common hydrologic workflows in *GRASS* in *Jupyter Notebook*. In addition to common *Python* packages, it demonstrates the usage of `grass.tools`, the *Python* API for GRASS, and `grass.jupyter`, a *Jupyter Notebook* specific package that helps with the launch of *GRASS* and with displaying maps.\n",
"\n",
"This interactive notebook is available online thanks to the [https://mybinder.org](Binder) service. To run the select part (called a *cell*), hit `Shift + Enter`.\n"
]
Expand All @@ -27,25 +27,24 @@
"# Import Python standard library and IPython packages we need.\n",
"import subprocess\n",
"import sys\n",
"import csv\n",
"import numpy as np\n",
"import matplotlib.pyplot as plt\n",
"from collections import defaultdict\n",
"\n",
"# Ask GRASS where its Python packages are.\n",
"sys.path.append(\n",
" subprocess.check_output([\"grass\", \"--config\", \"python_path\"], text=True).strip()\n",
")\n",
"\n",
"# Import the GRASS packages we need.\n",
"import grass.script as gs\n",
"import grass.jupyter as gj\n",
"from grass.tools import Tools\n",
"\n",
"# Start GRASS Session\n",
"session = gj.init(\"~/data/nc_basic_spm_grass7/user1\")\n",
"tools = Tools(session=session)\n",
"\n",
"# Set computational region to elevation raster\n",
"gs.run_command(\"g.region\", raster=\"elevation\", flags=\"pg\")"
"tools.g_region(raster=\"elevation\")"
]
},
{
Expand Down Expand Up @@ -91,29 +90,26 @@
"metadata": {},
"outputs": [],
"source": [
"gs.run_command(\n",
" \"r.fill.dir\",\n",
"tools.r_fill_dir(\n",
" input=\"elevation\",\n",
" output=\"elev_fill1\",\n",
" direction=\"dir1\",\n",
" areas=\"area1\",\n",
")\n",
"gs.run_command(\n",
" \"r.fill.dir\",\n",
"tools.r_fill_dir(\n",
" input=\"elev_fill1\",\n",
" output=\"elev_fill2\",\n",
" direction=\"dir2\",\n",
" areas=\"area2\",\n",
")\n",
"gs.run_command(\n",
" \"r.fill.dir\",\n",
"tools.r_fill_dir(\n",
" input=\"elev_fill2\",\n",
" output=\"elev_fill3\",\n",
" direction=\"dir3\",\n",
" areas=\"area3\",\n",
")\n",
"gs.mapcalc(\"depr_bin = if((elevation-elev_fill3) < 0., 1, null())\")\n",
"gs.run_command(\"r.colors\", map=\"depr_bin\", color=\"blues\")"
"tools.r_mapcalc(expression=\"depr_bin = if((elevation-elev_fill3) < 0., 1, null())\")\n",
"tools.r_colors(map=\"depr_bin\", color=\"blues\")"
]
},
{
Expand All @@ -127,7 +123,6 @@
"# Display the depressions with InteractiveMap to see how they compare to existing waterbodies\n",
"depr_map = gj.InteractiveMap()\n",
"depr_map.add_raster(\"depr_bin\")\n",
"depr_map.add_layer_control()\n",
"depr_map.show()"
]
},
Expand All @@ -148,8 +143,7 @@
"metadata": {},
"outputs": [],
"source": [
"gs.run_command(\n",
" \"r.watershed\",\n",
"tools.r_watershed(\n",
" elevation=\"elevation@PERMANENT\",\n",
" drainage=\"drainage\", # Drainage Direction\n",
" accumulation=\"flowacc\", # Flow Accumulation\n",
Expand All @@ -159,7 +153,7 @@
")\n",
"\n",
"# Convert streams raster to vector\n",
"gs.run_command(\"r.to.vect\", input=\"streams\", output=\"streams\", type=\"line\")"
"tools.r_to_vect(input=\"streams\", output=\"streams\", type=\"line\")"
]
},
{
Expand All @@ -183,7 +177,7 @@
"# Note that if the raster is located in a different mapset (for example,\n",
"# elevation is in PERMANENT, not user1), the `r.colors` will not change\n",
"# the color in InteractiveMap.\n",
"gs.run_command(\"r.colors\", map=\"drainage\", color=\"aspect\")\n",
"tools.r_colors(map=\"drainage\", color=\"aspect\")\n",
"\n",
"# Add elements to map\n",
"# We set opacity to 1.0 (default is 0.8) so layers won't interfere with each other.\n",
Expand All @@ -193,7 +187,6 @@
"hydro_map.add_raster(\"watersheds\", opacity=1.0)\n",
"hydro_map.add_vector(\"streams\")\n",
"\n",
"hydro_map.add_layer_control()\n",
"\n",
"hydro_map.show()"
]
Expand All @@ -214,22 +207,25 @@
"outputs": [],
"source": [
"# Count cells in each watershed\n",
"gs.run_command(\n",
" \"r.stats.zonal\",\n",
"tools.r_stats_zonal(\n",
" base=\"watersheds\",\n",
" cover=\"elevation\",\n",
" method=\"count\",\n",
" output=\"watersheds_count\",\n",
")\n",
"\n",
"# Get projection resolution\n",
"proj = gs.parse_command(\"g.region\", flags=\"m\")\n",
"# Get resolution\n",
"region = tools.g_region(flags=\"m\", format=\"json\")\n",
"\n",
"# Multiply N-S resollution by E-W resolution to get cell area\n",
"cell_area = float(proj[\"nsres\"]) * float(proj[\"ewres\"])\n",
"cell_area = region[\"nsres\"] * region[\"ewres\"]\n",
"\n",
"# Calculate watersheds areas and convert from m2 to km2\n",
"gs.mapcalc(\"'watershed_area' = float('watersheds_count'*{})/1000000\".format(cell_area))"
"tools.r_mapcalc(\n",
" expression=\"'watershed_area' = float('watersheds_count'*{})/1000000\".format(\n",
" cell_area\n",
" )\n",
")"
]
},
{
Expand All @@ -246,7 +242,7 @@
"outputs": [],
"source": [
"# Display a map of watershed areas.\n",
"gs.run_command(\"r.colors\", map=\"watershed_area\", color=\"plasma\")\n",
"tools.r_colors(map=\"watershed_area\", color=\"plasma\")\n",
"\n",
"watershed_map = gj.Map()\n",
"watershed_map.d_rast(map=\"watershed_area\")\n",
Expand Down Expand Up @@ -282,7 +278,7 @@
"outputs": [],
"source": [
"# Compute Slope\n",
"gs.run_command(\"r.slope.aspect\", elevation=\"elevation\", slope=\"slope\")"
"tools.r_slope_aspect(elevation=\"elevation\", slope=\"slope\")"
]
},
{
Expand Down Expand Up @@ -318,22 +314,10 @@
"metadata": {},
"outputs": [],
"source": [
"separator = \"|\"\n",
"\n",
"columns = defaultdict(list) # each value in each column is appended to a list\n",
"\n",
"text = gs.read_command(\n",
Comment thread
wenzeslaus marked this conversation as resolved.
" \"r.univar\", map=\"elevation\", zones=\"watersheds\", separator=separator, flags=\"t\"\n",
")\n",
"reader = csv.DictReader(text.splitlines(), delimiter=separator)\n",
"for row in reader: # read a row as {column1: value1, column2: value2,...}\n",
" for k, v in row.items(): # go over each column name and value\n",
" columns[k].append(v) # append the value into the appropriate list\n",
" # based on column name k\n",
"\n",
"watersheds = columns[\"zone\"]\n",
"means = np.array(columns[\"mean\"], dtype=np.float32)\n",
"stddevs = np.array(columns[\"stddev\"], dtype=np.float32)"
"univar = tools.r_univar(map=\"elevation\", zones=\"watersheds\", format=\"json\")\n",
"watersheds = [zone[\"zone\"] for zone in univar]\n",
"means = [zone[\"mean\"] for zone in univar]\n",
"stddevs = [zone[\"stddev\"] for zone in univar]"
]
},
{
Expand Down Expand Up @@ -371,9 +355,7 @@
"outputs": [],
"source": [
"# Convert to vector\n",
"gs.run_command(\n",
" \"r.to.vect\", flags=\"s\", input=\"watersheds\", output=\"watersheds_vector\", type=\"area\"\n",
")"
"tools.r_to_vect(flags=\"s\", input=\"watersheds\", output=\"watersheds_vector\", type=\"area\")"
]
},
{
Expand Down
19 changes: 9 additions & 10 deletions doc/examples/notebooks/jupyter_example.ipynb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -37,11 +37,12 @@
")\n",
"\n",
"# Import the GRASS packages we need.\n",
"import grass.script as gs\n",
"import grass.jupyter as gj\n",
"from grass.tools import Tools\n",
"\n",
"# Start GRASS Session\n",
"session = gj.init(\"~/data/nc_basic_spm_grass7/user1\")"
"session = gj.init(\"~/data/nc_basic_spm_grass7/user1\")\n",
"tools = Tools(session=session)"
]
},
{
Expand All @@ -60,10 +61,8 @@
"metadata": {},
"outputs": [],
"source": [
"gs.parse_command(\"g.region\", raster=\"lakes\", flags=\"pg\")\n",
"gs.run_command(\n",
" \"r.buffer\", input=\"lakes\", output=\"lakes_buff\", distances=[60, 120, 240, 500]\n",
")\n",
"tools.g_region(raster=\"lakes\", flags=\"pg\")\n",
"tools.r_buffer(input=\"lakes\", output=\"lakes_buff\", distances=[60, 120, 240, 500])\n",
"\n",
"# Start a Map\n",
"r_buffer_map = gj.Map()\n",
Expand Down Expand Up @@ -93,8 +92,8 @@
"metadata": {},
"outputs": [],
"source": [
"gs.run_command(\"v.buffer\", input=\"boundary_state\", output=\"buffer\", distance=-10000)\n",
"gs.parse_command(\"g.region\", vector=\"boundary_state\", flags=\"pg\")\n",
"tools.v_buffer(input=\"boundary_state\", output=\"buffer\", distance=-10000)\n",
"tools.g_region(vector=\"boundary_state\", flags=\"pg\")\n",
"\n",
"# Start another Map\n",
"v_buffer_map = gj.Map()\n",
Expand Down Expand Up @@ -134,7 +133,7 @@
"metadata": {},
"outputs": [],
"source": [
"print(gs.read_command(\"g.list\", type=\"all\"))"
"print(tools.g_list(type=\"all\").text)"
]
},
{
Expand All @@ -150,7 +149,7 @@
"metadata": {},
"outputs": [],
"source": [
"print(gs.read_command(\"g.search.modules\", flags=\"g\"))"
"print(tools.g_search_modules(flags=\"g\").text)"
]
}
],
Expand Down
11 changes: 7 additions & 4 deletions doc/examples/notebooks/jupyter_tutorial.ipynb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,14 +38,17 @@
")\n",
"\n",
"# Import GRASS packages\n",
"import grass.script as gs\n",
"import grass.jupyter as gj\n",
"from grass.tools import Tools\n",
"\n",
"# Start GRASS Session\n",
"session = gj.init(\"~/data/nc_basic_spm_grass7/user1\")\n",
"\n",
"# Create a Tools object tied to this session.\n",
"tools = Tools(session=session)\n",
"\n",
"# Set computational region to the elevation raster.\n",
"gs.run_command(\"g.region\", raster=\"elevation\")"
"tools.g_region(raster=\"elevation\")"
]
},
{
Expand Down Expand Up @@ -197,7 +200,7 @@
"metadata": {},
"outputs": [],
"source": [
"gs.run_command(\"g.region\", save=\"myregion\", n=224000, s=222000, w=633500, e=637300)\n",
"tools.g_region(save=\"myregion\", n=224000, s=222000, w=633500, e=637300)\n",
"myregion_map = gj.Map(saved_region=\"myregion\")\n",
"myregion_map.d_rast(map=\"elevation\")\n",
"myregion_map.d_rast(map=\"lakes\")\n",
Expand Down Expand Up @@ -479,7 +482,7 @@
"source": [
"series = gj.SeriesMap(height=500)\n",
"series.add_rasters([\"elevation\", \"elevation_shade\", \"slope\"])\n",
"series.add_vectors([\"streams\", \"streets\", \"lakes\"])\n",
"series.add_vectors([\"streams\", \"streets\", \"roadsmajor\"])\n",
"series.d_vect(map=\"streets\")\n",
"series.d_barscale()\n",
"series.show() # Create Slider"
Expand Down
5 changes: 3 additions & 2 deletions doc/examples/notebooks/parallelization_tutorial.ipynb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,14 +30,15 @@
")\n",
"\n",
"# Import GRASS packages\n",
"import grass.script as gs\n",
"import grass.jupyter as gj\n",
"from grass.tools import Tools\n",
"\n",
"# Start GRASS Session\n",
"session = gj.init(\"~/data/nc_basic_spm_grass7/user1\")\n",
"tools = Tools(session=session)\n",
"\n",
"# Set computational region to the elevation raster.\n",
"gs.run_command(\"g.region\", raster=\"elevation\")"
"tools.g_region(raster=\"elevation\")"
]
},
{
Expand Down
38 changes: 17 additions & 21 deletions doc/examples/notebooks/scripting_example.ipynb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,15 +38,17 @@
"\n",
"# Import the GRASS packages we need.\n",
"import grass.script as gs\n",
"from grass.tools import Tools\n",
"\n",
"# Create a GRASS session.\n",
"session = gs.setup.init(\"~/data/nc_basic_spm_grass7/user1\")\n",
"\n",
"# Create a Tools object tied to this session; overwrite=True lets us re-run cells freely.\n",
"tools = Tools(session=session, overwrite=True)\n",
"\n",
"# We want functions to raise exceptions and see standard output of the modules in the notebook.\n",
"gs.set_raise_on_error(True)\n",
"gs.set_capture_stderr(True)\n",
"# Simply overwrite existing maps like we overwrite Python variable values.\n",
"os.environ[\"GRASS_OVERWRITE\"] = \"1\"\n",
"# Enable map rendering in a notebook.\n",
"os.environ[\"GRASS_FONT\"] = \"sans\"\n",
"# Set display modules to render into a file (named map.png by default)\n",
Expand All @@ -71,13 +73,11 @@
"metadata": {},
"outputs": [],
"source": [
"gs.parse_command(\"g.region\", raster=\"lakes\", flags=\"pg\")\n",
"gs.run_command(\n",
" \"r.buffer\", input=\"lakes\", output=\"lakes_buff\", distances=[60, 120, 240, 500]\n",
")\n",
"gs.run_command(\"d.erase\")\n",
"gs.run_command(\"d.rast\", map=\"lakes_buff\")\n",
"gs.run_command(\"d.legend\", raster=\"lakes_buff\", range=(2, 5), at=(80, 100, 2, 10))\n",
"tools.g_region(raster=\"lakes\")\n",
"tools.r_buffer(input=\"lakes\", output=\"lakes_buff\", distances=[60, 120, 240, 500])\n",
"tools.d_erase()\n",
"tools.d_rast(map=\"lakes_buff\")\n",
"tools.d_legend(raster=\"lakes_buff\", range=(2, 5), at=(80, 100, 2, 10))\n",
"Image(filename=\"map.png\")"
]
},
Expand All @@ -98,17 +98,13 @@
"metadata": {},
"outputs": [],
"source": [
"gs.run_command(\"v.buffer\", input=\"boundary_state\", output=\"buffer\", distance=-10000)\n",
"gs.parse_command(\"g.region\", vector=\"boundary_state\", flags=\"pg\")\n",
"gs.run_command(\"d.erase\") # erase the display before drawing again\n",
"tools.v_buffer(input=\"boundary_state\", output=\"buffer\", distance=-10000)\n",
"tools.g_region(vector=\"boundary_state\")\n",
"tools.d_erase() # erase the display before drawing again\n",
"!rm -f $GRASS_LEGEND_FILE # and remove the legend file\n",
"gs.run_command(\n",
" \"d.vect\", map=\"boundary_state\", fill_color=\"#5A91ED\", legend_label=\"State boundary\"\n",
")\n",
"gs.run_command(\n",
" \"d.vect\", map=\"buffer\", fill_color=\"#F8766D\", legend_label=\"Inner portion\"\n",
")\n",
"gs.run_command(\"d.legend.vect\", at=(10, 35))\n",
"tools.d_vect(map=\"boundary_state\", fill_color=\"#5A91ED\", legend_label=\"State boundary\")\n",
"tools.d_vect(map=\"buffer\", fill_color=\"#F8766D\", legend_label=\"Inner portion\")\n",
"tools.d_legend_vect(at=(10, 35))\n",
"Image(filename=\"map.png\")"
]
},
Expand Down Expand Up @@ -136,7 +132,7 @@
"metadata": {},
"outputs": [],
"source": [
"print(gs.read_command(\"g.list\", type=\"all\"))"
"print(tools.g_list(type=\"all\").text)"
]
},
{
Expand All @@ -152,7 +148,7 @@
"metadata": {},
"outputs": [],
"source": [
"print(gs.read_command(\"g.search.modules\", flags=\"g\"))"
"print(tools.g_search_modules(flags=\"g\").text)"
]
},
{
Expand Down
Loading
Loading