Add mapbox charts and greatly improve documentation for all map-based visualizations

Plotly.NET.sln

@@ -74,15 +74,21 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "content", "content", "{60FB
 		docs\4_3_contour-plots.fsx = docs\4_3_contour-plots.fsx
 		docs\4_4_2d-histograms.fsx = docs\4_4_2d-histograms.fsx
 		docs\4_5_splom.fsx = docs\4_5_splom.fsx
-		docs\5_0_choropleth-map.fsx = docs\5_0_choropleth-map.fsx
-		docs\6_0_candlestick.fsx = docs\6_0_candlestick.fsx
-		docs\6_1_funnel.fsx = docs\6_1_funnel.fsx
-		docs\6_2_funnel_area.fsx = docs\6_2_funnel_area.fsx
-		docs\7_0_polar-charts.fsx = docs\7_0_polar-charts.fsx
-		docs\7_1_windrose-charts.fsx = docs\7_1_windrose-charts.fsx
-		docs\8_0_parallel-categories.fsx = docs\8_0_parallel-categories.fsx
-		docs\8_1_parallel-coords.fsx = docs\8_1_parallel-coords.fsx
-		docs\8_2_sankey.fsx = docs\8_2_sankey.fsx
+		docs\5_0_geo-vs-mapbox.fsx = docs\5_0_geo-vs-mapbox.fsx
+		docs\5_1_geo-plots.fsx = docs\5_1_geo-plots.fsx
+		docs\5_2_choropleth-map.fsx = docs\5_2_choropleth-map.fsx
+		docs\6_0_geo-vs-mapbox.fsx = docs\6_0_geo-vs-mapbox.fsx
+		docs\6_1_mapbox-plots.fsx = docs\6_1_mapbox-plots.fsx
+		docs\6_2_choropleth-mapbox.fsx = docs\6_2_choropleth-mapbox.fsx
+		docs\6_3_density-mapbox.fsx = docs\6_3_density-mapbox.fsx
+		docs\7_0_candlestick.fsx = docs\7_0_candlestick.fsx
+		docs\7_1_funnel.fsx = docs\7_1_funnel.fsx
+		docs\7_2_funnel_area.fsx = docs\7_2_funnel_area.fsx
+		docs\8_0_polar-charts.fsx = docs\8_0_polar-charts.fsx
+		docs\8_1_windrose-charts.fsx = docs\8_1_windrose-charts.fsx
+		docs\9_0_parallel-categories.fsx = docs\9_0_parallel-categories.fsx
+		docs\9_1_parallel-coords.fsx = docs\9_1_parallel-coords.fsx
+		docs\9_2_sankey.fsx = docs\9_2_sankey.fsx
 		docs\_template.html = docs\_template.html
 		docs\_template.ipynb = docs\_template.ipynb
 		docs\Dockerfile = docs\Dockerfile

docs/5_0_geo-vs-mapbox.fsx

