Skip to content

docs: Why H3 rationale page + iSamples Explorer layout/code-display cleanup#152

Merged
rdhyee merged 3 commits intoisamplesorg:mainfrom
rdhyee:docs/why-h3
Apr 30, 2026
Merged

docs: Why H3 rationale page + iSamples Explorer layout/code-display cleanup#152
rdhyee merged 3 commits intoisamplesorg:mainfrom
rdhyee:docs/why-h3

Conversation

@rdhyee
Copy link
Copy Markdown
Contributor

@rdhyee rdhyee commented Apr 30, 2026

This PR bundles three unrelated cleanups on the same branch:

1. Why H3? rationale page (tutorials/why_h3.qmd)

Documents why iSamples uses H3 — and why resolutions 4/6/8 specifically — so newcomers don't have to reverse-engineer the choice from the H3 tier files. Motivated by Raymond's observation that H3 has no standalone Wikipedia article, only a mention in Discrete global grid. Without that fallback, the site needs to make the design choice legible itself.

What the page covers:

  • What H3 is, in two sentences, with authoritative links (h3geo.org, GitHub, Uber Eng blog, Sahr 2008)
  • Why hexagons over squares (uniform neighbor distance, isotropic direction sampling)
  • Why H3 over S2 or geohash (DuckDB integration, 64-bit integer index, dateline behavior)
  • Why resolutions 4 / 6 / 8 specifically (cell size × altitude band × parquet payload budget — adding 5 / 7 / 9 ~triples on-the-wire bytes for a barely-perceptible smoothness win)
  • Two query patterns (region aggregate via tier file; per-cell filter via wide h3_res6 column)
  • What we'd revisit (dominant-source-per-cell color encoding can hide near-equal second sources — Eric Kansa flagged this in Dec 2025)

Wiring:

  • Added under "Architecture & Vocabularies" in both the navbar dropdown and the docked sidebar, alongside the existing "Technical: Narrow vs Wide" page (matches that precedent)
  • Cross-linked from data.qmd §4 (the H3 tier breakpoints table) and from how-to-use.qmd's H3 helpers section

2. Explorer: hide all OJS code (tutorials/isamples_explorer.qmd)

Replaces code-fold: true with echo: false at the format level so source code blocks no longer appear at all (previously shown behind a "Code" toggle that took visual space). Removes per-cell //| code-fold directives that were overriding the format setting, and drops the now-empty "Setup" and "Database & Queries" section headings (their cells produced no rendered output).

3. Explorer: layout A — globe in right column, table full-width

Moves the Cesium globe into the right column of the filters grid so it's visible immediately (was below the fold under its own ## Globe View heading). Drops the viewMode radio (globe / list / table) — globe is now always visible top-right and the results table renders full width below the grid as ### Results. Removes the now-unused list view, viewMode-keyed display toggles on the cesiumContainer/legend, and the v2-only deferred-mount branch in the viewer cell.

Test plan

  • quarto render tutorials/why_h3.qmd succeeds
  • quarto render data.qmd and quarto render how-to-use.qmd succeed (cross-link renders correctly)
  • Anchor #h3-tier-breakpoints-for-map-authors exists in docs/data.html (target of the back-link from why_h3)
  • quarto render tutorials/isamples_explorer.qmd succeeds; rendered HTML has zero visible code blocks; H2 sections are Search & Filters → Sample Card → Debug Info; cesiumContainer renders inside the Search & Filters grid right column; full-width results table appears below
  • Deployed to rdhyee fork preview (https://rdhyee.github.io/isamplesorg.github.io/tutorials/isamples_explorer.html?sources=OPENCONTEXT) — visual verification by Raymond
  • Reviewer eyeballs claims in §"Why H3 over S2 or geohash" — I assert we did not benchmark S2 head-to-head; if that's wrong, we should soften the section

🤖 Generated with Claude Code

H3 has no standalone Wikipedia article, so newcomers landing on the
iSamples site lack a fallback for understanding the choice. This page
documents why H3 over square grids and over S2/geohash, why resolutions
4/6/8 specifically (cell size × altitude band × parquet size budget),
and what we'd revisit (dominant-source-per-cell color encoding).

- New page: tutorials/why_h3.qmd
- Wired into navbar + sidebar under "Architecture & Vocabularies"
  alongside the existing "Technical: Narrow vs Wide" doc
- Cross-linked from data.qmd §4 and how-to-use.qmd's H3 section

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@rdhyee
Copy link
Copy Markdown
Contributor Author

rdhyee commented Apr 30, 2026

Review finding: the new Why H3 page says the wide parquet carries h3_res4/6/8, and the example queries https://data.isamples.org/current/wide.parquet with WHERE h3_res6 = .... That alias currently points to the 202604 wide parquet, which does not have H3 columns, so the copy-paste query fails with Referenced column "h3_res6" not found.

The H3 columns are in isamples_202601_wide_h3.parquet per SERIALIZATIONS.md. Please update the prose and the example to point to that H3-augmented wide file instead of current/wide.parquet.

Checks I ran:

  • quarto render tutorials/why_h3.qmd
  • quarto render data.qmd
  • quarto render how-to-use.qmd
  • git diff --check
  • DuckDB schema/query checks against local wide and wide_h3 parquet files

rdhyee and others added 2 commits April 30, 2026 16:31
Replaces code-fold with echo: false at the format level so source
code blocks no longer appear at all (previously shown behind a
"Code" toggle that took visual space). Removes per-cell
//| code-fold directives that were overriding the format setting,
and drops the now-empty "Setup" and "Database & Queries" section
headings (their cells produced no rendered output).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Move the Cesium globe into the right column of the filters grid so
it's visible immediately (was below the fold under its own ## Globe
View heading). Drop the viewMode radio (globe / list / table) — globe
is now always visible top-right and the results table renders full
width below the grid as ### Results. Removes the now-unused list
view, viewMode-keyed display toggles on the cesiumContainer/legend,
and the v2-only deferred-mount branch in the viewer cell.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@rdhyee rdhyee changed the title docs: add "Technical: Why H3?" rationale page docs: Why H3 rationale page + iSamples Explorer layout/code-display cleanup Apr 30, 2026
@rdhyee rdhyee merged commit 2d500ff into isamplesorg:main Apr 30, 2026
1 check passed
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.

1 participant