|
| 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. |
0 commit comments