Skip to content

Commit 4dbe981

Browse files
authored
(DOCSP-31114): Document new Candlestick Chart type (#610)
* Draft new candlestick chart type * Additional updates after demo * copy review feedback
1 parent 61886e2 commit 4dbe981

File tree

10 files changed

+201
-13
lines changed

10 files changed

+201
-13
lines changed

snooty.toml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,7 @@ toc_landing_pages = ["/installation", "/dashboards",
1212
"/tutorial/movie-details/movie-details-tutorial-overview",
1313
"/chart-types", "/chart-type-reference/data-table",
1414
"/chart-type-reference/geo-spatial",
15+
"/chart-type-reference/column-bar-chart",
1516
"/chart-type-reference/choropleth",
1617
"/customize-charts",
1718
"/customize-charts/conditional-formatting",
Lines changed: 169 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,169 @@
1+
.. _candlestick-chart-ref:
2+
3+
==================
4+
Candlestick 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+
You can use candlestick charts to visualize how a numeric data
16+
source changes over time. A candlestick chart consists of vertical
17+
columns, or "candles," that represent a range of your data source's
18+
opening and closing values over a period of time. If the closing value
19+
is higher or lower than the opening value, the column fills a certain
20+
color to indicate either a positive or negative change. Each column also
21+
might extend in either direction to show the highest and lowest values
22+
during the time period.
23+
24+
By observing the columns in your chart across consecutive periods of time,
25+
you can identify patterns in your data and make informed predictions.
26+
To learn about when you might use a candlestick chart, see
27+
:ref:`candlestick-chart-use-cases`. To learn about all column chart types,
28+
see :ref:`column-bar-chart-ref`.
29+
30+
Candlestick Chart Encoding Channels
31+
-----------------------------------
32+
33+
.. list-table::
34+
:header-rows: 1
35+
:widths: 20 80
36+
37+
* - Encoding Channel
38+
- Description
39+
40+
* - X Axis
41+
- The :guilabel:`category` encoding channel for your date field.
42+
43+
This channel creates a segment for each time period along the X axis
44+
based on the grouping that you select. By default, |charts| enables
45+
:ref:`binning <charts-bin-data>` to group date data into specific
46+
time periods. You can choose from the following bins:
47+
48+
.. hlist::
49+
:columns: 2
50+
51+
* Year
52+
* Month
53+
* Week of Year
54+
* Date of the Month
55+
* Day of the Week
56+
* Hour
57+
* Minute
58+
* Second
59+
60+
.. note::
61+
62+
For certain bins, you can enable the :guilabel:`Periodic`
63+
setting to visualize the aggregated results for the time period
64+
across your data. To learn more, see :ref:`Bin, Sort, and Limit Your Data
65+
<periodic-setting>`.
66+
67+
* - Y Axis
68+
- The :guilabel:`value` encoding channels for your numeric data.
69+
|charts-short| requires the following values:
70+
71+
- :guilabel:`High`, the highest value during each time period.
72+
- :guilabel:`Open`, the value at the start of each time period.
73+
- :guilabel:`Close`, the value at the end of each time period.
74+
- :guilabel:`Low`, the lowest value during each time period.
75+
76+
To define these values:
77+
78+
- If you have one field that contains your numeric data, drag the same
79+
field onto each of the channels. |charts-short| automatically calculates the
80+
high, open, close, and low values to build the chart.
81+
- If you have separate fields that represent the high, open, close, and low
82+
values for your data, drag each field onto their respective channel
83+
to build the chart.
84+
85+
.. _candlestick-chart-use-cases:
86+
87+
Use Cases
88+
---------
89+
90+
Candlestick charts are useful for visualizing :manual:`time series data
91+
</core/timeseries-collections/>` when you want to analyze a numeric
92+
measurement that changes over time. This type of chart is commonly used in
93+
financial analysis to track the price of assets such as stocks,
94+
commodities, or currencies. However, you can use candlestick charts for
95+
various types of data to suit your specific needs.
96+
97+
Consider the following examples:
98+
99+
- A trading firm tracks the stock price of a specific company by hour
100+
to make a trading decision.
101+
- A weather company tracks rainfall, snowfall, and temperature by day
102+
to predict next week's forecast.
103+
- A store owner tracks the cost of a specific item by month to determine
104+
the best time to restock inventory.
105+
106+
Customization Options
107+
---------------------
108+
109+
The following customization options are specific to candlestick
110+
charts. To see all available customization options, see
111+
:ref:`customize-charts`.
112+
113+
Customize Candlestick Color
114+
~~~~~~~~~~~~~~~~~~~~~~~~~~~
115+
116+
You can customize the colors that correspond to a positive
117+
or negative change in your chart:
118+
119+
1. Click the :guilabel:`Customize` tab for your chart.
120+
#. In the :guilabel:`General` section, enable the :guilabel:`Custom Color Palette`.
121+
#. In the dropdown next to :guilabel:`Positive` or :guilabel:`Negative`,
122+
use the color picker to select your desired color. To learn more, see
123+
:ref:`color-palette-customization`.
124+
125+
Adjust X-Axis Label Angle
126+
~~~~~~~~~~~~~~~~~~~~~~~~~~
127+
128+
.. include:: /includes/customization/adjust-x-axis-label-angle.rst
129+
130+
.. _candlestick-ref-example:
131+
132+
Example
133+
-------
134+
135+
The following chart visualizes the price of Bitcoin in US dollars
136+
as it changes every minute. The chart uses a :manual:`time series
137+
collection </core/timeseries-collections/#time-series-collections>`
138+
called ``ticker``, where each document in the collection
139+
represents a specific financial asset at a point in time. Each
140+
document includes information about the asset's ticker symbol,
141+
price, and time.
142+
143+
.. figure:: /images/charts/candlestick-chart-reference-large.png
144+
:figwidth: 750px
145+
:alt: Candlestick Chart Reference Large
146+
147+
.. tip::
148+
149+
To show the exact data values in a tooltip, hover over the body of
150+
a column in the chart.
151+
152+
The :guilabel:`X Axis` category channel, represented by the ``ticker.time``
153+
field, bins the numeric data by minute. The :guilabel:`value`
154+
encoding channels, represented by the ``ticker.price`` field, aggregate
155+
the high, open, close, and low prices during each minute to create the
156+
vertical columns in the chart.
157+
158+
The chart also uses :ref:`query filters <filter-embedded-charts>`
159+
on the ``ticker.symbol`` and ``ticker.time`` fields to include
160+
only results with the ``BTC-USD`` symbol and limit the chart to an
161+
hour-long subset of the data.
162+
163+
When the asset's closing price is higher than its opening price
164+
during a given minute, the column fills green to indicate a
165+
positive change. When its closing price is lower than its opening price,
166+
the column fills red to indicate a negative change. Each column also
167+
might extend in either direction to show the highest and lowest prices
168+
during each minute. Based on your analysis of the chart, you might make
169+
a decision to purchase, hold, or sell the asset.

source/chart-type-reference/column-bar-chart.txt

Lines changed: 23 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -20,8 +20,9 @@ trends by comparing values within a specific category.
2020
Column and Bar Chart Encoding Channels
2121
--------------------------------------
2222

23-
Column and bar charts provide the following
24-
:ref:`encoding channels <encoding-channels>`:
23+
Column and bar charts, except for
24+
the :ref:`candlestick chart type <candlestick-chart-ref>`,
25+
provide the following :ref:`encoding channels <encoding-channels>`:
2526

2627
.. list-table::
2728
:header-rows: 1
@@ -152,6 +153,20 @@ Column and bar charts provide the following sub-types:
152153
For a more detailed example, refer to the
153154
:ref:`colored bar chart example <colored-ref-example>`.
154155

156+
* - :ref:`Candlestick <candlestick-chart-ref>`
157+
- |charts| groups numeric data by the time period specified in the
158+
:guilabel:`category` :ref:`encoding channel
159+
<encoding-channels>`, and plots a vertical column that shows the
160+
highest, lowest, opening, and closing values in your data source
161+
for each time period. To learn more, see :ref:`candlestick-chart-ref`.
162+
163+
.. figure:: /images/charts/candlestick-chart-reference-small.png
164+
:figwidth: 600px
165+
:alt: Candlestick Chart Reference Small
166+
167+
For a more detailed example, refer to the
168+
:ref:`candlestick chart example <candlestick-ref-example>`.
169+
155170
Use Cases
156171
---------
157172

@@ -193,7 +208,6 @@ charts. To see all available customization options, see
193208

194209
Adjust X-Axis Label Angle
195210
~~~~~~~~~~~~~~~~~~~~~~~~~~
196-
You can adjust the X-axis label angle.
197211

198212
.. include:: /includes/customization/adjust-x-axis-label-angle.rst
199213

@@ -308,3 +322,9 @@ Limitations
308322

309323
The maximum query response size for column and bar charts is 5000
310324
documents.
325+
326+
.. toctree::
327+
:titlesonly:
328+
329+
/chart-type-reference/candlestick-chart
330+

source/chart-type-reference/combo-charts.txt

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -106,7 +106,6 @@ charts. To see all available customization options, see
106106

107107
Adjust X-Axis Label Angle
108108
~~~~~~~~~~~~~~~~~~~~~~~~~~
109-
You can adjust the X-axis label angle.
110109

111110
.. include:: /includes/customization/adjust-x-axis-label-angle.rst
112111

source/chart-type-reference/donut-chart.txt

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -193,7 +193,7 @@ total workout time is ``Surf``, followed by ``Bike Ride``.
193193
Donut Chart Using Multiple Arc Fields
194194
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
195195

196-
The following chart vizualizes rental property data. Each
196+
The following chart visualizes rental property data. Each
197197
document in the collection represents a single rental property, which
198198
includes information on prices. This donut chart shows the average price
199199
of all properties in the collection for a daily, weekly, and monthly

source/chart-type-reference/heatmap.txt

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -82,8 +82,6 @@ charts. To see all available customization options, see
8282
Adjust X-Axis Label Angle
8383
~~~~~~~~~~~~~~~~~~~~~~~~~
8484

85-
You can adjust the X-axis label angle.
86-
8785
.. include:: /includes/customization/adjust-x-axis-label-angle.rst
8886

8987
Examples

source/chart-type-reference/line-area-chart.txt

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -17,10 +17,10 @@ points connected by straight line segments. In area charts, the
1717
space beneath the line segments is filled in with color, whereas in
1818
line charts only the line segments are rendered with no additional
1919
coloring or shading. These charts facilitate visualizing data over a
20-
period of time (using time series data) and identifying trends and
21-
patterns across the entire data range. Line and area charts support
22-
visualizing both :ref:`discrete <discrete-charts>` and :ref:`continuous
23-
<continuous-charts>` data.
20+
period of time (using :manual:`time series </core/timeseries-collections/>`
21+
data) and identifying trends and patterns across the entire data range.
22+
Line and area charts support visualizing both :ref:`discrete <discrete-charts>`
23+
and :ref:`continuous <continuous-charts>` data.
2424

2525
.. _discrete-charts:
2626

Loading
Loading

source/includes/customization/adjust-x-axis-label-angle.rst

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
1-
You can choose one of the following options:
1+
You can adjust the X-axis label angle to one of
2+
the following options:
23

34
.. list-table::
45
:header-rows: 1
@@ -18,7 +19,7 @@ You can choose one of the following options:
1819

1920
To set this option:
2021

21-
1. Open the :ref:`Customize <customize-charts>` pane for your chart.
22+
1. Click the :guilabel:`Customize` tab for your chart.
2223

2324
#. In the :guilabel:`Axes` section, select a :guilabel:`Label Angle`
2425
for the :guilabel:`X Axis`.

0 commit comments

Comments
 (0)