Skip to content

Commit e3af28e

Browse files
jeff-allen-mongojeff-allen-mongo
committed
Choropleth Chart and Regions Pages (#146)
* (DOCSP-4566): Choropleth chart type page * Updates per Kay's feedback * Updates per Kay's feedback pt 2 * Fixing example * (DOCSP-4566): Adding choropleth region page * Updates per Tom's feedback * Updates per Kay's feedback * Updates per Kay's feedback pt 2 * Wording tweak * Wording tweak * Updates per Tom's feedback
1 parent bef58db commit e3af28e

File tree

6 files changed

+223
-1
lines changed

6 files changed

+223
-1
lines changed

‎config/sphinx_local.yaml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,8 @@ theme:
2222
- /tutorial/movie-details/movie-details-tutorial-overview
2323
- /chart-types
2424
- /chart-type-reference/data-table
25+
- /chart-type-reference/geo-spatial
26+
- /chart-type-reference/choropleth
2527
- /customize-charts
2628
sidebars:
2729
'**':

‎source/chart-type-reference/choropleth-regions.txt

Lines changed: 86 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,86 @@
1+
.. _choropleth-shape-scheme:
2+
3+
==============================
4+
Choropleth Chart Shape Schemes
5+
==============================
6+
7+
.. default-domain:: mongodb
8+
9+
|charts| provides shape schemes to help define regions in your
10+
:ref:`Choropleth Charts <choropleth-ref>`. Each shape scheme has a
11+
distinct set of expected values where each value corresponds to a
12+
region.
13+
14+
Shape Schemes and Location
15+
--------------------------
16+
17+
In choropleth charts, you specify regions with the
18+
:data:`Location` channel. The value in the location channel
19+
must match a region value for the selected :guilabel:`Shape Scheme`
20+
(case insensitive). For example, when using the :guilabel:`US States`
21+
scheme, the region of ``California`` will match both ``california``
22+
and ``CA`` as well as ``California``.
23+
24+
Available Shape Schemes
25+
~~~~~~~~~~~~~~~~~~~~~~~
26+
27+
The following table defines the available shape schemes and their
28+
expected :guilabel:`Location` values:
29+
30+
.. list-table::
31+
:header-rows: 1
32+
:widths: 30 60
33+
34+
* - Shape Scheme
35+
- Description
36+
37+
* - :guilabel:`Countries and Regions`
38+
- *Default shape scheme.* Accepts full country names
39+
(e.g., ``Brazil``) and 2-letter
40+
`ISO country codes
41+
<https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes>`__
42+
(e.g., ``BR``).
43+
44+
Also accepts some common country name variants (e.g.,
45+
``United States`` and ``USA``).
46+
47+
* - :guilabel:`US States`
48+
- Accepts full United States state names and 2 letter US state
49+
abbreviations. For example, ``New York`` or ``NY``.
50+
51+
* - :guilabel:`Canadian Provinces`
52+
- Accepts full Canadian province names (English or French) and
53+
2 letter Canadian province codes. For example, ``New Brunswick``
54+
or ``Nouveau-Brunswick``.
55+
56+
* - :guilabel:`UK Countries`
57+
- Accepts the following UK Countries:
58+
59+
- ``England``
60+
61+
- ``Scotland``
62+
63+
- ``Wales``
64+
65+
- ``Northern Ireland``
66+
67+
* - :guilabel:`UK Counties and Districts`
68+
- Accepts local administrative counties across the United Kingdom.
69+
For example, ``Norfolk`` or ``Essex``.
70+
71+
.. note::
72+
73+
This shape scheme does not include ceremonial counties.
74+
75+
* - :guilabel:`German States`
76+
- Accepts full German state names (English or German) and
77+
2 letter German state codes. For example, ``Saxony`` or
78+
``Sachsen``.
79+
80+
* - :guilabel:`Australian States`
81+
- Accepts full Australian state names and 2-3 letter Australian
82+
state abbreviations. For example, ``Victoria`` or ``VIC``.
83+
84+
* - :guilabel:`Australian Local Government Areas`
85+
- Accepts Australian local government areas. For example,
86+
``Yarra`` or ``Waverley``.

‎source/chart-type-reference/choropleth.txt

Lines changed: 133 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,133 @@
1+
.. _choropleth-ref:
2+
3+
================
4+
Choropleth Chart
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+
Choropleth charts are maps that use shading to depict differences
16+
across regions. The shading of a region (e.g. states, countries) is
17+
based on an aggregated value and is proportional to the corresponding
18+
value of other regions.
19+
20+
Unlike other geospatial charts, choropleths do not require coordinate
21+
data in your collections. Instead you can have names of regions as
22+
strings, so long as the region strings correspond to the names used in
23+
a supported :ref:`Shape Scheme <choropleth-shape-scheme>`.
24+
25+
.. _choropleth-regions:
26+
27+
Regions
28+
-------
29+
30+
To help define regions, |charts| provides
31+
:ref:`Shape Schemes <choropleth-shape-scheme>`. For example, with the
32+
:guilabel:`US States` scheme, you can define regions at a state level,
33+
and your location field value must be one of the 50 states.
34+
35+
.. _choropleth-enc-channels:
36+
37+
Encoding Channels
38+
-----------------
39+
40+
Choropleth charts use the following :ref:`encoding channels
41+
<encoding-channels>`:
42+
43+
.. list-table::
44+
:header-rows: 1
45+
:widths: 20 80
46+
47+
* - Encoding Channel
48+
- Description
49+
50+
* - .. data:: Location
51+
- Defines the :ref:`regions <choropleth-regions>` to be shaded
52+
on the map.
53+
54+
The value must match (case insensitive) a region value for the
55+
selected :guilabel:`Shape Scheme`. For example, when using the
56+
:guilabel:`US States` scheme, the region of ``California``
57+
matches ``california`` and ``CA`` as well as ``California``.
58+
59+
For a complete list of shape schemes and their expected values,
60+
refer to the :ref:`Shape Schemes <choropleth-shape-scheme>`
61+
page.
62+
63+
* - .. data:: Color
64+
- Defines the :guilabel:`Aggregation` that determines the
65+
shading of the corresponding :guilabel:`Location`. You
66+
can customize the range of colors that corresponds to
67+
the relative aggregated values.
68+
69+
Use Cases
70+
---------
71+
72+
Choropleth charts can be used to depict differences in your
73+
selected aggregated field between geographic subregions, such as
74+
states or countries. They are useful when you have a dataset with
75+
clearly defined subregions compatible with one of the
76+
:ref:`Shape Schemes <choropleth-shape-scheme>` |charts| provides.
77+
78+
A choropleth chart is a good choice to compare:
79+
80+
- Population density across US states.
81+
82+
- Annual rainfall across European countries.
83+
84+
- Number of cellphone towers across Australian states.
85+
86+
.. seealso::
87+
88+
If you are looking for a chart to depict exact values rather than
89+
a high-level comparison, consider using a
90+
:ref:`Data Table <data-table-ref>`.
91+
92+
Example
93+
-------
94+
95+
The following choropleth chart visualizes the total count of
96+
movie releases across various countries. Each document in the
97+
collection contains an array of countries where a particular movie was
98+
released.
99+
100+
.. figure:: /images/charts/choropleth-example.png
101+
102+
In this chart, we specify a
103+
:ref:`Shape Scheme <choropleth-shape-scheme>` of
104+
:guilabel:`World Countries` to divide the map into countries.
105+
106+
The ``countries`` array in the :guilabel:`Location` field contains
107+
an array of elements representing each country where a movie
108+
was released. These elements match the values expected by the
109+
:guilabel:`World Countries` shape scheme. We unwind the array so
110+
each movie contributes to the count for each country where it was
111+
released.
112+
113+
The :guilabel:`Color` field of ``id`` is aggregated by
114+
:guilabel:`Count`. As a result, each country is shaded based on its
115+
number of movies released.
116+
117+
The custom color palatte for this chart ranges from yellow for
118+
lower ratings to dark red for higher ratings. Based on the
119+
visualization, we see that France, India, and Japan have relatively
120+
high movie release counts compared with other countries.
121+
122+
.. seealso::
123+
124+
For a complete list of choropleth :guilabel:`Shape Schemes` and
125+
their expected values, refer to the
126+
:ref:`Choropleth Regions <choropleth-regions>` page.
127+
128+
.. class:: hidden
129+
130+
.. toctree::
131+
:titlesonly:
132+
133+
Shape Schemes </chart-type-reference/choropleth-regions>

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

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -91,3 +91,4 @@ map's data point markers. This setting defaults to ``2``.
9191
:titlesonly:
9292

9393
/chart-type-reference/geospatial-heatmap
94+
/chart-type-reference/choropleth.txt

‎source/chart-types.txt

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -83,4 +83,4 @@ Text Charts
8383
/chart-type-reference/grid-charts
8484
/chart-type-reference/donut-chart
8585
/chart-type-reference/text-charts
86-
/chart-type-reference/geo-spatial
86+
/chart-type-reference/geo-spatial

‎source/images/charts/choropleth-example.png

826 KB
Loading

0 commit comments

Comments
 (0)