Builtins and Libraries
3.1 Global Utilities
3.2 Numbers
3.3 Strings
3.4 Booleans
3.5 Raw  Array
3.6 Tables
3.7 lists
3.8 sets
3.9 arrays
3.10 string-dict
3.11 option
3.12 pick
3.13 either
3.14 srcloc
3.15 pprint
3.16 s-exp
3.17 s-exp-structs
3.18 image-structs
3.19 image
3.20 world
3.21 gdrive-sheets
3.22 data-source
3.23 reactors
3.24 chart
3.25 plot
3.26 statistics
3.27 math
On this page:
3.25.1 The Plot Type
3.25.2 Plot Functions
3.25.3 Visualization Functions
3.25.4 The Options Types and Default Values
Plot  Options
Plot  Window  Options

3.25 plot

include plot
import plot as ...

Note that the plot library has been completely rewritten as the chart library to use Google Charts, which would allow us to support more features and more types of charts easily. The current plot library will still be here for a period of time for those who still use it, but we will not support it further.

The Pyret Plot library. It consists of plot, chart, and data visualization tools. The visualization will appear in a separate dialog window, and/or be returned as an Image.

Every function in this library is available on the plot module object. For example, if you used import plot as P, you would write P.display-function to access display-function below. If you used include, then you can refer to identifiers without needing to prefix with P.

3.25.1 The Plot Type

(If you do not wish to customize the plotting, feel free to skip this section. There will be a link referring back to this section when necessary)

data Plot:
| function-plot(f :: (Number -> Number), options :: PlotOptions)
| line-plot(points :: Table, options :: PlotOptions)
| scatter-plot(points :: Table, options :: PlotOptions)

function-plot :: (f :: (Number -> Number), options :: PlotOptions) -> Plot

A graph of a function of one variable.

f :: (Number -> Number)
A function to be graphed. The function doesn’t need to be total: it can yield an error for some x (such as division by zero or resulting in an imaginary number).
options :: PlotOptions

line-plot :: (points :: Table, options :: PlotOptions) -> Plot

