copying over example notebooks part 1

Author: Conengmo

docs/advanced_guide.rst

@@ -1,2 +1,13 @@
 Advanced guide
 ==============
+
+.. toctree::
+  :maxdepth: 1
+
+  advanced_guide/flask
+  advanced_guide/choropleth with Jenks natural breaks optimization
+  advanced_guide/colormaps
+  advanced_guide/world_copy
+  advanced_guide/custom_panes
+  advanced_guide/geodedetic_image_overlay
+  advanced_guide/custom_tiles

docs/advanced_guide/choropleth with Jenks natural breaks optimization.md

@@ -0,0 +1,72 @@
+# 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
+url = (
+    "https://raw.githubusercontent.com/python-visualization/folium/main/examples/data"
+)
+us_states = f"{url}/us-states.json"
+
+geo_json_data = json.loads(requests.get(us_states).text)
+
+county_data = pd.read_csv(f"{url}/us_county_data.csv")
+clf = 'Civilian_labor_force_2011'
+labor_force = county_data[['State', clf]][
+    (county_data[clf].str.strip()!='') & (~county_data['State'].isin(['PR', 'US']))
+]
+labor_force[clf] = labor_force[clf].astype(int)
+labor_force = labor_force.groupby('State').sum().reset_index()
+
+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
+```

docs/advanced_guide/colormaps.md

@@ -0,0 +1,192 @@
+# Using `folium.colormap`
+
+**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 json
+
+import folium
+import pandas as pd
+import requests
+
+
+url = (
+    "https://raw.githubusercontent.com/python-visualization/folium/main/examples/data"
+)
+us_states = f"{url}/us-states.json"
+US_Unemployment_Oct2012 = f"{url}/US_Unemployment_Oct2012.csv"
+
+geo_json_data = json.loads(requests.get(us_states).text)
+unemployment = pd.read_csv(US_Unemployment_Oct2012)
+
+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
+```

docs/advanced_guide/custom_panes.md

@@ -0,0 +1,54 @@
+# 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 json
+
+import folium
+import requests
+
+url = (
+    "https://raw.githubusercontent.com/python-visualization/folium/main/examples/data"
+)
+us_states = f"{url}/us-states.json"
+geo_json_data = json.loads(requests.get(us_states).text)
+
+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, tiles="stamentoner")
+
+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="stamentonerbackground")
+
+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("stamentonerlabels", pane="labels").add_to(m)
+
+m
+```