DOCSP-4579: [Charts] Update top-level Geospatial chart type placeholder (#147)

* DOCSP-4579: [Charts] Update top-level Geospatial chart type placeholder

Author: steveren

source/chart-type-reference/geo-spatial.txt

@@ -14,76 +14,63 @@ Geospatial Charts
    :depth: 1
    :class: singlecol
 
-Placeholder description for the geospatial chart type.
+Geospatial data defines specific geographical
+locations, either in the form of latitude and longitude
+coordinates or text fields with names of geographical areas,
+such as countries or states. Geospatial charts combine
+geospatial data with other forms of data to create map-based
+charts. MongoDB collections can store geospatial data as
+:manual:`GeoJSON objects </geospatial-queries/#geospatial-geojson>`
+or as :manual:`legacy coordinate pairs
+</geospatial-queries/#geospatial-legacy>`.
 
-Customization
--------------
+Geospatial charts can visualize geospatial data in a variety
+of chart formats, including :ref:`choropleth
+<choropleth-description>`, :ref:`scatter <scatter-description>`,
+and :ref:`heatmap <heatmap-description>`.
 
-To access the available customizations for any chart, click the
-:guilabel:`Customization` tab above the :ref:`encoding channels
-<encoding-channels>` in the :doc:`Chart Builder </build-charts>`.
+.. seealso::
 
-.. figure:: /images/charts/geospatial-customization-tab.png
-   :figwidth: 242px
-   :alt: Geospatial customization tab
+   - :ref:`Geopoint encoding channel type <geopoint-channel>`
+   - :ref:`Geospatial chart customization <geospatial-customization>`
 
-Custom Color Palette
-~~~~~~~~~~~~~~~~~~~~
+.. _choropleth-description:
 
-The color palette specifies the range of colors that corresponds to
-relative aggregated values in your map. 
+Choropleth
+----------
 
-:ref:`Geospatial Scatter <scatter-ref>` charts use a discrete color
-picker, and :ref:`Geospatial Heatmap <geospatial-heatmap-type>` and
-:ref:`Choropleth <choropleth-ref>` charts use a gradient color picker,
-but the mechanism to enable customization is the same. To enable
-palette customization, toggle the :guilabel:`Custom Color Palette`
-switch in the :guilabel:`General Customization` section.
+:ref:`Choropleth charts <choropleth-ref>` use predefined :ref:`shapes
+<choropleth-shape-scheme>` for geographical areas, e.g. the countries
+of the world, or the states of the United States. They are useful for
+comparing aggregated values across defined geographical areas.
 
-For more information, see :ref:`Color Palette Customization
-<color-palette-customization>`.
+.. figure:: /images/charts/geo-type-choropleth.png
+   :figwidth: 700px
+   :alt: Choropleth chart example
 
-Automatically Set Viewport
-~~~~~~~~~~~~~~~~~~~~~~~~~~
+.. _scatter-description:
 
-By default, geospatial charts show a map which includes all the data
-point markers in your specified collection. You can pan and zoom to
-change the map view, but if you close the chart and re-open it the map
-reverts to its default state. This behavior is controlled by the
-:guilabel:`Automatically Set Viewport` option.
+Scatter
+-------
 
-When you toggle the :guilabel:`Automatically Set Viewport` switch to
-``Off``, the area and zoom level at which the map is saved becomes the
-new default view.
+:ref:`Scatter charts <scatter-ref>` use customizable data markers to
+indicate data points on a map.
 
-.. note::
+.. figure:: /images/charts/geo-type-scatter.png
+   :figwidth: 700px
+   :alt: Scatter chart example
 
-   You can pan and zoom the map area in a chart on a dashboard, but
-   these changes do not affect the default map view.
+.. _heatmap-description:
 
-Opacity
-~~~~~~~
+Heatmap
+-------
 
-The :guilabel:`Opacity` level of a map modifies the degree to which
-the chart's map data shows through the data point markers. This
-setting is available on all geospatial charts.
+:ref:`Heatmap charts <heatmap-chart-ref>` use gradations of color
+intensity to compare concentrations of data points on a map.
 
-On :ref:`Geospatial Heatmap <geospatial-heatmap-type>` and
-:ref:`Choropleth <choropleth-ref>` charts, the :guilabel:`Opacity`
-level defaults to 100%. On :ref:`Geospatial Scatter <scatter-ref>`
-charts, it defaults to 20%.
-
-Radius
-~~~~~~
-
-.. include:: /includes/radius-description.rst
-
-Stroke Thickness
-~~~~~~~~~~~~~~~~
-
-:ref:`Scatter <scatter-ref>` charts provide the customization option
-to set the :guilabel:`Stroke Thickness`, measured in pixels, of the 
-map's data point markers. This setting defaults to ``2``.
+.. figure:: /images/charts/geo-type-heatmap.png
+   :figwidth: 572px
+   :alt: Heatmap chart example
 
 .. class:: hidden
 

source/chart-type-reference/geospatial-heatmap.txt

@@ -42,8 +42,8 @@ Coordinates
 ~~~~~~~~~~~
 
 A :guilabel:`geopoint` encoding channel which defines the map
-area of the chart. See the :ref:`Geopoint <geopoint>` reference page
-for more information about what types of data you can use in this
+area of the chart. See the :ref:`Geopoint <geopoint-channel>` reference
+page for more information about what types of data you can use in this
 channel.
 
 Intensity

source/customize-charts.txt

@@ -38,6 +38,12 @@ Value Axis Options
   values. These options only affect the chart's axes, and not how
   |charts-short| formats data points in the visualization.
 
+Geospatial Customization Options
+  :ref:`Geospatial customization options <geospatial-customization>`
+  modify options specific to :ref:`geospatial charts
+  <geo-spatial-charts>`, including viewport options, data marker size
+  and opacity, and heatmap radius.
+
 To customize a chart, click the :guilabel:`Customization` tab above the
 :ref:`encoding channels <encoding-channels>` in the
 :doc:`Chart Builder </build-charts>`:
@@ -56,3 +62,4 @@ Your chart automatically updates as you modify customization options.
       /customize-charts/general-customization
       /customize-charts/field-level-options
       /customize-charts/value-axis-options
+      /customize-charts/geospatial-customization

source/customize-charts/geospatial-customization.txt

@@ -0,0 +1,79 @@
+.. _geospatial-customization:
+
+================================
+Geospatial Customization Options
+================================
+
+.. default-domain:: mongodb
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 1
+   :class: singlecol
+
+To access the available customizations for any chart, click the
+:guilabel:`Customization` tab above the :ref:`encoding channels
+<encoding-channels>` in the :doc:`Chart Builder </build-charts>`.
+
+.. figure:: /images/charts/geospatial-customization-tab.png
+   :figwidth: 242px
+   :alt: Geospatial customization tab
+
+Custom Color Palette
+--------------------
+
+The color palette specifies the range of colors that corresponds to
+relative aggregated values in your map. 
+
+:ref:`Geospatial Scatter <scatter-ref>` charts use a discrete color
+picker, and :ref:`Geospatial Heatmap <geospatial-heatmap-type>` and
+:ref:`Choropleth <choropleth-ref>` charts use a gradient color picker,
+but the mechanism to enable customization is the same. To enable
+palette customization, toggle the :guilabel:`Custom Color Palette`
+switch in the :guilabel:`General Customization` section.
+
+For more information, see :ref:`Color Palette Customization
+<color-palette-customization>`.
+
+Automatically Set Viewport
+--------------------------
+
+By default, geospatial charts show a map which includes all the data
+point markers in your specified collection. You can pan and zoom to
+change the map view, but if you close the chart and re-open it the map
+reverts to its default state. This behavior is controlled by the
+:guilabel:`Automatically Set Viewport` option.
+
+When you toggle the :guilabel:`Automatically Set Viewport` switch to
+``Off``, the area and zoom level at which the map is saved becomes the
+new default view.
+
+.. note::
+
+   You can pan and zoom the map area in a chart on a dashboard, but
+   these changes do not affect the default map view.
+
+Opacity
+-------
+
+The :guilabel:`Opacity` level of a map modifies the degree to which
+the chart's map data shows through the data point markers. This
+setting is available on all geospatial charts.
+
+On :ref:`Geospatial Heatmap <geospatial-heatmap-type>` and
+:ref:`Choropleth <choropleth-ref>` charts, the :guilabel:`Opacity`
+level defaults to 100%. On :ref:`Geospatial Scatter <scatter-ref>`
+charts, it defaults to 20%.
+
+Radius
+------
+
+.. include:: /includes/radius-description.rst
+
+Stroke Thickness
+----------------
+
+:ref:`Scatter <scatter-ref>` charts provide the customization option
+to set the :guilabel:`Stroke Thickness`, measured in pixels, of the 
+map's data point markers. This setting defaults to ``2``.