#### 3.25` `plot

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.

To close the dialog, click the close button on the title bar or press esc

To save a snapshot of the visualization, click the save button on the title bar and choose a location to save the 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)

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

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 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 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 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.

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)

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"})

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

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.

lam(default-configs): default-configs end

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: ...}

The default config is {color: blue}

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

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.