grass.jupyter layouts and plotting API

[cwhite911]

Here are some quick ideas for GRASS jupyter API integration with Matplotlib for GSoC 2025. The point of this is to show examples of how things could work.

This is not a fully worked out implementation/design.

Please share your thoughts and examples.

Example 1

Here is an example of creating a plot of mean flood depth overtime from a workshop.

Get the data

flood_output = gs.read_command("t.rast.univar", input="flooding", separator="comma")
df_flood = pd.read_csv(io.StringIO(flood_output), sep=",")
df_flood.head()

Create the figure with matplotlib

ax = df_flood.plot(x="start", y="mean", title="Mean flooding depth over time", label="Mean")
df_flood.plot(x="start", y="min", ax=ax, style='--', label="Min", color='gray')
df_flood.plot(x="start", y="max", ax=ax, style='--', label="Max", color='gray')
ax.fill_between(df_flood["start"], df_flood["min"], df_flood["max"], color='gray', alpha=0.3)
plt.ylabel("Flooding depth (m)")
plt.xlabel("Time (minutes)")
plt.show()

Proposed simplification

gj_plot = gj.Plot('flooding') 
gj_plot.line(x="start", y="mean", title="Mean flooding depth over time", label="Mean")
gj_plot.line(x="start", y="min", ax=ax, style='--', label="Min", color='gray')
gj_plot.line(x="start", y="max", ax=ax, style='--', label="Max", color='gray')
gj_plot.fill_between(df_flood["start"], df_flood["min"], df_flood["max"], color='gray', alpha=0.3)
gj_plot.ylabel("Flooding depth (m)")
gj_plot.xlabel("Time (minutes)")
gj_plot.show()

Example 2

Here is an example of a more complex layout from a webinar.

Overland flow depth map

m = gj.Map()
m.d_shade(color="depth.10", shade="hillshade")
m.d_legend(raster="depth.10", at=(5, 9, 50, 90), flags="bd", unit="m")
m.d_barscale(at=(5, 7), flags="n")
m.show()

Create a map for each output map and place the sample point

depth_json = gs.parse_command("t.rast.list", input="depth_sum", format="json")

for i in depth_json['data']:
    map_name = i['name']
    file_name = f"outputs/depth_{map_name.split('.')[-1]}.png"
    print(f"Creating {file_name}")
    i['thumbnail'] = file_name
    depth_map = gj.Map(filename=file_name, use_region=True)
    depth_map.d_shade(color=map_name, shade="hillshade")
    depth_map.d_vect(map="depth_sum_sample", color="red", fill_color="red", type="point", size=12, icon="basic/point")
    depth_map.d_legend(raster=map_name, at=(5, 9, 50, 90), flags="bd", unit="m")
    depth_map.d_barscale(at=(5, 7), flags="n")
    depth_map.show()

Create composite RGB map

image_map = gj.Map(filename="outputs/naip_2022_rgb.png", use_region=True)
image_map.d_shade(color="naip_2022_rgb", shade="hillshade")
image_map.d_grid(siz=100, color="black", flags="a")
image_map.d_vect(map="depth_sum_sample", color="red", fill_color="red", type="point", size=12, icon="basic/point")
image_map.d_barscale(at=(5, 7), flags="n")
image_map.show()

Create line graph of flow depth at a point at simulation output intervals.

gs.parse_command('v.what.strds', input='sample', strds='depth_sum', output="depth_sum_sample")
sample_json = gs.parse_command('v.db.select', map="depth_sum_sample", format="json")

# This is ugly and need to be improved
records = sample_json['records'][0]
del records['cat']
sample_df = pd.DataFrame([records])
transposed = sample_df.T
transposed.columns = ['depth']
sequence = [2, 4, 6, 8, 10]
transposed['time'] = sequence
transposed.set_index('time', inplace=True)

# Create a seaborn line plot
import matplotlib.pyplot as plt
transposed.dropna(inplace=True)

plt.figure(figsize=(10, 6))
transposed.plot(kind='line', y='depth', color='blue', marker='o', linestyle='-', linewidth=2)

# Add titles and labels
plt.title('Sample Depth vs. Time')
plt.xlabel('Time (minutes)')
plt.ylabel('Depth (m)')


# Save the plot as an image file
plt.savefig('outputs/line_plot.png')

# Show the plot
plt.show()

Create complex layout

import matplotlib.pyplot as plt
import matplotlib.gridspec as gridspec
from PIL import Image

# Create a figure
fig = plt.figure(figsize=(15, 10))
fig.suptitle('Chaco Canyon 2016 - Overland Flow Simulation', fontsize=24, fontweight='bold')
# Create a GridSpec with 2 rows and 6 columns, making the bottom row larger
grid = gridspec.GridSpec(2, 6, height_ratios=[2, 1])

# Add an image to the left of the plot on the top row
ax_left = fig.add_subplot(grid[0, 1:3])
ax_left.set_title('NAIP 2022', {"fontsize": 18, "fontweight": "bold"})
img_left = Image.open(image_map.filename)
ax_left.imshow(img_left)
ax_left.axis("off")

# Add a larger line graph on the top row spanning the remaining columns
ax_large = fig.add_subplot(grid[0, 3:])
img_large = Image.open("outputs/line_plot.png")
ax_large.imshow(img_large)
# ax_large.set_title('Depth vs. Time', {"fontsize": 18, "fontweight": "bold"})
ax_large.axis("off")

ax = fig.add_subplot(grid[1, 3:4])
ax.set_title(f"Depth Maps", {"fontsize": 16, "fontweight": "bold"})
ax.axis("off")
# Add 5 subplots on the bottom row
for idx, item in enumerate(depth_json['data']):
    ax = fig.add_subplot(grid[1, idx+1])
    map_name = item['name']
    time_stamp = map_name.split('.')[-1]
    img = Image.open(item['thumbnail'])  # Open the image file
    ax.imshow(img)
    ax.set_title(f"{time_stamp} minutes", {"fontsize": 16, "fontweight": "bold"})
    ax.axis("off")

# Adjust layout
plt.tight_layout()

# Show the plot
plt.show()

Proposed simplification

# Create the ortho map
image_map = gj.Map(filename="outputs/naip_2022_rgb.png", use_region=True)
image_map.d_shade(color="naip_2022_rgb", shade="hillshade")
image_map.d_grid(siz=100, color="black", flags="a")
image_map.d_vect(map="depth_sum_sample", color="red", fill_color="red", type="point", size=12, icon="basic/point")
image_map.d_barscale(at=(5, 7), flags="n")
image_map.show()

# Create the plot
gj_plot = gj.Plot('depth_sum', 'sample') 
gj_plot.line(x="time", y='depth')

# Create a layout add first row
layout = gj.Layout(figsize=(15, 10))
layout.add_fig(image_map, row=1)
layout.add_fig(gj_plot, row=1)

# Create a map template
depth_map_template = gj.Map(template=True,  use_region=True)
depth_map_template.d_shade(color=${stdrs_map}, shade="hillshade")
depth_map_template.d_vect(map="sample", color="red", fill_color="red", type="point", size=12, icon="basic/point")
depth_map_template.d_legend(raster=map_name, at=(5, 9, 50, 90), flags="bd", unit="m")
depth_map_template.d_barscale(at=(5, 7), flags="n")

# Add maps to second row
layout.add_stdrs_row('depth_sum', depth_map_template, row=2)
layout.show()

[cwhite911]

I'm reopening this discussion outside of the scope of GSoC 2025 (@petrasovaa) so we can continue to discuss how to improve the grass.jupyter API to include layouts and plotting.