BPCharts

   

Table of Contents

  1. Overview
  2. Getting Started
  3. Colors (chco)
  4. Line Styles (chls)
  5. Axis Definitions (chxt, chxr, chxl, chxs)
  6. Grid Lines (chgx)
  7. Fills (chf)
  8. Line Fills (chm=b/B/VLG) (currently not supported)
  9. Fonts and Font Sizes (chft and chfts)
  10. Margins (chmg)
  11. Chart Legend Text and Style(chdl, chdlp, chdls)
  12. Advanced Examples

Overview

The line chart is one of the most flexible charts in BPCharts. It can be used to draw a variety of different charts just by changing a few query string options.

The chart type code for the line chart is lc.

Getting Started

Description Image

Line values are drawn from left to right. The y-axis range will automatically be scaled based on the values.

For historical reasons, the line chart displays solid vertical grid lines and dotted horizontal grid lines by default. This can be controlled via Grid Lines (chgx). All future examples on this page will have grid lines explicitly turned off using chgx=.

 chd=t:13,8,6,11,8,
  9,5,8,7,12
As with all charts, you can specify data using different data encodings. See data encodings for more information. chd=s:sengelha
Missing values will be drawn as gaps. s:sen_elha
Multiple lines can be drawn by specifying multiple data sets. chd=s:sengelha,
  BOBCASEY
As with all charts, the chart size is controllable using the chs parameter. chs=75x75
As with all charts, you can generate other image types using the chof parameter.
chof=s (SVG)

Colors (chco)

You can control the colors of individual lines using the chco option.

See also Colors.

Syntax

chco=<color_1>|...|<color_n>
<color>
The color, in RRGGBB or RRGGBBAA format, to apply to the line.

Example

Description Image
Draw the line in red (FF0000). chco=FF0000
Make the first line red (FF0000) and the second line green (00FF00). chd=s:sengelha,
  BOBCASEY
chco=FF0000|00FF00

Line Styles (chls)

Syntax

chls=<thickness_1>,<opt_dash_length_1>,<opt_space_length_1>,<opt_tension_1>,<opt_monotonicity_1>
     |...|
     <thickness_n>,<opt_dash_length_n>,<opt_space_length_n>,<opt_tension_n>,<opt_monotonicity_n>
<thickness>
The thickness of the line.
<opt_dash_length>,<opt_space_length>
[Optional] Used to define dashed lines. The first parameter is the length of each line dash. The second parameter is the spacing between dashes. Specify 0 for <opt_space_length> for a solid line. Default values are 1,0.
<opt_tension>
[Optional] Used to define tension. Default values is 0. Valid range -1.0 to 1.0
<opt_monotonicity>
[Optional] Used to define monotonicity. Default values are 0.
0: The spline curve is not constraint to flow in any direction. This results in the smoothest spline curve.
1: The spline curve is constraint to not overshooting or undershooting in the x-axis direction. This means if the data points are monotonic in the x-axis direction, the spline curve will also be monotonic in the x-axis direction.
2: The spline curve is constraint to not overshooting or undershooting in the y-axis direction. This means if the data points are monotonic in the y-axis direction, the spline curve will also be monotonic in the y-axis direction.
3: The spline curve is constraint to not overshooting or undershooting in both the x-axis and the y-axis directions. This means if the data points are monotonic in the x-axis direction, the spline curve will also be monotonic in the x-axis direction. If the data points are monotonic in the y-axis direction, the spline curve will also be monotonic in the y-axis direction.
4: Automatically choose between MonotonicX, MonotonicY or MonotonicXY, depending on whether the data points are monotonic in the x-axis direction, or y-axis direction, or both

Example

Description Image
Draw a three pixel thick line. chls=3
Draw a dashed line. chls=1,4,2
Draw a three pixel thick line. chls=3
Draw with tension 1. chls=,,,1
Draw with tension -1. chls=,,,-1
Draw with monotonicity 1. chls=,,,,1


Axis Definitions (chxt, chxr, chxl, chxs)