A line plot or line chart, used to display "information as a series of data points called ‘markers’ connected by straight line segments." (see https://en.wikipedia.org/wiki/Line_chart)

points :: Table
A table of two columns: x :: Number and y :: Number Because two consecutive data points will be connected by a line segment as they are, the rows of the table should have been sorted by the x-value.
options :: PlotOptions

scatter-plot :: (points :: Table, options :: PlotOptions) -> Plot

A scatter plot or scatter chart, used "to display values for two variables for a set of data." (see https://en.wikipedia.org/wiki/Scatter_plot)

points :: Table
A table of two columns: x :: Number and y :: Number. The order of rows in this table does not matter.
options :: PlotOptions


my-plot = function-plot(lam(x): num-sqrt(x + 1) end, default-options)

3.25.2 Plot Functions

All plot functions will populate a dialog with controllers (textboxes and buttons) on the right which can be used to change the window boundaries and number of sample points. To zoom in at a specific region, you can click and drag on the plotting region. To zoom out, press shift and click on the plotting region. To reset to the initial window boundaries, simply click on the plotting region.

All changes by the controllers will not take an effect until the redraw button is pressed.

The window boundaries could be any kind of real number (e.g., fraction, roughnum). However, when processing, it will be converted to a decimal number. For example, 1/3 will be converted to 0.3333...33 which is actually 3333...33/10000...00. This incurs the numerical imprecision, but allows us to read the number easily.

For function plot, we make a deliberate decision to show points (the tendency of the function) instead of connecting lines between them. This is to avoid the problem of inaccurate plotting causing from, for example, discontinuity of the function, or a function which oscillates infinitely.

display-multi-plot :: (lst :: List<Plot>, options :: PlotWindowOptions) -> Image

Display all Plots in lst on a window with the configuration from options.


import image-structs as I p1 = function-plot(lam(x): x * x end, _.{color: I.red}) p2 = line-plot(table: x :: Number, y :: Number row: 1, 1 row: 2, 4 row: 3, 9 row: 4, 16 end, _.{color: I.green}) display-multi-plot( [list: p1, p2], _.{ title: 'quadratic function and a scatter plot', x-min: 0, x-max: 20, y-min: 0, y-max: 20 })

The above example will plot a function y = x^2 using red color, and show a line chart connecting points in the table using green color. The left, right, top, bottom window boundary are 0, 20, 0, 20 respectively.

display-function :: (title :: String, f :: (Number -> Number)) -> Image

A shorthand to construct an function-plot with default options and then display it. See function-plot for more information.


NUM_E = ~2.71828 display-function('converge to 1', lam(x): 1 - num-expt(NUM_E, 0 - x) end)

display-line :: (title :: String, tab :: Table) -> Image

A shorthand to construct a line-plot with default options and then display it. See line-plot for more information.


display-line('My line', table: x, y row: 1, 2 row: 2, 10 row: 2.1, 3 row: 2.4, 5 row: 5, 1 end)

display-scatter :: (title :: String, tab :: Table) -> Image

A shorthand to construct a scatter-plot with default options and then display it. See scatter-plot for more information.


display-scatter('My scatter plot', table: x, y row: 1, 2 row: 1, 3.1 row: 4, 1 row: 7, 3 row: 4, 6 row: 2, 5 end)

3.25.3 Visualization Functions

histogram :: (
tab :: Table,
n :: Number,
options :: PlotWindowOptions
-> Image

Display a histogram with n bins using data from tab which is a table with one column: value :: Number. The range of the histogram is automatically inferred from the data.


histogram(table: value :: Number row: 1 row: 1.2 row: 2 row: 3 row: 10 row: 3 row: 6 row: -1 end, 4, _.{title: "A histogram with 4 bins"})

pie-chart :: (tab :: Table, options :: PlotWindowOptions) -> Image

Display a pie chart using data from tab which is a table with two columns: label :: String and value :: Number.


pie-chart(table: label, value row: 'EU', 10.12 row: 'Asia', 93.1 row: 'America', 56.33 row: 'Africa', 101.1 end, _.{title: "A pie chart"})

bar-chart :: (tab :: Table, options :: String) -> Image

Display a bar chart using data from tab which is a table with two columns: label :: String and value :: Number.


bar-chart( table: label, value row: 'A', 11 row: 'B', 1 row: 'C', 3 row: 'D', 4 row: 'E', 9 row: 'F', 3 end, _.{title: 'Frequency of letters'})

grouped-bar-chart :: (
tab :: Table,
legends :: List<String>,
options :: PlotWindowOptions
-> Image

Display a bar chart using data from tab which is a table with two columns: label :: String and values :: List<Number>. legends indicates the legends of the data where the first value of the table column values corresponds to the first legend in legends, and so on.


grouped-bar-chart( table: label, values row: 'CA', [list: 2704659, 4499890, 2159981, 3853788, 10604510, 8819342, 4114496] row: 'TX', [list: 2027307, 3277946, 1420518, 2454721, 7017731, 5656528, 2472223] row: 'NY', [list: 1208495, 2141490, 1058031, 1999120, 5355235, 5120254, 2607672] row: 'FL', [list: 1140516, 1938695, 925060, 1607297, 4782119, 4746856, 3187797] row: 'IL', [list: 894368, 1558919, 725973, 1311479, 3596343, 3239173, 1575308] row: 'PA', [list: 737462, 1345341, 679201, 1203944, 3157759, 3414001, 1910571] end, [list: 'Under 5 Years', '5 to 13 Years', '14 to 17 Years', '18 to 24 Years', '25 to 44 Years', '45 to 64 Years', '65 Years and Over'], _.{title: 'Populations of different states by age group'})

3.25.4 The Options Types and Default Values

The PlotOptions and PlotWindowOptions type is actually a function type which consumes a default config and produces a desired config.

To use a default config, you could construct

lam(default-configs): default-configs end

which consumes a default config and merely returns it. We provide a value default-options which is the polymorphic identity function for convenience, which has both type PlotOptions and PlotWindowOptions

A new Options can be constructed by the using Extend Expressions on the default config.

new-options = lam(default-configs): default-configs.{val1: ..., val2: ...} end

Combining the Extend Expressions with the Curried Application Expressions, the above can be rewritten as:

new-options = _.{val1: ..., val2: ...}

A config associated with PlotOptions consists of the following fields: {color :: Color}

The default config is {color: blue}


import image-structs as I my-plot-options-1 = _.{color: I.red} my-plot-options-2 = default-options

A config associated with PlotWindowOptions consists of the following fields: {x-min :: Number, x-max :: Number, y-min :: Number, y-max :: Number, num-samples :: Number, infer-bounds :: Boolean, interact :: Boolean, title :: String}

The default config is {x-min: -10, x-max: 10, y-min: -10, y-max: 10, num-samples: 1000, infer-bounds: false, interact: true, title: ""}

If infer-bounds is true, x-min, x-max, y-min, y-max will be inferred, and old values will be overwritten.

num-samples is to control the number of sample points for function-plots.

title is displayed at the top of the plot window.

interact, when true (the default) shows a separate window containing the plot. When false, the window does not appear; this is useful for simply getting an Image from the plot.