Rewrite the tutorials and README around the boundary endpoint, layered maps, and named arguments.

Author: Nathaniel Henry

README.md

@@ -52,16 +52,15 @@ A few terms come up throughout the API:
 - **Destination type.** A category of place, such as grocery stores or libraries.
   Each type has a numeric id. Look them up with `close.destination_types()`.
 - **Mode.** How someone travels: walk, bike, or transit.
-- **Isochrone** or **catchment.** Two views of the same reachability: the area you
-  can reach from a point within a time limit (an isochrone), or every block that
-  can reach a place (a catchment).
+- **Isochrone** or **catchment**: the area you can reach starting from a point
+  within a time limit, by a selected travel mode.
 
 ## Choosing an output
 
 Set `output` on the client, or per call:
 
-- `output = "spatial"` (the default) returns a GeoDataFrame where geometry applies
-  and a DataFrame otherwise. Block routes join census-block boundaries with
+- `output = "spatial"` (the default) returns a GeoDataFrame for inherently spatial
+  data and a DataFrame otherwise. Block routes join census-block boundaries with
   `pygris` (the `tiger` extra), downloaded once and cached.
 - `output = "tabular"` returns a plain DataFrame for every route and never
   downloads boundaries. Reach for it when you only want the numbers.

docs/getting_started.md

@@ -8,9 +8,13 @@ kernelspec:
   name: python3
 ---
 
-# Getting started
+# Get started
 
