9 Plot Contracts

▼ |  | Plot: Graph Plotting

1 | Introduction
2 | 2D and 3D Plotting Procedures
3 | 2D Renderers
4 | 3D Renderers
5 | Nonrenderers
6 | Axis Transforms and Ticks
7 | Plot Utilities
8 | Plot and Renderer Parameters
9 | Plot Contracts
10 | Porting From Plot <= 5.1.3
11 | Legacy Typed Interface
12 | Compatibility Module

► | 9 | Plot Contracts

9.1 | Plot Element Contracts
9.2 | Appearance Argument Contracts
9.3 | Appearance Argument List Contracts

On this page:

9.1`` Plot Element Contracts
renderer2d?
renderer3d?
nonrenderer?
treeof
9.2`` Appearance Argument Contracts
anchor/ c
color/ c
plot-color/ c
plot-pen-style/ c
plot-brush-style/ c
font-family/ c
point-sym/ c
known-point-symbols
9.3`` Appearance Argument List Contracts
maybe-function/ c
maybe-apply
plot-colors/ c
pen-widths/ c
plot-pen-styles/ c
plot-brush-styles/ c
alphas/ c
labels/ c

6.5
top ← prev up next →

### 9`` Plot Contracts

(require plot/utils) | package: plot-lib

#### 9.1`` Plot Element Contracts

> procedure (renderer2d? value) → boolean?
> value : any/c

Returns #t if value is a 2D renderer; that is, if plot can plot value. See 2D Renderers for functions that construct them.

> procedure (renderer3d? value) → boolean?
> value : any/c

Returns #t if value is a 3D renderer; that is, if plot3d can plot value. See 3D Renderers for functions that construct them.

> procedure (nonrenderer? value) → boolean?
> value : any/c

Returns #t if value is a nonrenderer. See Nonrenderers for functions that construct them.

> procedure (treeof elem-contract) → contract?
> elem-contract : contract?

Identifies values that meet the contract elem-contract, lists of such values, lists of lists, and so on.

#### 9.2`` Appearance Argument Contracts

