Use Mapbox GL for visualisations in the worked examples

[jc-harrison]

Closes #526 #528 #711

I have:

• Formatted any Python files with black
• Brought the branch up to date with master
• Added any relevant Github labels
• Added tests for any new additions
• Added or updated any relevant documentation
• Added an Architectural Decision Record (ADR), if appropriate
• Added an MPLv2 License Header if appropriate
• Updated the Changelog

Description

This PR replaces the use of Folium with Mapbox GL for producing choropleths and heatmaps in the worked examples.

Running pipenv run build now also pre-caches flowmachine queries by executing docs/cache_queries.py, meaning that the example notebooks can run quickly enough to be executed during the CI docs build.

Note: Mapbox requires an API token for producing the visualisations. The dockerised worked examples are set up to read this from the MAPBOX_ACCESS_TOKEN env var. I haven't made it mandatory to set this env var before spinning up the worked examples container, because some people may want to run parts of the example notebooks without having to sign up for a mapbox account, but I have added a note to the docs explaining that a token is required to produce the maps.

Another note: mapboxgl-jupyter is not yet as full-featured as folium, and doesn't currently include some features we were previously using, such as multi-layered choropleths and time sliders. There are open issues for both of these features and more, though (see mapbox/mapboxgl-jupyter#34, mapbox/mapboxgl-jupyter#82), so we should continue to monitor this.

[codecov]

Codecov Report

Merging #770 into master will not change coverage.
The diff coverage is n/a.

@@           Coverage Diff           @@
##           master     #770   +/-   ##
=======================================
  Coverage   93.16%   93.16%           
=======================================
  Files         130      130           
  Lines        6522     6522           
  Branches      691      691           
=======================================
  Hits         6076     6076           
  Misses        326      326           
  Partials      120      120

Impacted Files	Coverage Δ
flowauth/backend/flowauth/models.py	93.29% <ø> (ø)	⬆️

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 53d4145...97961c4. Read the comment docs.

[codecov]

Codecov Report

Merging #770 into master will not change coverage.
The diff coverage is n/a.

@@           Coverage Diff           @@
##           master     #770   +/-   ##
=======================================
  Coverage   93.16%   93.16%           
=======================================
  Files         130      130           
  Lines        6522     6522           
  Branches      691      691           
=======================================
  Hits         6076     6076           
  Misses        326      326           
  Partials      120      120

Impacted Files	Coverage Δ
flowauth/backend/flowauth/models.py	93.29% <ø> (ø)	⬆️

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 4754da6...a1b5d78. Read the comment docs.

[jc-harrison]

Running
CI=true CIRCLE_SHA1=a010142b007b32d5f63012a16e295536a7645fbc bash <(curl -s https://raw.githubusercontent.com/Flowminder/FlowKit/a010142b007b32d5f63012a16e295536a7645fbc/quick_start.sh) examples
should spin up the demo system with the worked examples. You'll need to set the MAPBOX_ACCESS_TOKEN env var first.

[maxalbert]

@jch1g10 This command does indeed spin up the demo system with the worked examples, but running the notebooks fails because it spins up flowdb_testdata rather than flowdb_synthetic_data, so the flows calculation returns the following error:

FlowclientConnectionError: Something went wrong. API returned with status code 400.
Error message: 'Unable to create query object.'.
Payload: {'exception': 'No data for date: 2016-01-08 - 2016-01-09'}

Do you think there is an easy fix for this? If not, I'd rather address it in a separate PR.

[codecov]

Codecov Report

Merging #770 into master will not change coverage.
The diff coverage is n/a.

@@           Coverage Diff           @@
##           master     #770   +/-   ##
=======================================
  Coverage   93.16%   93.16%           
=======================================
  Files         130      130           
  Lines        6522     6522           
  Branches      691      691           
=======================================
  Hits         6076     6076           
  Misses        326      326           
  Partials      120      120

Impacted Files	Coverage Δ
flowauth/backend/flowauth/models.py	93.29% <ø> (ø)	⬆️

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 5a124bd...eb51ff1. Read the comment docs.

[jc-harrison]

@jch1g10 This command does indeed spin up the demo system with the worked examples, but running the notebooks fails because it spins up flowdb_testdata rather than flowdb_synthetic_data, so the flows calculation returns the following error:

FlowclientConnectionError: Something went wrong. API returned with status code 400.
Error message: 'Unable to create query object.'.
Payload: {'exception': 'No data for date: 2016-01-08 - 2016-01-09'}

Do you think there is an easy fix for this? If not, I'd rather address it in a separate PR.

Oops! Should use the synthetic data now, with the latest commit:

CI=true CIRCLE_SHA1=7c868eb4c71994241fa1ce1e9b3a98d1186b604a bash <(curl -s https://raw.githubusercontent.com/Flowminder/FlowKit/7c868eb4c71994241fa1ce1e9b3a98d1186b604a/quick_start.sh) examples

(once CI finishes)

[maxalbert]

Thanks! I tried to run the worked examples using this command. I can execute part of the Flows notebook, but sadly I get an internal error. I don't think this has anything to do with this PR, though, so I'm happy to merge this.

[maxalbert]

Excellent work. 🏅👍 🎉