# COD Knowledge Map (cod-kmap)

> Knowledge map for the Coastal Observatory Design (COD): coastal research facilities, people, funding, publications and datasets across the Americas, published as a MapLibre + DuckDB-Wasm site whose Parquet tables are queryable directly over HTTP.

## Start here

The rendered page at the site root is a JavaScript application (MapLibre GL + DuckDB-Wasm): fetching it without executing JavaScript returns an empty shell. Do not scrape it. Everything it displays is a plain static file, addressable as follows.

```
Documentation (Markdown)  https://tyson-swetnam.github.io/cod-kmap/docs/<file>.md
  mirrored on GitHub      https://raw.githubusercontent.com/tyson-swetnam/cod-kmap/main/docs/<file>.md      (branch main; a moving target)
Whole doc corpus          https://tyson-swetnam.github.io/cod-kmap/llms-full.txt
Data table (Parquet)      https://tyson-swetnam.github.io/cod-kmap/public/parquet/<table>.parquet
Table schemas (JSON)      https://tyson-swetnam.github.io/cod-kmap/public/parquet/schema.json
Map points (GeoJSON)      https://tyson-swetnam.github.io/cod-kmap/public/facilities.geojson
Overlay polygons          https://tyson-swetnam.github.io/cod-kmap/public/overlays/<layer>.geojson
  layer index             https://tyson-swetnam.github.io/cod-kmap/public/overlays/manifest.json
Controlled vocabularies   https://tyson-swetnam.github.io/cod-kmap/public/vocab/<name>.csv
Crawl surface             https://tyson-swetnam.github.io/cod-kmap/robots.txt · https://tyson-swetnam.github.io/cod-kmap/sitemap.xml
Source repository         https://github.com/tyson-swetnam/cod-kmap
```

Agent guide, including what to do if you cannot reach this host: https://tyson-swetnam.github.io/cod-kmap/docs/for_ai_agents.md

## Documentation

Human-authored Markdown, served as-is with content type `text/markdown`. Each entry gives the site address and the `raw.githubusercontent.com` mirror; both return the same bytes.

