Rewrite the docs and tutorials for the tabular output default.

Author: Nathaniel Henry

README.md

@@ -13,31 +13,32 @@ pip install closecity
 pip install "closecity[tiger]"   # to auto-download census-block boundaries
 ```
 
-This pulls in `httpx` and `geopandas`, so feature methods return GeoDataFrames out
-of the box.
+This pulls in `httpx`, `pandas`, and `geopandas`, so results come back as data
+frames out of the box: a GeoDataFrame where geometry applies, a plain DataFrame
+otherwise.
 
 ## A first call
 
-You make requests through a client. Feature results come back as GeoDataFrames, so
-you can map them right away.
+You make requests through a client. Routes with geometry come back as
+GeoDataFrames, so you can map them right away.
 
 ```python
 from closecity import Client
 
-# The key (ck_live_ or ck_test_) comes from https://account.close.city
+# The key (ck_live_) comes from https://account.close.city
 close = Client("ck_live_your_key")   # use your own key here
 
 # Grocery stores within a 1.5 km walk of a point, as points:
 groceries = close.pois_search(lat = 41.823, lon = -71.412, radius_m = 1500, type = 30)
 groceries.plot()
 ```
 
-Catalog and lookup routes are free and need no key:
+Catalog and lookup routes are free, need no key, and come back as data frames:
 
 ```python
 close = Client()
-close.modes().data["modes"]                    # walk, bike, transit
-close.places("Providence").data["places"][0]   # a city name to its GEOID and centre
+close.modes()                  # walk, bike, transit
+close.places("Providence")     # a city name to its GEOID and centre
 ```
 
 ## Words you will see
@@ -53,14 +54,20 @@ A few terms come up throughout the API:
   polygon.
 - **Catchment.** The reverse of an isochrone: every block that can reach a place.
 
-## Spatial output, on or off
+## Choosing an output
 
-Feature methods return GeoDataFrames by default. Block routes join census-block
-boundaries for you, using `pygris` (the `tiger` extra) to download them once. To work
-with the raw data instead, build the client with `spatial=False`:
+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
+  `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.
 
 ```python
-close = Client("ck_live_your_key", spatial = False)   # use your own key here
+close = Client("ck_live_your_key", output = "raw")   # use your own key here
 for poi in close.pois_search(lat = 41.823, lon = -71.412, radius_m = 1500):
     print(poi["name"])
 ```

docs/api.rst

@@ -19,8 +19,10 @@ Replies and pagination
 .. autoclass:: closecity.Paginator
    :members:
 
-Spatial conversion
-------------------
+Output conversion
+-----------------
+
+.. autofunction:: closecity.to_pandas
 
 .. autofunction:: closecity.to_geopandas
 

docs/getting_started.md

@@ -42,45 +42,65 @@ 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:
 
 ```{code-cell} python
-close.modes().data["modes"]
+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.
+GEOID and a centre point. Both are plain data frames, so you filter and index them
+the usual way.
 
 ```{code-cell} python
-types = close.destination_types().data["destination_types"]
-ids = {t["label"]: t["dest_type_id"] for t in types}
-grocery = ids["grocery_stores"]
+types = close.destination_types()
+grocery = types.loc[types["label"] == "grocery_stores", "dest_type_id"].iloc[0]
 
-providence = close.places("Providence").data["places"][0]
+matches = close.places("Providence")
+providence = matches.iloc[0]
 providence["geoid"]
 ```
 
 ## Make a call and map it
 
-Feature methods return a GeoDataFrame, so you can map the result straight away.
+Routes with geometry return a GeoDataFrame, so you can map the result straight
+away.
 
 ```{code-cell} python
 groceries = close.pois_search(lat = providence["lat"], lon = providence["lon"],
                               radius_m = 1500, type = grocery)
 groceries.plot(color = "#202a5b")
 ```
 
-## Turn spatial output off
+## Choose an output
 
-Set the client's `spatial` flag to `False` to work with the raw data.
+Every route returns tabular data by default. The `output` setting controls the
+shape:
+
+- `"spatial"` (the default) returns a GeoDataFrame where geometry applies, and a
+  plain DataFrame otherwise.
+- `"tabular"` returns a plain DataFrame for every route and never downloads block
+  boundaries. Reach for it when you only want the numbers.
+- `"raw"` returns the underlying reply, with the parsed body on `.data` and the
+  token counts alongside.
+
+Set it on the client, or pass `output=` to a single call.
 
 ```{code-cell} python
