BPCharts

   

Table of Contents

  1. Overview
  2. Getting Started
  3. Colors (chco)
  4. Color Ranges (chcor)
  5. Fills (chf)
  6. Font Name and Font Size (chft, chfts)
  7. Axis Definitions (chxt, chxr, chxl, chxlg)
  8. Axis Label Styles (chxs)
  9. Grid Lines (chgx)
  10. TODO: Chart Margins (chmg)
  11. TODO: Bar Spacing (chbh)
  12. TODO: Chart Markers (chm)

Overview

The horizontally-stacked bar chart may be used to draw both positive and negative values. The chart type code for the horizontally-stacked bar chart is bhs.

Getting Started

Description Image

Bar values are drawn from bottom to top. The x-axis range and bar sizes are scaled automatically to fit the plotted values.

For historical reasons, the bhs chart has the following defaults:

  • Solid vertical grid lines and no horizontal grid. This can be controlled via the chgx parameter and turned off using chgx=.
  • A visible x-axis with x-axis labels. This can be controlled via the chxt parameter and turned off using chxt=
  • A solid black veritcal chart marker through the 0 point. This can be controlled via (TODO) and turned off using chm=
chd=t:20,8,6,11,-8,
  -9,5,8,7,12
This is the same graph as the above but with all the defaults explicitly turned off. All future charts will have these defaults turned off as well.
chgx=
chxt=
chm=
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

Stacked bars can be drawn by specifying multiple data sets.

WARNING: The current implementation of this chart draws bars as overlays, not stacks. In the future we will create a bho chart with this behavior and bhs will be changed to match Google Charts and be stacked.
chd=t:10,50,60,80,40|
  50,60,100,40,20
chco=4d89f9,c6d9fd
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 specify the colors of individual bars, individual series, or multiple series using the chco parameter. If you don't specify a different color for each series, all series will be the same color.

See also Colors.

Syntax

chco=<series_1_color>, ..., <series_n_color>
<color>
The color, in RRGGBB or RRGGBBAA format, to apply to a series.

Example

Description Image
One color per series, with comma-delimited colors.
chd=s:SENGELHA,bobcasey
chco=4D89F9,C6D9FD

Color Ranges (chcor)

This parameter allows you to control the colors of the bars by specifying the colors that apply to specific numeric ranges.

A number that falls outside of any numeric ranges specified by this parameter will be rendered in a gray color.

Syntax

chcor=<opt_lower_1>,<opt_upper_1>,<color_1>
      |...|
      <opt_lower_n>,<opt_upper_n>,<color_n>
<opt_lower>
[Optional] The lower value, inclusive, of the numeric range. If a value is not specified it means negative infinity.
<opt_upper>
[Optional] The upper value, exclusive, of the numeric range. If a value is not specified it means positive infinity.
<color>
The color, in RRGGBB or RRGGBBAA format, to apply to the bar.

Example

Description Image
Render values less than 0 with red (FF0000) and values greater than 0 with green (008000).
chcor=,0,FF0000|0,,008000

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=x
Fill only the charting area with pale grey (EFEFEF).
chf=c,s,EFEFEF
chxt=x
Fill the chart background with semi-transparent yellow (FBF8DDCC).
chf=bg,s,FBF8DDCC
chxt=x
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=x

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.

Changing the font name or size only has effect if you have enabled labels using chxt. See Axis Definitions for more detail.

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 14-pixel-tall Times New Roman.
chft=Times New Roman
chfts=14
chxt=x

Axis Definitions (chxt, chxr, chxl, chxlg)

You can control chart axes using the chxt, chxr, chxl, and chxlg 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.

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

The chxlg option allows you to manually specify the gap between the labels for an axis and the axis itself.

chxr is not supported for the y-axis. If you enable the x-axis, you must specify labels by using chxl.

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>:<label_1>,...,<label_n>
chxlg=<axis_1>:<gap_1>
      |...|
      <axis_n>:<gap_n>
<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.
<label>
The label you wish to display. May be the empty string ("").
<gap>
The gap, in pixels for raster formats and points for vector formats, between the axis labels and the axis.

Example

Description Image
Display a x-axis on the bottom of the chart with an automatically determined range.
chxt=x
Display a x-axis on the bottom of the chart with a range from 0 to 100 and a major interval of 20.
chxt=x
chxr=x,0,100,20
Create a 20-pixel gap between the labels of the x-axis on the bottom of the chart and the chart itself.
chxt=x
chxlg=x,20

Axis Label Styles (chxs)

You can control the style of individual axis labels by using the chxs option.

Syntax

chxs=<axis_index>,<opt_label_color>,<opt_font_size>
     |...|
     <axis_index>,<opt_label_color>,<opt_font_size>
<axis_index>
The axis to which this applies. This is a zero-based index into the chxt parameter.
<opt_label_color>
[Optional] The color, in RRGGBB or RRGGBBAA format, to apply to the axis labels.
<opt_font_size>
[Optional] The font size to apply to the axis labels.
Description Image
Draw the x-axis labels in 14 pixel tall red (FF0000)
chxt=x
chxs=0,FF0000,14

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>
     |...|
     <axis>,<opt_dash_length>,<opt_space_length>,<opt_color>,<opt_thickness>
<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.

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.
chgx=x,4,2,FF0000,3