Update app.py

app.py

@@ -13,8 +13,7 @@ async def _():
     import marimo as mo
     import pandas as pd
 
-    # If running inside the browser (WebAssembly), explicitly download openpyxl first!
-    if "pyodide" in sys.modules:
+    if "pyodide" in sys.modules: # this is for running the resulting html visual in a browser (WebAssembly)
         import micropip
         await micropip.install("openpyxl")
 
@@ -23,75 +22,62 @@ async def _():
     return io, math, mo, pd
 
 
-@app.cell
-def _():
-    # TO DO:
-    # - on click: show a list of sites where that species type occurs
-    # - add axis on the seperation between species groups that shows the amount of sites the species occur in
-    # - maybe line up each species group
-    # - put the visual on a html site instead of here in the notebook
-    return
-
-
 @app.cell
 def _(mo):
-    # Create file upload buttons for the WASM environment
-    upload_yield = mo.ui.file(
-        label="Upload: Coffee_yield.xlsx", kind="button", multiple=False)
-    upload_species = mo.ui.file(
-        label="Upload: Plant_species_and_average...xlsx", kind="button", multiple=False)
-    upload_decomp = mo.ui.file(
-        label="Upload: Total_species_composition.xlsx", kind="button", multiple=False)
-
-    # Assign the layout to a variable
+    # Buttons to upload the data files required for the visualisation
+    upload_yield = mo.ui.file(label="Upload: Coffee_yield.xlsx", kind="button", multiple=False)
+    upload_species = mo.ui.file(label="Upload: Plant_species_and_average...xlsx", kind="button", multiple=False)
+    upload_decomp = mo.ui.file(label="Upload: Total_species_composition.xlsx", kind="button", multiple=False)
+
+    # Assign to variable and display the UI
     upload_ui = mo.vstack([
-        mo.md("### 📁 Please provide your data files to view the dashboard"),
+        mo.md("### Please provide the correct data files to view the visual"),
         upload_yield,
         upload_species,
         upload_decomp
     ], align="center")
     
-    # Place it as the last line so Marimo renders it to the screen!
+    # Place as the last statement to ensure Marimo renders it!
     upload_ui
-    return upload_decomp, upload_species, upload_yield, upload_ui
+    return upload_decomp, upload_species, upload_ui, upload_yield
 
 
 @app.cell
 def _(io, mo, pd, upload_decomp, upload_species, upload_yield):
-    # Pause execution of this cell (and everything below it) until files are uploaded
+    # Exectution of this cell and everything below is paused until all files are uploaded
     mo.stop(
         not upload_yield.value or not upload_species.value or not upload_decomp.value,
         mo.md("*Waiting for all three files to be uploaded...*")
     )
 
-    # Read the uploaded files directly from browser memory
+    ###### PREPARATION ######
+    # Read the uploaded files from browser memory
     df_yield = pd.read_excel(io.BytesIO(upload_yield.value[0].contents))
     df_species = pd.read_excel(io.BytesIO(upload_species.value[0].contents))
-    df_decomposition = pd.read_excel(
-        io.BytesIO(upload_decomp.value[0].contents))
+    df_decomposition = pd.read_excel(io.BytesIO(upload_decomp.value[0].contents))
 
+    # Hardcoded column names used in the data files
     COL_SPECIES_NAME = "Species name"
     COL_SPECIES_YIELD = "Average coffee yield (kg ha-1)"
     COL_SPECIES_GROUP = "Species group"
     COL_DECOMP_SPECIES = df_decomposition.columns[0]
 
-    # Forward fill empty group cells
+    # In `Plant_species_and_average_yield.xlsx`, empty group cells are filled
     df_species[COL_SPECIES_GROUP] = df_species[COL_SPECIES_GROUP].ffill()
     GROUPS = df_species[COL_SPECIES_GROUP].dropna().unique().tolist()
 
