Chapter 2

Module: plot.ss

The plot.ss module provides the ability to make basic plots, fit curves to data, and some useful miscellaneous functions.

2.1  Plotting

The plot and plot3d forms generate plots that can be viewed in the DrScheme Interactions window. The functions and data definitions for this module are as follows:

Forms:
  (plot 2d-plot-item 2d-plot-option*) -> VIEW
  (plot3d 3d-plot-item 3d-plot-option*) -> VIEW

2d-plot-option is one of:
  (x-min number)
  (x-max number)
  (y-min number)
  (y-max number)
  (x-label string)
  (y-label string)
  (title string)

3d-plot-option is one of:
  2d-plot-option
  (z-label)
  (z-min number)
  (z-max number)
  (alt number)    ; altitude angle, in degrees
  (az number)     ; azimuthal angle, in degrees

The 2d and 3d plot-options modify the view in which the graph is drawn. The 3d-plot-options alt and az set the viewing altitude (in degrees) and azimuth (also in degrees) respectively. The rest of the options should be self-explanatory.

Data Definitions:

2d-plot-item is one of:
  (points (list-of (vector number number)) point-options*)
  (line [(number -> number) | (number -> (vector number number))] line-options*)
  (error-bars (list-of (vector number number number)) error-bar-options*)
  (vector-field ((vector number number) -> (vector number number)) field-options*)
  (contour (number number -> number) contour-options*)
  (shade (number number -> number) shade-options*)
  (mix 2d-plot-item 2d-plot-item+)
  (custom (2d-view\% -> void))

3d-plot-item is one of:
  (surface (number number -> number) surface-options*)
  (mix 3d-plot-item 3d-plot-item+)
  (custom (3d-view\% -> void))

note: all of the options appear as
  option-name : enumeration of values with default enclosed in []
or
  option-name : type [default]

color is one of:
  'white 'black 'yellow 'green 'aqua 'pink
  'wheat 'grey 'brown 'blue 'violet 'cyan
  'turquoise 'magenta 'salmon 'red

point-options are:
  sym       : ['square], 'circle, 'odot, 'bullet
  color     : color ['black]

line-options are:
  samples   : number [150]
  width     : number [1]
  color     : color ['red]
  mode      : ['standard], 'parametric
  mapping   : ['cartesian], 'polar
  t-min     : number [-5]
  t-max     : number [5]

error-bar-options are:
  color     : color ['red]

field-options are:
  color     : color ['red]
  width     : number [1]
  style     : ['scaled],'normalized,'read

contour-options are:
  samples   : number [50]
  color     : color ['black]
  width     : number [1]
  levels    : number U (list-of number) [10]

shade-options are:
  samples   : number [50]
  levels    : number [10]

surface-options are:
  samples   : number [50]
  color     : color ['black]
  width     : number [1]

The 2d and 3d plot-items can be created in several ways. The first is by using the built-in constructors with your own data.

points will draw points on a graph given a list of vectors specifying their location. Sym specifies the appearance of the points.

line will draw a line specified in either functional, ie. y=f(x), or parametric mode, x,y = f(t). If the function is parametric, the line-option mode must be set to parametric. t-min and t-max set the parameter when in parametric mode. mapping can be set to 'radial.

error-bars will draw error bars given a list of vectors. The vector specifies the center of the error bar (x,y) as the first two elements, and its magnitude as the third.

vector-field will draw a vector field from a vector valued function. Styles are either real, scaled, or normalized.

Both shade and contour will render 3d functions on a 2d graph using colored shades and contours (respectively) to represent the value of the function at that position. contour will let you choose the levels explicitly if desired, by setting the levels option to a list of contour levels to be plotted.

surface plots a 3d surface in a 3d box, showing only the top of the surface.

2.2  Curve Fitting

PLTPlot uses the standard Non-Linear Least Squares fit algorithm for curve fitting. The code that implements the algorithm is public domain, and is used by the gnuplot package.

Data:

  a fit-result is
    (fit (number*-> number) parameter-guess-list  data)

    parameter-guess-list is a set of name-value pairs enclosed in (..)

    data is
      (list-of (vector number number number))
    | (list-of (vector number number number number))

Functions:

  fit-result-function : fit-result -> procedure
  fit-result-final-params : fit-result -> guess-list

The fit form attempts to fit a fittable-function to the data that is given. The guess-listshould be set of parameters and values. The more accurate your initial guesses are, the more likely the fit is to succeed. If there are no good values for the guesses, leave them as 1.

fit-result-final-params returns an associative list of the parameters specified in fit and their values. Note that the values may not be correct if the fit failed to converge. For a visual test use fit-result-function to get the function with the parameters in place and plot it along with the original data.

2.3  Misc Functions

The plot library comes with a few useful miscellaneous functions:

derivative      : (number -> number) [h .000001] -> (number -> number)
gradient : (number number -> number) [h .000001] -> (vector -> vector)
make-vec : (number number -> number) (number number -> number) -> (vector -> vector)

derivative creates a function that evaluates the numeric derivative of the given single-variable function using the definition. h is the divisor used in the calculation.

gradient creates a vector-valued function that is the gradient of the given function. h represents the numeric divisor, as with the derivative function.

make-vec creates one vector valued function from two parts.