Chart-Specific Features |
Marker Information
|
Overview
You can combine several chart types with line or candlestick markers to highlight data trends or show variance. When you add line or candlestick markers onto bar, scatter, or other chart types, the resulting chart is called a compound chart. Some compound charts look like a combination of two chart types—for instance, a bar chart with a tracking line:
while others look like completely new chart types—for instance, a box chart:
.
Creating a Compound Chart
All compound charts consist of one or more base chart types (line, scatter, bar, or radar) combined with one or more sets of markers. These markers require data to place them on the chart. Sometimes you can use the same data series as used to draw the bars or points on your chart, but typically you want the markers to have their own independent data sets. If you want your chart to have different data series for the base chart and for markers, you must hide the marker data from the base chart (so that it doesn't try to draw more bars or lines with that data). Here's how to do that:
- Add your marker data series to the
end of your
chd
parameter. For example, if your bar chart had datachd=t:30,10,20
, you could add new data for a line marker like this:chd=t:30,10,20|60,40,50
. - Hide your extra marker data from the base chart. If you
simply add an extra data series to a bar chart for your tracking line, the chart
would show that as a new series of bars. To prevent
this, you must hide this extra series. To hide a series, include a single digit
after the
chd
format descriptor: for example,chd=t1:30,10,20|60,40,50
. This digit tells the Chart API how many data series to use to draw elements for that base chart type as defined by thecht
parameter (bars for bar charts, data points for line charts, and so on). Any additional data series will be ignored by that chart type when drawing the chart. Note that this is a 1-based number, not 0-based. Sot1
means "use only the first data series for bars,"t2
means "use only the first two series for bars," etc.- Notes:
- Scatter charts - Scatter charts hide data in a different way; see the documentation for more details.
- lxy line charts -
Specify an even number of series to display (
t0
,t2
,t4
, etc). This is because each line in anlxy
chart is described by two data series: one for x-values, and one for y-values.
- Notes:
- Use the hidden data series to draw candlestick markers, line markers, or other markers. How to draw markers is covered in the linked sections. Reference the hidden data series as the source for your markers. You can include as many additional hidden data series as you like, and use them for additional chart markers.
Here's the chart we just described:
cht=bvg
chd=t1:30,10,20|60,40,50
chm=D,0033FF,1,0,5,1
Chart Types
Here is a list of marker types, and the chart types that they can be used with:
Marker Type | Base Chart Types That Support It |
---|---|
Line | Line, Scatter, Bar, Radar |
Candlestick | Line, Bar |
All others | Line, Scatter, Bar, Radar |
Here are some examples of the types of compound charts that you can create:
Chart Type | Description | Example |
---|---|---|
Line marker charts | Line markers can be used to show trends in many other chart types. | |
Candlestick charts | Candlestick charts are often used to show financial data. | |
Box charts | Box charts are used to show data grouped into range quartiles. |
|
Embedded charts | You can embed a chart within another chart. | |
Other markers | You can hide marker data in any of the acceptable base chart types and use it with any other kinds of markers that you like. | chd=t1: |
Line Marker Charts
You can add lines to line, scatter, bar, or radar charts to highlight trends.
Base Type + Marker Type | Description | Example |
---|---|---|
Bar + Line | Here is a bar chart with a trace line. The first two data
series are used for the stacked bars, and the remaining series is used
for the line.
|
chm= |
Scatter + Line | You can add a line to a scatter chart to show averages. Note that scatter charts hide marker data in a different way; see Scatter Charts for more details. |
|
Bar + Line | Here is another stacked bar chart with an independent line drawn over it. |
cht=bvs |
Bar + Circles | Same as the previous chart, but with circle markers instead of a line marker. We've specified every 0.5 data value, which adds calculated intermediary points in the dotted line. | cht=bvs |
Candlestick Charts
Candlestick charts require at least four data series to draw the candlesticks, plus additional series for any other chart elements. Candlestick charts can show only a set of candlestick markers, or can be a combination of candlestick markers plus bar or line charts, as shown here:
Base Type + Marker Type | Description | Example |
---|---|---|
Line (hidden) + Candlestick | This example shows a chart showing only candlestick markers.
|
cht=lc |
Line + Candlestick | Here's an example of a line chart with candlestick markers. Five data series are provided; the first is used for the chart
type (line), and the remaining "hidden" data series are used
for the candlestick markers. The We omitted the first and last candlestick markers using The |
|
Line + Candlestick | Another example of a candlestick chart, but with custom fill colors. |
chd=t1: |
Bar + Candlestick | Here is an example of a bar chart with candlestick markers. We show the first and last candlestick markers here, because the bars add enough spacing to prevent them from being cropped by the chart boundaries. |
cht=bvg |
Box Charts
Box charts, also called box plots or box and whisker charts, are a type of chart that shows the grouping of one or more series into quartiles (quartiles are groups that span 25% of the range of values, with the possible exception of outliers). Box charts are similar to candlestick charts, but with added markers for the bottom and top of the candlestick, plus a 50th percentile marker.
A box chart is made up completely of markers, as shown here:
chm= |
chm= |
chm= |
|
One set of candlestick
markers (chm=F ), for the body of the boxes: |
One set of adjustable-length horizontal
line shape markers (chm=H ) for the minimum, 50th, and 100th
percentile lines: |
Optionally some circle shape
markers (chm=o ) to show outliers in the data set. |
Put them all together, and you have a box chart! |
The base chart type for box charts is any of the bar
chart types (bhs
, bvs
, bhg
, bvg
)
or line chart types (lc
, ls
, lxy
).
But if you are hiding the base chart type by
adding a zero in the data format parameter (for example: chd=t0:
or chd=s0:
),
it doesn't matter which chart type you choose.
A box chart must have at least five data series: four for the boxes and the maximum
and minimum markers; one for the 50% marker; plus any additional data series for
any additional markers that you might want, such as outlier markers. Here is the
recommended series order. Note that if the value in series 1 is more than the corresponding
value in series 2, the box will be filled with the chm=F
marker color;
if the value in series 1 is less than the value in series 2, the box will be unfilled.
See Candlestick Markers for more information.
Series order for an unfilled box:
- Minimum value
- 25% marker (75% for a filled box)
- 75% marker (25% for a filled box)
- Maximum value
- 50% marker
- Series six and beyond are for any additional marker data, such as outliers.
You can actually put the additional marker series before or after the candlestick marker data, but it is simpler to put them all last.
You can make different styles of box charts by specifying different markers, different base chart types, or ordering the data differently
Description | Example | ||
---|---|---|---|
This is a standard box chart, but with different colors assigned to the different chart elements to highlight which marker is being used to create each chart element.
|
|
||
The lc chart type will always show axis lines. To create a chart without axis lines, specify a chart type of ls. |
|
||
To create a filled box, make the point in the second series greater than the corresponding point in the third series. The larger value is marked in red in the code shown on the right. | chd=t0: |
Embedded Charts
You can embed any chart type inside a bar, line, radar, or scatter chart
using dynamic icons. See the Embedded
Charts section of the Dynamic Icons (chem
) marker documentation.
Standard Features
The rest of the features on this page are standard chart features.
Description | Example |
---|---|
This is an example of drawing a marker line on a bar chart.
The z-order is set to |
chm=D,0033FF,0,0,5,1 |
This is the same bar chart, but with an additional data
series just for the line. This is an example of a compound chart.
Compound charts are drawn by adding additional data series to the See Compound Charts for more information. |
chm=D,0033FF,1,0,5,1 |
Shape Markers chm
[Bar, Line,
Radar, Scatter]
You can specify graphical markers for
all or individual data points on a chart. If two or more markers occupy the same
point, the markers are drawn in the order in which they appear in the chm
parameter.
You can also create text markers on data points, which is covered in Data
Point Markers.
You can combine shape markers with
any other chm
parameters using a pipe character ( |
)
to separate the chm
parameters.
Syntax
Specify one set of the following parameters for each series that should be marked. To mark multiple series, create additional parameter sets, delimited by a pipe character. You do not need to mark up all series. If you do not assign markers to a data series, it will not get any markers.
Shape markers behave slightly differently in scatter charts. See that documentation for more information.
chm= [@]<marker_type>,<color>,<series_index>,<opt_which_points>,<size>,<opt_z_order>,<opt_offset> |...| [@]<marker_type>,<color>,<series_index>,<opt_which_points>,<size>,<opt_z_order>,<opt_offset>
- @
- [Optional] If you precede the marker type with the optional @ character, then <opt_which_points> should use the x:y format.
- <marker_type>
- The type of marker to use. Specify one of the following
types:
a
- Arrowc
- CrossC
- Rectangle. If a rectangle marker, you must have at least two data series, where series 0 specifies the bottom edge and series 1 specifies the top edge. <size> specifies the width of the rectangle, in pixels.d
- DiamondE
- Error-bar marker () This marker requires two data series to create, one value for the bottom, and the corresponding point in the second series for the top. It also exposes an extended <size> syntax: line_thickness[:top_and_bottom_width] where top_and_bottom_width is optional. See the examples below.
h
- Horizontal line across the chart at a specified height. (The only valid format for <opt_which_points> parameter is n.d.)H
- Horizontal line through the specified data marker. This supports an extended <size> syntax that lets you specify an exact line length: line_thickness[:length] where :length is optional, and defaults to the full chart area width.o
- Circles
- Squarev
- Vertical line from the x-axis to the data pointV
- Vertical line of adjustable length. This supports an extended <size> value syntax that lets you specify an exact line length: line_thickness[:length] where :length is optional, and defaults to the full chart area height. The marker is centered on the data point.x
- An X
- <color>
- The color of the markers for this series, in RRGGBB hexadecimal format.
- <series_index>
- The zero-based index of the data series on which to draw the markers. Ignored
for
h
markers and markers that specify location by x/y position (start with the @ character). You can use hidden data series as a source for markers; see Compound Charts for more information. Grouped vertical bar charts support a special extended syntax to align markers with specific bars. - <opt_which_points>
- [Optional] Which point(s) to draw markers on. Default is
all markers. Use one of the following values:
n.d
- Where to draw the marker. The meaning depends on the marker type:- All types except h - Which data point to draw the marker on, where n.d is the zero-based index in the series. If you specify a non-integer value, then the fraction indicates a calculated intermediate point. For example, 3.5 means halfway between point 3 and point 4.
h
- A number from 0.0 to 1.0, where 0.0 is the bottom of the chart, and 1.0 is the top of the chart.
-1
- Draw a marker on all data points. You can also leave this parameter empty to draw on all data points.-n
- Draw a marker on every n-th data point. Floating point value; if n is less than 1 the chart will calculate additional intermediary points for you. For example, -0.5 will put twice as many markers as data points.start:end:n
- Draw a marker on every n-th data point in a range, from start to end index values, inclusive. All parameters are optional (may be absent), so 3::1 would be from the fourth element to the last, step 1, and omitting this parameter entirely would default to first:last:1. All values can be floating point numbers. start and end can be negative, to count backward from the last value. If both start and end are negative, be sure that they are listed in increasing value (for example, -6:-1:1). If the n step value is less than 1, it will calculate additional data points by interpolating the data values given. Default values are first:last:1x:y
- Draw a marker at a specific x/y point on the chart. This point does not have to be on a line. Add the @ character before the marker type to use this option. Specify the coordinates as floating point values, where0:0
is the bottom left corner of the chart and1:1
is the top right corner of the chart. For example, to add a red, 15-pixel diamond to the center of a chart, use@d,FF0000,0,0.5:0.5,15
.
- <size>
- The size of the marker, in pixels. Most take a single number value for this parameter; the V, H, and S markers support the syntax <size>[:width] where the optional second part specifies the line or marker length.
- <opt_z_order>
- [Optional] The layer on which to draw the marker, compared to other markers and all other chart elements. This is a floating point number from -1.0 to 1.0, inclusive, where -1.0 is the bottom and 1.0 is the top. Chart elements (lines and bars) are just lower than zero. If two markers have the same value, they are drawn in the order given by the URL. Default value is 0.0 (just above the chart elements).
- <opt_offset>
- [Optional] Let you specify horizontal and vertical offsets from the
specified location. Here is the syntax, which uses a : delimiter:
reserved:<horizontal_offset>:<vertical_offset>
. If specified, you can include an empty ,, value in thechm
parameter string for <opt_z_order>. Examples:o,FF9900,0,4,12,,:10 o,FF9900,0,4,12.0,,:-10:20 o,FF9900,0,4,12,1,::20
- reserved - Leave blank.
<horizontal_offset>
- A positive or negative number specifying the horizontal offset, in pixels. Optional; leave blank if not used.<vertical_offset>
- A positive or negative number specifying the vertical offset, in pixels. Optional; leave blank if not used.
Examples
Description | Example |
---|---|
Here's an example of several of the shape and line markers.
|
chm= |
Here's an example using diamonds for one data series, and circles for the other data series. If two or more markers occupy the same point, the markers are drawn in
the order in which they appear in the |
chm= |
Here's a line chart with a marker on every second data point (-2 means every other point). |
chd=t: |
Here's a line chart with twice as many markers as data points (-0.5 means every half point). | chd=t: |
This example shows how to use h and v markers
to create grid lines with custom colors and thickness. The z-order value
(the last value) is set to -1 so that the grid lines are drawn
beneath the data line. |
chm= |
This chart adds vertical fill lines to a line chart:
|
chm= |
This example adds an arrow and text marker to the chart using exact coordinates. The first D marker is the trace line under the bars. The second marker is the arrow, and the third marker is the arrow text. | chm= |
A horizontal line fixed to a specific data point (H )
can be useful for showing relative values, or emphasizing the height of a
data value on a chart. |
chm=H,FF0000,0,18,1 |
This graph demonstrates the markers that can specify line thickness and length in the <size> parameter.
|
chm=
|
Candlestick Markers chm=F
[Bar,
Line]
Candlestick markers indicate variance and direction change in a data series. Often they are used to show stock values during the course of a day. The marker includes segments that show the high and low value, as well as the opening and closing value for a specific time period (typically a day). For more about candlestick markers, see here.
A candlestick marker is drawn as a rectangle bisected by a vertical line. It requires four data series to draw a candlestick marker; here is what each series specifies:
- Series 1 and 4 specify the bottom and top of the vertical line, respectively. These typically represent the low and high values for the day.
- Series 2 and 3 specify the vertical borders of the rectangle. Series 2 is the opening value, and series 3 is the closing value. The color of the rectangle depends on which is higher: when the opening value (series 2) is lower than the closing value (series 3), the price has increased, and the rectangle is filled with solid green by default; when the opening value (series 2) is higher than the closing value (series 3), the price has decreased, and the rectangle is filled with solid red by default. You can only specify a fill color for the rectangle with decreasing value. When you specify that, the rectangle with increasing value is unfilled (empty). Note that series 2 can be either the top or the bottom of the rectangle, depending on whether the price has gone up or down.
You can combine candlestick markers with any other chm
parameters
using a pipe character ( |
) to separate the chm
parameters.
Note: If you do not want the lines for the data
used to draw the markers to appear in the chart, you must include a 0 after the
format type. For example: chd=t0:10,20,30,40
in a text format data
string. See Compound Charts for more information.
Here's an example, showing the lines for each series:
Syntax
chm= F,<opt_declining_color>,<data_series_index>,<opt_which_points>,<width>,<opt_z_order>
- F
- Indicates that this is a candlestick marker.
- <opt_declining_color>
- [Optional] Fill color for the rectangles when the value is decreasing (when series 2 value > corresponding series 3 value). This is an RRGGBB format hexadecimal number. When the values increase, the rectangle will be empty. Default is solid green for increasing, solid red for decreasing (you cannot specify a custom fill color for increasing values).
- <data_series_index>
- The index of the data series to use as the first series for your candlestick markers. This is a zero-based index. So, if you specify 1 here, and you have six series, the second, third, fourth and fifth will be used to draw candlestick markers.
- <opt_which_points>
- [Optional] Specifies which data points are used to draw markers. Default
is all markers. Use one of
the following formats:
n.d
- Draw a marker on a single point in the series, where n.d is the index of the point in the series. If you specify a non-integer value, then the fraction indicates a calculated intermediate point. For example, 3.5 means halfway between point 3 and point 4.-1
- Draw a marker on all data points. You can also leave this parameter empty to draw on all markers.-n
- Draw a marker on every n-th data point.start:end:n
- Draw a marker on every n-th data point in a range, from start to end index values, inclusive. All parameters are optional (may be absent), so 3::1 would be from the fourth element to the last, step 1, and omitting this parameter entirely would default to first:last:1. All values can be floating point numbers. start and end can be negative, to count backward from the last value. If both start and end are negative, be sure that they are listed in increasing value (for example, -6:-1:1). If the n step value is less than 1, it will calculate additional data points by interpolating the data values given. Default values are first:last:1
- <width>
- The width of all rectangles, in pixels.
- <opt_z_order>
- [Optional] The layer on which to draw the marker, compared to other markers and all other chart elements. This is a floating point number from -1.0 to 1.0, inclusive, where -1.0 is the bottom and 1.0 is the top. Chart elements (lines and bars) are just lower than zero. If two markers have the same value, they are drawn in the order given by the URL. Default value is 0.0 (just above the chart elements).
Examples
Description | Example |
---|---|
Here's an example of candlestick markers on a line chart
with four series. The custom fill color The first and last rectangle are trimmed by the chart. To eliminate these values, you could specify 1:4 for the fourth parameter of chm. Note the zero in the data string, to hide the lines for the series: The <which_point> parameter is blank, which draws candlesticks on all data points. |
chd=t0: |
Here's an example of the same chart, using the default colors, and removing the first and last item. This is a compound chart: it is a combination of a line chart (the base
chart type) and candlestick markers. The value of 1 in |
|