- [For AI agents](https://tyson-swetnam.github.io/cod-kmap/docs/for_ai_agents.md): How agents should consume this site: the llms.txt / raw-Markdown / Parquet endpoints, what is queryable over HTTP and what is not, trust and provenance signals, and what to do if you cannot fetch this host. Type: Reference. Raw source: https://raw.githubusercontent.com/tyson-swetnam/cod-kmap/main/docs/for_ai_agents.md
- [Data endpoints](https://tyson-swetnam.github.io/cod-kmap/docs/data_endpoints.md): Reference for every published data endpoint: all 46 Parquet tables with row counts and column lists, the GeoJSON overlays, the vocabulary CSVs, and worked DuckDB / Python / curl recipes against each. Type: Reference. Raw source: https://raw.githubusercontent.com/tyson-swetnam/cod-kmap/main/docs/data_endpoints.md
- [Purpose & MSI handout](https://tyson-swetnam.github.io/cod-kmap/docs/cod_purpose_and_msi_handout.md): The CCZO proposal brief: NSF Mid-scale RI-1 24-598 deadlines, the four design pillars, the four Grand Challenge questions, the named PI/co-PI team, and a theme-to-cod-kmap mapping table. Type: Report. Raw source: https://raw.githubusercontent.com/tyson-swetnam/cod-kmap/main/docs/cod_purpose_and_msi_handout.md
- [Methods](https://tyson-swetnam.github.io/cod-kmap/docs/METHODS.md): Table-by-table schema summary, the polygon overlay sources with feature counts, the dedup rules (URL match, RapidFuzz >= 92, 5 km haversine), the Parquet list DuckDB-Wasm loads, and the known data gaps. Type: Reference. Raw source: https://raw.githubusercontent.com/tyson-swetnam/cod-kmap/main/docs/METHODS.md
- [Team, scholars & data](https://tyson-swetnam.github.io/cod-kmap/docs/team_scholars_datasets_methods.md): Build provenance for the Org chart, People and Data tabs: the WBS DuckLake snapshot run, the scholar cohorts, 72 datasets with 242 access endpoints, and the ordered script chain that produces each. Type: Guide. Raw source: https://raw.githubusercontent.com/tyson-swetnam/cod-kmap/main/docs/team_scholars_datasets_methods.md
- [Person registry](https://tyson-swetnam.github.io/cod-kmap/docs/person_registry.md): How canonical_id works (orcid:/openalex: forms, merging on identifier equality and never on name), the core vs archive tier split that decides what ships to the browser, and six caveats on reading registry figures. Type: Reference. Raw source: https://raw.githubusercontent.com/tyson-swetnam/cod-kmap/main/docs/person_registry.md
- [Validation report](https://tyson-swetnam.github.io/cod-kmap/docs/VALIDATION_REPORT.md): Run val-20260729T035944Z: 40,380 identity verdicts over 10,095 core registry rows, 2 ORCID conflicts, 114 inactive RORs, a co-author harvest at 30% coverage, and the OWL/SHACL conformance accounting. Type: Report. Raw source: https://raw.githubusercontent.com/tyson-swetnam/cod-kmap/main/docs/VALIDATION_REPORT.md
- [References](https://tyson-swetnam.github.io/cod-kmap/docs/REFERENCES.md): A 2026-04-26 snapshot of the COD Zotero group library (group 5711743): 58 articles, 8 books, 10 reports and 21 webpages, with the curl commands to regenerate it. BibTeX form (97 entries): docs/references.bib. Type: Reference. Raw source: https://raw.githubusercontent.com/tyson-swetnam/cod-kmap/main/docs/REFERENCES.md
- [Reference documents report](https://tyson-swetnam.github.io/cod-kmap/docs/reference_documents_report.md): Inventory of COD background reading (the 2018 landscape survey, WATERS plans, NSF solicitations) plus proposed schema extensions with DDL and dated built/superseded notes on each. Type: Report. Raw source: https://raw.githubusercontent.com/tyson-swetnam/cod-kmap/main/docs/reference_documents_report.md
- [Map visualization plan](https://tyson-swetnam.github.io/cod-kmap/docs/map_visualization_plan.md): Design of the Network tab's MVG cartogram: the grouping options with polygon counts, the three-step supergraph/subgraph/Voronoi layout, the PCL toggle, and the click and filter interaction rules. Type: Guide. Raw source: https://raw.githubusercontent.com/tyson-swetnam/cod-kmap/main/docs/map_visualization_plan.md
- [Network fix metrics](https://tyson-swetnam.github.io/cod-kmap/docs/NETWORK_FIX_METRICS.md): M7 crossing-pair decomposition before and after 59 researchers move into interstitial space (694 -> 821 pairs, 86% within x between), correcting an earlier claim. Describes models, not the shipped layout. Type: Report. Raw source: https://raw.githubusercontent.com/tyson-swetnam/cod-kmap/main/docs/NETWORK_FIX_METRICS.md
- [Funding pipeline plan](https://tyson-swetnam.github.io/cod-kmap/docs/funding_pipeline_plan.md): Funding table layout, the high/medium/low confidence rules, current NSF Awards API coverage, and the USAspending, Form-990 and budget-book passes still to run. (draft: describes work not yet done) Type: Plan. Raw source: https://raw.githubusercontent.com/tyson-swetnam/cod-kmap/main/docs/funding_pipeline_plan.md
- [Suitability roadmap](https://tyson-swetnam.github.io/cod-kmap/docs/suitability_roadmap.md): Roadmap for a site-suitability layer that is NOT built yet: MEOW/Koppen/EEZ, GHSL and GBIF/OBIS source tables, a weighted H3 hex-cell scoring formula, and an effort estimate. (draft: describes work not yet done) Type: Plan. Raw source: https://raw.githubusercontent.com/tyson-swetnam/cod-kmap/main/docs/suitability_roadmap.md
- [Personnel gap research](https://tyson-swetnam.github.io/cod-kmap/docs/personnel_gap_research_plan.md): How facility leaders are sourced per network group, every facility_personnel column recorded, the coverage figure achieved, and the rule that unresolvable leadership stays NULL rather than guessed. Type: Guide. Raw source: https://raw.githubusercontent.com/tyson-swetnam/cod-kmap/main/docs/personnel_gap_research_plan.md
- [ORCID enrichment](https://tyson-swetnam.github.io/cod-kmap/docs/orcid_enrichment_plan.md): The strict ORCID matcher's accept rules (family name, given name, and a distinctive employer-token gate), the pub.orcid.org endpoints used, the staff coverage achieved, and the resolution log. Type: Guide. Raw source: https://raw.githubusercontent.com/tyson-swetnam/cod-kmap/main/docs/orcid_enrichment_plan.md
- [Google Scholar enrichment](https://tyson-swetnam.github.io/cod-kmap/docs/google_scholar_enrichment_plan.md): Measured result of a four-tier Scholar-id lookup: OpenAlex and ORCID yield almost nothing, only a handful of people carry an id, and the reasoning for not scraping Scholar at all. Type: Guide. Raw source: https://raw.githubusercontent.com/tyson-swetnam/cod-kmap/main/docs/google_scholar_enrichment_plan.md

- [References in BibTeX](https://tyson-swetnam.github.io/cod-kmap/docs/references.bib): the same library as References above, as a flat BibTeX export. Raw source: https://raw.githubusercontent.com/tyson-swetnam/cod-kmap/main/docs/references.bib

## Queryable data (Parquet over HTTP)

46 tables, 23.18 MB in total. Every table is one Parquet file at `https://tyson-swetnam.github.io/cod-kmap/public/parquet/<table>.parquet`. They are served with HTTP range-request support, so DuckDB (or any Parquet reader) can query one in place without downloading it:

```sql
INSTALL httpfs; LOAD httpfs;
SELECT canonical_name, acronym, facility_type, country
FROM 'https://tyson-swetnam.github.io/cod-kmap/public/parquet/facilities.parquet'
-- slugs come from facility_types.parquet / vocab/facility_types.csv
WHERE facility_type = 'university-marine-lab'
ORDER BY canonical_name
LIMIT 10;
```

Row counts below are of the PUBLISHED file. Several tables ship only a subset of what the pipeline builds (see the per-table notes), so treat counts as floors rather than totals.

### Facilities and places

The spine of the dataset. `facilities` is one row per catalogued site; `regions` holds attributes for the polygons of 7 of the 15 overlay layers (147 of 3,566 features); `facility_regions` is the spatial-containment edge between them.

- `facilities` — 3,519 rows, 205 KB. Mixes two populations — 210 research organisations and 3,309 protected-area units (facility_type prefixed protected-area-). Filter on facility_type; do not read the row count as a count of research facilities. Columns: facility_id VARCHAR, canonical_name VARCHAR, acronym VARCHAR, parent_org VARCHAR, facility_type VARCHAR, country VARCHAR, region VARCHAR, hq_address VARCHAR, hq_lat DOUBLE, hq_lng DOUBLE, url VARCHAR, contact VARCHAR, established INTEGER, created_at TIMESTAMP, ror VARCHAR.
- `locations` — 3,566 rows, 230 KB. One row per site location; a facility may have several. Columns: location_id VARCHAR, facility_id VARCHAR, label VARCHAR, address VARCHAR, lat DOUBLE, lng DOUBLE, role VARCHAR.
- `facility_types` — 18 rows, 1 KB. Columns: slug VARCHAR, label VARCHAR, description VARCHAR.
- `provenance` — 3,534 rows, 65 KB. Per-record source URL, retrieval date and confidence. Not registered by the site's own app; externally queryable. Columns: record_type VARCHAR, record_id VARCHAR, source_url VARCHAR, retrieved_at DATE, confidence VARCHAR, agent VARCHAR.
- `regions` — 147 rows, 15 KB. Attributes for overlay polygons — the geometry is in public/overlays/*.geojson and features carry no region_id, so join on (source_file, name). Covers only the 7 curated layers, not the 8 bulk coastal-* / ramsar / neon-sites layers. Columns: region_id VARCHAR, name VARCHAR, acronym VARCHAR, kind VARCHAR, network_id VARCHAR, url VARCHAR, manager VARCHAR, designated INTEGER, state VARCHAR, description VARCHAR, source_file VARCHAR, source VARCHAR, created_at TIMESTAMP.
- `facility_regions` — 366 rows, 5 KB. Columns: facility_id VARCHAR, region_id VARCHAR, relation VARCHAR, distance_km DOUBLE.
- `region_area_links` — 385 rows, 3 KB. Columns: region_id VARCHAR, area_id VARCHAR.

### Research areas and networks

Controlled-vocabulary topic and consortium membership for facilities.

- `research_areas` — 40 rows, 2 KB. Columns: area_id VARCHAR, label VARCHAR, gcmd_uri VARCHAR, parent_id VARCHAR.
- `research_areas_active` — 40 rows, 2 KB. Columns: area_id VARCHAR, label VARCHAR, parent_id VARCHAR, n_facilities INTEGER, collapsed_into VARCHAR.
- `area_links` — 9,624 rows, 72 KB. Columns: facility_id VARCHAR, area_id VARCHAR.
- `networks` — 35 rows, 2 KB. Columns: network_id VARCHAR, label VARCHAR, level VARCHAR, url VARCHAR.
- `network_membership` — 688 rows, 12 KB. Columns: facility_id VARCHAR, network_id VARCHAR, role VARCHAR.
- `area_coverage_matrix` — 147 rows, 2 KB. Per-research-area coverage metrics used by the Stats tab. Columns: area_id VARCHAR, dim VARCHAR, bucket VARCHAR, n_facilities BIGINT.

### People

Three human layers unified by `person_registry`: facility staff (`people`), the COD project team (`cod_team_members`), and the coastal-science scholar roster (`community_scholars`).

- `person_registry` — 10,095 rows, 1008 KB. Core tier only: the full population stays in the local DuckDB, so counts here are floors, not totals. Columns: canonical_id VARCHAR, display_name VARCHAR, name_family VARCHAR, name_given VARCHAR, orcid VARCHAR, openalex_id VARCHAR, google_scholar_id VARCHAR, scopus_author_id VARCHAR, wos_researcher_id VARCHAR, homepage_url VARCHAR, affiliation VARCHAR, affiliation_ror VARCHAR, affiliation_country VARCHAR, is_team BOOLEAN, is_site_personnel BOOLEAN, is_scholar BOOLEAN, person_id VARCHAR, scholar_id VARCHAR, works_count INTEGER, cited_by_count BIGINT, h_index INTEGER, i10_index INTEGER, two_yr_mean_citedness DOUBLE, coastal_works_count INTEGER, coastal_share DOUBLE, first_pub_year INTEGER, tier VARCHAR, tier_rank INTEGER, tier_score DOUBLE, source VARCHAR, source_url VARCHAR, confidence VARCHAR, retrieved_at VARCHAR, notes VARCHAR.
- `person_identity_source` — 10,728 rows, 323 KB. Which rule (ORCID equality, OpenAlex id) bound each identifier, and its conflicts. Columns: canonical_id VARCHAR, field VARCHAR, value VARCHAR, method VARCHAR, evidence VARCHAR, source_url VARCHAR, confidence VARCHAR, retrieved_at VARCHAR.
- `people` — 280 rows, 32 KB. Columns: person_id VARCHAR, name VARCHAR, name_family VARCHAR, name_given VARCHAR, email VARCHAR, orcid VARCHAR, openalex_id VARCHAR, scopus_author_id VARCHAR, wos_researcher_id VARCHAR, google_scholar_id VARCHAR, homepage_url VARCHAR, photo_url VARCHAR, research_interests VARCHAR, bio VARCHAR, status VARCHAR, notes VARCHAR, created_at TIMESTAMP, updated_at TIMESTAMP.
- `facility_personnel` — 246 rows, 32 KB. Columns: person_id VARCHAR, facility_id VARCHAR, role VARCHAR, title VARCHAR, is_key_personnel BOOLEAN, start_date DATE, end_date DATE, source VARCHAR, source_url VARCHAR, retrieved_at DATE, confidence VARCHAR, notes VARCHAR.
- `registry_facilities` — 263 rows, 5 KB. Researcher-to-site links joined on ROR equality only. Columns: canonical_id VARCHAR, facility_id VARCHAR, ror VARCHAR, method VARCHAR, confidence VARCHAR, retrieved_at VARCHAR.
- `cod_wbs` — 52 rows, 3 KB. Work-breakdown hierarchy for the COD project org chart. Columns: wbs_code VARCHAR, parent_code VARCHAR, title VARCHAR, lead_person_id VARCHAR, sort_order INTEGER, notes VARCHAR.
- `cod_team_members` — 67 rows, 8 KB. Member_id is NOT unique (57 distinct over 67 rows). Columns: member_id VARCHAR, person_id VARCHAR, display_name VARCHAR, wbs_code VARCHAR, role VARCHAR, institution VARCHAR, institution_slug VARCHAR, is_pi BOOLEAN, is_copi BOOLEAN, is_leadership_committee BOOLEAN, committees VARCHAR, status VARCHAR, sort_order INTEGER, source VARCHAR, notes VARCHAR.
- `community_scholars` — 523 rows, 102 KB. Gated on a coastal-topic share, not name matching. Columns: scholar_id VARCHAR, person_id VARCHAR, name VARCHAR, orcid VARCHAR, openalex_id VARCHAR, google_scholar_id VARCHAR, affiliation VARCHAR, affiliation_country VARCHAR, affiliation_ror VARCHAR, homepage_url VARCHAR, works_count INTEGER, cited_by_count INTEGER, h_index INTEGER, i10_index INTEGER, two_yr_mean_citedness DOUBLE, coastal_works_count INTEGER, coastal_recent_works INTEGER, first_pub_year INTEGER, is_preeminent BOOLEAN, is_most_active BOOLEAN, is_rising BOOLEAN, rank_preeminent INTEGER, rank_most_active INTEGER, rank_rising INTEGER, top_topics VARCHAR, rationale VARCHAR, source VARCHAR, source_url VARCHAR, confidence VARCHAR, retrieved_at DATE.
- `scholar_area_assignments` — 442 rows, 17 KB. Not registered by the site's own app; externally queryable. Columns: canonical_id VARCHAR, name VARCHAR, assigned_area VARCHAR, topic_vote_confidence DOUBLE, h_index INTEGER.
- `person_areas` — 1,065 rows, 14 KB. Columns: person_id VARCHAR, area_id VARCHAR, weight DOUBLE, evidence_count INTEGER, source VARCHAR.
- `person_area_metrics` — 2,704 rows, 50 KB. Columns: area_id VARCHAR, person_id VARCHAR, person_name VARCHAR, n_publications BIGINT, total_citations DOUBLE, h_index BIGINT, n_co_authors BIGINT, composite_z DOUBLE.

### Publications and collaboration

Bibliometric layer harvested from OpenAlex, plus the co-authorship graphs and the identifier-validation audit trail.

- `publications` — 12,505 rows, 1.43 MB. Columns: publication_id VARCHAR, doi VARCHAR, title VARCHAR, abstract VARCHAR, pub_year INTEGER, pub_type VARCHAR, journal VARCHAR, venue VARCHAR, cited_by_count INTEGER, openalex_id VARCHAR, scopus_eid VARCHAR, wos_uid VARCHAR, url VARCHAR, source VARCHAR, retrieved_at DATE, created_at TIMESTAMP.
- `authorship` — 8,772 rows, 85 KB. Columns: person_id VARCHAR, publication_id VARCHAR, author_position INTEGER, is_corresponding BOOLEAN, raw_name VARCHAR.
- `publication_topics` — 356,201 rows, 3.41 MB. OpenAlex lists a work under every topic it carries, so summing over a topic set double-counts multi-topic works. Columns: publication_id VARCHAR, concept_id VARCHAR, concept_name VARCHAR, score DOUBLE, level INTEGER, kind VARCHAR, source VARCHAR.
- `collaborations` — 116 rows, 4 KB. Columns: person_a_id VARCHAR, person_b_id VARCHAR, co_pub_count INTEGER, first_year INTEGER, last_year INTEGER, strength DOUBLE.
- `registry_collaborations` — 5,300 rows, 40 KB. Core-to-core co-publication edges only. Columns: canonical_id_a VARCHAR, canonical_id_b VARCHAR, co_pub_count INTEGER, first_year INTEGER, last_year INTEGER, shared_areas VARCHAR, shared_facilities VARCHAR.
- `coauthor_edges` — 213,021 rows, 10.34 MB. Every row names the OpenAlex Work that proves it and the identifier-equality rule that matched it. Columns: edge_id VARCHAR, canonical_id_a VARCHAR, canonical_id_b VARCHAR, co_pub_count INTEGER, first_year INTEGER, last_year INTEGER, weight DOUBLE, exemplar_work_id VARCHAR, exemplar_work_doi VARCHAR, exemplar_work_year INTEGER, evidence_work_ids VARCHAR, evidence_truncated BOOLEAN, match_method VARCHAR, shared_areas VARCHAR, shared_facilities VARCHAR, same_institution BOOLEAN, source VARCHAR, source_url VARCHAR, retrieved_at VARCHAR, confidence VARCHAR, run_id VARCHAR.
- `coauthor_candidates` — 43,355 rows, 3.24 MB. Review queue, NOT personnel records: co-authors seen on registry members' works who are not registry rows. Columns: candidate_id VARCHAR, display_name VARCHAR, orcid VARCHAR, openalex_id VARCHAR, affiliation VARCHAR, affiliation_ror VARCHAR, affiliation_country VARCHAR, seen_with_canonical_id VARCHAR, seen_on_work_id VARCHAR, n_registry_coauthors INTEGER, n_shared_works INTEGER, works_count INTEGER, coastal_works_count INTEGER, coastal_share DOUBLE, h_index INTEGER, decision VARCHAR, decided_by VARCHAR, decided_at VARCHAR, ambiguity_note VARCHAR, source VARCHAR, source_url VARCHAR, retrieved_at VARCHAR, confidence VARCHAR, run_id VARCHAR, notes VARCHAR.
- `person_validation` — 40,380 rows, 1.93 MB. Append-only: one row per (registry row, check, run), so filter to the latest run_id before counting. Columns: validation_id VARCHAR, canonical_id VARCHAR, check_id VARCHAR, subject_id_type VARCHAR, subject_id_value VARCHAR, verdict VARCHAR, http_status INTEGER, evidence VARCHAR, mismatch_detail VARCHAR, method VARCHAR, source VARCHAR, source_url VARCHAR, retrieved_at VARCHAR, confidence VARCHAR, run_id VARCHAR, notes VARCHAR.

### Funding

Award-level funding events and their rollups. Amounts are NOMINAL USD: no inflation adjustment is applied anywhere in the published tables.

- `funders` — 91 rows, 4 KB. Columns: funder_id VARCHAR, name VARCHAR, type VARCHAR, country VARCHAR, url VARCHAR, notes VARCHAR.
- `funding_events` — 3,634 rows, 203 KB. Columns: event_id VARCHAR, funder_id VARCHAR, facility_id VARCHAR, amount_usd DOUBLE, amount_currency VARCHAR, fiscal_year INTEGER, period_start DATE, period_end DATE, award_id VARCHAR, award_title VARCHAR, program VARCHAR, relation VARCHAR, source VARCHAR, source_url VARCHAR, retrieved_at DATE, confidence VARCHAR, notes VARCHAR, created_at TIMESTAMP.
- `funding_links` — 3,634 rows, 80 KB. A 7-column projection of funding_events kept for backwards compatibility, materialised as its own file; same 3,634 rows. Columns: funder_id VARCHAR, facility_id VARCHAR, amount_usd DOUBLE, fiscal_year INTEGER, award_id VARCHAR, relation VARCHAR, source_url VARCHAR.
- `facility_area_funding` — 54 rows, 5 KB. Columns: area_id VARCHAR, facility_id VARCHAR, facility_name VARCHAR, facility_acronym VARCHAR, country VARCHAR, n_funding_events BIGINT, total_usd_nominal DOUBLE, n_distinct_funders BIGINT, min_fy INTEGER, max_fy INTEGER, funder_top1_name VARCHAR, funder_top1_usd DOUBLE.
- `funder_area_funding` — 45 rows, 3 KB. Columns: area_id VARCHAR, funder_id VARCHAR, funder_name VARCHAR, funder_type VARCHAR, n_events BIGINT, total_usd DOUBLE, n_facilities BIGINT.
- `cpi_index_us` — 0 rows, 1 KB. Intentionally EMPTY — the deflator series is not loaded, so no real-dollar view can be computed yet. Not registered by the site's own app; externally queryable. Columns: year INTEGER, cpi_u DOUBLE, source VARCHAR.

### Coastal datasets

Curated catalogue of external coastal datasets and their machine-readable access endpoints.

- `coastal_datasets` — 72 rows, 45 KB. Columns: dataset_id VARCHAR, name VARCHAR, acronym VARCHAR, provider VARCHAR, program VARCHAR, parent_dataset_id VARCHAR, category VARCHAR, description VARCHAR, network_id VARCHAR, spatial_coverage VARCHAR, temporal_start INTEGER, temporal_end INTEGER, license VARCHAR, doi VARCHAR, homepage_url VARCHAR, variables VARCHAR, update_frequency VARCHAR, source VARCHAR, source_url VARCHAR, retrieved_at DATE, confidence VARCHAR, notes VARCHAR.
- `dataset_endpoints` — 242 rows, 16 KB. Columns: dataset_id VARCHAR, endpoint_type VARCHAR, url VARCHAR, label VARCHAR, format_notes VARCHAR, auth_required BOOLEAN.
- `dataset_facilities` — 48 rows, 5 KB. Columns: dataset_id VARCHAR, facility_id VARCHAR, role VARCHAR, method VARCHAR, confidence VARCHAR, evidence VARCHAR, source VARCHAR, source_url VARCHAR, retrieved_at DATE.

### Knowledge-map layout

Precomputed groupings and coordinates that drive the Network tab's MVG cartogram. Derived artifacts, not source data.

- `facility_primary_groups` — 3,519 rows, 61 KB. Columns: facility_id VARCHAR, primary_area_id VARCHAR, primary_area_label VARCHAR, score DOUBLE.
- `person_primary_groups` — 280 rows, 8 KB. Columns: person_id VARCHAR, primary_area_id VARCHAR, primary_area_label VARCHAR, score DOUBLE, source VARCHAR.
- `mvg_node_layout` — 713 rows, 64 KB. Not registered by the site's own app; externally queryable. Columns: node_uid VARCHAR, name VARCHAR, source_id VARCHAR, cohort VARCHAR, area_label VARCHAR, degree BIGINT, connected BOOLEAN, kmap_x DOUBLE, kmap_y DOUBLE, pcl_x DOUBLE, pcl_y DOUBLE.
- `mvg_area_polygons` — 21 rows, 27 KB. Not registered by the site's own app; externally queryable. Columns: research_area VARCHAR, n_nodes BIGINT, n_leadership BIGINT, n_personnel BIGINT, n_scholar BIGINT, polygon_area DOUBLE, area_share DOUBLE, size_share DOUBLE, wkt VARCHAR.
- `mvg_layout_metrics` — 2 rows, 8 KB. Two rows: before/after metrics for the cartogram layout. Not registered by the site's own app; externally queryable. Columns: method VARCHAR, nodes BIGINT, edges BIGINT, groups BIGINT, M1 DOUBLE, M2 DOUBLE, M3 DOUBLE, M4 DOUBLE, M5 DOUBLE, M6 DOUBLE, M7 DOUBLE, within_crossings BIGINT, between_crossings BIGINT, total_crossings BIGINT.

## What is queryable where

Three different things are easy to confuse. Only the first is reachable over HTTP.

**1. Parquet tables — queryable by anyone.** All 46 files under `/public/parquet/` are fetchable and range-readable by any external DuckDB, pandas or Arrow client. Nothing else on this site is a queryable relation.

   Note: `cpi_index_us`, `mvg_area_polygons`, `mvg_layout_metrics`, `mvg_node_layout`, `provenance`, `scholar_area_assignments` are published and externally queryable, but are NOT registered by the site's own `src/db.js`, so the in-app SQL tab cannot see them. That asymmetry affects the app only, not you.

**2. Helper views recreated in the browser — not fetchable.** `src/db.js` recreates 6 views inside DuckDB-Wasm on first use of the SQL tab: `v_facility_funding_by_year`, `v_funder_funding_by_year`, `v_facility_key_personnel`, `v_funding_ledger`, `v_person_enriched`, `v_cod_team_enriched`. A view is not a file, so these have no URL. To use one externally, copy its `CREATE OR REPLACE VIEW` body from https://raw.githubusercontent.com/tyson-swetnam/cod-kmap/main/src/db.js (the `helperViews` array) or from https://raw.githubusercontent.com/tyson-swetnam/cod-kmap/main/schema/schema.sql, and run it against the Parquet tables above — all of their base tables are published.

**3. Views that exist only in the repo schema — not available either place.** `v_facility_map`, `v_facility_enriched`, `v_region_enriched`, `v_facility_funding_by_year_real`, `v_person_areas_enriched`, `v_person_validation_latest`, `v_person_validation_summary`, `v_coauthor_edges_enriched` are defined in `schema/schema.sql` but are NOT recreated in the browser. Reproduce them against a local DuckDB built from the committed Parquet (`python scripts/rebuild_db_from_parquet.py`), or inline their SQL. `v_facility_funding_by_year_real` additionally needs `cpi_index_us`, which ships with zero rows, so it cannot return real-dollar figures yet.

To run SQL that uses bare table names, bind them first:

```sql
INSTALL httpfs; LOAD httpfs;
CREATE OR REPLACE VIEW facilities AS SELECT * FROM
  read_parquet('https://tyson-swetnam.github.io/cod-kmap/public/parquet/facilities.parquet');
CREATE OR REPLACE VIEW funding_events AS SELECT * FROM
  read_parquet('https://tyson-swetnam.github.io/cod-kmap/public/parquet/funding_events.parquet');
-- ...one per table you need, then run the query verbatim.
```

## Other data endpoints

- [facilities.geojson](https://tyson-swetnam.github.io/cod-kmap/public/facilities.geojson): all catalogued facilities as GeoJSON points, the map's first-paint fallback. Properties: `id`, `name`, `acronym`, `type`, `country`, `parent_org`, `url`. Use this if you want coordinates without a Parquet reader.
- [overlays/manifest.json](https://tyson-swetnam.github.io/cod-kmap/public/overlays/manifest.json): index of the polygon overlay layers — label, colour, category, and for the newer layers the authoritative source and feature count. Each key `<id>` resolves to `https://tyson-swetnam.github.io/cod-kmap/public/overlays/<id>.geojson`.
- [vocab/facility_types.csv](https://tyson-swetnam.github.io/cod-kmap/public/vocab/facility_types.csv) (`slug,label,description`), [vocab/research_areas.csv](https://tyson-swetnam.github.io/cod-kmap/public/vocab/research_areas.csv) (`slug,label,gcmd_uri,parent_slug`), [vocab/networks.csv](https://tyson-swetnam.github.io/cod-kmap/public/vocab/networks.csv) (`slug,label,aliases,level,url`): the controlled vocabularies behind `facilities.facility_type`, `research_areas` and `networks`. MIND THE COLUMN NAMES: every CSV calls its key `slug`, but in Parquet only `facility_types` does — the others are `research_areas.area_id` and `networks.network_id` (and the CSV's `parent_slug` is `research_areas.parent_id`). The VALUES are identical slugs; only the column names differ, so `research_areas.slug` and `networks.slug` are binder errors, not empty results. `gcmd_uri` is populated for only 3 of the 40 research areas.
- [parquet/schema.json](https://tyson-swetnam.github.io/cod-kmap/public/parquet/schema.json): every table's columns, types and row count, as JSON. Fetch this instead of reading 46 Parquet footers.

## Provenance and how much to trust this

- Every facility record carries `source_url`, `retrieved_at` and a `confidence` grade; the `provenance` table holds them per record. Prefer high-confidence rows and cite the `source_url`, not this site.
- People are linked to publications on ORCID or OpenAlex-id equality **only, never by name**. A missing identifier is deliberate; it is not a gap to be filled by guessing.
- Funding amounts are nominal USD with no inflation adjustment.
- Tables marked core-tier publish a subset of the pipeline's full output, so aggregate counts are floors.
- Co-authorship degree 0 means *unmeasured*, not *publishes alone*: the graph harvest covers a fraction of registry identities.
- `*_plan.md` pages marked draft above describe intended work. Do not read them as descriptions of shipped features.
- Full method and caveat detail: https://tyson-swetnam.github.io/cod-kmap/docs/METHODS.md and https://tyson-swetnam.github.io/cod-kmap/docs/person_registry.md.

## Worked examples

Against the published Parquet, with no local data. All four run in a plain DuckDB shell.

```sql
-- 1. Facility counts by type, resolved through the vocabulary.
INSTALL httpfs; LOAD httpfs;
SELECT ft.label AS facility_type, count(*) AS n
FROM 'https://tyson-swetnam.github.io/cod-kmap/public/parquet/facilities.parquet' f
JOIN 'https://tyson-swetnam.github.io/cod-kmap/public/parquet/facility_types.parquet' ft
  ON ft.slug = f.facility_type
GROUP BY 1 ORDER BY n DESC;
```

```sql
-- 2. Who funds the most distinct facilities.
SELECT fu.name AS funder, fu.type,
       count(DISTINCT fl.facility_id) AS facilities
FROM 'https://tyson-swetnam.github.io/cod-kmap/public/parquet/funding_links.parquet' fl
JOIN 'https://tyson-swetnam.github.io/cod-kmap/public/parquet/funders.parquet' fu
  USING (funder_id)
GROUP BY 1, 2 ORDER BY facilities DESC LIMIT 20;
```

```sql
-- 3. Current key personnel with a resolved ORCID.
SELECT f.acronym, f.canonical_name, p.name, fp.role, p.orcid
FROM 'https://tyson-swetnam.github.io/cod-kmap/public/parquet/facility_personnel.parquet' fp
JOIN 'https://tyson-swetnam.github.io/cod-kmap/public/parquet/people.parquet' p USING (person_id)
JOIN 'https://tyson-swetnam.github.io/cod-kmap/public/parquet/facilities.parquet' f USING (facility_id)
WHERE fp.is_key_personnel AND p.orcid IS NOT NULL
ORDER BY f.canonical_name, p.name;
```

```python
# 4. Same idea from Python, no DuckDB: read one column of one table.
import pandas as pd
base = "https://tyson-swetnam.github.io/cod-kmap/public/parquet/"
df = pd.read_parquet(base + "facilities.parquet",
                     columns=["canonical_name", "country", "facility_type"])
print(df.value_counts("country").head())
```

More recipes, and one example per table group: https://tyson-swetnam.github.io/cod-kmap/docs/data_endpoints.md

## Application routes (for people, not fetchable)

The app is a hash router, so these are fragments of the single page at https://tyson-swetnam.github.io/cod-kmap/ — they are not separate URLs and are deliberately absent from sitemap.xml. Listed so you can point a human at the right tab.

`#/` map · `#/browse` facility list · `#/network` MVG cartogram · `#/people` roster · `#/org` COD org chart · `#/data` dataset catalogue · `#/sql` SQL console · `#/stats` per-area dashboards · `#/docs/<slug>` documentation. Doc slugs are the filename stem, lower-cased, with underscores turned into dashes: `docs/for_ai_agents.md` is `#/docs/for-ai-agents`.

## Meta

- [Full documentation corpus in one file](https://tyson-swetnam.github.io/cod-kmap/llms-full.txt): every page above, concatenated, links made absolute. Prefer it over fetching pages one at a time.
- [For AI agents](https://tyson-swetnam.github.io/cod-kmap/docs/for_ai_agents.md): endpoints, trust signals, and what to do if your sandbox cannot reach this host.
- [Data endpoints](https://tyson-swetnam.github.io/cod-kmap/docs/data_endpoints.md): the per-table reference with worked recipes.
- [robots.txt](https://tyson-swetnam.github.io/cod-kmap/robots.txt) and [sitemap.xml](https://tyson-swetnam.github.io/cod-kmap/sitemap.xml). Note that the authoritative crawl policy is the origin root's: https://tyson-swetnam.github.io/robots.txt
- [Source repository](https://github.com/tyson-swetnam/cod-kmap): the pipeline that builds all of this. Rules for coding agents: https://github.com/tyson-swetnam/cod-kmap/blob/main/AGENTS.md. Canonical schema: https://github.com/tyson-swetnam/cod-kmap/blob/main/schema/schema.sql.
- Licence: MIT. Third-party data under `data/raw/synthesis-networks/` keeps its upstream MIT licence.