31:T971,fills = { let choropleth = html`

`; yield choropleth; let map = new mapboxgl.Map({ container: "fills", accessToken, style: "mapbox://styles/fndvit/cmizz9o6b004n01sa2ke19nlr", center: [2.84, 41.985], zoom: 12, minZoom: 11.5, maxBounds: [ [2.7, 41.75], [3.1, 42.25] ] }); let hoveredPolygonId = null; map.on("load", function () { map.addSource("census_tracts", { type: "vector", url: "mapbox://fndvit.6inpb1f7", promoteId: "id" }); map.addLayer( { id: "census_tracts-fill", type: "fill", source: "census_tracts", "source-layer": "girona_census_tracts-22y6s7", paint: { "fill-color": "#8AD5EE" } }, "water" ); map.addLayer( { id: "census_tracts-line", type: "line", source: "census_tracts", "source-layer": "girona_census_tracts-22y6s7", paint: { "line-color": "#000000", "line-width": [ "case", ["boolean", ["feature-state", "hover"], false], 1, 0 ] } }, "settlement-subdivision-label" ); map.on("mousemove", "census_tracts-fill", (e) => { if (e.features.length > 0) { if (hoveredPolygonId !== null) { map.setFeatureState( { source: "census_tracts", sourceLayer: "girona_census_tracts-22y6s7", id: hoveredPolygonId }, { hover: false } ); } hoveredPolygonId = e.features[0].id; mutable hoveredPolygonId = hoveredPolygonId; map.setFeatureState( { source: "census_tracts", sourceLayer: "girona_census_tracts-22y6s7", id: hoveredPolygonId }, { hover: true } ); } }); map.on("mouseleave", "census_tracts-fill", () => { if (hoveredPolygonId !== null) { map.setFeatureState( { source: "census_tracts", sourceLayer: "girona_census_tracts-22y6s7", id: hoveredPolygonId }, { hover: false } ); } hoveredPolygonId = null; mutable hoveredPolygonId = hoveredPolygonId; }); }); invalidation.then(() => map.remove()); }32:T1a6c,## A simple map of census tracts The cell pinned above creates a simple map that: - renders Girona census tracts from a vector tileset, - shows them as a blue base, - highlights the tract under the mouse using feature-state, - cleans up the map when the cell is re-run or removed. Here's a step-by-step explanation. You'll need to read the **['Understanding color expressions' guide](https://observablehq.com/@udg-master-data-science/5th-hackathon-map-tutorials#cell-461)** to create a choropleth —I wasn't about to spoon feed y'all everything 😉 ### Observable cell wrapper and DOM container ```js map = { let choropleth = html`

`; yield choropleth; … } ``` - `map = { … }` defines a generator cell in Observable. - `html\…` creates a `

` element with `id="map"` and a fixed height; Mapbox uses this as the map container. - `yield choropleth`; renders that DOM element into the notebook before the map is fully ready, so you don’t get a blank cell while Mapbox initializes. Once yielded, the rest of the code runs and attaches the Mapbox map to this `

`. ### Initializing the Mapbox GL map ```js let map = new mapboxgl.Map({ container: "map", accessToken, style: "mapbox://styles/fndvit/cmizz9o6b004n01sa2ke19nlr", center: [2.84, 41.985], zoom: 12, minZoom: 11.5, maxBounds: [ [-0.9, 39.6], [4.5, 44.3] ] }); ``` - `container: "map"` binds the map to the `