-close.spatial = False
+close.output = "raw"
 summary = close.block_summary("440070008001068", mode = "walk")
 summary.results
 ```
 
+```{code-cell} python
+:tags: [remove-cell]
+close.output = "spatial"
+```
+
+In the frame modes, the token counts and other reply metadata ride on `df.attrs`.
+
 ## Errors
 
 Problem responses become typed exceptions.

docs/index.rst

@@ -9,21 +9,24 @@ public transit. This is the data behind `close.city <https://close.city>`_.
 
    from closecity import Client
 
-   # The key (ck_live_ or ck_test_) comes from https://account.close.city
+   # The key (ck_live_) comes from https://account.close.city
    close = Client("ck_live_your_key")   # use your own key here
 
-   # Feature methods return a GeoDataFrame, ready to map:
+   # Routes with geometry return a GeoDataFrame, ready to map:
    groceries = close.pois_search(lat = 41.823, lon = -71.412, radius_m = 1500)
    groceries.plot()
 
-Install with ``pip install closecity``. The catalog and lookup routes are free; the
-data routes need a key from `account.close.city <https://account.close.city>`_.
+Results are tabular by default: a GeoDataFrame where geometry applies, a plain
+DataFrame otherwise. Install with ``pip install closecity``. The catalog and
+lookup routes are free; the data routes need a key from
+`account.close.city <https://account.close.city>`_.
 
 .. toctree::
    :maxdepth: 2
    :caption: Contents
 
    installation
    getting_started
+   token_use
    tutorials/index
    api

docs/installation.rst

@@ -12,14 +12,17 @@ the box.
 Optional extras
 ---------------
 
-Block methods (``blocks_query``, ``place_blocks``, ``poi_catchment``) join
-census-block boundaries. To let them download the boundaries for you, add the
-``tiger`` extra:
+In the default spatial output mode, block methods (``blocks_query``,
+``place_blocks``, ``poi_catchment``) join census-block boundaries. To let them
+download the boundaries for you, add the ``tiger`` extra:
 
 .. code-block:: bash
 
    pip install "closecity[tiger]"
 
+You do not need it for ``output="tabular"``, which returns the same rows without
+geometry.
+
 Plotting a GeoDataFrame uses matplotlib:
 
 .. code-block:: bash
@@ -29,8 +32,8 @@ Plotting a GeoDataFrame uses matplotlib:
 API keys
 --------
 
-The catalog and lookup routes are free and need no key. Every data route needs a key
-(``ck_live_`` or ``ck_test_``), created at
+The catalog and lookup routes are free and need no key. Every data route needs a
+key (``ck_live_``), created at
 `account.close.city <https://account.close.city>`_.
 
 .. code-block:: python

docs/token_use.md