You can control chart axes using the chxt, chxr, and chxl options.

The chxt option controls which axes you wish to display.

The chxr option controls a range for one or more axes. It can only be used for the y and r axes. (use chxl to specify labels for the x-axis)

The chxl option allows you to manually specify the labels for an axis.

The chxs option controls style for one or more axes.

Syntax

chxt=<axis_1>,...,<axis_n>

chxr=<axis_1>,<range_start_1>,<range_end_1>,<opt_major_interval_1>,<opt_minor_interval_1>
|...|<axis_n>,<range_start_n>,<range_end_n>,<opt_major_interval_n>,<opt_minor_interval_n>

chxl=<axis_index_1>:|<label_1>|...|<label_n>
|...|<axis_index_n>:|<label_1>|...|<label_n>

chxs=<axis_index_1><opt_format_string>,<opt_label_color>,<opt_font_size>,<opt_alignment>,<opt_axis_or_tick>,<opt_tick_color>
|...|<axis_index_n><opt_format_string>,<opt_label_color>,<opt_font_size>,<opt_alignment>,<opt_axis_or_tick>,<opt_tick_color>
<axis>

Display the axis, using the following axis codes:

  • x - X-Axis on the bottom of the chart
  • y - Y-Axis on the left of the chart
  • r - Y-Axis on the right of the chart
<range_start>
The start of the range for the axis. When Chart Version (chvs=) is greater than zero (default is zero) then <range_start> may be optionally ommitted. The range-start will then be calculated automatically.
<range_end>
The end of the range for the axis. When Chart Version (chvs=) is greater than zero (default is zero) then <range_end> may be optionally ommitted. The range-end will then be calculated automatically.
<opt_major_interval>
[Optional] The major interval for the axis. Determines how frequently grid lines are displayed.
<opt_minor_interval>
[Optional] The minor interval for the axis.
<axis_index>
A zero-based index to specify the axis for which you want to specify labels. This is a zero-based index into the chxt parameter.
<label>
The label you wish to display. May be the empty string ("").
<opt_format_string>
[Optional] This is an optional format string that, if used, follows immediately after the axis index number without an intervening comma. It starts with a literal letter N followed by an optional format string.

The formatting string syntax is as follows:
       N<preceding_text>*<number_type><decimal_places>zs<x or y>*<following_text>

Here is the meaning of each element:
  • <preceding_text> - Literal text to precede each value.
  • *...* - An optional block wrapped in literal asterisks, in which you can specify formatting details for numbers. The following values are supported, and are all optional:
    • <number_type> - The number format, for numeric values. Choose one of the following:
      • f - [Default] Floating point format.
      • p - Percentage format. A % sign is appended automatically.
        Note: When using this format, data values from 0.0 — 1.0 map to 0 — 100% (for example, 0.43 will be shown as 43%).
      • k - Thousand abbreviated number. The value will be divided by 1,000 before display.
        Note: If you want a symbol to indicate thousand abbreviation (such as "1.2k") then add the symbol as <following_text> or <preceding_text>.
      • m - Million abbreviated number. The value will be divided by 1,000,000 before display.
        Note: If you want a symbol to indicate million abbreviation (such as "1.2m") then add the symbol as <following_text> or <preceding_text>.
      • e - Scientific notation format.
      • c<CUR> - Format the number in the currency specified, with the appropriate currency marker. Replace <CUR> with a three-letter currency code. Example: cEUR for Euros. You can find a list of codes on the ISO web site, although not all symbols are supported.
    • <decimal_places> - An integer specifying how many decimal places to show. The value is rounded (not truncated) to this length. Default is 2.
    • z - Display trailing zeros. Default is no.
    • s - Display group separators. Default is no.
    • x or y - This parameter is not currently supported - its content will be ignored.
  • <following_text> - Literal text to follow each value.
