(DOCSP-4212): Geospatial Scatter Charts (#185)

* (DOCSP-4212) Early work on geospatial scatter doc.

* (DOCSP-4212) Started drafting use case before interrupt.

* (DOCSP-4212-B) First reviewable draft of Geospatial Scatter reference for Charts.

* (DOCSP-4212-B) Tweaks before review.

* (DOCSP-4212-B) Review by Jeff.

* (DOCSP-4212-B) Review by Tom Hollander.

Author: rob-mongodb

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

@@ -79,3 +79,4 @@ intensity to compare concentrations of data points on a map.
 
       /chart-type-reference/geospatial-heatmap
       /chart-type-reference/choropleth.txt
+      /chart-type-reference/geospatial-scatter.txt

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

@@ -0,0 +1,121 @@
+.. _scatter-ref:
+.. _geospatial-scatter-type:
+.. _geo-spatial:
+
+==================
+Geospatial Scatter
+==================
+
+.. default-domain:: mongodb
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 1
+   :class: singlecol
+
+Overview
+--------
+
+Geospatial scatter charts distribute data from a data source across geographical locations, 
+and, optionally, color the data points based on the database field of your choice and scale
+the size of data points.  The sample images in the next section demonstrate
+how to construct a geospatial scatter chart to locate the nighborhoods in NYC with the most rooms available
+at a specified price.
+
+Encoding Channels
+-----------------
+
+Geospatial scatter charts use the :guilabel:`Coordinates`, :guilabel:`Color`
+and :guilabel:`Size` encoding channels. See :doc:`Geospatial Customization Options </customize-charts/geospatial-customization>`
+for additional options for customizing your geospatial charts.
+
+Coordinates
+~~~~~~~~~~~
+
+The :guilabel:`Coordinates` encoding channel defines the map
+area of geospatial charts. The image below distributes all of the instances
+of the ``location`` geopoint in the `Sample AirBnB Listings Dataset <https://docs.atlas.mongodb.com/sample-data/sample-airbnb>`_.
+However, all of the circles are green and the same size since we have
+not yet specified fields for the :guilabel:`Size` and :guilabel:`Color`
+encoding channels.
+
+.. note::
+
+   |service| provides `several sample data sets <https://docs.atlas.mongodb.com/sample-data/available-sample-datasets/>`_ 
+   for download.
+
+See the :ref:`Geopoint <geopoint-channel>` reference
+page for more information about what types of data you can use in this
+channel. 
+
+.. figure:: /images/charts/geospatial-scatter-coordinates-example.png
+
+Color
+~~~~~
+
+(*Optional*) The :guilabel:`Color` encoding channel changes the color of the data points to
+categorize the displayed geopoints by the value of the selected collection field. |charts| lists
+the colors used in a key to the right of the chart. In the image below, the ``property_type`` 
+distributes the property types in NYC by color. The key to the right of the chart indicates
+green for guest suites and dark blue for apartments, for example.
+However, all of the circles are still the same size since we have
+not yet specified a field for the :guilabel:`Size` encoding channel.
+
+.. figure:: /images/charts/geospatial-scatter-color-example.png
+
+Size
+~~~~
+
+(*Optional*) The :guilabel:`Size` aggregation encoding channel changes the size of the
+data point markers, with larger sizes indicating larger aggregated values. The image below
+uses the mean of the ``weekly_price`` collection field to aggregate all instances of the geopoint that you 
+chose for the :guilabel:`Coordinates` encoding channel. The key to right of the chart
+indicates the aggregation value for the different circle sizes.
+
+.. figure:: /images/charts/geospatial-scatter-size-example.png
+
+.. note::
+
+   If no fields are encoded in the :guilabel:`Size` encoding channel, |charts-short| displays all points with the same size.
+
+
+Limitations
+-----------
+
+The maximum query response size for Scatter charts is 1000 documents.
+
+Build a Geospatial Scatter Chart
+--------------------------------
+
+To create a geospatial scatter chart:
+
+1. On the :guilabel:`Chart Builder`, select :guilabel:`Geospatial` from
+   the :guilabel:`Chart Type` list.
+
+#. Select :guilabel:`Scatter` from the three available geospatial
+   chart types.
+
+#. Choose the data source for your chart from the :guilabel:`Data Source` list.
+
+   .. note:: See :ref:`Add a Data Source <add-data-source>` if you have not yet defined a data source for your charts.
+
+#. Drag a geopoint field from :guilabel:`Fields` to the :guilabel:`Coordinates`
+   encoding channel.
+   
+   |charts| distributes the data from your MongoDB collection based
+   on the values of the selected geopoint field.
+
+#. (*Optional*) Drag another collection field from the :guilabel:`Fields` to the :guilabel:`Color`
+   encoding channel.
+
+   |charts| colors the data points according to your selection.
+
+#. (*Optional*) Drag another collection field to the :guilabel:`Size`
+   encoding channel.
+
+   |charts| aggregates document fields with matching values in the data source. 
+
+#. Click the pencil icon above the chart to give it name.
+
+#. Click :guilabel:`Save and Close`.

source/chart-types.txt

@@ -14,6 +14,14 @@ Chart Types
    :depth: 2
    :class: singlecol
 
+:ref:`Geospatial Charts <geo-spatial>`
+--------------------------------------
+
+Geospatial charts display a mark for each unique geographic location.
+
+.. figure:: /images/charts/geospatial-chart-ref.png
+   :figwidth: 791px
+
 :ref:`Column and Bar Charts <column-bar-chart-ref>`
 ---------------------------------------------------