@@ -0,0 +1,77 @@
+---
+jupytext:
+  text_representation:
+    extension: .md
+    format_name: myst
+kernelspec:
+  display_name: Python 3
+  name: python3
+---
+
+# Efficient token use
+
+```{code-cell} python
+:tags: [remove-cell]
+import os
+from closecity import Client
+close = Client(os.environ.get("CLOSECITY_KEY"))
+```
+
+The API is metered in tokens: one per returned row, minimum one per request, and
+10 per isochrone contour. Tokens are rows, so spending well is mostly about not
+asking for rows you will throw away.
+
+## Free things
+
+The whole catalog is free and keyless: `modes()`, `destination_types()`,
+`vintage()`, `places()`, `isochrone_meta()`, `last_updated()`, and `health()`. Do
+your lookups before you spend a token.
+
+Revalidation is free too. Keep a reply's `etag` and pass it back as
+`if_none_match`; an unchanged response returns a free `304`. Read `output="raw"`
+when you want the etag:
+
+```python
+close.output = "raw"
+first = close.block_summary("440070008001068", mode = "walk")
+again = close.block_summary("440070008001068", mode = "walk",
+                            if_none_match = first.etag)
+again.not_modified   # True, and nothing was charged
+```
+
+## The big levers
+
+The rows a query returns multiply out as modes times types times blocks:
+
+- **Pass `mode`.** Omitting it returns all three modes, so three times the rows.
+- **Request leaf types, not parents.** A parent type expands to its leaves, so
+  `type = grocery` (one leaf) is a quarter of the rows of the `parks` parent.
+- **Shrink the area.** Cost grows with the square of `radius_m`, so halving the
+  radius is roughly a quarter of the tokens.
+- **Use `max_minutes`.** It drops rows you would filter out anyway.
+
+## Isochrones are the cheap reach primitive
+
+An isochrone is 10 tokens per contour regardless of area, and `format="blocks"`
+returns every reachable block with its minutes. A whole walkshed for 10 tokens,
+where a catchment or block query charges per block:
+
+```python
+shed = close.isochrone(block = "440070008001068", minutes = 30, mode = "walk",
+                       format = "blocks")
+```
+
+## Watch what you spend
+
+Every metered reply carries the token counts. In the frame output modes they ride
+on `df.attrs`; in `output="raw"` they are on the reply.
+
+```{code-cell} python
+groceries = close.pois_search(lat = 41.823, lon = -71.412, radius_m = 1200)
+groceries.attrs["tokens_charged"], groceries.attrs["tokens_remaining"]
+```
+
+When you only want the numbers, `output="tabular"` skips the block-boundary
+download entirely. The block boundaries the spatial mode joins are cached locally,
+so re-running a script costs time, not tokens; pass a `block_geometry` frame you
+already have to skip even that.

docs/tutorials/amenity_basket.md

@@ -17,6 +17,8 @@ where the gaps are. The idea follows
 [this analysis](https://nathenry.com/writing/2023-02-07-seattle-walkability.html),
 here applied to Richmond, Virginia.
 
+*Running this tutorial uses about 3,500 tokens.*
+
 ```{code-cell} python
 :tags: [remove-cell]
 import os
@@ -36,8 +38,8 @@ close = Client("ck_live_your_key")   # use your own key here
 ```
 
 ```{code-cell} python
-types = close.destination_types().data["destination_types"]
-ids = {t["label"]: t["dest_type_id"] for t in types}
+types = close.destination_types()
+ids = dict(zip(types["label"], types["dest_type_id"]))
 basket = {
     "grocery": ids["grocery_stores"],
     "library": ids["libraries"],
@@ -47,7 +49,7 @@ basket = {
     "cafe": ids["cafes"],
 }
 
-city = close.places("Richmond").data["places"][0]
+city = close.places("Richmond").iloc[0]
 ```
 
 ## Pull the blocks, with population
@@ -86,6 +88,20 @@ one_per_block = one_per_block.assign(
 one_per_block.plot(column = "has_transit", cmap = "Greens")
 ```
 
+## 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.
+
+```{code-cell} python
+covered = blocks[blocks.travel_time <= 15]
+score = covered.groupby("geoid")["dest_type_id"].nunique()
+one_per_block = one_per_block.assign(
+    score = one_per_block.geoid.map(score).fillna(0).astype(int))
+one_per_block.plot(column = "score", cmap = "viridis", legend = True)
+```
+
 ## Who can reach all six
 
 A block is fully covered only if all six amenities are within 15 minutes.

docs/tutorials/competitor_walksheds.md

@@ -15,6 +15,8 @@ does. Its **walkshed** is every residential block that can walk to it. This tuto
 finds nearby competitors and measures how much of that walkshed they share. The
 example city is Providence, Rhode Island.
 
+*Running this tutorial uses about 900 tokens.*
+
 ```{code-cell} python
 :tags: [remove-cell]
 import os
@@ -33,11 +35,11 @@ close = Client("ck_live_your_key")   # use your own key here
 ```
 
 ```{code-cell} python
-types = close.destination_types().data["destination_types"]
-ids = {t["label"]: t["dest_type_id"] for t in types}
+types = close.destination_types()
+ids = dict(zip(types["label"], types["dest_type_id"]))
 cafe = ids["cafes"]
 
-city = close.places("Providence").data["places"][0]
+city = close.places("Providence").iloc[0]
 ```
 
 ## Find the shops