-    # Set index to species for easy row lookups
+    # In `Total_species_decomposition.xlsx`, set index to species for easy row lookups
     df_decomposition.set_index(COL_DECOMP_SPECIES, inplace=True)
     ALL_SITES = [str(col) for col in df_decomposition.columns]
 
-    # Build the species_data dictionary
+    ###### DATA EXTRACTION/PARSING ######
+    # Build the species_data dictionary >> dictionary used to build the visual later
     species_data = []
-
     for idx, row in df_species.iterrows():
         sp_id = str(row[COL_SPECIES_NAME])
         avg_yield = float(row[COL_SPECIES_YIELD])
 
-        group = str(row[COL_SPECIES_GROUP]
-                    ) if COL_SPECIES_GROUP in df_species.columns else GROUPS[idx % len(GROUPS)]
+        group = str(row[COL_SPECIES_GROUP]) if COL_SPECIES_GROUP in df_species.columns else GROUPS[idx % len(GROUPS)]
 
         present_in = []
 
@@ -104,29 +90,41 @@ def _(io, mo, pd, upload_decomp, upload_species, upload_yield):
             "id": sp_id,
             "group": group,
             "yield": avg_yield,
-            "num_sites": len(present_in),
+            "num_sites": len(present_in), 
             "sites": present_in
         })
 
-    # Sort species from most common (center) to least common (edges)
+    # Sort species from most common (center) to least common (edge)
     species_data.sort(key=lambda x: x["num_sites"], reverse=True)
     return ALL_SITES, GROUPS, species_data
 
 
 @app.cell
 def _(ALL_SITES, mo, species_data):
-    # Setup Marimo UI Controls
+    # Create UI controls
     total_species = len(species_data)
 
     slider_count = mo.ui.slider(
-        start=5, stop=total_species, step=1, value=total_species, label="Species shown:")
+        start=5, stop=total_species, step=1, value=int(total_species/2), label="Species shown:"
+    )
+
     drop_single = mo.ui.dropdown(
-        options=ALL_SITES, value=ALL_SITES[0] if ALL_SITES else "", label="Highlight Site:")
+        options=ALL_SITES, value=ALL_SITES[0] if ALL_SITES else "", label="Highlight Site:"
+    )
+
     drop_comp1 = mo.ui.dropdown(
-        options=ALL_SITES, value=ALL_SITES[0] if ALL_SITES else "", label="Compare Site 1:")
-    drop_comp2 = mo.ui.dropdown(options=ALL_SITES, value=ALL_SITES[1] if len(
-        ALL_SITES) > 1 else ALL_SITES[0], label="Compare Site 2:")
+        options=ALL_SITES, value=ALL_SITES[0] if ALL_SITES else "", label="Compare Site 1:"
+    )
 
+    drop_comp2 = mo.ui.dropdown(
+        options=ALL_SITES, value=ALL_SITES[1] if len(ALL_SITES) > 1 else ALL_SITES[0], label="Compare Site 2:"
+    )
+    return drop_comp1, drop_comp2, drop_single, slider_count
+
+
+@app.cell
+def _(drop_comp1, drop_comp2, drop_single, mo, slider_count):
+    # CSS styling
     dropdown_styles = mo.Html("""
     <style>
       .marimo-dropdown select, select {
@@ -170,57 +168,42 @@ def _(ALL_SITES, mo, species_data):
     </style>
     """)
 
+    # Group the UI elements into interactive tabs
     tabs = mo.ui.tabs({
         "General Overview": mo.md("*Viewing all species colored by their primary group.*"),
         "Individual Site": drop_single,
         "Compare Sites": mo.hstack([drop_comp1, drop_comp2], gap=4)
     })
 
+    # Build the final control panel
     controls = mo.vstack([
         dropdown_styles,
         tabs,
         mo.hstack([slider_count], justify="center")
     ], align="center", gap=4)
