-
Notifications
You must be signed in to change notification settings - Fork 2.2k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
273 changed files
with
140,433 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,4 @@ | ||
# Sphinx build info version 1 | ||
# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done. | ||
config: f66bc19377d80d1511a0dbeece3af46c | ||
tags: 645f666f9bcd5a90fca523b33c5a78b7 |
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,17 @@ | ||
Advanced guide | ||
============== | ||
|
||
.. toctree:: | ||
:maxdepth: 1 | ||
|
||
advanced_guide/flask | ||
advanced_guide/choropleth with Jenks natural breaks optimization | ||
advanced_guide/subplots | ||
advanced_guide/colormaps | ||
advanced_guide/world_copy | ||
advanced_guide/custom_panes | ||
advanced_guide/geodedetic_image_overlay | ||
advanced_guide/custom_tiles | ||
advanced_guide/piechart_icons | ||
advanced_guide/polygons_from_list_of_points | ||
advanced_guide/customize_javascript_and_css |
66 changes: 66 additions & 0 deletions
66
dev/_sources/advanced_guide/choropleth with Jenks natural breaks optimization.md.txt
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,66 @@ | ||
# Integrating Jenks Natural Break Optimization with choropleth | ||
|
||
Choropleths provide an easy way to visually see data distributions across geography. By default, folium uses the breaks created by numpy.histogram (np.histogram), which generally creates an evenly spaced quantiles. | ||
|
||
This works well enough for evenly distributed data, but for unevenly distributed data, these even quantiles can obscure more than they show. To demonstrate this, I have created maps showing the labor force of each US state. | ||
|
||
The data was taken from the county-level data and aggregated. Since our geographic data does not have areas representing Puerto Rico or the United States as a whole, I removed those entries while keeping Washington, D.C. in our data set. Already, looking at the first five states alphabetically, we can see that Alaska (AK) has a work force roughly 2% the size of California (CA). | ||
|
||
```{code-cell} ipython3 | ||
import folium | ||
import numpy as np | ||
import pandas as pd | ||
import json | ||
import requests | ||
``` | ||
|
||
```{code-cell} ipython3 | ||
geo_json_data = requests.get( | ||
"https://raw.githubusercontent.com/python-visualization/folium-example-data/main/us_states.json" | ||
).json() | ||
|
||
clf = 'Civilian_labor_force_2011' | ||
labor_force = pd.read_csv( | ||
"https://raw.githubusercontent.com/python-visualization/folium-example-data/main/us_labor_force_2011.csv" | ||
) | ||
|
||
labor_force.head() | ||
``` | ||
|
||
Using default breaks, most states are represented as being part of the bottom quantile. This distribution is similar to what we might expect if US states follow a Power Law or a Zipf distribution. | ||
|
||
```{code-cell} ipython3 | ||
m = folium.Map(location=[38, -96], zoom_start=4) | ||
|
||
folium.Choropleth( | ||
geo_data=geo_json_data, | ||
data=labor_force, | ||
columns=['State', clf], | ||
key_on='id', | ||
fill_color='RdBu', | ||
).add_to(m) | ||
|
||
m | ||
``` | ||
|
||
However, when using Jenks natural Breaks Optimization, we now see more granular detail at the bottom of the distribution, where most of our states are located. The upper western states (Idaho, Montana, Wyoming and the Dakotas) are distinguished from their Midwestern and Mountain West neighbors to the south. Gradations in the deep south between Mississippi and Alabama provide more visual information than in the previous map. Overall, this is a richer representation of the data distribution. | ||
|
||
One notable drawback of this representation is the legend. Because the lower bins are smaller, the numerical values overlap, making them unreadable. | ||
|
||
```{code-cell} ipython3 | ||
m = folium.Map(location=[38, -96], zoom_start=4) | ||
|
||
choropleth = folium.Choropleth( | ||
geo_data=geo_json_data, | ||
data=labor_force, | ||
columns=['State', clf], | ||
key_on='id', | ||
fill_color='RdBu', | ||
use_jenks=True, | ||
) | ||
choropleth.add_to(m) | ||
|
||
choropleth.color_scale.width = 800 | ||
|
||
m | ||
``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,193 @@ | ||
```{code-cell} ipython3 | ||
--- | ||
nbsphinx: hidden | ||
--- | ||
import folium | ||
``` | ||
|
||
# Using colormaps | ||
|
||
A few examples of how to use `folium.colormap` in choropleths. | ||
|
||
Let's load a GeoJSON file, and try to choropleth it. | ||
|
||
```{code-cell} ipython3 | ||
import pandas | ||
import requests | ||
|
||
geo_json_data = requests.get( | ||
"https://raw.githubusercontent.com/python-visualization/folium-example-data/main/us_states.json" | ||
).json() | ||
unemployment = pandas.read_csv( | ||
"https://raw.githubusercontent.com/python-visualization/folium-example-data/main/us_unemployment_oct_2012.csv" | ||
) | ||
|
||
unemployment_dict = unemployment.set_index("State")["Unemployment"] | ||
``` | ||
|
||
## Self-defined | ||
|
||
You can build a choropleth in using a self-defined function. | ||
It has to output an hexadecimal color string of the form `#RRGGBB` or `#RRGGBBAA`. | ||
|
||
```{code-cell} ipython3 | ||
def my_color_function(feature): | ||
"""Maps low values to green and high values to red.""" | ||
if unemployment_dict[feature["id"]] > 6.5: | ||
return "#ff0000" | ||
else: | ||
return "#008000" | ||
``` | ||
|
||
```{code-cell} ipython3 | ||
m = folium.Map([43, -100], tiles="cartodbpositron", zoom_start=4) | ||
|
||
folium.GeoJson( | ||
geo_json_data, | ||
style_function=lambda feature: { | ||
"fillColor": my_color_function(feature), | ||
"color": "black", | ||
"weight": 2, | ||
"dashArray": "5, 5", | ||
}, | ||
).add_to(m) | ||
|
||
m | ||
``` | ||
|
||
## StepColormap | ||
|
||
But to help you define your colormap, we've embedded `StepColormap` in `folium.colormap`. | ||
|
||
You can simply define the colors you want, and the `index` (*thresholds*) that correspond. | ||
|
||
```{code-cell} ipython3 | ||
import branca.colormap as cm | ||
|
||
step = cm.StepColormap( | ||
["green", "yellow", "red"], vmin=3, vmax=10, index=[3, 4, 8, 10], caption="step" | ||
) | ||
|
||
step | ||
``` | ||
|
||
```{code-cell} ipython3 | ||
m = folium.Map([43, -100], tiles="cartodbpositron", zoom_start=4) | ||
|
||
folium.GeoJson( | ||
geo_json_data, | ||
style_function=lambda feature: { | ||
"fillColor": step(unemployment_dict[feature["id"]]), | ||
"color": "black", | ||
"weight": 2, | ||
"dashArray": "5, 5", | ||
}, | ||
).add_to(m) | ||
|
||
m | ||
``` | ||
|
||
If you specify no index, colors will be set uniformly. | ||
|
||
```{code-cell} ipython3 | ||
cm.StepColormap(["r", "y", "g", "c", "b", "m"]) | ||
``` | ||
|
||
## LinearColormap | ||
|
||
But sometimes, you would prefer to have a *continuous* set of colors. This can be done by `LinearColormap`. | ||
|
||
```{code-cell} ipython3 | ||
linear = cm.LinearColormap(["green", "yellow", "red"], vmin=3, vmax=10) | ||
|
||
linear | ||
``` | ||
|
||
```{code-cell} ipython3 | ||
m = folium.Map([43, -100], tiles="cartodbpositron", zoom_start=4) | ||
|
||
folium.GeoJson( | ||
geo_json_data, | ||
style_function=lambda feature: { | ||
"fillColor": linear(unemployment_dict[feature["id"]]), | ||
"color": "black", | ||
"weight": 2, | ||
"dashArray": "5, 5", | ||
}, | ||
).add_to(m) | ||
|
||
m | ||
``` | ||
|
||
Again, you can set the `index` if you want something irregular. | ||
|
||
```{code-cell} ipython3 | ||
cm.LinearColormap(["red", "orange", "yellow", "green"], index=[0, 0.1, 0.9, 1.0]) | ||
``` | ||
|
||
If you want to transform a linear map into a *step* one, you can use the method `to_step`. | ||
|
||
```{code-cell} ipython3 | ||
linear.to_step(6) | ||
``` | ||
|
||
You can also use more sophisticated rules to create the thresholds. | ||
|
||
```{code-cell} ipython3 | ||
linear.to_step( | ||
n=6, | ||
data=[30.6, 50, 51, 52, 53, 54, 55, 60, 70, 100], | ||
method="quantiles", | ||
round_method="int", | ||
) | ||
``` | ||
|
||
And the opposite is also possible with `to_linear`. | ||
|
||
```{code-cell} ipython3 | ||
step.to_linear() | ||
``` | ||
|
||
## Built-in | ||
|
||
For convenience, we provide a (small) set of built-in linear colormaps, in `folium.colormap.linear`. | ||
|
||
```{code-cell} ipython3 | ||
cm.linear.OrRd_09 | ||
``` | ||
|
||
You can also use them to generate regular `StepColormap`. | ||
|
||
```{code-cell} ipython3 | ||
cm.linear.PuBuGn_09.to_step(12) | ||
``` | ||
|
||
Of course, you may need to scale the colormaps to your bounds. This is doable with `.scale`. | ||
|
||
```{code-cell} ipython3 | ||
cm.linear.YlGnBu_09.scale(3, 12) | ||
``` | ||
|
||
```{code-cell} ipython3 | ||
cm.linear.RdGy_11.to_step(10).scale(5, 100) | ||
``` | ||
|
||
At last, if you want to check them all, simply ask for `linear` in the notebook. | ||
|
||
```{code-cell} ipython3 | ||
cm.linear | ||
``` | ||
|
||
## Draw a `ColorMap` on a map | ||
|
||
By the way, a ColorMap is also a Folium `Element` that you can draw on a map. | ||
|
||
```{code-cell} ipython3 | ||
m = folium.Map(tiles="cartodbpositron") | ||
|
||
colormap = cm.linear.Set1_09.scale(0, 35).to_step(10) | ||
colormap.caption = "A colormap caption" | ||
m.add_child(colormap) | ||
|
||
m | ||
``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,56 @@ | ||
```{code-cell} ipython3 | ||
--- | ||
nbsphinx: hidden | ||
--- | ||
import folium | ||
``` | ||
|
||
# Panes and CustomPane | ||
|
||
Panes are used to control the ordering of layers on the map. You can customise | ||
them using the `CustomPane` class. | ||
|
||
For more info on the panes Leaflet has, see https://leafletjs.com/reference.html#map-pane. | ||
|
||
First we'll load geojson data to use in the examples: | ||
|
||
```{code-cell} ipython3 | ||
import requests | ||
|
||
geo_json_data = requests.get( | ||
"https://raw.githubusercontent.com/python-visualization/folium-example-data/main/us_states.json" | ||
).json() | ||
|
||
style_function = lambda x: {"fillOpacity": 0.8} | ||
``` | ||
|
||
## Map without custom pane | ||
|
||
We'll make an example to show how the GeoJson we add hides any labels | ||
underneath. | ||
|
||
```{code-cell} ipython3 | ||
m = folium.Map([43, -100], zoom_start=4) | ||
|
||
folium.GeoJson(geo_json_data, style_function=style_function).add_to(m) | ||
|
||
m | ||
``` | ||
|
||
## Map with custom pane | ||
|
||
Now we'll create a custom pane and add a tile layer that contains only labels. | ||
The labels will show on top off the geojson. | ||
|
||
```{code-cell} ipython3 | ||
m = folium.Map([43, -100], zoom_start=4, tiles="cartodbpositronnolabels") | ||
|
||
folium.GeoJson(geo_json_data, style_function=style_function).add_to(m) | ||
|
||
folium.map.CustomPane("labels").add_to(m) | ||
|
||
# Final layer associated to custom pane via the appropriate kwarg | ||
folium.TileLayer("cartodbpositrononlylabels", pane="labels").add_to(m) | ||
|
||
m | ||
``` |
Oops, something went wrong.