globe: Phase 1 unification — Specimen Type filter, SKOS labels, portable predicate, v2 facets

[rdhyee]

Implements Phase 1 of #156 — unify Search Explorer and Interactive Explorer into a single page. This PR brings tutorials/progressive_globe.qmd to facet parity with the explorer, so subsequent phases can layer cross-filter counts, URL params, and the table view on a single source of truth.

What changed

Data contract — switch to v2 facets. facets_url now points at isamples_202601_sample_facets_v2.parquet, which carries URI-string columns for material, context, and object_type (the explorer was already on v2; the globe was on the older short-label file). vocab_labels.parquet is preloaded for SKOS prefLabel lookups.

Specimen Type filter. New collapsible #objectTypeFilter section in the side panel, populated alongside Material / Sampled Feature from facet_summaries.parquet.

SKOS prefLabels. prettyLabel(uri) ports cleanly from the explorer: looks up the URI in a 535-row vocab map (English pref_labels) and falls back to URI tail when no match. Display labels for all three facet groups now read as human terms ("Natural Solid Material", "Site of past human activities", "Other solid object") rather than URI fragments.

Portable facetFilterSQL() predicate. Replaces the alias-dependent AND f.material IN (...) fragments with a portable AND pid IN (SELECT DISTINCT pid FROM read_parquet(facets_url) WHERE ...) subquery. Two consequences:

• The cluster-click and viewport-sample queries no longer need the JOIN/no-JOIN branching — both branches collapse to a single query that works whether or not facet filters are active.
• Multi-valued facets (a sample with two materials) no longer duplicate rows via JOIN, which matters for Phase 4's table mode. Addresses Codex's contract #5.

UNCHECKED-by-default semantics for the URI-valued facet groups. Empty = no filter, checked = include only those values. Matches the explorer's UX — defaulting to "all 200 materials checked" would be unusable, and "empty = no filter" is the natural reading. Source filter semantic unchanged (still all-checked-by-default with 4 named sources).

Cluster-mode honesty. The H3 summary parquets only carry dominant_source, so material/feature/specimen filters cannot affect cluster counts. When any of the three facet groups is active in cluster mode, #facetNote surfaces an explanatory message: "Material / feature / specimen filters apply at sample zoom level — zoom in or click a cluster." Ships with the new filters in the same PR so users never see silently-wrong filter results.

Verification

• quarto render tutorials/progressive_globe.qmd — PASS
• Playwright smoke test (/tmp/globe_smoke_test.py) — PASS, 0 JS exceptions, 0 console errors, 0 network failures
• Filter populations verified: 19 materials, 16 features, 17 specimen types, all with SKOS labels
• Default state confirmed UNCHECKED across all three URI-valued groups
• Vocab map size: 535 entries

Diff summary

 tutorials/progressive_globe.qmd | 230 ++++++++++++++++++++----------------
 1 file changed, 136 insertions(+), 94 deletions(-)

Single-file change. Globe-only — explorer file untouched, both pages remain live and independently functional.

Out of scope (lands in later phases)

• Cross-filtered live counts → Phase 2
• URL query params + multi-term search → Phase 3
• Table view + maxSamples slider → Phase 4
• /explorer.html rename + redirects → Phase 5

🤖 Generated with Claude Code

[rdhyee]

Codex review (relayed): no findings.

Reviewed PR #157's single-file change in tutorials/progressive_globe.qmd, including the generated docs/tutorials/progressive_globe.html after rendering. The new facet SQL matches the actual sample_facets_v2.parquet shape: one row per pid with material, context, and object_type columns, so the combined AND predicate is valid and does not introduce duplicate rows.

Verified:

• gh pr view / gh pr diff for PR metadata and patch
• quarto render tutorials/progressive_globe.qmd passed
• DuckDB checks against downloaded parquet assets:
  • sample_facets_v2: 5,980,282 rows, 5,980,282 distinct pids
  • facet summaries include object_type
  • vocab labels load with 535 English URI labels

Small clarification on the PR description: the "duplicate rows from multi-valued facets" framing is prophylactic given the v2 file's actual one-row-per-pid shape — no rows are being de-duplicated against the current data. The portable predicate is still the right shape (forward-compatible if the schema ever goes multi-valued, and removes the alias dependency Phase 4 needs), but the dedup framing is overstated for today's file.

Posted from Codex.