-    return controls, drop_comp1, drop_comp2, drop_single, slider_count, tabs
+
+    return controls, tabs
 
 
 @app.cell
-def _(
-    GROUPS,
-    controls,
-    drop_comp1,
-    drop_comp2,
-    drop_single,
-    math,
-    mo,
-    slider_count,
-    species_data,
-    tabs,
-):
-    active_data = species_data[:slider_count.value]
+def _(math):
+    # Sunburst chart: dimensions + position
     CX, CY = 500, 380
     MAX_RADIUS = 370
     MIN_RADIUS = 80
-
-    # ── Define Tooltip Dimensions Globally ──
     TW, TH = 245, 105
 
-    # ── Plant Group Color Update ──
+    # Colors 
     preferred_hues = [30, 120, 210]
-    group_hues = {
-        group_name: preferred_hues[i % len(preferred_hues)]
-        for i, group_name in enumerate(GROUPS)
-    }
-
-    # ── Site Comparison Color Updates ──
-    SITE_LEGEND_BKG = "#1e1e2e"  # Legend card background
-    SITE_LEGEND_BORDER = "#45475a"  # Legend card border
-    SITE_LEGEND_TEXT = "#cdd6f4"  # Legend text color
-    SITE_COLOR_S1_ONLY = "#f5b0c6"  # Softer Pink (Site 1 only)
-    SITE_COLOR_S2_ONLY = "#d8b4fe"  # Lighter Purple (Site 2 only)
-    SITE_COLOR_BOTH = "#f9e2af"  # Light Yellow (In both)
-    SITE_COLOR_NEITHER = "#e0e0e0"  # Light Grey (In neither)
-
+    SITE_LEGEND_BKG = "#1e1e2e"
+    SITE_LEGEND_BORDER = "#45475a"
+    SITE_LEGEND_TEXT = "#cdd6f4"
+    SITE_COLOR_S1_ONLY = "#f5b0c6"
+    SITE_COLOR_S2_ONLY = "#d8b4fe"
+    SITE_COLOR_BOTH = "#f9e2af"
+    SITE_COLOR_NEITHER = "#e0e0e0"
+
+    # Helper functions
     def polar_to_cartesian(cx, cy, r, angle_deg):
         rad = math.radians(angle_deg)
         return cx + r * math.cos(rad), cy + r * math.sin(rad)