> value anchor/c : contract?
> = |
> (one-of/c 'top-left 'top 'top-right
> 'left 'center 'right
> 'bottom-left 'bottom 'bottom-right)

The contract for anchor arguments and parameters, such as plot-legend-anchor.

> value color/c : contract?
> = |
> (or/c (list/c real? real? real?)
> string? symbol?
> (is-a?/c color%))

A contract for very flexible color arguments. Functions that accept a color/c almost always convert it to an RGB triplet using ->color.

> value plot-color/c : contract? = (or/c exact-integer? color/c)

The contract for #:color arguments, and parameters such as line-color and surface-color. For the meaning of integer colors, see ->pen-color and ->brush-color.

> value plot-pen-style/c : contract?
> = |
> (or/c exact-integer?
> (one-of/c 'transparent 'solid 'dot 'long-dash
> 'short-dash 'dot-dash))

The contract for #:style arguments when they refer to lines, and paramters such as line-style. For the meaning of integer pen styles, see ->pen-style.

> value plot-brush-style/c : contract?
> = |
> (or/c exact-integer?
> (one-of/c 'transparent 'solid
> 'bdiagonal-hatch 'fdiagonal-hatch 'crossdiag-hatch
> 'horizontal-hatch 'vertical-hatch 'cross-hatch))

The contract for #:style arguments when they refer to fills, and parameters such as interval-style. For the meaning of integer brush styles, see ->brush-style.

> value font-family/c : flat-contract?

Identifies legal font family values. The same as font-family/c from racket/draw.

> value point-sym/c : contract?
> = (or/c char? string? integer? (apply one-of/c known-point-symbols))

The contract for the #:sym arguments in points and points3d, and the parameter point-sym.

> value known-point-symbols : (listof symbol?)
> = |
> (list 'dot 'point 'pixel
> 'plus 'times 'asterisk
> '5asterisk 'odot 'oplus
> 'otimes 'oasterisk 'o5asterisk
> 'circle 'square 'diamond
> 'triangle 'fullcircle 'fullsquare
> 'fulldiamond 'fulltriangle 'triangleup
> 'triangledown 'triangleleft 'triangleright
> 'fulltriangleup 'fulltriangledown 'fulltriangleleft
> 'fulltriangleright 'rightarrow 'leftarrow
> 'uparrow 'downarrow '4star
> '5star '6star '7star
> '8star 'full4star 'full5star
> 'full6star 'full7star 'full8star
> 'circle1 'circle2 'circle3
> 'circle4 'circle5 'circle6
> 'circle7 'circle8 'bullet
> 'fullcircle1 'fullcircle2 'fullcircle3
> 'fullcircle4 'fullcircle5 'fullcircle6
> 'fullcircle7 'fullcircle8)

A list containing the symbols that are valid points symbols.

#### 9.3`` Appearance Argument List Contracts

> procedure (maybe-function/c in-contract out-contract) → contract?
> in-contract : contract?
> out-contract : contract?
> = | (or/c out-contract (in-contract . -> . out-contract))

Returns a contract that accepts either a function from in-contract to out-contract, or a plain out-contract value.

> > (require racket/contract)
> > (define/contract (maybe-function-of-real-consumer x)
> ((maybe-function/c real? real?) . -> . real?)
> (maybe-apply x 10))
> > (maybe-function-of-real-consumer 4)
> 4
> > (maybe-function-of-real-consumer (λ (x) x))
> 10

Many plot functions, such as contours and isosurfaces3d, optionally take lists of appearance values (such as (listof plot-color/c)) as arguments. A very flexible argument contract would accept functions that produce lists of appearance values. For example, contours would accept any f with contract (-> (listof real?) (listof plot-color/c)) for its #:colors argument. When rendering a contour plot, contours would apply f to a list of the contour z values to get the contour colors.

However, most uses do not need this flexibility. Therefore, plot’s functions accept either a list of appearance values or a function from a list of appropriate values to a list of appearance values. The maybe-function/c function constructs contracts for such arguments.

In plot functions, if in-contract is a listof contract, the output list’s length need not be the same as the input list’s length. If it is shorter, the appearance values will cycle; if longer, the tail will not be used.

> procedure (maybe-apply f arg) → any/c
> f : (maybe-function/c any/c any/c)
> arg : any/c

If f is a function, applies f to args; otherwise returns f.

This is used inside many renderer-producing plot functions to convert maybe-function/c values to lists of appearance values.

> procedure (plot-colors/c in-contract) → contract?
> in-contract : contract?
> = | (maybe-function/c in-contract (listof plot-color/c))

Returns a contract for #:colors arguments, as in contours and contour-intervals. See maybe-function/c for a discussion of the returned contract.

The following example sends a list-valued (plot-colors/c ivl?) to contour-intervals, which then cycles through the colors:

> > (plot (contour-intervals (λ (x y) (+ x y)) 0 1 0 1
> #:colors '(1 2)))

This is equivalent to sending (λ _ '(1 2)).

The next example is more sophisticated: it sends a function-valued (plot-colors/c ivl?) to contour-intervals. The function constructs colors from the values of the contour intervals.

> > (define (brown-interval-colors ivls)
> (define z-size (- (ivl-max (last ivls))
> (ivl-min (first ivls))))
> (for/list ([i (in-list ivls)])
> (match-define (ivl z-min z-max) i)
> (define z-mid (/ (* 1/2 (+ z-min z-max)) z-size))
> (list (* 255 z-mid) (* 128 z-mid) (* 64 z-mid))))
> > (plot (contour-intervals (λ (x y) (+ x y)) 0 1 0 1
> #:colors brown-interval-colors))

> procedure (pen-widths/c in-contract) → contract?
> in-contract : contract?
> = | (maybe-function/c in-contract (listof (>=/c 0)))

Like plot-colors/c, but for line widths.

> procedure (plot-pen-styles/c in-contract) → contract?
> in-contract : contract?
> = | (maybe-function/c in-contract (listof plot-pen-style/c))

Like plot-colors/c, but for line styles.

> procedure (plot-brush-styles/c in-contract) → contract?
> in-contract : contract?
> = | (maybe-function/c in-contract (listof plot-brush-style/c))

Like plot-colors/c, but for fill styles.

> procedure (alphas/c in-contract) → contract?
> in-contract : contract?
> = | (maybe-function/c in-contract (listof (real-in 0 1)))

Like plot-colors/c, but for opacities.

> procedure (labels/c in-contract) → contract?
> in-contract : contract?
> = | (maybe-function/c in-contract (listof (or/c string? #f)))

Like plot-colors/c, but for strings. This is used, for example, to label stacked-histograms.
top ← prev up next →