Skip to content

Commit 4fedeef

Browse files
jeff-allen-mongojeff-allen-mongo
committed
(DOCSP-4211): Geopoint encoding channels (#141)
* (DOCSP-4211): Geopoint encoding channels WIP * Updates per Steve's feedback * Updates per Tom's feedback * Updates per Tom's feedback pt 2
1 parent 0f16677 commit 4fedeef

File tree

2 files changed

+170
-95
lines changed

2 files changed

+170
-95
lines changed

‎source/encoding-channels.txt

Lines changed: 61 additions & 95 deletions
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ Encoding Channels
99
.. contents:: On this page
1010
:local:
1111
:backlinks: none
12-
:depth: 2
12+
:depth: 1
1313
:class: singlecol
1414

1515
Encoding channels are the building blocks of your visualizations.
@@ -19,14 +19,17 @@ the visualization. The encoding process dictates how that data
1919
appears in the chart based on the :ref:`channel type
2020
<charts-channel-type-table>` selected.
2121

22+
.. _charts-channel-type-table:
23+
24+
Encoding Channel Types
25+
----------------------
26+
2227
Each encoding channel type provides different capabilities for
23-
processing and visualizing your data, which vary based on the type of
24-
data you provide to the channel (e.g., ``string`` versus ``numeric``
28+
processing and visualizing your data. Each channel type accepts
29+
distinct data types (e.g., ``string`` versus ``numeric``
2530
data). The following table describes each encoding channel type in
2631
|charts|:
2732

28-
.. _charts-channel-type-table:
29-
3033
.. list-table::
3134
:widths: 30 70
3235
:header-rows: 1
@@ -56,12 +59,23 @@ data). The following table describes each encoding channel type in
5659
* - Aggregation
5760
- A point on the chart is created by applying an
5861
:manual:`aggregation <aggregation>` function over the values of
59-
this field from multiple documents; for example
60-
:manual:`$count </reference/operator/aggregation/count/>` and
61-
:manual:`$sum </reference/operator/aggregation/sum/>`. For more
62+
this field from multiple documents. For more
6263
information on aggregation in |charts-short|, see the
6364
:ref:`Aggregation <building-charts-aggregation>` section.
6465

66+
* - Geopoint
67+
- When you create a chart using a geopoint channel type, |charts|
68+
renders a map to visualize your data. A mark is plotted on the
69+
map for each document containing the selected field based on
70+
the field's latitude and longitude values. Geopoint channel
71+
types are used in the :guilabel:`Coordinates` channel on
72+
:guilabel:`Geospatial Scatter` and
73+
:guilabel:`Geospatial Heatmap` chart types.
74+
75+
For more information on the geopoint encoding channel type,
76+
refer to the :ref:`Geopoint Channel Type <geopoint-channel>`
77+
section.
78+
6579
.. _building-charts-aggregation:
6680

6781
Aggregation
@@ -99,102 +113,54 @@ appropriate aggregation options accordingly.
99113
We see from the chart that the most common landslide trigger is
100114
``Downpour`` followed by ``Rain``.
101115

102-
.. _multi-series-charts:
103-
104-
Multi-Series Charts
105-
-------------------
106-
107-
|charts| supports building *multi-series* charts, which split your
108-
chart data into groups, or *series*, to compare additional
109-
fields within your schema. There are two ways to create multi-series
110-
charts:
116+
.. _geopoint-channel:
111117

112-
- :ref:`Using multiple aggregation or value field mappings
113-
<multiple-field-mappings>`. Use this method to compare or aggregate
114-
upon multiple non-categorical fields in the schema.
118+
Geopoint Channel Type
119+
---------------------
115120

116-
- :ref:`Using the Series field in the chart builder
117-
<charts-series-encoding>`. Use this method when grouping data based
118-
on a discrete list of items.
121+
Geopoint channel types are used in the :guilabel:`Coordinates` channel
122+
on :guilabel:`Geospatial Scatter` and :guilabel:`Geospatial Heatmap`
123+
chart types. Geospatial charts visualize data that references specific
124+
geographic locations.
119125

120-
.. _multiple-field-mappings:
126+
|charts| automatically determines which fields in your dataset, if
127+
any, are :manual:`GeoJSON Points </reference/geojson/>`.
128+
|charts-short| signifies these fields with a :icon-charts:`geoglobe`
129+
icon. You can map these fields directly to a geopoint channel type
130+
by dragging them onto an appropriate geopoint channel type in
131+
the chart builder. |charts-short| automatically determines the latitude
132+
and longitude values from the field and adds a point to the map for
133+
each document.
121134

122-
Multiple Field Mappings
123-
~~~~~~~~~~~~~~~~~~~~~~~
135+
.. note::
124136

125-
|charts| allows you to map multiple :ref:`aggregation
126-
<building-charts-aggregation>` or :guilabel:`value`
127-
:ref:`encoding channels <encoding-channels>` to a single chart property
128-
(e.g. :guilabel:`X Axis` or :guilabel:`Y Axis`). This allows you to
129-
compare additional fields in your visualization by creating new series
130-
based on the encoding channels added.
137+
You can also assign numeric coordinates or arrays to a
138+
geopoint channel type to specify latitude and
139+
longitude not stored as :manual:`GeoJSON Points
140+
</reference/geojson/#point>`. For details on this process, see the
141+
following section.
131142

132-
After dragging a field to an :guilabel:`aggregation`
133-
or :guilabel:`value` :ref:`encoding channel <encoding-channels>`, an
134-
additional optional encoding channel of the same type appears below the
135-
one which was just added, allowing you to add additional series to your
136-
visualization. This process repeats with each channel you add, so
137-
you can map as many fields as desired to your chart.
143+
Assign Non-GeoJSON Fields to a Geopoint Channel Type
144+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
138145

139-
.. example::
140-
141-
The following multi-series column chart shows average movie ratings
142-
by genre from two different sources: `IMDB <https://www.imdb.com/>`_
143-
and `Rotten Tomatoes <https://www.rottentomatoes.com/>`_:
146+
This section describes how to use fields not stored as
147+
:manual:`GeoJSON Points </reference/geojson/#point>` in a
148+
geopoint channel type.
144149

145-
.. figure:: /images/charts/multi-series-agg.png
146-
:figwidth: 720px
147-
:alt: Movie Ratings Multiseries Chart
150+
- You can drag numeric fields onto a geopoint channel type to
151+
specify latitude and longitude. When you drag a numeric field onto a
152+
geopoint channel type, the channel updates to use the selected field
153+
as either :guilabel:`Latitude` or :guilabel:`Longitude`.
154+
|charts-short| prompts you for a second numeric field to fill in the
155+
other value.
148156

149-
There are two :guilabel:`aggregation` encoding channels on
150-
the chart's :guilabel:`Y Axis`, one for each of the site's rating
151-
fields. By selecting the :guilabel:`mean` aggregation option, the
152-
chart aggregates these two fields using the
153-
:manual:`$avg </reference/operator/aggregation/avg/>` operator to
154-
provide a comparison of the average of two fields in the same
155-
column.
156-
157-
.. tip::
158-
159-
Use multiple field mappings to create a multi-series chart when
160-
the values being compared in the visualization come from two or more
161-
separate fields in the schema.
162-
163-
In the example above, there is one series for Rotten Tomato ratings
164-
and one series for IMDB ratings. Since these are separate fields
165-
within the schema, adding multiple :guilabel:`aggregation` encoding
166-
channels to map the data is the best choice to compare the fields.
167-
168-
.. _charts-series-encoding:
169-
170-
Series Encoding Channel
171-
~~~~~~~~~~~~~~~~~~~~~~~
172-
173-
You can also create multi-series charts by using the :guilabel:`Series`
174-
field in the chart builder. The :guilabel:`Series` field differs from
175-
:guilabel:`aggregation` :ref:`encoding channels <encoding-channels>`
176-
because it instead utilizes a :ref:`Category encoding channel
177-
<charts-channel-type-table>`. When creating a series using the
178-
:guilabel:`category` encoding channel, each unique value from the
179-
data field becomes a series in the visualization.
180-
181-
.. example::
182-
183-
The following multi-series column chart shows order data from an
184-
office supply store, showing the most common items sold by
185-
store location:
186-
187-
.. figure:: /images/charts/series-encoding-channel-example.png
188-
:figwidth: 720px
189-
:alt: Supply Store Series Encoding Channel Example
157+
- Alternatively, you can drag a numeric array onto a
158+
geopoint channel type to specify location coordinates
159+
from a field. When you use this approach, you can specify which
160+
indexes of the array to use for latitude and longitude components.
190161

191-
By using the ``item.name`` in the :guilabel:`Series` encoding
192-
channel, a series within each location group is added for each
193-
item name.
162+
For additional information and examples on :guilabel:`Geospatial`
163+
:guilabel:`Scatter` and :guilabel:`Heatmap` charts which utilize
164+
geopoint channel types, refer to the relevant chart type pages.
194165

195-
.. tip::
196166

197-
The :guilabel:`Series` field is useful when you are grouping data
198-
based on a discrete list of items. This approach should be used when
199-
the values for all series are stored in a single field, with a
200-
separate field used to establish the discrete categories.

‎source/multi-series-charts.txt

Lines changed: 109 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,109 @@
1+
.. _multi-series-charts:
2+
3+
===================
4+
Multi-Series Charts
5+
===================
6+
7+
.. default-domain:: mongodb
8+
9+
.. contents:: On this page
10+
:local:
11+
:backlinks: none
12+
:depth: 1
13+
:class: singlecol
14+
15+
|charts| supports building *multi-series* charts, which split your
16+
chart data into groups, or *series*, to compare additional
17+
fields within your schema. There are two ways to create multi-series
18+
charts:
19+
20+
- :ref:`Using multiple aggregation or value field mappings
21+
<multiple-field-mappings>`. Use this method to compare or aggregate
22+
upon multiple non-categorical fields in the schema.
23+
24+
- :ref:`Using the Series field in the chart builder
25+
<charts-series-encoding>`. Use this method when grouping data based
26+
on a discrete list of items.
27+
28+
.. _multiple-field-mappings:
29+
30+
Multiple Field Mappings to a Single Axis
31+
----------------------------------------
32+
33+
|charts| allows you to map multiple :ref:`Aggregation
34+
<building-charts-aggregation>` or :guilabel:`Value`
35+
:ref:`encoding channels <encoding-channels>` to a single chart property
36+
(e.g. :guilabel:`X Axis` or :guilabel:`Y Axis`). This allows you to
37+
compare additional fields in your visualization by creating new series
38+
based on the encoding channels added.
39+
40+
After dragging a field to an :guilabel:`aggregation`
41+
or :guilabel:`value` :ref:`encoding channel <encoding-channels>`, an
42+
additional optional encoding channel of the same type appears below the
43+
one which was just added, allowing you to add additional series to your
44+
visualization. This process repeats with each channel you add, so
45+
you can map as many fields as desired to your chart.
46+
47+
.. example::
48+
49+
The following multi-series column chart shows average movie ratings
50+
by genre from two different sources: `IMDB <https://www.imdb.com/>`_
51+
and `Rotten Tomatoes <https://www.rottentomatoes.com/>`_:
52+
53+
.. figure:: /images/charts/multi-series-agg.png
54+
:figwidth: 720px
55+
:alt: Movie Ratings Multiseries Chart
56+
57+
There are two :guilabel:`aggregation` encoding channels on
58+
the chart's :guilabel:`Y Axis`, one for each of the site's rating
59+
fields. By selecting the :guilabel:`mean` aggregation option, the
60+
chart aggregates these two fields using the
61+
:manual:`$avg </reference/operator/aggregation/avg/>` operator to
62+
provide a comparison of the average of two fields in the same
63+
column.
64+
65+
.. tip::
66+
67+
Use multiple field mappings to create a multi-series chart when
68+
the values being compared in the visualization come from two or more
69+
separate fields in the schema.
70+
71+
In the example above, there is one series for Rotten Tomato ratings
72+
and one series for IMDB ratings. Since these are separate fields
73+
within the schema, adding multiple :guilabel:`aggregation` encoding
74+
channels to map the data is the best choice to compare the fields.
75+
76+
.. _charts-series-encoding:
77+
78+
Series Field
79+
------------
80+
81+
You can also create multi-series charts by using the :guilabel:`Series`
82+
field in the chart builder. The :guilabel:`Series` field differs from
83+
:guilabel:`aggregation` :ref:`encoding channels <encoding-channels>`
84+
because it instead utilizes a :guilabel:`Category`
85+
:ref:`encoding channel <charts-channel-type-table>` instead of a
86+
:guilabel:`Value` or :guilabel:`Aggregation` channel. When creating a
87+
series using the :guilabel:`Category` encoding channel, each unique
88+
value from the data field becomes a series in the visualization.
89+
90+
.. example::
91+
92+
The following multi-series column chart shows order data from an
93+
office supply store, showing the most common items sold by
94+
store location:
95+
96+
.. figure:: /images/charts/series-encoding-channel-example.png
97+
:figwidth: 720px
98+
:alt: Supply Store Series Encoding Channel Example
99+
100+
By using the ``item.name`` in the :guilabel:`Series` encoding
101+
channel, a series within each location group is added for each
102+
item name.
103+
104+
.. tip::
105+
106+
The :guilabel:`Series` field is useful when you are grouping data
107+
based on a discrete list of items. This approach should be used when
108+
the values for all series are stored in a single field, with a
109+
separate field used to establish the discrete categories.

0 commit comments

Comments
 (0)