(lispkit draw chart function)

Library (lispkit draw chart function) supports drawing function plots based on a data-driven API in which function charts are being described declaratively. A drawing procedure is then able to render one or more mathematical functions into a given drawing.

Function Chart Model

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

• A function chart is defined by one or more function graphs.

• Each function graph consists of a Scheme procedure (accepting and returning a single number), an optional label string, a color, a line width in points, as well as a list of floating-point numbers specifying an alternating list of dash/space lengths.

• The domain of the chart is specified by a minimum and maximum x value. The range is specified by a minimum and maximum y value.

• Tick marks are placed along both axes at regular intervals defined by step sizes.

• Optional grid lines (dashed) are drawn at each tick position to aid readability.

• The axes are drawn at x = 0 and y = 0 when the origin falls within the visible area; otherwise they are drawn at the boundary of the plot area.

• A legend shows the function labels and the colors used to draw the corresponding curves.

• A legend configuration specifies how the legend is layed out.

• A function chart configuration specifies how the chart overall is being drawn. This includes all fonts, colors, padding values, stroke widths, grid line styles, the number of samples, etc.

The chart layout is structured as follows (from left to right): left padding, y-axis label area, plot area, right padding. From top to bottom: top padding, plot area, x-axis label area, bottom padding. Function curves are clipped to the plot area so that extreme values do not overflow into the surrounding labels or padding.

Function Graphs

A function graph bundles a Scheme procedure, an optional label, a color, a line width in points, as well as a list of floating-point numbers specifying an alternating list of dash/space lengths. Function graphs are immutable objects created via procedure function-graph.

(function-graph proc) (function-graph proc label) (function-graph proc label color) (function-graph proc label color width) (function-graph proc label color width lengths)

Creates a new function graph. proc is a procedure accepting a single numeric argument and returning a numeric result. label is an optional string used to identify the function in the legend; if #f or omitted, the function will not appear in the legend. color is an optional color used to draw the curve; it defaults to blue if omitted. width is the line width in points (default is #f). lengths is a list of floating-point numbers specifying an alternating list of dash/space lengths (default is #f).

(function-graph sin)
(function-graph sin "sin(x)")
(function-graph sin "sin(x)" blue)
(function-graph (lambda (x) (* x x)) "x²" red)

(vertical-line-graph x) (vertical-line-graph x label) (vertical-line-graph x label color) (vertical-line-graph x label color width) (vertical-line-graph x label color width lengths)

Returns a new function graph object representing a vertical line at coordinate x. label is an optional string used to identify the vertical line; if #f or omitted, the vertical line will not appear in the legend. color is an optional color used to draw the line; it defaults to blue if omitted. width is the line width in points (default is #f). lengths is a list of floating-point numbers specifying an alternating list of dash/space lengths (default is #f).

(inline-label-graph loc label) (inline-label-graph loc label color) (inline-label-graph loc label color font)

Returns a new function graph object representing an inline label at point loc. label is an optional string used to identify the vertical line; if #f or omitted, the vertical line will not appear in the legend. color is an optional color used to draw the inline label; it defaults to blue if omitted. font is the font used to draw the inline label; "Helvetica" in size 8 is used as a default.

(function-graph? obj)

Returns #t if obj is a function graph, otherwise #f is returned.

(function-graph-procedure f)

Returns the procedure of the given function graph f.

(function-graph-label f)

Returns the label string of the given function graph f, or #f if no label was provided.

(function-graph-color f)

Returns the color of the given function graph f.

(function-graph-line-width f)

Returns the line width of the given function graph f.

(function-graph-line-lengths f)

Returns a list of floating-point numbers specifying an alternating list of dash/space lengths for the given function graph f.

Legend Configurations

A legend configuration is a record encapsulating all parameters needed for drawing a legend in a chart. Legend configurations are defined independently by library (lispkit draw chart). But there is a specialized make-function-legend-config procedure which provides defaults specifically for usage with function charts.

(make-function-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 9).

• stroke-width: Width of a stroke for drawing the bounding box of the legend (0.5).

• horizontal-offset: Horizontal offset from chart bounds. Positive values are offsets from the left bound; negative values are offsets from the right bound (-10).

• vertical-offset: Vertical offset from chart bounds (10).

• sample-length: Length of the colored line sample drawn next to each label (20).

• line-pad: Vertical padding between legend entries (3).

• entry-pad: Padding around legend entries on all sides (6).