<opt_label_color>
[Optional]The color, in RRGGBB or RRGGBBAA format, to apply to the label.
<opt_font_size>
[Optional]The point size of the font used to render the labels.
<opt_alignment>
[Optional] If supplied, this parameter should always be -1.
<opt_axis_or_tick>
[Optional] Whether to show tick marks and/or axis lines for this axis. Use one of the following values:
  • l (lowercase 'L') - Draw axis line only.
  • t - Draw tick marks only. Tick marks are the little lines next to axis labels.
  • lt - Draw both an axis line and tick marks for all labels.
  • _ - (Underscore) Draw neither axis line nor tick marks. If you want to hide an axis line, use this value.
<opt_tick_color>
[Optional]The color, in RRGGBB or RRGGBBAA format, to apply to the axis 'tick marks'.

Example

Description Image
Display a y-axis on the left of the chart with an automatically determined range.
chxt=y
Display a y-axis on the right of the chart with a range from 0 to 100. Draw the axis labels in 12 point red font, with trailing % symbol
chxt=r
chxr=r,0,100,10
chxs=0N*f0*%,FF0000,12
Display an x-axis on the bottom of the chart with labels every other year. Enable the axis-line with tick-marks in blue.
chxt=x
chxl=0:||1999||2000||2001
chxs=0,000000,10,-1,lt,0000FF


Grid Lines (chgx)

You can control the chart grid lines using the chgx option.

chgx stands for axis-aligned grid lines. The horizontal grid lines are drawn aligned with the axis major interval for the y/r-axis, as specified by the chxr option. For vertical grid-lines, grid lines are drawn for every point with a non-empty label on the x-axis, as specified by the chxl option. Use a space or non-empty string to denote the place where you want to denote a grid line to be drawn and an empty string to denote no grid line.

Syntax

chgx=<axis>,<opt_dash_length>,<opt_space_length>,<opt_color>,<opt_thickness>,<opt_z_order>
     |...|
     <axis>,<opt_dash_length>,<opt_space_length>,<opt_color>,<opt_thickness>,<opt_z_order>
<axis>

The axis with whose major interval you want the grid lines synchronized.

  • x - Vertical grid lines aligned with the x-axis major interval
  • y - Horizontal grid lines aligned with the y-axis major interval.
<opt_dash_length>,<opt_space_length>
[Optional] Used to define dashed grid lines. The first parameter is the length of each line dash. The second parameter is the spacing between dashes. Specify 0 for <opt_space_length> for a solid line. Default values are 1,0.
<opt_color>
[Optional] The color, in RRGGBBAA format, of the grid lines. Defaults to black (000000)
<opt_thickness>
[Optional] The thickness of the grid lines. Defaults to 1.
<opt_z_order>
[Optional] When supplied, any negative integer will cause the grid lines to be sent to the back of the Z Order.

NOTE: Both horizontal and vertical grid lines must share the same Z Order. Sending either to the back, will cause both to be sent to the back.

Example

Description Image
Turn off all grid lines. chgx=
Draw a chart with solid horizontal grid lines only. chgx=y
Draw a chart with solid gray (CCCCCC) horizontal axis lines and dotted gray (CCCCCC) vertical axis lines. chgx=x,1,3,CCCCCC|
  y,1,0,CCCCCC
Draw a chart with 3-pixel-thick dashed red (FF0000) vertical grid lines. By default a vertical grid line will be drawn through every data point. chgx=x,4,2,FF0000,3
Draw a chart with 3-pixel-thick dashed red (FF0000) vertical grid lines for every other data point. This uses spaces to denote "draw a grid line" and an empty string to denote "no grid line". chgx=x,4,2,FF0000,3
chxl=0:| || || |

Fills (chf)

The background color of the chart can be controlled using the chart fill option.

Syntax

chf=<fill_type>,s,<color>
<fill_type>

The part of the chart being filled. Specify one of the following values:

  • bg - Background fill
  • c - Chart area fill - the part of the chart that contains the data
s
Indicates a solid fill.
<color>
The fill color, in RRGGBB or RRGGBBAA format.

Example

