Merge pull request #339 from rdhyee/feat/explorer-guided-tour

Guided tour of the Explorer replaces the migration-era Zenodo analysis tutorial

Author: rdhyee

README.md

@@ -18,7 +18,7 @@ Visit the [Quarto site](https://quarto.org/docs/guide/) for documentation on usi
 The `tutorials/` directory contains interactive data analysis tutorials:
 
 - **`isamples_explorer.qmd`** - Interactive search and exploration of 6.7M samples
-- **`zenodo_isamples_analysis.qmd`** - Deep-dive DuckDB-WASM analysis tutorial
+- **`explorer_guided_tour.qmd`** - Guided tour of the Interactive Explorer (replaced the migration-era Zenodo deep-dive, 2026-07)
 - **`parquet_cesium_isamples_wide.qmd`** - Cesium-based 3D globe visualization
 - **`narrow_vs_wide_performance.qmd`** - Technical schema comparison
 

SERIALIZATIONS.md

@@ -104,7 +104,7 @@ builder — a fresh build is NOT bit-for-bit identical to them (see
 
 | File | Role | Size | Rows | Upstream | Consumers | Spec |
 |---|---|---:|---:|---|---|---|
-| `isamples_202601_wide_h3.parquet` | Wide with `h3_res{4,6,8}` BIGINT columns pre-joined | 292 MB | 20.7 M | wide | Deep-Dive Analysis tutorial (H3 filtering without join) | QUERY_SPEC §2.4 |
+| `isamples_202601_wide_h3.parquet` | Wide with `h3_res{4,6,8}` BIGINT columns pre-joined | 292 MB | 20.7 M | wide | archival/analyst convenience (former Deep-Dive tutorial, replaced 2026-07 by the Guided Tour which uses summary files) | QUERY_SPEC §2.4 |
 | `isamples_202601_h3_summary_res4.parquet` | Continental tier: `(h3_cell, sample_count, center_lat, center_lng, dominant_source, source_count, resolution)` | 580 KB | 38 K | wide_h3 | Interactive Explorer globe (zoomed out), Python Explorer H3 tier mode | QUERY_SPEC §2.4 |
 | `isamples_202601_h3_summary_res6.parquet` | Regional tier | 1.6 MB | 112 K | wide_h3 | Interactive Explorer globe (mid zoom) | QUERY_SPEC §2.4 |
 | `isamples_202601_h3_summary_res8.parquet` | Neighborhood tier | 2.4 MB | 176 K | wide_h3 | Interactive Explorer globe (close zoom) | QUERY_SPEC §2.4 |

_quarto.yml

@@ -38,8 +38,8 @@ website:
         menu:
           - text: Overview
             href: how-to-use.qmd
-          - text: Deep-Dive Analysis
-            href: tutorials/zenodo_isamples_analysis.qmd
+          - text: Guided Tour
+            href: tutorials/explorer_guided_tour.qmd
       - text: About
         menu:
           - text: Objectives
@@ -85,8 +85,8 @@ website:
       contents:
         - href: how-to-use.qmd
           text: Overview
-        - text: "Deep-Dive Analysis"
-          href: tutorials/zenodo_isamples_analysis.qmd
+        - text: "Guided Tour"
+          href: tutorials/explorer_guided_tour.qmd
     - id: about
       title: "About"
       style: "docked"

explorer.qmd

@@ -7484,5 +7484,5 @@ Pre-aggregated H3 hexagonal indices achieve near-instant globe rendering, with s
 
 ## See Also
 
-- [Deep-Dive Analysis](/tutorials/zenodo_isamples_analysis.html) — DuckDB-WASM SQL tutorial
+- [Guided Tour](/tutorials/explorer_guided_tour.html) — seven views of the Explorer, with the queries behind them
 - [Tutorials](/tutorials/) — index of all interactive tutorials

how-to-use.qmd

@@ -36,7 +36,7 @@ Works in Chrome, Firefox, Edge, Safari, and Brave. No plugins, no downloads, no
 
 All code is visible and foldable on tutorial pages. Want to build your own analysis?
 
-- **[Deep-Dive Analysis](/tutorials/zenodo_isamples_analysis.html)** — statistical exploration with Observable Plot
+- **[Guided Tour](/tutorials/explorer_guided_tour.html)** — seven views of the Explorer and the queries behind them
 - **[Tutorials index](/tutorials/)** — step-by-step guides from basic exploration to advanced analysis
 - **[GitHub](https://github.com/isamplesorg/)** — all source code and data pipelines
 - **[Zenodo](https://zenodo.org/communities/isamples)** — archived datasets for reproducible research
@@ -115,16 +115,15 @@ browsers use the parquet versions.
 
 ### Which tutorial uses which file {.unnumbered}
 
-| | Interactive Explorer | Search Explorer | Deep-Dive Analysis |
+| | Interactive Explorer | Search Explorer | Guided Tour |
 |---|:-:|:-:|:-:|
 | `wide.parquet` | | ● | |
-| `wide_h3.parquet` | | | ● |
 | `facet_summaries.parquet` | ● | ● | ● |
 | `facet_cross_filter.parquet` | | ● | |
 | `sample_facets_v2.parquet` | ● | ● | |
-| `h3_summary_res4/6/8.parquet` | ● | | |
+| `h3_summary_res4/6/8.parquet` | ● | | ● (res4) |
 | `samples_map_lite.parquet` | ● | | |
-| `vocab_labels.parquet` | ● | ● | |
+| `vocab_labels.parquet` | ● | ● | ● |
 
 ### Quick query recipes {.unnumbered}
 

tests/test_navbar_dropdowns.py

@@ -29,11 +29,11 @@ def test_how_to_use_dropdown_has_overview(self, page):
         menu = _open_dropdown(page, "How to Use")
         assert menu.get_by_text("Overview").count() > 0
 
-    def test_how_to_use_dropdown_has_deep_dive(self, page):
-        """And I see Deep-Dive Analysis."""
+    def test_how_to_use_dropdown_has_guided_tour(self, page):
+        """And I see Guided Tour."""
         page.goto(SITE_URL, wait_until="domcontentloaded")
         menu = _open_dropdown(page, "How to Use")
-        assert menu.get_by_text("Deep-Dive Analysis").count() > 0
+        assert menu.get_by_text("Guided Tour").count() > 0
 
 
 class TestAboutDropdown:

tests/test_navigation.py

@@ -24,7 +24,7 @@ def test_about_sidebar_only_shows_own_items(self, page):
         sidebar = page.locator(".sidebar-navigation")
         assert sidebar.get_by_text("Objectives", exact=True).count() > 0
         # Should NOT show items from other sections
-        assert sidebar.get_by_text("Deep-Dive Analysis").count() == 0
+        assert sidebar.get_by_text("Guided Tour").count() == 0
         assert sidebar.get_by_text("Vocabularies", exact=True).count() == 0
 
     def test_architecture_sidebar_only_shows_own_items(self, page):
@@ -33,15 +33,15 @@ def test_architecture_sidebar_only_shows_own_items(self, page):
         assert sidebar.get_by_text("Vocabularies", exact=True).count() > 0
         # Should NOT show items from other sections
         assert sidebar.get_by_text("Objectives", exact=True).count() == 0
-        assert sidebar.get_by_text("Deep-Dive Analysis").count() == 0
+        assert sidebar.get_by_text("Guided Tour").count() == 0
 
     def test_research_sidebar_only_shows_own_items(self, page):
         page.goto(f"{SITE_URL}/pubs.html", wait_until="domcontentloaded")
         sidebar = page.locator(".sidebar-navigation")
         assert sidebar.get_by_text("Publications & Conferences").count() > 0
         # Should NOT show items from other sections
         assert sidebar.get_by_text("Objectives", exact=True).count() == 0
-        assert sidebar.get_by_text("Deep-Dive Analysis").count() == 0
+        assert sidebar.get_by_text("Guided Tour").count() == 0
 
     def test_sidebar_does_not_show_old_information_architecture(self, page):
         page.goto(f"{SITE_URL}/design/index.html", wait_until="domcontentloaded")
@@ -57,10 +57,10 @@ def test_how_to_use_has_overview(self, page):
         sidebar = page.locator(".sidebar-navigation")
         assert sidebar.get_by_text("Overview", exact=True).count() > 0
 
-    def test_how_to_use_has_deep_dive(self, page):
+    def test_how_to_use_has_guided_tour(self, page):
         page.goto(f"{SITE_URL}/how-to-use.html", wait_until="domcontentloaded")
         sidebar = page.locator(".sidebar-navigation")
-        assert sidebar.get_by_text("Deep-Dive Analysis").count() > 0
+        assert sidebar.get_by_text("Guided Tour").count() > 0
 
     def test_how_to_use_has_globe_viz(self, page):
         page.goto(f"{SITE_URL}/how-to-use.html", wait_until="domcontentloaded")

tests/test_tutorials_landing.py

@@ -15,10 +15,11 @@
 class TestHowToUseLanding:
     """Scenario: Landing page lists all tutorial pathways."""
 
-    def test_has_deep_dive_link(self, page):
-        """Given I am on the How to Use page, Then I see a link to Deep-Dive Analysis."""
+    def test_has_guided_tour_link(self, page):
+        """Given I am on the How to Use page, Then I see a link to the Guided Tour
+        in the MAIN CONTENT (scoped so the permanent navbar link can't satisfy it)."""
         page.goto(HOW_TO_USE_URL, wait_until="domcontentloaded")
-        link = page.locator("a:has-text('Deep-Dive')")
+        link = page.locator("main a:has-text('Guided Tour')")
         assert link.count() > 0
 
     def test_has_globe_viz_link(self, page):
@@ -37,14 +38,18 @@ def test_has_narrow_vs_wide_link(self, page):
 class TestTutorialPageLoads:
     """Scenario: Each tutorial page loads without JavaScript errors."""
 
-    def test_deep_dive_loads(self, page):
-        """Given I navigate to the Deep-Dive tutorial, Then no JS errors appear."""
+    def test_guided_tour_loads(self, page):
+        """Given I navigate to the Guided Tour, Then the LIVE CELLS actually render
+        (waits for an Observable Plot SVG — DuckDB query + chart — not just DOM)."""
         errors = []
         page.on("pageerror", lambda e: errors.append(str(e)))
         page.goto(
-            f"{SITE_URL}/tutorials/zenodo_isamples_analysis.html",
+            f"{SITE_URL}/tutorials/explorer_guided_tour.html",
             wait_until="domcontentloaded",
         )
+        # The source-counts chart is the first Plot output; its appearance proves
+        # OJS booted, DuckDB-WASM initialized, and a remote parquet query ran.
+        page.wait_for_selector("figure svg, svg.plot-d6a7b5", timeout=90_000)
         assert page.title() != ""
         # Allow known non-critical errors but flag unexpected ones
         critical = [e for e in errors if "TypeError" in e or "ReferenceError" in e]

tutorials/archive/parquet_cesium_isamples_wide.qmd

@@ -1079,4 +1079,4 @@ html`${
 
 - [Interactive Explorer](/tutorials/isamples_explorer.html) - Search and filter samples
 - [Narrow vs Wide Performance](/tutorials/narrow_vs_wide_performance.html) - Benchmark comparison
-- [Deep-Dive Analysis](/tutorials/zenodo_isamples_analysis.html) - Comprehensive DuckDB-WASM tutorial
+- [Guided Tour](/tutorials/explorer_guided_tour.html) - Seven views of the Explorer, with live queries