-A short tour of the client. The tutorials go further.
+`closecity` reads the Close API: travel times from every US census block to nearby
+places, on foot, by bike, and by public transit. This page is a short tour; the
+three tutorials go further. The full list of query methods is on the
+[API reference](api.rst), and the wider API is documented at
+[docs.close.city](https://docs.close.city).
 
 ```{code-cell} python
 :tags: [remove-cell]
@@ -28,20 +32,21 @@ close = Client(os.environ.get("CLOSECITY_KEY"))
 A few terms come up throughout:
 
 - **Census block.** The smallest area the Census Bureau publishes. Each one has a
-  15-digit id, its **GEOID**.
+  15-digit id, its **GEOID**. Block GEOIDs come from the census — look them up with
+  `pygris` or the Census Bureau geocoder/API, or read them straight off Close's
+  block routes (`blocks_query`, `place_blocks`).
 - **Destination type.** A category of place, such as grocery stores or libraries.
   Every type has a numeric id.
 - **Mode.** How someone travels: walk, bike, or transit.
-- **Isochrone** or **catchment.** Two views of the same reachability: the area
-  reachable from a point within a time limit (an isochrone), or every block that
-  can reach a given place (a catchment).
+- **Isochrone** or **catchment**: the area you can reach starting from a point
+  within a time limit, by a selected travel mode.
 
 ## Travel times
 
 Times to nearby places are **capped at 30 minutes** for each mode, and recorded in
 **whole minutes**. A missing time means the place is not reachable within the cap,
-not that it is zero. Isochrones are the exception: they are available for any
-budget up to an hour.
+not that it is zero. Isochrones are the exception: they are available for any budget
+up to an hour.
 
 ## Build a client
 
@@ -53,71 +58,85 @@ from closecity import Client, close_map
 close = Client("ck_live_your_key")   # use your own key here
 ```
 
-The catalog and lookup routes are free, so `Client()` with no key works for those.
-They come back as data frames:
+The catalog and lookup routes are free, so `Client()` with no key also works for
+those.
 
 ```{code-cell} python
 close.modes()
 ```
 
 ## Look things up instead of guessing
 
-Read the numeric id for a category from the catalog, and turn a city name into a
-GEOID and a centre point. Both are plain data frames, so you filter and index them
-the usual way. The catalog's `name` column is the readable label ("Grocery
-stores"); the underscored `label` is the internal key you match on. A place lookup
-carries a `state`, so you can tell Providence, RI from the one in Utah.
+Two free calls save you from memorising codes. Both come back as data frames, so you
+filter and index them the usual way: read the numeric id for a category from the
+catalog, and turn a city name into a GEOID and a centre point.
 
 ```{code-cell} python
-types = close.destination_types()
-supermarket_dest_type = types.loc[types["label"] == "grocery_stores",
-                                  "dest_type_id"].iloc[0]
+amenity_types = close.destination_types()
+supermarket_type = amenity_types.loc[amenity_types["label"] == "grocery_stores",
+                                     "dest_type_id"].iloc[0]
 
-providence_ri = close.places("Providence").iloc[0]
+providence_ri = close.places(q = "Providence").iloc[0]
 providence_ri[["name", "state", "geoid"]]
 ```
 
+The catalog's `name` column is the readable label ("Grocery stores"); the underscored
+`label` is the internal key you match on. A place lookup carries a `state`, so you can
+tell Providence, RI from the one in Utah. When you have a point rather than a block,
+`point_summary(lat = , lon = )` reads the same travel times for a `lat`/`lon` starting
+point instead of a GEOID.
+
 ## Make a call and map it
 
-Routes with geometry return a GeoDataFrame. `close_map()` draws it on an
-interactive basemap in one line — bright, hoverable points here.
+Routes with geometry return a GeoDataFrame. `close_map()` draws it on an interactive
+basemap in one line — bright, hoverable points here, with the city boundary behind
+them and the view zoomed to fit.
 
 ```{code-cell} python
-supermarkets = close.place_pois(providence_ri["geoid"], type = supermarket_dest_type)
-close_map(supermarkets, color = "#e8590c")
+supermarkets = close.place_pois(geoid = providence_ri["geoid"], type = supermarket_type)
+city_boundary = close.place_boundary(geoid = providence_ri["geoid"])
+close_map(supermarkets, color = "#e8590c", boundary = city_boundary, label = "name")
 ```
 
 ## Choose an output
 
-Every route returns tabular data by default: a GeoDataFrame where geometry applies,
-a plain DataFrame otherwise. The `output` setting changes the shape — `"tabular"`
-never downloads boundaries, and `"raw"` returns the underlying reply with its
-metering and cursor fields. Set it on the client, or pass `output=` to one call.
+Set `output` on the client, or per call:
+
+- `output = "spatial"` (the default) returns a GeoDataFrame for inherently spatial
+  data and a DataFrame otherwise. Block routes join census-block boundaries with
+  `pygris` (the `tiger` extra), downloaded once and cached.
+- `output = "tabular"` returns a plain DataFrame for every route and never downloads
+  boundaries. Reach for it when you only want the numbers.
+- `output = "raw"` returns the underlying `Reply` / `Paginator`, with the parsed body
+  on `.data` and the token counts alongside.
 
-The same block summary as a DataFrame (the default):
+A block summary, with the readable category names merged on and sorted by time:
 
 ```{code-cell} python
-close.block_summary("440070008001068", mode = "walk")
+walk_times = close.block_summary(geoid = "440070008001068", mode = "walk")
+walk_times = walk_times.merge(amenity_types[["dest_type_id", "name"]], on = "dest_type_id")
+walk_times.sort_values("travel_time")[["name", "travel_time"]]
 ```
 
-...and as the raw reply, whose `results` you can index yourself:
+...and the same call as the raw reply, whose parsed `results` you can inspect yourself:
 
 ```{code-cell} python
-raw = close.block_summary("440070008001068", mode = "walk", output = "raw")
-raw.results[:3]
+raw = close.block_summary(geoid = "440070008001068", mode = "walk", output = "raw")
+raw.data["results"][:3]
 ```
 
-In the frame modes, the token counts and other reply metadata ride on `df.attrs`.
-
-## Errors
+## Handling errors
 
-Problem responses become typed exceptions.
+Problem responses become typed exceptions. Catch a specific one, or the
+`CloseAPIError` base.
 
-```{code-cell} python
-from closecity import CloseAPIError
+```python
+from closecity import TokensExhaustedError, CloseAPIError
 
 try:
-    close.block_summary("000000000000000")
+    close.block_summary(geoid = "000000000000000")
+except TokensExhaustedError:
+    ...
 except CloseAPIError as err:
     print(err.status, err.slug)
 ```

docs/token_use.md

@@ -33,8 +33,8 @@ when you want the etag:
 
 ```python
 close.output = "raw"
-first = close.block_summary("440070008001068", mode = "walk")
-again = close.block_summary("440070008001068", mode = "walk",
+first = close.block_summary(geoid = "440070008001068", mode = "walk")
+again = close.block_summary(geoid = "440070008001068", mode = "walk",
                             if_none_match = first.etag)
 again.not_modified   # True, and nothing was charged
 ```

docs/tutorials/amenity_basket.md

@@ -22,6 +22,7 @@ here applied to Richmond, Virginia.
 ```{code-cell} python
 :tags: [remove-cell]
 import os
+import pandas as pd
 from closecity import Client, close_map
 import plotly.io as pio
 
@@ -33,7 +34,7 @@ close = Client(os.environ.get("CLOSECITY_KEY"))
 ## Set up
 
 Read the six category ids from the free catalog, and turn the city name into a centre
-point.
+point and a boundary.
 
 ```python
 from closecity import Client, close_map
@@ -42,8 +43,8 @@ close = Client("ck_live_your_key")   # use your own key here
 ```
 
 ```{code-cell} python
-types = close.destination_types()
-ids = dict(zip(types["label"], types["dest_type_id"]))
+amenity_types = close.destination_types()
+ids = dict(zip(amenity_types["label"], amenity_types["dest_type_id"]))
 basket = {
     "supermarket": ids["grocery_stores"],
     "library": ids["libraries"],
@@ -53,22 +54,23 @@ basket = {
     "cafe": ids["cafes"],
 }
 
-city = close.places("Richmond").iloc[0]
+city = close.places(q = "Richmond").iloc[0]
+city_boundary = close.place_boundary(geoid = city["geoid"])
 ```
 
 ## Pull the blocks, with population
 
-One call gets the walk time from every block to each of the six categories, plus
-each block's population. To keep this tutorial cheap we take the central blocks
-within a radius; `place_blocks(city["geoid"])` pulls **every** block in the city
-the same way (at a higher token cost).
+One call gets the walk time from every block to each of the six categories, plus each
+block's population. To keep this tutorial cheap we take the central blocks within a
+radius; `place_blocks(geoid = city["geoid"])` pulls **every** block in the city the
+same way (at a higher token cost).
 
 ```{code-cell} python
 blocks = close.blocks_query(
     center = {"lon": city["lon"], "lat": city["lat"]}, radius_m = 2500,
     mode = "walk", type = list(basket.values()), include_population = True)
 
-one_per_block = blocks.drop_duplicates("geoid").copy()
+one_per_block = blocks.drop_duplicates("geoid").reset_index(drop = True)
 total_pop = one_per_block["population"].sum()
 ```
 
@@ -84,26 +86,29 @@ for name, type_id in basket.items():
     print(f"{name:11} {100 * pop / total_pop:3.0f}%")
 ```
 
-Map one amenity — every block shown, the covered ones highlighted.
+Parks and restaurants tend to be everywhere; supermarkets and libraries are usually
+the hardest to reach. Map one amenity — every block shown, the covered ones
+highlighted, the city boundary behind.
 
 ```{code-cell} python
-near_transit = set(blocks.loc[(blocks.dest_type_id == basket["transit"]) &
+near_library = set(blocks.loc[(blocks.dest_type_id == basket["library"]) &
                               (blocks.travel_time <= 15), "geoid"])
-one_per_block["has_transit"] = one_per_block.geoid.isin(near_transit)
-close_map(one_per_block, highlight = "has_transit", color = "#058040")
+one_per_block["has_library"] = one_per_block.geoid.isin(near_library)
+close_map(one_per_block, highlight = "has_library", color = "#058040",
+          boundary = city_boundary)
 ```
 
 ## The 15-minute-city score
 
 Count, for each block, how many of the six amenities are within a 15-minute walk.
-That score, from 0 to 6, is the map planners reach for. It reuses the data you
-already pulled, so it costs nothing more.
+That score, from 0 to 6, is the map planners reach for; blue marks the best-served
+blocks. It reuses the data you already pulled, so it costs nothing more.
 
 ```{code-cell} python
 covered = blocks[blocks.travel_time <= 15]
 score = covered.groupby("geoid")["dest_type_id"].nunique()
 one_per_block["score"] = one_per_block.geoid.map(score).fillna(0).astype(int)
-close_map(one_per_block, fill = "score")
+close_map(one_per_block, fill = "score", boundary = city_boundary)
 ```
 
 ## Who can reach all six
@@ -122,7 +127,8 @@ basket_pop = one_per_block.loc[one_per_block.geoid.isin(covered_all),
 print(f"All six amenities: {100 * basket_pop / total_pop:.0f}% of residents")
 
 one_per_block["full_basket"] = one_per_block.geoid.isin(covered_all)
-close_map(one_per_block, highlight = "full_basket", color = "#f36e21")
+close_map(one_per_block, highlight = "full_basket", color = "#f36e21",
+          boundary = city_boundary)
 ```
 
 ## Which amenity to add first
@@ -140,15 +146,49 @@ for name, type_id in basket.items():
     print(f"{name:11} {pop:6.0f} residents would gain access")
 ```
 
+## Who is one or two amenities away
+
+The residents worth targeting first are the ones *almost* there — a block that has
+five of the six is a much easier win than one that has none. Build a block-by-amenity
+coverage grid, count how many amenities each block is missing, and for the blocks
+short by just one or two, break down which amenities are the gap.
+
+```{code-cell} python
+import numpy as np
+
+names = list(basket)
+covered_by = {name: set(blocks.loc[(blocks.dest_type_id == basket[name]) &
+                                   (blocks.travel_time <= 15), "geoid"])
+              for name in names}
+geoids = one_per_block["geoid"].to_numpy()
+pops = one_per_block["population"].to_numpy()
+
+# One row per block: which amenities are missing (not within 15 minutes)?
+missing = np.array([[g not in covered_by[name] for name in names] for g in geoids])
+n_missing = missing.sum(axis = 1)
+gap = np.array([" + ".join(n for n, m in zip(names, row) if m) for row in missing])
+
+almost = np.isin(n_missing, [1, 2])
+almost_pop = pops[almost].sum()
+print(f"{100 * almost_pop / total_pop:.0f}% of residents are one or two amenities "
+      f"short of the full basket.\n")
+
+by_gap = (pd.Series(pops[almost], index = gap[almost])
+          .groupby(level = 0).sum().sort_values(ascending = False))
+for g, p in by_gap.items():
+    print(f"  missing {g:22} {100 * p / almost_pop:3.0f}%")
+```
+
 ## Site a new supermarket
 
 The counts above say *which* amenity to add; the next question is *where*. Take a
-candidate site near the city centre and ask how many residents would newly gain a
-supermarket within a 15-minute walk if one opened there. A `direction="to"`
+candidate site on land north of the James River and ask how many residents would newly
+gain a supermarket within a 15-minute walk if one opened there. A `direction="to"`
 isochrone gives exactly the blocks that could reach the site on foot in 15 minutes.
 
 ```{code-cell} python
-reachable = close.isochrone(lon = city["lon"], lat = city["lat"], mode = "walk",
+site_lon, site_lat = -77.437, 37.548
+reachable = close.isochrone(lon = site_lon, lat = site_lat, mode = "walk",
                             direction = "to", minutes = 15, format = "blocks")
 
 near_supermarket = set(blocks.loc[(blocks.dest_type_id == basket["supermarket"]) &
@@ -163,5 +203,6 @@ Map the whole city and highlight the blocks that would newly gain access.
 
 ```{code-cell} python
 one_per_block["newly_served"] = one_per_block.geoid.isin(newly_served)
-close_map(one_per_block, highlight = "newly_served", color = "#e8590c")
+close_map(one_per_block, highlight = "newly_served", color = "#e8590c",
+          boundary = city_boundary)
 ```