Description Image
Fill the chart background with pale grey (EFEFEF). chf=bg,s,EFEFEF
chxt=y
Fill only the charting area with pale grey (EFEFEF). chf=c,s,EFEFEF
chxt=y
Fill the chart background with semi-transparent yellow (FBF8DDCC). chf=bg,s,FBF8DDCC
chxt=y
Fill the charting area with semi-transparent yellow (FBF8DDCC). Note: We must also make the chart background fully transparent (00000000), otherwise the semi-transparent area will simply show the default chart background (white). chf=bg,s,00000000
chf=c,s,FBF8DDCC
chxt=y

Fonts and Font Sizes (chft and chfts)

The fonts that BPCharts uses to renders labels can be controlled using the chft (font name) and chfts (font size) options.

For raster (e.g. PNG) charts, only fonts which exist on the BPCharts server may be used. For vector (e.g. SVG) charts, the font does not need to exist on the BPCharts server but the client which renders the SVG must have the font installed.

Syntax

chft=<font_name>
chfts=<font_size>
<font_name>
The name of the font to use to render the chart. Defaults to Verdana.
<font_size>

The size of the font to use to render the chart. For raster charts (e.g. PNG) this is in pixels; for vector charts (e.g. SVG) this is in points.

For raster charts, defaults to 11 pixels tall. For vector charts, defaults to 8 points tall.

Example

Description Image
Draw the axis labels in 18-pixel-tall Times New Roman. chft=Times New Roman
chfts=18

Margins (chmg)

A chart's margins are defined as the area outside of the rendering of the chart data itself. The chart margin may include labels or legends.

By default, BPCharts automatically picks chart margins which fit the labels and legends.

Syntax

chmg=<top>,<right>,<bottom>,<left>
<top>
The top margin for the chart.
<right>
The right margin for the chart.
<bottom>
The bottom margin for the chart.
<left>
The left margin for the chart.

Example

Description Image
Adjust the chart margins to 5 pixels on top, 30 pixels on the right, 20 pixels on the bottom, and 10 pixels on the left. Use background and chart area colors to demonstrate the separation between the two. chmg=5,30,20,10
chxt=r
chf=bg,s,93C5D0
chf=c,s,FBF8DD

Chart Legend Text and Style (chdl, chdlp, chdls)

This parameter is used to declare where the labels is inserted in a chart and legend order.

Syntax

chdl=<data_series_1_label>|...|<data_series_n_label>
chdlp=<opt_position>|<opt_label_order>
chdls=<color>,<size>
<data_series_label>

The text for the legend entries. Each label applies to the corresponding series in the chd array

<opt_position>

Specifies the position of the legend on the chart:

  • t - Top
  • b - Bottom
  • l - Left
  • r - Right
  • tv - Top and legend is showed vertically
  • bv - Bottom and legend is showed vertically
<opt_label_order>

The order in which the labels are shown in the legend. Choose one of the following value:

  • l - Display labels in the order given to chdl
  • r - Display labels in the reverse order as given to chdl. This is useful in stacked bar charts to show the legend
  • a - Automatic ordering: roughly means sorting by length, shortest first, as measured in 10 pixel blocks. When two elements are the same length (divided into 10 pixel blocks), the one listed first will appear first.
  • 0,1 - Custom label order. This is a list of zero-based label indexes from chdl, separated by commas
<color>

Specify color (hex format): rrggbb

<font-size>

Specify font-color (pt)

Example

Description Image
Legend position: top chdlp=t
Legend position: bottom and vertical legend chdlp=bv
Legend position: Reverse order legend chdlp=bv|r
Legend Color chdls=ff0000
Legend font size chdls=ff0000,8

TODO

  • Locale (locale)
  • Axis label gap (chxlg)
  • Markers (horizontal lines and vertical lines) (chm)

Advanced Examples

Description Image
This chart is used in EDM. It demonstrates multiple lines, a gradient fill, horizontal chart markers, and custom axis ranges.
This chart is used in the Target Date Report. It demonstrates chart area fills and inter-line fills.
This chart demonstrates custom grid lines, axis labels, and extended encoding with data scaling.
This chart demonstrates removing the vertical grid lines and adding a vertical line marker.