` you just yielded. - `accessToken` is read from another cell (you'll need to create your own, and you define it elsewhere, in a cell or in a secret). - `style` points to a custom Mapbox style. - `center` and `zoom` focus the map on Girona. - `minZoom` prevents zooming out too far (keeps the map focused on the city). - `maxBounds` clamps panning so users can’t drag completely away from Catalunya. This section bootstraps a standard Mapbox GL map with your preferred view and constraints. ### Adding the census tracts source Inside the load event: ```js map.on("load", function () { map.addSource("census_tracts", { type: "vector", url: "mapbox://fndvit.6inpb1f7", promoteId: "id" }); … }); ``` - `map.on("load", …)` ensures you only add sources and layers once the base style has loaded. - `addSource("census_tracts", …)` registers a vector tileset containing Girona census tracts. - `promoteId: "id"` promotes the `id` property on each feature to be the Mapbox feature id. This is important: `feature-state` requires a stable `id` per feature to work. From now on you reference this source by name (`"census_tracts"`) in your layers. ### Fill layer: drawing the polygons ```js map.addLayer( { id: "census_tracts-fill", type: "fill", source: "census_tracts", "source-layer": "girona_census_tracts-22y6s7", paint: { "fill-color": "#DCDCDC" } }, "water" ); ``` - `type: "fill"` draws the census tracts as solid polygons. - `"source-layer"` is the internal layer name inside the vector tileset. - `"fill-color": "#DCDCDC"` gives a neutral grey fill — a base choropleth canvas. - The second argument` "water"` inserts this layer just above the water layer in your style’s layer stack, so it sits below labels and other overlays. At this point you have a plain grey map of census tracts. ### Line layer: outlines with hover styling ```js map.addLayer( { id: "census_tracts-line", type: "line", source: "census_tracts", "source-layer": "girona_census_tracts-22y6s7", paint: { "line-color": "#000000", "line-width": [ "case", ["boolean", ["feature-state", "hover"], false], 1, 0 ] } }, "settlement-subdivision-label" ); ``` - `type: "line"` draws only the borders of each census tract. - `"line-color": "#000000"` makes them black. - `"line-width"` uses a Mapbox expression, read as if `feature-state["hover"]` is `true` → `line width = 1`, otherwise → `line width = 0` (invisible). - the layer is inserted before `settlement-subdivision-label`, so labels render above the outlines. This sets up the visual part of the hover effect. ### Mouse interaction with feature-state #### Mouse move over polygons: ```js map.on("mousemove", "census_tracts-fill", (e) => { if (e.features.length > 0) { if (hoveredPolygonId !== null) { map.setFeatureState( { source: "census_tracts", sourceLayer: "girona_census_tracts-22y6s7", id: hoveredPolygonId }, { hover: false } ); } hoveredPolygonId = e.features[0].id; mutable hoveredPolygonId = hoveredPolygonId; map.setFeatureState( { source: "census_tracts", sourceLayer: "girona_census_tracts-22y6s7", id: hoveredPolygonId }, { hover: true } ); } }); ``` - `map.on("mousemove", "census_tracts-fill", …)` listens for mouse movement over that layer only. - `e.features[0].id` is the feature currently under the cursor (thanks to `promoteId`). If there was a previously hovered feature `(hoveredPolygonId !== null)`, its `feature-state.hover` is set to false. Then: - **`hoveredPolygonId`** is updated to the new feature’s id. - `mutable hoveredPolygonId = hoveredPolygonId` updates the Observable mutable variable, so other cells can react to which tract is hovered (e.g. show a sidebar with details). - `setFeatureState` sets `{ hover: true }` for the newly hovered feature. Because the line layer’s `line-width` depends on `feature-state.hover`, the outline appears only around the current polygon. #### Mouse leaving the layer: ```js map.on("mouseleave", "census_tracts-fill", () => { if (hoveredPolygonId !== null) { map.setFeatureState( { source: "census_tracts", sourceLayer: "girona_census_tracts-22y6s7", id: hoveredPolygonId }, { hover: false } ); } hoveredPolygonId = null; mutable hoveredPolygonId = hoveredPolygonId; }); ``` When the mouse leaves the `census_tracts-fill` layer entirely, the last hovered feature has its hover flag turned off. - `hoveredPolygonId` is reset to null. - The mutable is updated so any linked UI can also clear its highlight. This ensures no feature remains “stuck” highlighted after you move the mouse away. ### Cleanup on cell invalidation `invalidation.then(() => map.remove());` It is an Observable promise that resolves when: - the cell is re-run, - or the notebook state changes so the cell needs to be cleaned up. - `map.remove()` tears down the Mapbox instance: it removes the canvas, event listeners, and internal state. This prevents memory leaks and overlapping maps when you edit the code, and Observable re-executes the cell.33:T644,### What Mapbox is expecting When you set a layer’s `fill-color`, Mapbox lets you pass an expression instead of a fixed color. Two expressions matter here: #### `match` Looks up a value based on a feature’s property —it's great for joining external data to features using an ID. `["match", input, key1, value1, key2, value2, ..., defaultValue]` #### `step` Buckets a numeric input into a set of colors —perfect for choropleths. `["step", input, baseColor, stop1, color1, stop2, color2, ...]` ### Why expressions become painful To color features using external data, you have to: - Map feature IDs to values (match). - Feed that resulting value into a step scale. - Build both arrays in the exact order Mapbox expects. - Nest them correctly. Writing this by hand is error-prone, repetitive, and unreadable — especially with dozens or hundreds of entries. ### What the helper function does It automatically builds: - **A match expression** that maps each feature ID to the correct numeric value from your external dataset. - **A step expression** that constructs a color scale from the domain and range values you pass in. - **Nested!** So that Mapbox GL JS understands it, with the exact structure required for a data-driven choropleth. ### How to use it Just call: ```js createColorExpression( /*Your data*/, /*promoteId that identifies each feature*/, { id: /*id in your data to join*/, prop: /*variable name as String*/ }, { domain: [ /*Thresholds list*/ ], range: [ /*Colors list*/ ]} ) ``` Use that as your `"fill-color"` when you `paint` your layer, _et voilà!_:34:[{"id":"68845725c512339723821da7fc45a695a805a82cdef0bfe0fc79d524a2cb8dacb1e366c55d6933f801c717a7be736a56ce98495a68a31e6c93d77058976af857","href":"https://static.observableusercontent.com/files/68845725c512339723821da7fc45a695a805a82cdef0bfe0fc79d524a2cb8dacb1e366c55d6933f801c717a7be736a56ce98495a68a31e6c93d77058976af857","name":"emissions-per-municipi@2.json","type":"application/json","lastModified":1765370828219.12,"size":7790301},{"id":"fa9ad37f0455a41a630db2532d9902db92afa9bccc15a34fc7c7d2091473676c94802e5008ac85a2e8c9a6b1d7024059c6590bf2a49cc739c595bc4faabe6132","href":"https://static.observableusercontent.com/files/fa9ad37f0455a41a630db2532d9902db92afa9bccc15a34fc7c7d2091473676c94802e5008ac85a2e8c9a6b1d7024059c6590bf2a49cc739c595bc4faabe6132","name":"Screenshot 2025-12-11 at 17.14.36.png","type":"image/png","lastModified":1765469725647.444,"size":755185},{"id":"68c4992e5a1935ce5314bc74278f29de97c13e26f99a9b2561b63257db27cc2d733caf478ee5ad35162fe97af23083e82f11cc19ad6fb3045ce87362b7fed655","href":"https://static.observableusercontent.com/files/68c4992e5a1935ce5314bc74278f29de97c13e26f99a9b2561b63257db27cc2d733caf478ee5ad35162fe97af23083e82f11cc19ad6fb3045ce87362b7fed655","name":"girona_census_tracts.geojson","type":"application/geo+json","lastModified":1770222719922.441,"size":343357}] 2f:{"title":"Mapbox GL tutorial","cells":[{"id":793,"value":"

Mapbox GL tutorial

","pinned":false,"hidden":false,"mode":"html"},{"id":780,"value":"hackatoHero01","pinned":false,"hidden":false,"mode":"ojs"},{"id":0,"value":"# A hands-on tutorial on interactive maps with Mapbox GL\nYou already know `Plot`, and you already know [how to make maps with it](https://observablehq.com/@fndvit/dia-25-mapes-mes-mapes-i-no-tant-mapes) —and yet here you are, ready to make your live slightly more complicated in exchange for zooming, panning, and shiny hover states. If you’re feeling reckless, Mapbox GL gives you full control: tiles, layers, sources, and just enough complexity to keep things exciting. Don’t worry —we got you.","pinned":false,"hidden":false,"mode":"md"},{"id":933,"value":"---\nAlso in this collection:\n- [Brief](https://observablehq.com/@udg-master-data-science/5th-hackathon-brief?collection=@udg-master-data-science/5th-hackathon-affordable-housing)\n- [Schedule and teams](https://observablehq.com/@udg-master-data-science/5th-hackathon-teams-schedule-awards-and-grading?collection=@udg-master-data-science/5th-hackathon-affordable-housing)\n- [Datasets](https://observablehq.com/@udg-master-data-science/5th-hackathon-datasets?collection=@udg-master-data-science/5th-hackathon-affordable-housing)\n- [Tutorial on Mosaic and vgplot](https://observablehq.com/@udg-master-data-science/5th-hackathon-mosaic-tutorial?collection=@udg-master-data-science/5th-hackathon-affordable-housing)","pinned":false,"hidden":false,"mode":"md"},{"id":619,"value":"---\n🌏 More map materials:\n\n- [Observable's hands-on tutorial on maps](https://observablehq.com/@observablehq/build-your-first-map-with-observable-plot?collection=@observablehq/tutorial)\n- [Plot Gallery: Geo](https://observablehq.com/@observablehq/plot-gallery#geo)\n- [Maps, More Maps, and Not-Quite Maps](https://observablehq.com/@fndvit/dia-25-mapes-mes-mapes-i-no-tant-mapes) (In Catalan)\n\n---","pinned":false,"hidden":false,"mode":"md"},{"id":537,"value":"mutable hoveredPolygonId = null","pinned":false,"hidden":false,"mode":"ojs"},{"id":4,"value":"$31","pinned":true,"hidden":false,"mode":"ojs"},{"id":588,"value":"$32","pinned":false,"hidden":false,"mode":"md"},{"id":889,"value":"---\n\n## I can be a fill, I can be a dot, I can be any layer you want\n\nSwitching from a fill layer to a point layer is mostly about:\n\n- Providing a GeoJSON source with coordinates, and\n- Using type: `\"circle\"` (or `symbol`) instead of `fill`.\n\nYou need the point layers as a `GeoJSON`.","pinned":false,"hidden":false,"mode":"md"},{"id":852,"value":"girona_services","pinned":false,"hidden":false,"mode":"ojs"},{"id":856,"value":"Here's a helper function to convert the array above into `GeoJSON` points.","pinned":false,"hidden":false,"mode":"md"},{"id":858,"value":"pointsToGeoJSON = (points, [lon, lat], keys) => {\n return {\n type: \"FeatureCollection\",\n features: points\n .filter((d) => d[lon] != null && d[lat] != null)\n .map((d) => {\n const properties = keys\n ? Object.fromEntries(keys.map((k) => [k, d[k]]))\n : { ...d };\n\n return {\n type: \"Feature\",\n geometry: {\n type: \"Point\",\n coordinates: [d[lon], d[lat]]\n },\n properties\n };\n })\n };\n}","pinned":true,"hidden":false,"mode":"ojs"},{"id":860,"value":"services = pointsToGeoJSON(girona_services, [\"lon\", \"lat\"])","pinned":true,"hidden":false,"mode":"ojs"},{"id":843,"value":"Add a `GeoJSON` **source** for your points:\n\n```js\nmap.addSource(\"services_points\", {\n type: \"geojson\",\n data: services\n});\n```\n\nAdd a circle **layer** for the points:\n\n```js\nmap.addLayer(\n {\n id: \"services\",\n type: \"circle\",\n source: \"services_points\",\n paint: {\n \"circle-radius\": 4,\n \"circle-color\": \"#d7191c\",\n \"circle-opacity\": 0.8\n }\n },\n \"census_tracts-line\"\n);\n```\n\n- `type: \"circle\"` draws each feature as a point.\n- The layer is inserted above the tract outlines (`\"census_tracts-line\"`), so points sit on top of the polygons.\n- You can later replace `\"circle-color\"` with a data-driven color expression (e.g., by category).","pinned":false,"hidden":false,"mode":"md"},{"id":839,"value":"dots = {\n let choropleth = html`

`;\n yield choropleth;\n\n let map = new mapboxgl.Map({\n container: \"dots\",\n accessToken,\n style: \"mapbox://styles/fndvit/cmizz9o6b004n01sa2ke19nlr\",\n center: [2.84, 41.985],\n zoom: 12,\n minZoom: 11.5,\n maxBounds: [\n [2.7, 41.75],\n [3.1, 42.25]\n ]\n });\n\n map.on(\"load\", function () {\n map.addSource(\"services_points\", {\n type: \"geojson\",\n data: services\n });\n\n map.addLayer(\n {\n id: \"services\",\n type: \"circle\",\n source: \"services_points\",\n paint: {\n \"circle-radius\": 2,\n \"circle-color\": \"#0A1D3F\",\n \"circle-opacity\": 0.8\n }\n },\n \"bridge-simple\"\n );\n });\n\n invalidation.then(() => map.remove());\n}","pinned":false,"hidden":false,"mode":"ojs"},{"id":971,"value":"---\n## Dots in a polygon\nYou might need to find which polygons some dots belong to. There might be other ways to do it, but that's what [Turf's tag](https://turfjs.org/docs/api/tag) function was created for.\n\nYou need:","pinned":false,"hidden":false,"mode":"md"},{"id":999,"value":"- A polygon layer, a `GeoJSON` —like [**`girona_census_tracts`**](https://observablehq.com/@udg-master-data-science/5th-hackathon-map-tutorials#girona_census_tracts).\n- A points layer, also `GeoJSON` —like [**`services`**](https://observablehq.com/@udg-master-data-science/5th-hackathon-map-tutorials#services).\n- A unique **`id`** in the polygons —that'll be mapped to the points.\n- An **`id name`** for the property in the new, joined points layer that the method returns.","pinned":false,"hidden":false,"mode":"md"},{"id":1013,"value":"And you use it like so:","pinned":false,"hidden":false,"mode":"md"},{"id":1047,"value":"pointsWithTractTurf = turf.tag(\n services,\n girona_census_tracts,\n \"id\",\n \"census_tract\"\n)","pinned":true,"hidden":false,"mode":"ojs"},{"id":1069,"value":"And here's that points layer as a `CSV` with the new `census_tract` column for every point.","pinned":false,"hidden":false,"mode":"md"},{"id":1071,"value":"pointsJoinedAsCSV = pointsWithTractTurf.features.map((d) => d.properties)","pinned":false,"hidden":false,"mode":"ojs"},{"id":1073,"value":"pointsJoinedAsCSV","pinned":false,"hidden":false,"mode":"ojs"},{"id":461,"value":"---\n## Understanding Mapbox color expressions\nMapbox color expressions are powerful but notoriously awkward. They’re not JavaScript, but JSON-encoded mini-programs with strict positional syntax. This makes them great for data visualization and terrible to write by hand, especially when you need to join external data and then apply a color scale.\n\nI created a helper, so ... Relax.","pinned":false,"hidden":false,"mode":"md"},{"id":280,"value":"createColorExpression = (data, id, join, scheme) => {\n const { id: idJoin, prop: propJoin } = join;\n const { domain, range } = scheme;\n\n const colors = range.flatMap((color, index) => {\n return index < domain.length ? [color, domain[index]] : [color];\n });\n\n const colorExpression = [\"step\", [\"get\", propJoin], ...colors];\n\n const matchExpression = [\"match\", [\"get\", id]];\n\n data.forEach((entry) => {\n matchExpression.push(entry[idJoin], entry[propJoin]);\n });\n\n matchExpression.push(0);\n\n colorExpression[1] = matchExpression;\n\n return colorExpression;\n}","pinned":true,"hidden":false,"mode":"ojs"},{"id":769,"value":"$33","pinned":false,"hidden":false,"mode":"md"},{"id":940,"value":"map","pinned":false,"hidden":false,"mode":"ojs"},{"id":953,"value":"mapTooltip","pinned":false,"hidden":false,"mode":"ojs"},{"id":608,"value":"---\n### Addendum","pinned":false,"hidden":false,"mode":"md"},{"id":10,"value":"accessToken = \"pk.eyJ1IjoiZm5kdml0IiwiYSI6ImNrYzBzYjhkMDBicG4yc2xrbnMzNXVoeDIifQ.mrdvw_7AIeOwa5IgHLaHJg\"","pinned":false,"hidden":false,"mode":"ojs"},{"id":7,"value":"mapboxgl = {\n const gl = await require(\"mapbox-gl\");\n if (!gl.accessToken) {\n gl.accessToken = accessToken;\n const href = await require.resolve(\"mapbox-gl@1/dist/mapbox-gl.css\");\n document.head.appendChild(html``);\n }\n return gl;\n}","pinned":false,"hidden":false,"mode":"ojs"},{"id":40,"value":"simple = require(\"simple-statistics@7\")","pinned":false,"hidden":false,"mode":"ojs"},{"id":981,"value":"girona_census_tracts = FileAttachment(\"girona_census_tracts.geojson\").json()","pinned":false,"hidden":false,"mode":"ojs"},{"id":783,"value":"import { hackatoHero01 } from \"@udg-master-data-science/5th-hackathon-datasets\"","pinned":false,"hidden":false,"mode":"ojs"},{"id":849,"value":"import { girona_services } from \"@udg-master-data-science/5th-hackathon-datasets\"","pinned":false,"hidden":false,"mode":"ojs"},{"id":937,"value":"import { map, hovered, mouse, mapTooltip } from \"@fndvit/certificats-energetics\"","pinned":false,"hidden":false,"mode":"ojs"},{"id":961,"value":"d3 = require(\"d3-geo@3\")","pinned":false,"hidden":false,"mode":"ojs"},{"id":1042,"value":"turf = require(\"@turf/turf\")","pinned":false,"hidden":false,"mode":"ojs"}],"files":"$W34","stdlib":"1","titling":"auto"}