Brokenspoke-analyzer¶

The Brokenspoke Analyzer is a tool allowing the user to run “Bicycle Network Analysis” locally.

Requirements¶

docker: official page
docker compose plugin V2: official page
osmium: official page
osm2pgrouting: official page
osm2pgsql: official page
osmconvert: OSM wiki
osmium-tool: official page
psql: official page
postgis: official page

Quickstart¶

There are 2 main ways to use the brokenspoke-analyzer:

All in Docker
Native Python with the database running in a Docker container

The different methods are being described in the sections below, with their advantages and inconveniences.

For more details about the different ways to run an analysis and how to adjust the options, please refer to the full documentation.

All in Docker¶

The benefit of running eveything using the provided Docker images, is that there is no need to install any of the required dependencies, except Docker itself of course. This guarantees that the user will have the right versions of the multiple tools that are combined to run an analysis. This is the simplest way, and the recommended way for people who just want to run the analyzer.

Start the database from Docker Compose, in the background:

docker compose up -d

Export the database URL:

export DATABASE_URL=postgresql://postgres:postgres@localhost:5432/postgres

Run the analysis:

docker run \
  --rm \
  --network brokenspoke-analyzer_default \
  -e DATABASE_URL \
  ghcr.io/peopleforbikes/brokenspoke-analyzer:2.4.0 \
  -vv run "united states" "santa rosa" "new mexico" 3570670

Export the results:

docker run \
  --rm \
  --network brokenspoke-analyzer_default \
  -u $(id -u):$(id -g) \
  -v ./results:/usr/src/app/results \
  -e DATABASE_URL \
  ghcr.io/peopleforbikes/brokenspoke-analyzer:2.4.0 \
  -vv export local-calver "united states" "santa rosa" "new mexico"

Clean up:

docker compose down
docker compose rm -sfv
docker volume rm brokenspoke-analyzer_postgres

Native w/ Database-only in Docker¶

This method gives you the most control, and is recommended if you intend to work on the project.

Export the database URL:

export DATABASE_URL=postgresql://postgres:postgres@localhost:5432/postgres

At this point, all the requirements must be installed locally. Otherwise the brokenspoke-analyzer will not install.

Once all the tools are installed, the brokenspoke-analyzer can be installed. We recommend using Poetry for installing the tool and working in a virtual environment. Once you have Poetry set up:

git clone git@github.com:PeopleForBikes/brokenspoke-analyzer.git
cd brokenspoke-analyzer
poetry install

Run the analysis:

poetry run bna run-with compose "united states" "santa rosa" "new mexico" 3570670

This command takes care of starting and stopping the PostgreSQL/PostGIS server, running all the analysis commands, and exporting the results.

The data required to perform the analysis will be saved in data/santa-rosa-new-mexico-united-states, and the results exported in results/united-states/new mexico/santa rosa/23.11.

Configure the database manually¶

In most cases, the brokenspoke-analyzer will auto-detect this information. But sometimes the auto-detection might fail. Here are the commands that will help retrieve the resource allocation values.

Get the number of vCPUs allocated to Docker:

docker info --format json | jq .NCPU

Get the amount of memory (in MB) allocated to Docker:

docker info --format json | jq .MemTotal | numfmt --to-unit=1M

And then run the command to configure the database with custom values:

poetry run bna configure custom 4 4096 postgres

Warning

Be aware that running an analysis can take several hours!

GENERAL:

DEVELOPMENT: