(lispkit draw chart bar)

Library (lispkit draw chart bar) supports drawing bar charts based on a data-driven API in which bar charts are being described declaratively. A drawing function is then able to draw a bar chart into a given drawing as defined by library (lispkit draw).

Bar Chart Model

The following diagram shows a generic bar chart model including the various elements that make up bar charts and parameters that can be configured:

The bar chart model on which library (lispkit draw chart bar) is based on consists of the following components:

• A bar chart is defined by a list of bar groups.
• Each bar group consists of a list of bars and an optional label.
• Each bar consists of a list of values and optionally a label and a color.
• Each value of a bar matches a bar segment (via the position in the list).
• A list of bar segments is provided when a bar chart is being drawn. Each bar segment consists of a label, a bar color, and optionally, a text color (for the value shown in the bar).
• A legend shows the provided bar segments and the color used to highlight them in the bar chart.
• A legend configuration specifies how the legend is layed out (see the various parameters in the diagram above)
• A bar chart configuration specifies how the bar chart overall is being drawn. This includes all fonts, offsets, padding values, etc. that are shown in the diagram above.

Legend Configurations

A legend configuration is a record encapsulating all parameters needed for drawing a legend in a bar chart. Legend configurations are mutable objects that are created via procedure make-legend-config. For every parameter, there is an accessor and a setter procedure.

(make-legend-config key val ...)

Creates a new legend configuration object from the provided keyword/value pairs. The following keyword arguments are supported. The default value is provided in parenthesis.

• font: Font used for all text in a legend (Helvetica 10).
• stroke-width: Width of a stroke for drawing the bounding box of the legend (1.0).
• horizontal-offset: Horizontal offset from chart bounds (negative values are interpreted as offsets from the right bound) (70).
• vertical-offset: Vertical offset from chart bounds (negative values are interpreted as offsets from the bottom bound) (10).
• sample-area-width: Width of the sample area (17).
• sample-length: Heigh and width of color sample boxes for the various segments (10).
• line-pad: Padding between segment lines (3).
• entry-pad: Top/bottom and left/right padding around segment descriptions including the sample area (6).

(make-legend-config
  'font: (font "Helvetica" 7)
  'stroke-width: 0.4
  'entry-pad: 5
  'sample-area-width: 16
  'sample-length: 8
  'horizontal-offset: 50)

(legend-config? obj)

Returns #t if obj is a legend configuration object, #f otherwise.

(legend-font lconf)

Returns the font defined by the given legend configuration lconf.

(legend-font-set! lconf font)

Sets the font for the given legend configuration lconf to font.

(legend-stroke-width lconf)

Returns the stroke width defined by the given legend configuration lconf.

(legend-stroke-width-set! lconf val)

Sets the stroke width for the given legend configuration lconf to val.

(legend-horizontal-offset lconf)

Returns the horizontal offset defined by the given legend configuration lconf.

(legend-horizontal-offset-set! lconf val)

Sets the horizontal offset for the given legend configuration lconf to val.

(legend-vertical-offset lconf)

Returns the vertical offset defined by the given legend configuration lconf.

(legend-vertical-offset-set! lconf val)

Sets the horizontal offset for the given legend configuration lconf to val.

(legend-sample-area-width lconf)

Returns the sample area width defined by the given legend configuration lconf.

(legend-sample-area-width-set! lconf val)

Sets the sample area width for the given legend configuration lconf to val.

(legend-sample-length lconf)

Returns the sample length defined by the given legend configuration lconf.

(legend-sample-length-set! lconf val)

Sets the sample length for the given legend configuration lconf to val.

(legend-line-pad lconf)

Returns the line padding defined by the given legend configuration lconf.

(legend-line-pad-set! lconf val)

Sets the line padding for the given legend configuration lconf to val.

(legend-entry-pad lconf)

Returns the entry padding defined by the given legend configuration lconf.

(legend-entry-pad-set! lconf val)

Sets the entry padding for the given legend configuration lconf to val.

Bar Chart Configurations

A bar chart configuration is a record encapsulating all parameters needed for drawing a bar chart (excluding the bar chart legend). Bar chart configurations are mutable objects that are created via procedure make-bar-chart-config. For every parameter of the configuration, there is an accessor and a setter procedure.

(make-bar-chart-config key val ...)

Creates a new bar chart configuration object from the provided keyword/value pairs. The following keyword arguments are supported. The default value is provided in parenthesis.

• size: The rectangle in which the chart is drawn (495 x 200)
• color: Color of text, axis, etc. (black)
• bg-color: Color of legend background (white)
• value-font: Font for displaying values (Helvetica 10)
• bar-font: Font for displaying values on top of bars (Helvetica 11)
• label-font: Font for displaying bar labels (Helvetica 12)
• group-font: Font for displaying bar group labels (Helvetica-Bold 12)
• descr-font: Font for describing the axis (Helvetica-LightOblique 10)
• stroke-width: Width of a stroke in pixels (1.0)
• top-pad: Top padding in pixels (20)
• bottom-pad: Padding below the x axis (5)
• right-pad: Right-side padding (15)
• left-pad: Padding left to the y axis (10)
• bar-gap: Space between two bar groups (20)
• group-gap: Space between two bars within a group (5)
• vlabel-width: Width of labels on y axis (50)
• vindicator-width: Width of y label indicator lines (10)
• vline-lengths: List of alternating dash/space lengths; can be set to #f to disable the line ((1 2))
• value-pad: Padding between bar and displayed value (1)
• blabel-height: Height of bar labels (14)
• glabel-height: Height of group labels (30)
• xaxis-overhead: Overhead on x axis (20)
• yaxis-overhead: Overhead on y axis (20)

(make-bar-chart-config
  'size: (size 495 200)
  'color: (color 0.9 0.9 0.9)
  'value-font: (font "Helvetica" 8.5)
  'bar-font: (font "Helvetica" 8)
  'label-font: (font "Helvetica" 9)
  'top-pad: 5
  'left-pad: 10
  'right-pad: 5
  'bar-gap: 10
  'vlabel-width: 34
  'glabel-height: 5
  'blabel-height: 20)

(bar-chart-config? obj)

Returns #t if obj is a bar chart configuration, otherwise #f is returned.

(bar-chart-size bconf)

Returns the size defined by the given bar chart configuration bconf.

(bar-chart-size-set! bconf size)

Sets the size for the given bar chart configuration bconf to size. size is a size object.

(bar-chart-value-font bconf)

Returns the value font defined by the given bar chart configuration bconf.

(bar-chart-value-font-set! bconf font)

Sets the value font for the given bar chart configuration bconf to font.

(bar-chart-bar-font bconf)

Returns the bar font defined by the given bar chart configuration bconf.

(bar-chart-bar-font-set! bconf font)

Sets the bar font for the given bar chart configuration bconf to font.

(bar-chart-label-font bconf)

Returns the label font defined by the given bar chart configuration bconf.

(bar-chart-label-font-set! bconf font)

Sets the label font for the given bar chart configuration bconf to font.

(bar-chart-group-font bconf)

Returns the group font defined by the given bar chart configuration bconf.

(bar-chart-group-font-set! bconf font)

Sets the group font for the given bar chart configuration bconf to font.

(bar-chart-descr-font bconf)

Returns the description font defined by the given bar chart configuration bconf.

(bar-chart-descr-font-set! bconf font)

Sets the description font for the given bar chart configuration bconf to font.

(bar-chart-stroke-width bconf)

Returns the stroke width defined by the given bar chart configuration bconf.

(bar-chart-stroke-width-set! bconf val)

Sets the stroke width for the given bar chart configuration bconf to val.

(bar-chart-top-pad bconf)

Returns the top padding defined by the given bar chart configuration bconf.

(bar-chart-top-pad-set! bconf val)

Sets the top padding for the given bar chart configuration bconf to val.

(bar-chart-bottom-pad bconf)

Returns the bottom padding defined by the given bar chart configuration bconf.

(bar-chart-bottom-pad-set! bconf val)

Sets the bottom padding for the given bar chart configuration bconf to val.

(bar-chart-right-pad bconf)

Returns the right padding defined by the given bar chart configuration bconf.

(bar-chart-right-pad-set! bconf val)

Sets the right padding for the given bar chart configuration bconf to val.

(bar-chart-left-pad bconf)

Returns the left padding defined by the given bar chart configuration bconf.

(bar-chart-left-pad-set! bconf val)

Sets the left padding for the given bar chart configuration bconf to val.

(bar-chart-bar-gap bconf)

Returns the bar gap defined by the given bar chart configuration bconf.

(bar-chart-bar-gap-set! bconf val)

Sets the bar gap for the given bar chart configuration bconf to val.

(bar-chart-group-gap bconf)

Returns the group gap defined by the given bar chart configuration bconf.

(bar-chart-group-gap-set! bconf val)

Sets the group gap for the given bar chart configuration bconf to val.

(bar-chart-vlabel-width bconf)

Returns the vertical label width defined by the given bar chart configuration bconf.

(bar-chart-vlabel-width-set! bconf val)

Sets the vertical label width for the given bar chart configuration bconf to val.

(bar-chart-vindicator-width bconf)

Returns the vertical value indicator width defined by the given bar chart configuration bconf.

(bar-chart-vindicator-width-set! bconf val)

Sets the vertical value indicator width for the given bar chart configuration bconf to val.

(bar-chart-vline-lengths bconf)

Returns a list of alternating dash/space lengths defined by the given bar chart configuration bconf. If #f is returned, no horizontal value lines are drawn.

(bar-chart-vline-lengths-set! bconf val)

Sets the list of alternating dash/space lengths for the given bar chart configuration bconf to val. val may be set to #f to disable drawing horizontal value lines.

(bar-chart-value-pad bconf)

Returns the value padding defined by the given bar chart configuration bconf.

(bar-chart-value-pad-set! bconf val)

Sets the value padding for the given bar chart configuration bconf to val.

(bar-chart-blabel-height bconf)

Returns the value padding, i.e. the space between bar and displayed value, defined by the given bar chart configuration bconf.

(bar-chart-blabel-height-set! bconf val)

Sets the value padding, i.e. the space between bar and displayed value, for the given bar chart configuration bconf to val.

(bar-chart-glabel-height bconf)

Returns the group label height defined by the given bar chart configuration bconf.

(bar-chart-glabel-height-set! bconf val)

Sets the group label height for the given bar chart configuration bconf to val.

(bar-chart-xaxis-overhead bconf)

Returns the overhead on the x axis of the coordinate system defined by the given bar chart configuration bconf.

(bar-chart-xaxis-overhead-set! bconf val)

Sets the overhead on the x axis of the coordinate system for the given bar chart configuration bconf to val.

(bar-chart-yaxis-overhead bconf)

Returns the overhead on the y axis of the coordinate system defined by the given bar chart configuration bconf.

(bar-chart-yaxis-overhead-set! bconf val)

Sets the overhead on the y axis of the coordinate system for the given bar chart configuration bconf to val.

Constructing Bar Charts

(bar-spec? obj)

Returns #t if obj is a bar diagram specification, #f otherwise. A bar diagram specification is a list of bars and bar groups.

(bar? obj)

Returns #t if obj is a bar object, otherwise #f is returned.

(bar label value ...)
(bar label color value ...)

Creates a new bar object. A bar without bar segments consists of a single value and an optional label string (#f disables the label) and color. A segmented bar has a value for all segments (i.e. all bars of a bar diagram should have the same number of segments). A segment is disabled by setting its value to 0.

(bar-label bar)

Returns the label of the given bar object bar.

(bar-color bar)

Returns the color of the given bar object bar.

(bar-values bar)

Returns the values of the given bar object bar.

(bar-group? obj)

Returns #t if obj is a bar group object, otherwise #f is returned.

(bar-group label bar ...)

Creates a new bar group from the bars bar ... with string label as label.

(bar-group-label group)

Returns the label of the given bar group group.

(bar-group-bars group)

Returns the bars of the given bar group group.

(bar-segment label col)
(bar-segment label col textcol)

Creates a bar segment represented by label string label and segment color col. Text color textcol is optional (and might be #f).

Drawing Bar Charts

(draw-bar-chart bars col ystep ydescr xdescr loc config legend)
(draw-bar-chart bars col ystep ydescr xdescr loc config legend drawing)

Draws the bar diagram bars with col as the default bar color into the drawing drawing. If drawing is not provided, the drawing provided by the current-drawing parameter object of library (lispkit draw) is used.

ystep defines the increment between values on the y axis. ydescr defines the label of the y axis. xdescr defines the label of the x axis. loc is a point at which the bar diagram is drawn with the bar diagram configuration config. If a legend should be drawn, a legend configuration needs to be provided as parameter legend and col needs to refer to a list of bar-segment objects describing a label string, a bar and a text color for all the segments used within a bar. The legend links labels to bar colors.

(define d (make-drawing))
(draw-bar-chart 
  (list (bar "Jan" 0) (bar "Feb" 2) (bar "Mar" 6)
        (bar "Apr" 9) (bar "May" 14) (bar "Jun" 16)
        (bar "Jul" 19) (bar "Aug" 18) (bar "Sep" 15)
        (bar "Oct" 11) (bar "Nov" 5) (bar "Dec" 2))
  gray 5 "Temperature [C°]" "Month"
  (point 10 0)
  (make-bar-chart-config 'size: (size 500 200))
  #f d)
(save-drawing "test.pdf" d (size 520 210))