@@ -0,0 +1,131 @@
+(**
+---
+title: Geo vs. Mapbox
+category: Geo map charts
+categoryindex: 6
+index: 1
+---
+*)
+
+(*** hide ***)
+
+(*** condition: prepare ***)
+#r "nuget: Newtonsoft.JSON, 12.0.3"
+#r "../bin/Plotly.NET/netstandard2.0/Plotly.NET.dll"
+
+(*** condition: ipynb ***)
+#if IPYNB
+#r "nuget: Plotly.NET, {{fsdocs-package-version}}"
+#r "nuget: Plotly.NET.Interactive, {{fsdocs-package-version}}"
+#endif // IPYNB
+
+(** 
+# Mapbox Maps vs Geo Maps
+
+[![Binder]({{root}}img/badge-binder.svg)](https://mybinder.org/v2/gh/plotly/Plotly.NET/gh-pages?filepath={{fsdocs-source-basename}}.ipynb) 
+[![Script]({{root}}img/badge-script.svg)]({{root}}{{fsdocs-source-basename}}.fsx) 
+[![Notebook]({{root}}img/badge-notebook.svg)]({{root}}{{fsdocs-source-basename}}.ipynb)
+
+*Summary:* This introduction shows the differences between Geo and Mapbox based geographical charts.
+
+Plotly and therefore Plotly.NET supports two different kinds of maps:
+
+- **Mapbox maps** are tile-based maps. If your figure is created with a `Chart.*Mapbox` function or otherwise contains one or more traces of type `scattermapbox`, 
+    `choroplethmapbox` or `densitymapbox`, the layout.mapbox object in your figure contains configuration information for the map itself.
+
+- **Geo maps** are outline-based maps. If your figure is created with a `Chart.ScatterGeo, `Chart.PointGeo`, `Chart.LineGeo` or `Chart.Choropleth` function or 
+    otherwise contains one or more traces of type `scattergeo` or `choropleth`, the layout.geo object in your figure contains configuration information for the map itself.
+
+_This page documents Geo outline-based maps, and the [Mapbox Layers documentation]({{root}}/6_0_geo-vs-mapbox.html) describes how to configure Mapbox tile-based maps._
+
+## Physical Base Maps
+
+Plotly Geo maps have a built-in base map layer composed of "physical" and "cultural" (i.e. administrative border) data from the Natural Earth Dataset. 
+Various lines and area fills can be shown or hidden, and their color and line-widths specified. 
+In the default plotly template, a map frame and physical features such as a coastal outline and filled land areas are shown, at a small-scale 1:110m resolution:
+
+*)
+
+open Plotly.NET
+
+let baseMapOnly = 
+    Chart.PointGeo([]) // deliberately empty chart to show the base map only
+    |> Chart.withMarginSize(0,0,0,0)
+
+(*** condition: ipynb ***)
+#if IPYNB
+baseLayerOnly
+#endif // IPYNB
+
+(***hide***)
+baseMapOnly |> GenericChart.toChartHTML
+(***include-it-raw***)
+
+(**
+To control the features of the map, a `Geo` object is used that can be associtaed with a given chart using the `Chart.WithGeo` function.
+Here is a map with all physical features enabled and styled, at a larger-scale 1:50m resolution:
+*)
+
+let myGeo =
+    Geo.init(
+        Resolution=StyleParam.GeoResolution.R50,
+        ShowCoastLines=true, 
+        CoastLineColor="RebeccaPurple",
+        ShowLand=true, 
+        LandColor="LightGreen",
+        ShowOcean=true, 
+        OceanColor="LightBlue",
+        ShowLakes=true, 
+        LakeColor="Blue",
+        ShowRivers=true, 
+        RiverColor="Blue"
+    )
+
+let moreFeaturesBaseMap =
+    Chart.PointGeo([])
+    |> Chart.withMap myGeo
+    |> Chart.withMarginSize(0,0,0,0)
+
+(*** condition: ipynb ***)
+#if IPYNB
+moreFeaturesBaseMap
+#endif // IPYNB
+
+(***hide***)
+moreFeaturesBaseMap |> GenericChart.toChartHTML
+(***include-it-raw***)
+
+(**
+## Cultural Base Maps
+
+In addition to physical base map features, a "cultural" base map is included which is composed of country borders and selected sub-country borders such as states.
+
+_Note and disclaimer: cultural features are by definition subject to change, debate and dispute. Plotly includes data from Natural Earth "as-is" and defers to the Natural Earth policy regarding disputed borders which read:_
+
+> Natural Earth Vector draws boundaries of countries according to defacto status. We show who actually controls the situation on the ground.
+
+Here is a map with only cultural features enabled and styled, at a 1:50m resolution, which includes only country boundaries. See below for country sub-unit cultural base map features:
+*)
+
+let countryGeo =
+    Geo.init(
+        Visible=false, 
+        Resolution=StyleParam.GeoResolution.R50,
+        ShowCountries=true, 
+        CountryColor="RebeccaPurple"
+    )
+
+
+let countryBaseMap =
+    Chart.PointGeo([])
+    |> Chart.withMap countryGeo
+    |> Chart.withMarginSize(0,0,0,0)
+
+(*** condition: ipynb ***)
+#if IPYNB
+countryBaseMap
+#endif // IPYNB
+
+(***hide***)
+countryBaseMap |> GenericChart.toChartHTML
+(***include-it-raw***)

docs/5_1_geo-plots.fsx

@@ -0,0 +1,127 @@
+(**
+---
+title: Scatter and line plots on Geo maps
+category: Geo map charts
+categoryindex: 6
+index: 2
+---
+*)
+
+(*** hide ***)
+
+(*** condition: prepare ***)
+#r "nuget: Newtonsoft.JSON, 12.0.3"
+#r "../bin/Plotly.NET/netstandard2.0/Plotly.NET.dll"
+
+(*** condition: ipynb ***)
+#if IPYNB
+#r "nuget: Plotly.NET, {{fsdocs-package-version}}"
+#r "nuget: Plotly.NET.Interactive, {{fsdocs-package-version}}"
+#endif // IPYNB
+
+(** 
+# Scatter and line plots on Geo maps
+
+[![Binder]({{root}}img/badge-binder.svg)](https://mybinder.org/v2/gh/plotly/Plotly.NET/gh-pages?filepath={{fsdocs-source-basename}}.ipynb) 
+[![Script]({{root}}img/badge-script.svg)]({{root}}{{fsdocs-source-basename}}.fsx) 
+[![Notebook]({{root}}img/badge-notebook.svg)]({{root}}{{fsdocs-source-basename}}.ipynb)
+
+*Summary:* This example shows how to create Point and Line charts on geo maps in F#.
+
+let's first create some data for the purpose of creating example charts:
+*)
+open Plotly.NET 
+
+let cityNames = [
+    "Montreal"; "Toronto"; "Vancouver"; "Calgary"; "Edmonton";
+    "Ottawa"; "Halifax"; "Victoria"; "Winnepeg"; "Regina"
+]
+
+let lon = [
+    -73.57; -79.24; -123.06; -114.1; -113.28;
+    -75.43; -63.57; -123.21; -97.13; -104.6
+]
+let lat = [
+    45.5; 43.4; 49.13; 51.1; 53.34; 45.24;
+    44.64; 48.25; 49.89; 50.45
+]
+
+(**
+The simplest type of geo plot is plotting the (lon,lat) pairs of a location via `Chart.PointGeo`. 
+Here is an example using the location of Canadian cities:
+*)
+
+let pointGeo =
+    Chart.PointGeo(
+        lon,
+        lat,
+        Labels=cityNames,
+        TextPosition=StyleParam.TextPosition.TopCenter
+    )
+    |> Chart.withMapStyle(
+        Scope=StyleParam.GeoScope.NorthAmerica, 
+        Projection=GeoProjection.init(StyleParam.GeoProjectionType.AzimuthalEqualArea),
+        CountryColor = "lightgrey"
+    )
+    |> Chart.withMarginSize(0,0,0,0)
+
+(*** condition: ipynb ***)
+#if IPYNB
+pointGeo
+#endif // IPYNB
+
+(***hide***)
+pointGeo |> GenericChart.toChartHTML
+(***include-it-raw***)
+
+
+(**
+To connect the given (lon,lat) pairs via straight lines, use `Chart.LineGeo`. 
+Below is an example that pulls external data as a Deedle data 
+frame containing the source and target locations of American Airlines flights from Feb. 2011:
+*)
+
+#r "nuget: Deedle"
+#r "nuget: FSharp.Data"
+open Deedle
+open FSharp.Data
+open System.IO
+open System.Text
+
+let data = 
+    Http.RequestString "https://raw.githubusercontent.com/plotly/datasets/c34aaa0b1b3cddad335173cb7bc0181897201ee6/2011_february_aa_flight_paths.csv"
+    |> fun csv -> Frame.ReadCsvString(csv,true,separators=",")
+
+let opacityVals : float [] = data.["cnt"] |> Series.values |> fun s -> s |> Seq.map (fun v -> v/(Seq.max s)) |> Array.ofSeq
+let startCoords = Series.zipInner data.["start_lon"] data.["start_lat"]
+let endCoords = Series.zipInner data.["end_lon"] data.["end_lat"]
+let coords = Series.zipInner startCoords endCoords |> Series.values
+
+let flights = 
+    coords 
+    |> Seq.mapi (fun i (startCoords,endCoords) ->
+        Chart.LineGeo(
+            [startCoords; endCoords],
+            Opacity = opacityVals.[i],
+            Color = "red"
+        )
+    )
+    |> Chart.Combine
+    |> Chart.withLegend(false)
+    |> Chart.withMapStyle(
+        Scope=StyleParam.GeoScope.NorthAmerica, 
+        Projection=GeoProjection.init(StyleParam.GeoProjectionType.AzimuthalEqualArea),
+        ShowLand=true,
+        LandColor = "lightgrey"
+    )
+    |> Chart.withMarginSize(0,0,50,0)
+    |> Chart.withTitle "Feb. 2011 American Airline flights"
+
+(*** condition: ipynb ***)
+#if IPYNB
+flights
+#endif // IPYNB
+
+(***hide***)
+flights |> GenericChart.toChartHTML
+(***include-it-raw***)

docs/5_0_choropleth-map.fsx → docs/5_2_choropleth-map.fsx

@@ -1,9 +1,9 @@
 (**
 ---
 title: Choropleth maps
-category: Map Charts
+category: Geo map charts
 categoryindex: 6
-index: 1
+index: 3
 ---
 *)
 
@@ -193,10 +193,8 @@ open System.IO
 open System.Text
 
 let data = 
-     let dataString = Http.RequestString "https://raw.githubusercontent.com/plotly/datasets/master/fips-unemp-16.csv"
-     let byteArray = Encoding.UTF8.GetBytes(dataString)
-     use stream = new MemoryStream(byteArray)
-     Frame.ReadCsv(stream,true,separators=",",schema="fips=string,unemp=float")
+    Http.RequestString "https://raw.githubusercontent.com/plotly/datasets/master/fips-unemp-16.csv"
+    |> fun csv -> Frame.ReadCsvString(csv,true,separators=",",schema="fips=string,unemp=float")
 
 
 (**
@@ -239,7 +237,10 @@ let choroplethGeoJSON =
     )
     |> Chart.withMap(
         Geo.init(
-            Scope=StyleParam.GeoScope.Usa
+            Scope=StyleParam.GeoScope.NorthAmerica, 
+            Projection=GeoProjection.init(StyleParam.GeoProjectionType.AzimuthalEqualArea),
+            ShowLand=true,
+            LandColor = "lightgrey"
         )
     )
     |> Chart.withSize (800.,800.)