(make-function-legend-config
  'font: (font "Helvetica" 8)
  'stroke-width: 0.4
  'horizontal-offset: -15
  'vertical-offset: 15
  'sample-length: 18
  'entry-pad: 5
  'line-pad: 3)

Accessor procedures for legend configuration objects are provided by library (lispkit draw chart).

Function Chart Configurations

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

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

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

• size: Size of the rectangle in which the chart is drawn (500 × 300).

• color: Color of text, axes, and ticks (black).

• bg-color: Background color of the plot area (white).

• box-color: Color of the plot border box or #f to disable the box (grey).

• axis-font: Font for tick labels on both axes (Helvetica 9).

• label-font: Font for axis name labels (Helvetica 10).

• descr-font: Font for axis description text (Helvetica-LightOblique 9).

• stroke-width: Width of the axis strokes and the plot border in points (1.0).

• line-width: Width of the function curve strokes in points (1.5).

• top-pad: Top padding in points (10).

• bottom-pad: Bottom padding in points (5).

• left-pad: Left padding in points (10).

• right-pad: Right padding in points (10).

• axis-label-width: Width reserved for y-axis tick labels in points (40).

• axis-label-height: Height reserved for x-axis tick labels in points (20).

• tick-length: Length of axis tick marks in points (5).

• grid-line-lengths: List of alternating dash/space lengths for grid lines; can be set to #f to disable grid lines ((1 3)).

• samples: Number of sample points used to render each function curve (200).

• axis-overhead: Extra length in points by which axes extend beyond the plot area (15).

(make-function-chart-config
  'size: (size 500 300)
  'samples: 300
  'line-width: 2.0
  'axis-font: (font "Helvetica" 8)
  'descr-font: (font "Helvetica-LightOblique" 9)
  'stroke-width: 0.7
  'top-pad: 15
  'left-pad: 15
  'right-pad: 10
  'axis-label-width: 35
  'axis-label-height: 22
  'grid-line-lengths: '(1 2))

(function-chart-config? obj)

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

(function-chart-size fconf)

Returns the size defined by the given function chart configuration fconf.

(function-chart-size-set! fconf size)

Sets the size for the given function chart configuration fconf to size. size is a size object.

(function-chart-color fconf)

Returns the foreground color (used for axes, ticks, labels, and border) defined by the given function chart configuration fconf.

(function-chart-color-set! fconf color)

Sets the foreground color for the given function chart configuration fconf to color.

(function-chart-bg-color fconf)

Returns the background color of the plot area defined by the given function chart configuration fconf.

(function-chart-bg-color-set! fconf color)

Sets the background color of the plot area for the given function chart configuration fconf to color. Set to #f to disable background filling.

(function-chart-box-color fconf)

Returns the box color defining the border of the plot area of the given function chart configuration fconf. The box color is set to #f if no box is drawn.

(function-chart-box-color-set! fconf color)

Sets the box color defining the border of the plot area of the given function chart configuration fconf to color. Set to #f to disable drawing the box.

(function-chart-axis-font fconf)

Returns the axis tick label font defined by the given function chart configuration fconf.

(function-chart-axis-font-set! fconf font)

Sets the axis tick label font for the given function chart configuration fconf to font.

(function-chart-label-font fconf)

Returns the axis name label font defined by the given function chart configuration fconf.

(function-chart-label-font-set! fconf font)

Sets the axis name label font for the given function chart configuration fconf to font.

(function-chart-descr-font fconf)

Returns the axis description font defined by the given function chart configuration fconf.

(function-chart-descr-font-set! fconf font)

Sets the axis description font for the given function chart configuration fconf to font.

(function-chart-stroke-width fconf)

Returns the axis and border stroke width defined by the given function chart configuration fconf.

(function-chart-stroke-width-set! fconf val)

Sets the axis and border stroke width for the given function chart configuration fconf to val.

(function-chart-line-width fconf)

Returns the function curve stroke width defined by the given function chart configuration fconf.

(function-chart-line-width-set! fconf val)

Sets the function curve stroke width for the given function chart configuration fconf to val.

(function-chart-top-pad fconf)

Returns the top padding defined by the given function chart configuration fconf.

(function-chart-top-pad-set! fconf val)

Sets the top padding for the given function chart configuration fconf to val.

(function-chart-bottom-pad fconf)

Returns the bottom padding defined by the given function chart configuration fconf.

(function-chart-bottom-pad-set! fconf val)

Sets the bottom padding for the given function chart configuration fconf to val.

(function-chart-left-pad fconf)

Returns the left padding defined by the given function chart configuration fconf.

(function-chart-left-pad-set! fconf val)

Sets the left padding for the given function chart configuration fconf to val.

(function-chart-right-pad fconf)

Returns the right padding defined by the given function chart configuration fconf.

(function-chart-right-pad-set! fconf val)

Sets the right padding for the given function chart configuration fconf to val.

(function-chart-axis-label-width fconf)

Returns the width reserved for y-axis tick labels defined by the given function chart configuration fconf.

(function-chart-axis-label-width-set! fconf val)

Sets the width reserved for y-axis tick labels for the given function chart configuration fconf to val.

(function-chart-axis-label-height fconf)

Returns the height reserved for x-axis tick labels defined by the given function chart configuration fconf.

(function-chart-axis-label-height-set! fconf val)

Sets the height reserved for x-axis tick labels for the given function chart configuration fconf to val.

(function-chart-tick-length fconf)

Returns the tick mark length defined by the given function chart configuration fconf.

(function-chart-tick-length-set! fconf val)

Sets the tick mark length for the given function chart configuration fconf to val.

(function-chart-grid-line-lengths fconf)

Returns a list of alternating dash/space lengths for grid lines defined by the given function chart configuration fconf. If #f is returned, no grid lines are drawn.

(function-chart-grid-line-lengths-set! fconf val)

Sets the list of alternating dash/space lengths for grid lines for the given function chart configuration fconf to val. val may be set to #f to disable drawing grid lines.

(function-chart-samples fconf)

Returns the number of sample points used for rendering function curves as defined by the given function chart configuration fconf.

(function-chart-samples-set! fconf val)

Sets the number of sample points for the given function chart configuration fconf to val. Higher values produce smoother curves at the cost of more computation.

(function-chart-axis-overhead fconf)

Returns the axis overhead defined by the given function chart configuration fconf. The axis overhead is the extra length by which axes extend beyond the plot area boundary.

(function-chart-axis-overhead-set! fconf val)

Sets the axis overhead for the given function chart configuration fconf to val.

Drawing Function Charts

(draw-function-chart funcs xmin xmax ymin ymax xstep ystep xdescr ydescr loc config legend) (draw-function-chart funcs xmin xmax ymin ymax xstep ystep xdescr ydescr loc config legend drawing)

Draws a function chart into the drawing drawing. If drawing is not provided, the drawing provided by the current-drawing parameter object of library (lispkit draw) is used.

funcs is either a single function graph (as created by function-graph) or a list of function graphs. Each function is sampled across the domain and rendered as a curve in its associated color, clipped to the plot area. xmin and xmax define the domain (x-axis range) of the chart. ymin and ymax define the visible range (y-axis range). xstep defines the increment between tick marks on the x-axis. ystep defines the increment between tick marks on the y-axis. Tick labels are generated automatically for each tick position. xdescr is a string describing the x-axis, or #f to omit the description. ydescr is a string describing the y-axis, or #f to omit the description. loc is a point specifying the top-left corner at which the chart is placed within the drawing. config is a function chart configuration object as created by make-function-chart-config. legend is either a function legend configuration (as created by make-function-legend-config) or #f. If #f, no legend is drawn. If a legend configuration is provided, a legend box is drawn showing the label and color for each function graph that has a non-#f label.

Here is an example showcasing the usage of draw-function-chart:

(define d (make-drawing))
(draw-function-chart
  (list (function-graph sin "sin(x)" blue)
        (function-graph cos "cos(x)" red))
  -6.3 6.3                      ; x range
  -1.5 1.5                      ; y range
  2.0                           ; x-axis tick step
  0.5                           ; y-axis tick step
  "x"                           ; x-axis description
  "y"                           ; y-axis description
  (point 50 30)                 ; location
  (make-function-chart-config
    'size: (size 500 300)
    'samples: 200)              ; chart config
  (make-function-legend-config) ; legend config
  d)                            ; target drawing
(save-drawing "functions.pdf" d (size 600 380))

A single function can also be plotted without a legend:

(define d (make-drawing))
(draw-function-chart
  (function-graph (lambda (x) (* x x)) "x²" red)
  -5.0 5.0                    ; x range
  -2.0 25.0                   ; y range
  1.0                         ; x-axis tick step
  5.0                         ; y-axis tick step
  "x"                         ; x-axis description
  "f(x)"                      ; y-axis description
  (point 10 15)               ; location
  (make-function-chart-config
    'box-color: #f
    'size: (size 400 250))    ; chart config
  #f                          ; no legend
  d)                          ; target drawing
(save-drawing "parabola.pdf" d (size 420 270))

The draw-function-chart procedure can also be used within the drawing syntax form, in which case the drawing argument can be omitted and the chart is drawn into the current-drawing:

(define my-chart
  (drawing
    (draw-function-chart
      (list (function-graph sin "sin(x)" blue)
            (function-graph cos "cos(x)" green))
      -6.3 6.3 -1.5 1.5
      2.0 0.5 "x" "y"
      (point 50 30)
      (make-function-chart-config
        'color: (color 0.6 0.6 0.6)
        'box-color: #f
        'size: (size 500 300)
        'samples: 300)
      (make-function-legend-config
        'horizontal-offset: -15
        'vertical-offset: 15))))
(save-drawing "trig.pdf" my-chart (size 600 380))