Start a codelab for a new area

docs/codelab_examples.md

@@ -1,8 +1,8 @@
 # Codelab: Running pre-made examples
 
-<od2net.org> includes some example networks. This codelab will teach you how to
-generate these yourself, then modify the cost function. This is a good codelab
-to complete before trying to create your own od2net input.
+<https://od2net.org> includes some example networks. This codelab will teach
+you how to generate these yourself, then modify the cost function. This is a
+good codelab to complete before trying to create your own od2net input.
 
 ## Setup
 
@@ -125,3 +125,7 @@ Some tips for writing your own cost function:
 - You can use any language you want. It just needs to read STDIN and write to STDOUT in the way that was described.
 - The output costs need to be rounded to integers.
 - If you want to debug your script, you can't print to STDOUT, because od2net will try to parse this as the JSON number result. You can instead write to STDERR or to a temporary log file. Keep in mind od2net will call your script multiple times when running (there's some internal batch size set), so if you write to a file, name it something unique.
+
+## Next steps
+
+Now you can [setup od2net in a new place](codelab_new_area.md), with your own origin/destination data!

docs/codelab_new_area.md

@@ -0,0 +1,61 @@
+# Codelab: Running in a new area
+
+This codelab will guide you through using od2net in a new area. I'm assuming you've been through the [previous codelab](codelab_examples.md).
+
+The overall process is:
+
+1.  Create your study area
+2.  Prepare origin/destination input
+3.  Specify configuration to customize the route cost function, level of traffic stress, uptake model, etc.
+4.  Run `odnet`
+5.  Use the web viewer to explore the output, or write your own analysis to use the results
+
+## Where to put your code
+
+You can keep all of your work just on your own computer, or start your own git repo if you like. At minimum, it'll just be a few files, like any of the [examples](https://github.com/Urban-Analytics-Technology-Platform/od2net/tree/main/examples/london).
+
+If you'd like to contribute your area to the od2net examples, please do! I'm not sure yet how many official examples I'll maintain long-term, but I'm happy to add many for now. Please fork the od2net repo, start a new branch with your addition, then [send a PR from your fork](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork).
+
+## Scripting
+
+The od2net examples all use Python and rely on external tools like `osmium` and `ogr2ogr` to do lots of the heavy lifting. You're free to use R, Java, or any language you're comfortable with, and to use any dependencies that're helpful. You can also just create all of the inputs manually, though I'd encourage scripting so somebody else can reproduce your data science workflow.
+
+## Step 1: Creating your study area
+
+od2net needs an `osm.pbf` file as input. You can create this however you like -- the examples download a big file from Geofabrik, then use osmium to clip.
+
+## Step 2: Preparing origin/destination input
+
+od2net needs to know where to calculate routes.
+
+The simplest input here is literally a GeoJSON file with thousands (or millions) of LineStrings, saying where each route should start and end. (Those endpoints don't have to be exactly on the road; they'll snap to the nearest intersection.) I don't recommend using raw LineStrings as input, because they're large to store, slow to read, and because od2net can help generate these from different patterns.
+
+Most of the patterns use a GeoJSON file to specify individual origins and destinations as points. These are where trips will begin or end, usually buildings where people live, go to work, school, shops, etc.
+
+Then you can specify an [ODPattern](https://github.com/Urban-Analytics-Technology-Platform/od2net/blob/main/od2net/src/config.rs) in the `config.json` file:
+
+- `BetweenZones` is the most common pattern. You describe zone polygons that divide up your area, usually based on some kind of census boundary. Then you describe how many trips go between these zones.
+  - You have to create a `zones.geojson` file with polygons that have a `name` property.
+  - You also need an `od.csv` file with three columns: `from`, `to`, and `count`. The first two must match the zone names.
+  - od2net will pick specific points within zones from the origin and destination GeoJSON points. It'll randomly sample (with replacement -- the same point can be used many times).
+- `FromEveryOriginToNearestDestination` creates one trip for every point in your origin GeoJSON file. It'll go to the nearest destination point, measured as straight-line distance.
+
+The other patterns are niche and may be removed or simplified soon.
+
+The OD data you use depends on what you want to calculate. Some ideas:
+
+- If you want to understand how cyclists currently travel around, find some data with start and endpoints.
+- Or to explore how to "mode shift" existing trips by car to potential new cycling trips, look for data about short driving trips that happen today.
+- Your country/city might have census data describing flows of people between home and work.
+- You could generate your own demand or activity model by using census data to figure out how many schoolchildren live in different areas, then assigning them to different schools.
+
+## Step 3: Configuration
+
+TODO
+
+https://github.com/Urban-Analytics-Technology-Platform/od2net/blob/main/od2net/src/config.rs
+config.json spec
+
+## Step 4: Running od2net
+
+## Step 5: Using the output

docs/quick_start.md

@@ -6,36 +6,14 @@ There are 3 ways to use od2net:
 2.  Run an example
 3.  Use od2net in your own project
 
-## Running examples
+TODO point to codelabs
 
-The examples in this repo all use Python to download and prepare od2net input for different studies.
-
-### Setup
-
-You'll need:
-
-- Rust (1.71 or newer) or Docker
-- Python 3 (no external dependencies)
-- Standard Unix tools like curl and gunzip
-- ogr2ogr with [OSM support](https://gdal.org/drivers/vector/osm.html)
-- [tippecanoe](https://github.com/felt/tippecanoe)
-- [osmium](https://osmcode.org/osmium-tool/manual.html#installation)
-
-### Run an example
+### Docker
 
 ```shell
-cd examples/london
-python3 setup.py
-# Building the Rust binary
-cargo run --release config.json
-# Or use Docker instead
-# docker run -v $(pwd):/app ghcr.io/urban-analytics-technology-platform/od2net:main /app/config.json
+docker run -v $(pwd):/app ghcr.io/urban-analytics-technology-platform/od2net:main /app/config.json
 ```
 
-Then go to <https://Urban-Analytics-Technology-Platform.github.io/od2net/> and load `examples/london/output/rnet.pmtiles`.
-
-Some steps will be slow the first time (compiling Rust, parsing OpenStreetMap data, and building a contraction hierarchy). Subsequent runs will be faster.
-
 ### Exploring individual routes
 
 While developing OD data, a route cost function, an uptake model, etc, it can be helpful to debug individual routes produced by the tool. You can pass `--detailed-routes=50` to output 50 GeoJSON files with more detail. Here's an example in York using Docker to run: