US dams example dashboard (#1350)

Adds US dams showcase example

Author: allisonhorst

docs/assets/us-dams-dark.webp

@@ -35,6 +35,12 @@
 
 [Source](./mortgage-rates) · This dashboard visualizes Freddie Mac’s historical mortgage rates data. The included data loader demonstrates how to retrieve CSV data from Freddie Mac and visualize the result as a zoomable chart with Observable Plot. The larger time-series line chart at the bottom allows brushing to select an arbitrary time range, while the smaller visualization above zooms to show the selected range.
 
+### [`us-dams`](https://observablehq.observablehq.cloud/framework-example-us-dams/) - U.S. dam conditions
+
+<a href="https://observablehq.observablehq.cloud/framework-example-us-dams/"><img src="../docs/assets/us-dams.webp" alt="U.S. dams" width="312" height="237"></a>
+
+[Source](./us-dams) · This dashboard visualizes locations and conditions for 90k+ dams in the U.S. with data from the National Inventory of Dams (NID). An R data loader accesses the data directly from the NID and generates a simplified CSV. Maps created with deck.gl allow a user to zoom and scroll while exploring dam locations nationwide, or by state. Bar and bubble charts made in Observable Plot highlight dam conditions and hazard potential.
+
 ## Technique examples 🛠️
 
 ### Charts

docs/assets/us-dams.webp

@@ -0,0 +1,8 @@
+.DS_Store
+dist/
+src/.observablehq/cache/
+node_modules/
+yarn-error.log
+src/.observablehq/deploy.json
+.Rhistory
+.Rdata

examples/README.md

@@ -0,0 +1,39 @@
+[Framework examples →](../)
+
+# U.S. dams
+
+View live: <https://observablehq.observablehq.cloud/framework-example-us-dams/>
+
+This Observable Framework example explores data for 90,000+ dams in the United States from the [National Inventory of Dams](https://nid.sec.usace.army.mil/) (NID).
+
+The pages feature nationwide and state-by-state summaries of dam locations, highlighting dam conditions and hazard assessment.
+
+Interactive maps are created with [deck.gl](https://deck.gl/). To create your own maps with deck.gl in Observable Framework, see our [documentation](https://observablehq.com/framework/lib/deckgl). All other charts are built with [Observable Plot](https://observablehq.com/plot/), and searchable tables are created with Observable Inputs by combining [Inputs.search and Inputs.table](https://observablehq.com/framework/inputs/search).
+
+## Implementation
+
+```
+.
+├── README.md
+├── observablehq.config.js
+├── package.json
+└── src
+    ├── data
+    │   ├── county_fips_master.csv
+    │   ├── dam-simple.csv.R
+    │   └── us-state-capitals.csv
+    ├── by-state.md
+    └── index.md
+```
+
+The R data loader `dam-simple.csv.R` accesses data directly from the NID (at https://nid.sec.usace.army.mil/api/nation/csv) and generates the `dam-simple.csv` snapshot used in both pages. To run the data loader, you need to have [R](https://www.r-project.org/) installed, along with the [data.table](https://github.com/Rdatatable/data.table), [dplyr](https://github.com/tidyverse/dplyr), and [readr](https://github.com/tidyverse/readr) packages (e.g. with `install.packages("dplyr")`).
+
+### Data
+
+- Dam records are accessed from the NID API as a CSV, then minimally wrangled by the `dam-simple.csv.R` data loader to produce the static file with dam records used in our dashboard (`dam-simple.csv`)
+
+- County FIPS codes (`src/data/county_fips_master.csv`) are from https://github.com/kjhealy/fips-codes/blob/master/county_fips_master.csv
+
+- US state capitals and locations (`src/data/us-state-capitals.csv`) are from https://github.com/jasperdebie/VisInfo/blob/master/us-state-capitals.csv
+
+- County, state, and nation-level spatial polygons are accessed from the [us-atlas](https://www.npmjs.com/package/us-atlas?activeTab=readme) repository

examples/us-dams/.gitignore

@@ -0,0 +1,8 @@
+export default {
+  root: "src",
+  title: "U.S. dams overview",
+  theme: "wide",
+  sidebar: true,
+  pager: false,
+  toc: false
+};

examples/us-dams/README.md

@@ -0,0 +1,24 @@
+{
+  "type": "module",
+  "private": true,
+  "scripts": {
+    "clean": "rimraf src/.observablehq/cache",
+    "build": "rimraf dist && observable build",
+    "dev": "observable preview",
+    "deploy": "observable deploy",
+    "observable": "observable"
+  },
+  "dependencies": {
+    "@observablehq/framework": "^1.7.1",
+    "d3-dsv": "^3.0.1",
+    "d3-time-format": "^4.1.0",
+    "topojson-client": "^3.1.0",
+    "topojson-simplify": "^3.0.3"
+  },
+  "devDependencies": {
+    "rimraf": "^5.0.5"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}