@@ -236,10 +219,11 @@ def _(
         return f"M {p1[0]} {p1[1]} A {r_outer} {r_outer} 0 {large_arc} 1 {p2[0]} {p2[1]} L {p3[0]} {p3[1]} A {r_inner} {r_inner} 0 {large_arc} 0 {p4[0]} {p4[1]} Z"
 
     def make_tooltip(index, tx, ty, group_name, species_name, avg_yield, num_sites):
+        # Bound the tooltip coordinates so it doesn't clip off the 1000x1000 SVG canvas
         tx = max(10, min(tx, 1000 - TW - 10))
         ty = max(10, min(ty, 1000 - TH - 10))
         safe_group = group_name.strip().upper()[:40]
-        safe_name = species_name.strip()[:38]
+        safe_name  = species_name.strip()[:38]
         yield_str = f"Average yield: {avg_yield:.1f} kg ha\u207b\u00b9"
         sites_str = f"Occurs in: {num_sites} site(s)"
         return f"""
@@ -258,35 +242,94 @@ def _(
             fill="#f9e2af">{sites_str}</text>
     </g>"""
 
-    path_elements = []
-    tooltip_elements = []
-    css_hover_rules = []
+    return (
+        CX,
+        CY,
+        MAX_RADIUS,
+        MIN_RADIUS,
+        SITE_COLOR_BOTH,
+        SITE_COLOR_NEITHER,
+        SITE_COLOR_S1_ONLY,
+        SITE_COLOR_S2_ONLY,
+        SITE_LEGEND_BKG,
+        SITE_LEGEND_BORDER,
+        SITE_LEGEND_TEXT,
+        TH,
+        TW,
+        build_arc,
+        make_tooltip,
+        polar_to_cartesian,
+        preferred_hues,
+    )
+
+
+@app.cell
+def _(GROUPS, preferred_hues, slider_count, species_data, tabs):
+    # Filtering data + active tab
+    active_data = species_data[:slider_count.value]
+    active_tab = tabs.value
+
+    group_hues = {
+        group_name: preferred_hues[i % len(preferred_hues)]
+        for i, group_name in enumerate(GROUPS)
+    }
 
     grouped_data = {g: [] for g in GROUPS}
     for s in active_data:
         grouped_data[s["group"]].append(s)
+    return active_tab, group_hues, grouped_data
 
-    active_tab = tabs.value
-    seg_index = 0
+
+@app.cell
+def _(
+    CX,
+    CY,
+    GROUPS,
+    MAX_RADIUS,
+    MIN_RADIUS,
+    SITE_COLOR_BOTH,
+    SITE_COLOR_NEITHER,
+    SITE_COLOR_S1_ONLY,
+    SITE_COLOR_S2_ONLY,
+    TH,
+    TW,
+    active_tab,
+    build_arc,
+    drop_comp1,
+    drop_comp2,
+    drop_single,
+    group_hues,
+    grouped_data,
+    make_tooltip,
+    polar_to_cartesian,
+):
+    # Build the core sunburst paths
+    core_paths = []
+    tooltip_elements = []
+    css_hover_rules = []
+
+    seg_index = 0 # unique id counter shared across all segments
 
     for group_idx, group_name in enumerate(GROUPS):
         group_items = grouped_data[group_name]
         if not group_items:
             continue
-        base_angle = group_idx * 120
+        
+        base_angle = group_idx * 120 # hardcoded 120 degree angle bcs only 3 groups
         tiers = {}
         for item in group_items:
             sites = item["num_sites"]
             if sites not in tiers:
                 tiers[sites] = []
             tiers[sites].append(item)
+        
         sorted_tier_keys = sorted(tiers.keys(), reverse=True)
         num_tiers = len(sorted_tier_keys)
         ring_thickness = (MAX_RADIUS - MIN_RADIUS) / max(1, num_tiers)
 
         for tier_idx, sites_key in enumerate(sorted_tier_keys):
             tier_items = tiers[sites_key]
-            r_inner = MIN_RADIUS + (tier_idx * ring_thickness)
+            r_inner = MIN_RADIUS + (tier_idx * ring_thickness) # calculate segment properties (width / radius / ...)
             r_outer = r_inner + ring_thickness
             r_center = (r_inner + r_outer) / 2
             total_yield = sum(item["yield"] for item in tier_items)
@@ -297,49 +340,41 @@ def _(
                     sweep_angle = (item["yield"] / total_yield) * 120
                 else:
                     sweep_angle = 120 / len(tier_items)
+                
                 end_angle = current_start_angle + sweep_angle
                 opacity = 1.0
                 fill_color = ""
 
-                if active_tab == "Compare Sites":
+                if active_tab == "Compare Sites": # coloring depends on which tab the user is viewing
                     in_s1 = drop_comp1.value in item["sites"]
                     in_s2 = drop_comp2.value in item["sites"]
-                    if in_s1 and in_s2:
-                        fill_color = SITE_COLOR_BOTH
-                    elif in_s1:
-                        fill_color = SITE_COLOR_S1_ONLY
-                    elif in_s2:
-                        fill_color = SITE_COLOR_S2_ONLY
-                    else:
-                        fill_color = SITE_COLOR_NEITHER
+                    if in_s1 and in_s2:   fill_color = SITE_COLOR_BOTH
+                    elif in_s1:           fill_color = SITE_COLOR_S1_ONLY
+                    elif in_s2:           fill_color = SITE_COLOR_S2_ONLY
+                    else:                 fill_color = SITE_COLOR_NEITHER
                 elif active_tab == "Individual Site":
                     hue = group_hues[group_name]
-                    lightness = 85 - \
-                        min(50, (item["yield"] / max(1, total_yield)) * 45)
+                    lightness = 85 - min(50, (item["yield"] / max(1, total_yield)) * 45)
                     fill_color = f"hsl({hue}, 70%, {lightness}%)"
                     if drop_single.value not in item["sites"]:
                         opacity = 0.15
                 else:
                     hue = group_hues[group_name]
-                    lightness = 85 - \
-                        min(50, (item["yield"] / max(1, total_yield)) * 45)
+                    lightness = 85 - min(50, (item["yield"] / max(1, total_yield)) * 45)
                     fill_color = f"hsl({hue}, 70%, {lightness}%)"
 
-                path_d = build_arc(CX, CY, r_inner, r_outer,
-                                   current_start_angle, end_angle)
+                path_d = build_arc(CX, CY, r_inner, r_outer, current_start_angle, end_angle)
                 angle_center = current_start_angle + sweep_angle / 2
 
-                path_elements.append(
+                core_paths.append(
                     f'<path id="seg-{seg_index}" d="{path_d}" '
                     f'fill="{fill_color}" opacity="{opacity}" '
                     f'stroke="white" stroke-width="2" cursor="pointer"/>'
                 )
 
                 tip_r = r_outer + 20
-                tip_cx, tip_cy = polar_to_cartesian(
-                    CX, CY, tip_r, angle_center)
-
-                tx = tip_cx if tip_cx < CX else tip_cx - TW
+                tip_cx, tip_cy = polar_to_cartesian(CX, CY, tip_r, angle_center)
+                tx = tip_cx if tip_cx < CX else tip_cx - TW 
                 ty = tip_cy - TH / 2
 
                 tooltip_elements.append(
@@ -347,6 +382,7 @@ def _(
                                  item["id"], item["yield"], item["num_sites"])
                 )
 
+                # add hovering effect
                 css_hover_rules.append(
                     f"svg:has(#seg-{seg_index}:hover) #seg-{seg_index} "
                     f"{{ filter: brightness(1.35) drop-shadow(0 0 7px rgba(255,255,255,0.6)); }}\n"
@@ -356,9 +392,31 @@ def _(
 
                 current_start_angle = end_angle
                 seg_index += 1
+    return core_paths, css_hover_rules, tooltip_elements
+
 
-    # ── legend for Compare Sites tab ───────────────────────────
-    if active_tab == "Compare Sites":
+@app.cell
+def _(
+    CX,
+    CY,
+    MAX_RADIUS,
+    MIN_RADIUS,
+    SITE_COLOR_BOTH,
+    SITE_COLOR_NEITHER,
+    SITE_COLOR_S1_ONLY,
+    SITE_COLOR_S2_ONLY,
+    SITE_LEGEND_BKG,
+    SITE_LEGEND_BORDER,
+    SITE_LEGEND_TEXT,
+    active_tab,
+    drop_comp1,
+    drop_comp2,
+    polar_to_cartesian,
+):
+    # Build annotations and legends
+    annotation_elements = []
+
+    if active_tab == "Compare Sites": # legend for Compare Sites tab
         site1_label = drop_comp1.value
         site2_label = drop_comp2.value
 
@@ -371,10 +429,10 @@ def _(
 
         LX, LY = 0, 0    # top-left corner of the legend box
         LW, LH = 210, 150  # box dimensions
-        ROW_H = 26         # vertical spacing between rows
-        SWATCH_S = 14         # swatch square size
+        ROW_H = 26        # vertical spacing between rows
+        SWATCH_S = 14        # swatch square size
 
-        path_elements.append(
+        annotation_elements.append(
             f'<g id="compare-legend" style="pointer-events:none;">'
             f'<rect x="{LX}" y="{LY}" width="{LW}" height="{LH}" rx="10" ry="10" '
             f'fill="{SITE_LEGEND_BKG}" stroke="{SITE_LEGEND_BORDER}" stroke-width="1.5" '
@@ -388,35 +446,49 @@ def _(
 
         for i, (color, label) in enumerate(legend_items):
             row_y = LY + 42 + i * ROW_H
-            path_elements.append(
+            annotation_elements.append(
                 f'<rect x="{LX+12}" y="{row_y}" width="{SWATCH_S}" height="{SWATCH_S}" '
                 f'rx="3" fill="{color}" stroke="white" stroke-width="1"/>'
                 f'<text x="{LX+12+SWATCH_S+10}" y="{row_y+11}" '
                 f'font-family="Inter,sans-serif" font-size="12" fill="{SITE_LEGEND_TEXT}">{label}</text>'
             )
+        annotation_elements.append('</g>')
 
-        path_elements.append('</g>')
-
-    # Dividers
+    # dividers
     for i in range(3):
         angle = i * 120
         p1 = polar_to_cartesian(CX, CY, MIN_RADIUS, angle)
         p2 = polar_to_cartesian(CX, CY, MAX_RADIUS, angle)
-        path_elements.append(
+        annotation_elements.append(
             f'<line x1="{p1[0]}" y1="{p1[1]}" x2="{p2[0]}" y2="{p2[1]}" '
             f'stroke="#fff" stroke-width="4" style="pointer-events:none;"/>'
         )
 
-    # Group labels
+    # group labels
     lbl_1 = polar_to_cartesian(CX, CY, MAX_RADIUS + 25, 60)
     lbl_2 = polar_to_cartesian(CX, CY, MAX_RADIUS + 25, 180)
     lbl_3 = polar_to_cartesian(CX, CY, MAX_RADIUS + 25, 300)
-    path_elements.extend([
+    annotation_elements.extend([
         f'<text x="{lbl_1[0]}" y="{lbl_1[1]}" font-family="sans-serif" font-weight="bold" fill="black"  text-anchor="middle" style="pointer-events:none;">Woody vascular plants</text>',
         f'<text x="{lbl_2[0]}" y="{lbl_2[1]}" font-family="sans-serif" font-weight="bold" fill="black" text-anchor="middle" style="pointer-events:none;">Non-woody vascular plants</text>',
         f'<text x="{lbl_3[0]}" y="{lbl_3[1]}" font-family="sans-serif" font-weight="bold" fill="black"   text-anchor="middle" style="pointer-events:none;">Bryophytes</text>',
     ])
+    return (annotation_elements,)
 
+
+@app.cell
+def _(
+    CX,
+    CY,
+    MIN_RADIUS,
+    annotation_elements,
+    controls,
+    core_paths,
+    css_hover_rules,
+    mo,
+    tooltip_elements,
+):
+    # Combine everything + visualize
     css = f"""
     <style>
       .tip {{ visibility: hidden; pointer-events: none; }}
@@ -425,6 +497,7 @@ def _(
     </style>
     """
 
+    # core + annotions are merged here
     svg_markup = f"""
     {css}
     <svg width="1000" height="1000" viewBox="0 0 1000 1000"
@@ -437,17 +510,16 @@ def _(
       </defs>
 
       <circle cx="{CX}" cy="{CY}" r="{MIN_RADIUS}" fill="#f4f4f4" stroke="none"/>
-      {"".join(path_elements)}
-
+  
+      {"".join(core_paths)}
+  
+      {"".join(annotation_elements)}
+  
       {"".join(tooltip_elements)}
-
     </svg>
     """
 
-    # Assign layout to variable
     final_dashboard = mo.vstack([controls, mo.Html(svg_markup)], align="center", gap=8)
-    
-    # Place as the last line so Marimo renders it to the screen!
     final_dashboard
     return final_dashboard,