big batch of layout.geo docs

Author: nicolaskruchten

doc/python/axes.md

@@ -5,7 +5,7 @@ jupyter:
     text_representation:
       extension: .md
       format_name: markdown
-      format_version: '1.2'
+      format_version: "1.2"
       jupytext_version: 1.3.0
   kernelspec:
     display_name: Python 3
@@ -22,7 +22,8 @@ jupyter:
     pygments_lexer: ipython3
     version: 3.7.3
   plotly:
-    description: How to adjust axes properties in python. Includes examples of linear
+    description:
+      How to adjust axes properties in python. Includes examples of linear
       and logarithmic axes, axes titles, styling and coloring axes and grid lines,
       and more.
     display_as: file_settings
@@ -34,23 +35,24 @@ jupyter:
     thumbnail: thumbnail/axes.png
 ---
 
-This tutorial explain how to set the properties of Cartesian axes, namely [`go.layout.XAxis`](/python/reference/#layout-xaxis) and [`go.layout.YAxis`](python/reference/#layout-xaxis). Other kinds of axes are described in other tutorials:
+This tutorial explain how to set the properties of 2-dimensional Cartesian axes, namely [`go.layout.XAxis`](/python/reference/#layout-xaxis) and [`go.layout.YAxis`](python/reference/#layout-xaxis). Other kinds of axes are described in other tutorials:
+
 - [3D axes](/python/3d-axes) The axis object is [`go.layout.Scene`](/python/reference/#layout-scene)
 - [Polar axes](/python/polar-chart/). The axis object is [`go.layout.Polar`](/python/reference/#layout-polar)
 - [Ternary axes](/python/ternary-plots). The axis object is [`go.layout.Ternary`](/python/reference/#layout-ternary)
-- For Geo axes, see [this choropleth example](/python/choropleth-maps/#world-choropleth-map). The axis object is [`go.layout.Geo`](/python/reference/#layout-geo)
-- For Mapbox axes, see the different mapbox tutorials in the [Maps page](/python/maps/). The axis object is [`go.layout.Mapbox`](/python/reference/#layout-mapbox)
-- Color axes are described in the [color scales tutorial](/python/colorscales/).
+- [Geo axes](/python/map-configuration/). The axis object is [`go.layout.Geo`](/python/reference/#layout-geo)
+- [Mapbox axes](/python/mapbox-layers/). The axis object is [`go.layout.Mapbox`](/python/reference/#layout-mapbox)
+- [Color axes](/python/colorscales/). The axis object is [`go.layout.Coloraxis`](/python/reference/#layout-coloraxis).
 
 **See also** the tutorials on [subplots](/python/subplots) and [multiple axes](/python/multiple-axes/).
 
-The different types of Cartesian axes are 
+The different types of Cartesian axes are
+
 - 'linear'
 - 'log' (see the [example below](#logarithmic-axes))
 - 'date' (see the [tutorial on timeseries](/python/time-series/))
 - 'category' (see for example [Bar Charts](/python/bar-charts/))
-- 'multicategory' (see the [example below](#subcategory-(multicategory)-axes) ))
-
+- 'multicategory' (see the [example below](<#subcategory-(multicategory)-axes>))
 
 #### Logarithmic Axes
 
@@ -92,7 +94,7 @@ fig.show()
 
 ### Forcing an axis to be categorical
 
-If you pass string values for the `x` or `y` parameter, plotly will automatically set the corresponding axis type to `category`, with the exception of string of numbers, in which case the axis is linear. It is however possible to force the axis type by setting explicitely `xaxis_type` to be `category`. 
+If you pass string values for the `x` or `y` parameter, plotly will automatically set the corresponding axis type to `category`, with the exception of string of numbers, in which case the axis is linear. It is however possible to force the axis type by setting explicitely `xaxis_type` to be `category`.
 
 ```python
 import plotly.express as px
@@ -150,17 +152,16 @@ fig.update_layout(title_text="Multi-category axis",)
 fig.show()
 ```
 
-
 #### Toggling Axes Lines, Ticks, Labels, and Autorange
 
-The different groups of Cartesian axes properties are 
+The different groups of Cartesian axes properties are
+
 - tick values (locations of tick marks) and tick labels. Tick labels are placed at tick values.
 - lines: grid lines (passing through tick values), axis lines, zero lines
 - title of the axis
 - range of the axis
 - domain of the axis
 
-
 #### Tick Placement, Color, and Style
 
 ##### Toggling axis tick marks
@@ -169,7 +170,6 @@ Axis tick marks are disabled by default for the default `plotly` theme, but they
 
 Here is an example of turning on inside x-axis and y-axis ticks in a faceted figure created using Plotly Express. Note how the `col` argument to `update_yaxes` is used to only turn on the y-axis ticks for the left-most subplot.
 
-
 ```python
 import plotly.express as px
 df = px.data.iris()
@@ -265,7 +265,6 @@ fig.update_yaxes(showticklabels=False)
 fig.show()
 ```
 
-
 ##### Set axis label rotation and font
 
 The orientation of the axis tick mark labels is configured using the `tickangle` axis property. The value of `tickangle` is the angle of rotation, in the clockwise direction, of the labels from vertical in units of degrees. The font family, size, and color for the tick labels are stored under the `tickfont` axis property.
@@ -324,7 +323,6 @@ fig.update_layout(title_text="Apple Stock Price")
 fig.show()
 ```
 
-
 ### Axis lines: grid and zerolines
 
 ##### Toggling Axis grid lines
@@ -534,7 +532,6 @@ fig.update_yaxes(range=[3, 9])
 fig.show()
 ```
 
-
 ### Fixed Ratio Axes
 
 The `scaleanchor` and `scaleratio` axis properties can be used to force a fixed ratio of pixels per unit between two axes.
@@ -593,7 +590,7 @@ fig.show()
 
 ##### Decreasing the domain spanned by an axis
 
-In the example below, the x and y axis are anchored together, and the range of the `xaxis` is set manually. By default, plotly extends the range of the axis (overriding the `range` parameter) to fit in the figure `domain`. You can restrict the `domain`  to force the axis to span only the set range, by setting `constrain='domain'` as below.
+In the example below, the x and y axis are anchored together, and the range of the `xaxis` is set manually. By default, plotly extends the range of the axis (overriding the `range` parameter) to fit in the figure `domain`. You can restrict the `domain` to force the axis to span only the set range, by setting `constrain='domain'` as below.
 
 ```python
 import plotly.graph_objects as go
@@ -687,7 +684,7 @@ fig.show()
 
 ### Axis range for log axis type
 
-If you are using a `log` type of axis and you want to set the range of the axis, you have to give the `log10` value of the bounds when using `fig.update_xaxes` or `fig.update_layout`. However, with `plotly.express` functions you pass directly the values of the range bounds (`plotly.express` then computes the appropriate values to pass to the figure layout). 
+If you are using a `log` type of axis and you want to set the range of the axis, you have to give the `log10` value of the bounds when using `fig.update_xaxes` or `fig.update_layout`. However, with `plotly.express` functions you pass directly the values of the range bounds (`plotly.express` then computes the appropriate values to pass to the figure layout).
 
 ```python
 import plotly.express as px

doc/python/bubble-maps.md

@@ -33,6 +33,10 @@ jupyter:
     thumbnail: thumbnail/bubble-map.jpg
 ---
 
+#### Base Map Configuration
+
+Plotly figures made with `px.scatter_geo`, `px.line_geo` or `px.choropleth` functions or containing `go.Choropleth` or `go.Scattergeo` graph objects have a `go.layout.Geo` object which can be used to [control the appearance of the base map](/python/map-configuration/) onto which data is plotted.
+
 ### Bubble map with Plotly Express
 
 [Plotly Express](/python/plotly-express/) is the easy-to-use, high-level interface to Plotly, which [operates on "tidy" data](/python/px-arguments/). With `px.scatter_geo`, each line of the dataframe is represented as a marker point. The column set as the `size` argument gives the size of markers.

doc/python/choropleth-maps.md

@@ -5,12 +5,22 @@ jupyter:
     text_representation:
       extension: .md
       format_name: markdown
-      format_version: "1.1"
-      jupytext_version: 1.1.1
+      format_version: '1.2'
+      jupytext_version: 1.3.1
   kernelspec:
     display_name: Python 3
     language: python
     name: python3
+  language_info:
+    codemirror_mode:
+      name: ipython
+      version: 3
+    file_extension: .py
+    mimetype: text/x-python
+    name: python
+    nbconvert_exporter: python
+    pygments_lexer: ipython3
+    version: 3.6.8
   plotly:
     description: How to make choropleth maps in Python with Plotly.
     display_as: maps
@@ -23,14 +33,143 @@ jupyter:
     thumbnail: thumbnail/choropleth.jpg
 ---
 
-A [Choropleth Map](https://en.wikipedia.org/wiki/Choropleth_map) is a heatmap using geographical boundaries. It is used to represent spatial variations of a quantity. See also the [index of other geographical charts](/python/maps/).
+A [Choropleth Map](https://en.wikipedia.org/wiki/Choropleth_map) is a map composed of colored polygons. It is used to represent spatial variations of a quantity. This page documents how to build **outline** choropleth maps, but you can also build [choropleth **tile maps** using our Mapbox trace types](/python/mapbox-county-choropleth).
 
-Below we show how to create Choropleth Maps using either Plotly Express' `px.choropleth` or the lower-level `go.Choropleth`.
+Below we show how to create Choropleth Maps using either Plotly Express' `px.choropleth` function or the lower-level `go.Choropleth` graph object.
+
+#### Base Map Configuration
+
+Plotly figures made with `px.scatter_geo`, `px.line_geo` or `px.choropleth` functions or containing `go.Choropleth` or `go.Scattergeo` graph objects have a `go.layout.Geo` object which can be used to [control the appearance of the base map](/python/map-configuration/) onto which data is plotted.
+
+### Introduction: main parameters for choropleth outline maps
+
+Making choropleth maps requires two main types of input:
+
+1. Geometry information:
+   1. This can either be a supplied GeoJSON file where each feature has either an `id` field or some identifying value in `properties`; or
+   2. one of the built-in geometries within `plotly`: US states and world countries (see below)
+2. A list of values indexed by feature identifier.
+
+The GeoJSON data is passed to the `geojson` argument, and the data is passed into the `color` argument of `px.choropleth_mapbox` (`z` if using `graph_objects`), in the same order as the IDs are passed into the `location` argument.
+
+**Note** the `geojson` attribute can also be the URL to a GeoJSON file, which can speed up map rendering in certain cases.
 
 ### Choropleth Map with plotly.express
 
 [Plotly Express](/python/plotly-express/) is the easy-to-use, high-level interface to Plotly, which [operates on "tidy" data](/python/px-arguments/).
 
+#### GeoJSON with `feature.id`
+
+Here we load a GeoJSON file containing the geometry information for US counties, where `feature.id` is a [FIPS code](https://en.wikipedia.org/wiki/FIPS_county_code).
+
+```python
+from urllib.request import urlopen
+import json
+with urlopen('https://raw.githubusercontent.com/plotly/datasets/master/geojson-counties-fips.json') as response:
+    counties = json.load(response)
+
+counties["features"][0]
+```
+
+#### Data indexed by `id`
+
+Here we load unemployment data by county, also indexed by [FIPS code](https://en.wikipedia.org/wiki/FIPS_county_code).
+
+```python
+import pandas as pd
+df = pd.read_csv("https://raw.githubusercontent.com/plotly/datasets/master/fips-unemp-16.csv",
+                   dtype={"fips": str})
+df.head()
+```
+
+### Choropleth map using GeoJSON
+
+**Note** In this example we set `layout.geo.scope` to `usa` to automatically configure the map to display USA-centric data in an appropriate projection. See the [Geo map configuration documentation](/python/map-configuration/) for an explanation.
+
+```python
+from urllib.request import urlopen
+import json
+with urlopen('https://raw.githubusercontent.com/plotly/datasets/master/geojson-counties-fips.json') as response:
+    counties = json.load(response)
+
+import pandas as pd
+df = pd.read_csv("https://raw.githubusercontent.com/plotly/datasets/master/fips-unemp-16.csv",
+                   dtype={"fips": str})
+
+import plotly.express as px
+
+fig = px.choropleth(df, geojson=counties, locations='fips', color='unemp',
+                           color_continuous_scale="Viridis",
+                           range_color=(0, 12),
+                           scope="usa",
+                           labels={'unemp':'unemployment rate'}
+                          )
+fig.update_layout(margin={"r":0,"t":0,"l":0,"b":0})
+fig.show()
+```
+
+### Indexing by GeoJSON Properties
+
+If the GeoJSON you are using either does not have an `id` field or you wish you use one of the keys in the `properties` field, you may use the `featureidkey` parameter to specify where to match the values of `locations`.
+
+In the following GeoJSON object/data-file pairing, the values of `properties.district` match the values of the `district` column:
+
+```python
+import plotly.express as px
+
+df = px.data.election()
+geojson = px.data.election_geojson()
+
+print(df["district"][2])
+print(geojson["features"][0]["properties"])
+```
+
+To use them together, we set `locations` to `district` and `featureidkey` to `"properties.district"`. The `color` is set to the number of votes by the candidate named Bergeron.
+
+**Note** In this example we set `layout.geo.visible` to `False` to hide the base map and frame, and we set `layout.geo.fitbounds` to `'locations'` to automatically zoom the map to show just the area of interest. See the [Geo map configuration documentation](/python/map-configuration/) for an explanation.
+
+```python
+import plotly.express as px
+
+df = px.data.election()
+geojson = px.data.election_geojson()
+
+fig = px.choropleth(df, geojson=geojson, color="Bergeron",
+                    locations="district", featureidkey="properties.district",
+                    projection="mercator"
+                   )
+fig.update_geos(fitbounds="locations", visible=False)
+fig.update_layout(margin={"r":0,"t":0,"l":0,"b":0})
+fig.show()
+```
+
+### Discrete Colors
+
+In addition to [continuous colors](/python/colorscales/), we can [discretely-color](/python/discrete-color/) our choropleth maps by setting `color` to a non-numerical column, like the name of the winner of an election.
+
+**Note** In this example we set `layout.geo.visible` to `False` to hide the base map and frame, and we set `layout.geo.fitbounds` to `'locations'` to automatically zoom the map to show just the area of interest. See the [Geo map configuration documentation](/python/map-configuration/) for an explanation.
+
+```python
+import plotly.express as px
+
+df = px.data.election()
+geojson = px.data.election_geojson()
+
+fig = px.choropleth(df, geojson=geojson, color="winner",
+                    locations="district", featureidkey="properties.district",
+                    projection="mercator", hover_data=["Bergeron", "Coderre", "Joly"]
+                   )
+fig.update_geos(fitbounds="locations", visible=False)
+fig.update_layout(margin={"r":0,"t":0,"l":0,"b":0})
+fig.show()
+```
+
+### Using Built-in Geometries
+
+Plotly comes with two built-in geometries which do not require an external GeoJSON file: countries as defined in the Natural Earth dataset (see the "Cultural Base Map" section of the [Geo map configuration documentation](/python/map-configuration/) for an explanation and disclaimer) and US states. 
+
+To use the countries dataset, provide `locations` as [three-letter ISO country codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3).
+
 ```python
 import plotly.express as px
 
@@ -42,6 +181,15 @@ fig = px.choropleth(df, locations="iso_alpha",
 fig.show()
 ```
 
+To use the USA states dataset, set `locationmode='USA-states'` and provide `locations` as two-letter state abbreviations:
+
+```python
+import plotly.express as px
+
+fig = px.choropleth(locations=["CA", "TX", "NY"], locationmode="USA-states", color=[1,2,3], scope="usa")
+fig.show()
+```
+
 ### Choropleth Maps with go.Choropleth
 
 #### United States Choropleth Map

doc/python/filled-area-on-mapbox.md

@@ -5,7 +5,7 @@ jupyter:
     text_representation:
       extension: .md
       format_name: markdown
-      format_version: '1.1'
+      format_version: "1.1"
       jupytext_version: 1.1.1
   kernelspec:
     display_name: Python 3
@@ -35,16 +35,16 @@ jupyter:
 
 <!-- #region -->
 
-### Mapbox Access Token
-
-To plot on Mapbox maps with Plotly you *may* need a Mapbox account and a public [Mapbox Access Token](https://www.mapbox.com/studio). See our [Mapbox Map Layers](/python/mapbox-layers/) documentation for more information.
+### Mapbox Access Token and Base Map Configuration
 
+To plot on Mapbox maps with Plotly you _may_ need a Mapbox account and a public [Mapbox Access Token](https://www.mapbox.com/studio). See our [Mapbox Map Layers](/python/mapbox-layers/) documentation for more information.
 
 There are three different ways to show a filled area in a Mapbox map:
+
 1. Use a [Scattermapbox](https://plot.ly/python/reference/#scattermapbox) trace and set `fill` attribute to 'toself'
 2. Use a Mapbox layout (i.e. by minimally using an empty [Scattermapbox](https://plot.ly/python/reference/#scattermapbox) trace) and add a GeoJSON layer
 3. Use the [Choroplethmapbox](https://plot.ly/python/mapbox-county-choropleth/) trace type
-<!-- #endregion -->
+   <!-- #endregion -->
 
 ### Filled `Scattermapbox` Trace
 
@@ -140,4 +140,5 @@ fig.show()
 ```
 
 #### Reference
+
 See https://plot.ly/python/reference/#scattermapbox for more information about mapbox and their attribute options.