Graph Object Wishlist

This article has been retained as a historical document. It is not up-to-date and the formatting may be lacking. Use the information herein with caution.

I. Introduction

The central idea is that a math object will have a graphing method associated with it that will produce a graph when referenced in the text section of a problem. The method call will be constant across the different object types, and simple to invoke with default parameters. For a math object variable $m, $m->image will produce a graph of m with the default parameters, which can be overridden in the options.

In order to combine graphs we will use the list object. For example, if we wanted to graph two functions $f1, $f2, and a label $s, $f1,$f2 would be declared as formula objects and $s as a string object.

$f1 = Formula(“x+2”);

$f2 = Formula(“3x^2”);

$s = String(“A simple graph”);

$graph = List($f1,$f2,$s);   ## Quotes here?

BEGIN_TEXT

\{ $graph->image\}

END_TEXT

will produce a graph of $f1,$f2 (over the same domain and range) and the label $s using the defaults.
To create more complicated graphs we can use the built in limits for Formula objects to restrict the domain, along with some new options:
Context()-strings->add(“Piecewise Defined”=>{});
$f1 = Formula(“x+3”);
$f1->set(limits =>'[-3,-1)',color=>blue); # we need a string for limits if we want to indicate open and closed intervals. [a,b) doesn't make sense in perl, while [a,b] is an anonymous vector of two elements.
$f2 = Formula(“5”);
$f2->set(limits=>"[-1,1]", color=>blue);
$title=String(“Piecewise Defined”);
$title->{position=>header};
$graph = List($f1,$f2,$title);
BEGIN_TEXT
\{ $graph->image\}
END_TEXT

Notice that the plot has to know whether the limits are open or closed, so that it knows whether to use an open or closed circle. The default is to plot the endpoints with circles, but they can be turned off.

What remains then is to specify the options and default values for each object type. We will list the object type, a description of the type of graph associated with the object, options that can be specified by the user. Following that we will list the actual identifier for each object, default values for the option, and an example of its use.

We will specify plot options for the following objects, including two new(?) geometric objects (circle and polygon):
Circle
Complex
ImplicitEquation
Formula
Interval
List
Point
RegularPolygon
Real
Set
String
Union
Vector

Some options are common to numerous graph types, so we list them here. An effort was made to assimilate the current graphing options, although some have been altered. We have adopted the plan of first identifying the options, and then separately identifying the defaults for the option and how to modify it.

II. Common Options

1) Size
2) Color
3) Axes

   a) Ticks
   b) Grid
   c) Font
   d) Labels

4) Weight
5) Style

Common Options Identifiers and Defaults:
For our purposes $gr is the object to be graphed.

1) Size. For all graphing objects.
There are three sizes that can be specified:

  a) The size of the graph file in pixels: $gr->{filesize=>[a,b]}, default is 200 by 200.
  b) The display size of the graph on the screen: $gr->{size=>[a,b]}.

  c) The hardcopy scaling of the image: $gr->{texsize=>a} where a is an integer scaling factor  
      given as a percentage (a = 100 is 100%).
     Note that filesize is new, and size is used in a different way than in current graphing  
     commands.

2) Color. For all graphing objects. $gr->{color=> c} where c is one of the built in color names or an RGB triplet, the default is black.

3) Axes. For objects of type circle, complex, equation, formula, infinity, point, regularpolygon, real, union, vector, and list (if the list contains any of the previous objects). Note that specifying these options for a list object overrides any options specified for members of the list.

$gr->{axes=>a} where a is the point for the intersection of the two axes, a can also have the value none. a can be specified as a point object or an ordered pair.

   a) Ticks. Defines the tickmarks on each axis.
                 $gr->{ticks=>[a]} for one dimensional objects: real, infinity, interval, union, and list.                        
                 $gr->{ticks=>[a,b]} for two dimensional objects: circle, complex, equation, formula, 
                                                point, regularpolygon, vector, and list. 
                $gr->{ticks=>[a,b,c]} for three dimensional objects: equation, formula, point, vector, 
                                               and list.
       Here each coordinate specifies either the number of tickmarks on each coordinate axis ans an integer, or is a comma delimited list of tickmarks. It is important that elements of a comma delimited list can be of type real or constant so that the TeX method can be used to display numbers like π.  If there are ticks outside an objects limits, the axes are widened to include the ticks. 
   b) Grid. For one and two dimensional objects.
       $gr->{grid=>[a,b,options]}  or  $gr->{grid=>[a,b,c,options]}, specifies the number of grid lines on each axes. Options are style, color, and weight for the gridlines, which can specified as $gr->{grid=>[a,b,style=> , color=> , weight=> ]}. Style can have the values dotted, dashed, and line, the default is dotted. The color can be specified as one of the built in color names or an RGB triplet, the default for gridlines is gray. Weight can be one of the integers 1,2,3, the default is 1. If there are gridlines outside an objects limits, the axes are widened to include the grid. 
   c) Font. The font for the axes labels and ticks. Specified by $gr->{font=>[size,font name]}.
   d) Labels. Labels for the axes, given as strings: $gr->{labels=>[a,b,c]}.

4) Weight. For objects of type circle, complex, equation, formula, regularpolygon, vector. $gr->{weight=>a} where a has the value 1,2, or 3. Default is 1. This is the thickness of the line in the graph.

5) Style. For objects of type circle, complex, equation, formula, regularpolygon, vector. This option specifies the style of the line used to produce the graph of the image. $gr->{style=>a} where a has the value dotted, dashed, or line. Default is line.

III. Object Specific Behavior and Options

A. Circle->image: There is a philosophical question of whether the center and radius of a circle are part of the plot options for the circle, or whether they should be specified when the circle is created. We are adopting the notion that circles are objects independent of their position and size, and that dimensions should be specified in the plot options. Options:
1) Radius.
2) Center.
3) Size – one of the common options above.
4) Color – one of the common options above.
5) Thickness – one of the common options above.
6) Style – one of the common options above.
7) Axes – one of the common options above.

   a) Ticks
   b) Font

Options Identifiers and Defaults:
By default the plot of a circle will display a circle without axes with radius 1 centered at the origin.
Context(“Geometry”);
$c = Circle();
1) Radius. $c->{radius=>r}. Default is 1.
2) Center. $c->{center=>P} where P is an object of type point or $c->{center=>(a,b)} where a and b are real numbers. Default is (0,0).

B. Complex->image: Will display a complex number in the complex plane. The default options are the same as a 2D point object.

C. Formula->image: Will plot the graph of a formula.
User options:
1) Size – one of the common options above.
2) Color – one of the common options above.
3) Axes – one of the common options above.

   a) Ticks
   b) Grid
   c) Font
   d) Labels

4) Weight – one of the common options above.
5) Style – one of the common options above.
6) Test_points to create the plot: use the already built in flags granularity, num_points, and resolution for the input variable.

D. ImplicitEquation->image: Will create an implicit plot of an equation, as an example:
Context("ImplicitEquation");
$e = Equation(“x^2 + 3*y = sin(y)”);
BEGIN_TEXT
\{ $e->image\}
END_TEXT
User options:
1) Size – one of the common options above.
2) Color – one of the common options above.
3) Axes – one of the common options above.

   a) Ticks
   b) Grid
   c) Font
   d) Labels

4) Weight – one of the common options above.
5) Style – one of the common options above.
6) Domain (use limits as in a formula): $e ->set(limits=>[[-3,3],[-3,3]];
7) Test_points to create the plot: use the already built in flags granularity, num_points, and resolution for the variables x and y.

E. Interval->image: Will display a number line with a graph of the interval. By default the endpoints of the interval are the endpoints of the number line. The user has the option of displaying the interval using parenthesis () and brackets [] for delimeters, or open and closed circles and the option to change the color of the line inside the interval.
Example:
Context()->flags->set(delimiters=>circles);
$I = Interval("(-2,5]");
$I->{color=>red,weight=3,limits=>[-6,6]};
BEGIN_TEXT
\{ $graph->image\}
END_TEXT

User options:
1) Size – one of the common options above.
2) Axes – one of the common options above.

   a) Ticks
   c) Font
   d) Labels

3) Delimiters – a context flag that controls whether the endpoints are shown as parenthesis or circles.
4) Filled – a context flag that controls if the interval is filled in with a line or not. If filled is true:

    a) Color  – one of the common options above, default red
    b) Weight  – one of the common options above, default 3.

Options Identifiers and Defaults:
3) Delimiters: the options are delimiters => circles and delimeters => parens, the default is circles. 4) Filled: the options are filled => true and filled => false, the default is true.

F. List->image: A plot of a list of objects will graph the objects on the same graph - the members of the list are type checked to ensure they produce the same type of graph. Each formula in a list is graphed over the domain specified in its options, making it possible to graph a piecewise function using a list. If options for several objects conflict in a domain (ticks for example), the options for the last element of the list are used.

G. Point->image: A point plot graphs the point in the appropriate axes (1D,2D, 3D). 1D points will default to a Real plot.
Options:
1) Size – one of the common options above.
2) Color – one of the common options above.
3) Axes – one of the common options above.

   a) Ticks
   b) Grid
   c) Font
   d) Labels

4) Delimeter – the mark used to denote the point.

Options Identifiers and Defaults:
4) Delimiter - $p->{delimiter=>a} where a can be star, filled_circle, and hollow_circle.

H. Real->image:The graph of a real number will produce a number line with the number displayed on the line. By default the endpoints of the line will be zero and the number to be displayed will be the endpoints of the interval. The graphing committee suggests that limits be added as an option to objects of type real, so that we can have:
$x = Real(“pi/6”);
$x->set(limits=>[-2,2]);
to be used to control the endpoints of the interval.
User options:
1) Size – one of the common options above.
2) Axes – one of the common options above.

   a) Ticks
   c) Font
   d) Labels

3) Delimiter – the mark used to denote the number.
Options Identifiers and Defaults:
3) Delimiter. $p->{delimiter=>a} where a can be star, filled_circle, and hollow_circle.

I. RegularPolygon->image: produces a plot of an n-sided regular polygon, the number of sides will have to be specified at instantiation.
Options:
Same as circle.
Options Identifiers and Defaults:

J. Set->image: The plot of a set produces a list of the elements of the set inside curly braces. Since this is an object type it probably should have a plot associated with it. The point of this particular plot is a little vague, so no options have been specified. Perhaps if it was a list of numbers the graph of the list could be a number line with the numbers displayed on it?

K. String->image: Will display a string in a graph, generally used as a label for a graph. By default a plot of string will display the string as text. If the string is included in a list of other graphs, then it will be displayed by default as a title for the graph.
User options:
1) Font – same font for axes.
2) Color
3) Position and justification
4) Angle the text makes with the horizontal axes.
Position should include the options header and footer.
Options Identifiers and Defaults:
2) Color: $s->{color=c} where c is one of the built in color names or an RGB triplet, the default is black.
3) Position and justification: $s->{position=>[p,horizontal,vertical]} where p is a point, and horizontal vertical are the horizontal and vertical justifications and can have the values left, right, and center. The default position is header.
example
$s->{position=>[(1,2),center,center]};
4) Angle: $s->{angle=A} where A is an angle in degrees.

L. Union->image: The union of interval objects will produce a number line spanning the convex hull of the union. The options and defaults are the same as interval. If several intervals have different options specified use the options for the last interval in the list.

M. Vector->image: Will display a constant vector as an arrow with tail at the origin by default. The graphing committee suggests that limits be added as an option to objects of type real, so that we can have:
$v = Vector(-1,2);
$v->set(limits=>[[-2,2],[-3,3]]);
to be used to control the endpoints of the axes. If the vector is really a parametric equation, then the independent variable is the first limit specified:
$v=Compute(“<t^2,sin(t)>”);
$v=->set(limits=>[[0,2],[0,4],[0,1]]);
would graph the parametric equation in the xy plane from t = 0 to t = 2 with the horizontal axis labeled from 0 to 4 and the vertical axis labeled from 0 to 1. Defaults for limits will be [-5,5] for all of the parameters.
Options:
1) Size – one of the common options above.
2) Color – one of the common options above.
3) Axes – one of the common options above.

   a) Ticks
   b) Grid
   c) Font
   d) Labels

4) Weight – one of the common options above.
5) Style – one of the common options above.
6) Tail

Options Identifiers and Defaults:
If the vector is <x,y,z>, then the default dimensions of the axes will be [-abs(x),abs(x)], [-abs(y),abs(y)], [-abs(z),abs(z)], which can be overridden using ticks.
6) Tail. $v->{tail=>p} where is a point.

AIM Graph synopsis - this is the original AIM document

This material has been replaced by the material above

# an empty graph
$g = Graph();
$g = Graph({options});

# graph with one function, with and without various options
$g = Graph($f);
$g = Graph({options}, $f);
$g = Graph($f=>{options});
$g = Graph({options}, $f=>{options});

# graph with multiple functions, with and without various options
$g = Graph($f, $f2, $f3, ...);
$g = Graph({graph}, $f, $f2, $f3, ...);
$g = Graph($f=>{options}, $f2=>{options}, $f3=>{options}, ...);
$g = Graph({options}, $f=>{options}, $f2=>{options}, $f3=>{options}, ...);

# convenience method of Formula to generate a graph
$g = $f->graph;
$g = $f->graph + $f2->graph + $f3->graph;

# with options
$g = $f->graph(options);
$g = $f->graph(options) + $f2->graph(options) + $f3->graph(options);

# should support some other types similarly, like Point ($p)
$g = $p->graph;
$g = Graph($p, $p2, $p3);

# graph elements (Formulas, Points, etc.) should have an intermediate form
# to provide an API for easily adding novel types. call it Graph::Element.
# consist primarily of a plot subroutine which actually draws the graph
$ge = GraphElement(sub {...}, {options});

# when the graph needs to plot the element, it calls the plot function.
# passes it the graph object, so it can actually do the plotting, and the
# {options} structure (which is opaque to everyone but the plot function)
$plotfn->($g, {options});

# example for Point:
sub Point::graph {
    my ($self, @options) = @_;
    return Graph($self->graph_element(@options));
}
sub Point::graph_element {
    my ($self, @options) = @_;
    return Graph::Element(sub { ... }, {options});
}

# consider using infrastructure on top of GD, such as GD::Graph

Graphs

• A Formula object $f has associated with it a graph object, which can be instantiated using

$g = $f->graph(options)

with all of the options having default values.

• Multiple functions can be graphed simultaneously using

Graph($f->graph(options), $g->graph(options),...) 

or if the defaults are desired

Graph($f,$g,...). 

• The + operator is also overloaded for combining graphs, as in $f->graph(options)+$g->graph(options).

• As another option Graph() can be given an expression as in Graph("3x^2+8") in which case the defaults are used, which could also be used in conjunction with plus: Graph("3x^2+8")+Graph("x^4+sin(x)").

• Information about what is to be graphed (i.e. a function of one variable versus a parametric curve in 3-space) is contained in the Formula object, so the graph function does much of the work in differentiating what information is appropriate, creating uniformity in how the graph is called.

• The constructor Graph() takes any number of MathObjects or strings which can become MathObjects(originally, the objects understood are Formulas, but eventually it should understand Intervals, Sets, Points, Vectors, Complex Numbers, Reals) and options (specified as key value pairs), including

• • Line color (default red for a single graph, when multiple functions are graphed the functions have different color by default, the colors to be determined by the programmers),

• • Line weight (pixels; default: 1),

• • Line style (solid, dashed, dotted, etc.; default: solid),

• • • There are properties associated to functions (such as color and style) and properties associated to the graph as a whole (such as display and grid).

$f->graph(color=>'black',weight=>3,style=>'dotted'); 

• • viewing area is displayed using display. For a 2d graph display=>[1,2] would specify the domain as [1,2] and use defaults for the range. Similarly for a 2d graph dislay=>[[1,2],[3,4]] would do what it should. In 3d graphs display=>[[1,2],[3,4]] and display=>[[1,2],[3,4],[5,6]] would do what one would expect. Display is a global option and is a property of a graph, not the property of a function. (This option should be called something else, 'display is too common', perhaps window=>[1,2])

• • For a parametric function (of one or two variables) one must use something like parametric_range=>[[1,2],[3,4]] and parametric_vars=>[s,t] to give the variables and ranges for these. Similarly, parametric_range=>[1,2], parametric_vars=>t should work for a function of one parametric variable.

• In the case of a call of the form Graph(“3x^2+8a”) the variables are taken alphabetically. But, the variables can be ordered explicity (which is important for 3d plots so that the correct orientation of the axes is correct). This can be done by vars=>[x,t].

• If no display is given defaults are used ( [[-10,10], [-10,10]]). BUT, if functions have a domain that is an interval then display is set to be that interval (this is done whenever it can make sense).

• [-10,10] is the default value for each display range. If range is not specified it should determined, using the domain, by determining maximum and minimum values for the function.

• By default a grid is not displayed. The grid can be turned on using

grid => [spacing1,spacing2] on a two dimensional axis or grid =>[spacing1,spacing2,spacing3] for a three dimensional axis. Spacing specifies the amount space between grid lines. Grid options can be specified by gridopts=> (need more here)

• An alternative version of grid uses a string of values specifying where each gridline is to be placed, allowing non-uniformly spaced grids to be constructed. If specified gridlines lie outside the domain or range of the graph they are expanded.

ex. grid=>[“1,2,5”,”2,3”].

Since grid is used as a switch to turn the gridlines on default values are not specified.

By default the grid lines have weight 1, are grey and are dotted, the defaults can be overridden using options.

ex. $f->graph(grid =>[2,3], gridcolor=>black,gridweight=>3]);

Graph(“e^x”, display=>[[1,5],[-4,4]] , grid=>[“0,1,3,5”,”2,7”] ,gridcolor=>red]) 

In this case, since the domain and range are specified the graph would plot over the domain [1,5] and range [-4,4]. Graph(“e^x”, grid=>[“0,1,3,5”,”2,7”] ,gridcolor=>red]) would graph over the range [[0,5],[2,7]].

Note to programmers: this would be easy to implement by constructing a separate graph for each gridline, which would automatically expand the domain and range.

* Axes: Styles For 2D graphs you can choose between none, normal and boxed. 3D graphs have the option of none, normal, boxed. The default is normal. ex. axes => “boxed” Tickmarks Tickmarks for each axis can be specified either as the number of total ticks on the axis or as a list of values. Axes Labels The labels for the axes can be specified using the labels option, the default is [x,y] or [x,y,z] depending on the situation. To specify no axes labels use empty brackets. ex. labels=> ['p','r'] labels=> [,] Axes Font The font type and size for the axes labels. Default is to be filled along with a list of possible fonts and sizes. ex. axesfont=>[“Arial”,12] Title The default is no title. ex. title => [“Hello”] * The output dimensions of the graph (in pixels, points, inches, etc.) are given by the size option with default units of pixels. Defaults will be specified. ex. size => [200,300] size => [2,3,inches] * need specs for the tex and output dimensions * labeling of a function * piecewise function objects, where the domain of each piece will be specified as an interval object, will have special graphing properties: 1) Whether the endpoint of the interval is open or closed will determine whether a dot or open circle is plotted. * whether the x and y (and z) axes have the same scaling * viewing angle (for 3d graphs) * graphing engine * other options depending on the graphing engine . . . * Like formula objects geometric objects will have graphs associated with them. For example a square with given dimensions can be plotted in an xy axis with lower left corner at a given point and given line colors, etc. Graphs know from the Context() when they are created whether they are 2-d or 3-d (or, eventually 1-d, for intervals and sets). They smoothly upgrade to higher dimension when that is reasonable, for example, when a 3-d function is added to a 2-d graph. Example 1: $g = Graph($f1,$f2,'x^2 + 2','(3,2)'); Graph takes '(3,2)' to be a point in 2-space. '

Example 2:

DESCRIPTION
KEYWORDS()

ENDDESCRIPTION

DOCUMENT(); # This should be the first executable line in the problem.

loadMacros(
 'PGstandard.pl',
 'MathObjects.pl">MathObjects.pl',
 'Graph.pl">Graph.pl',
 'PGcourse.pl',
);

TEXT(beginproblem());
$showPartialCorrectAnswers = 1;

$f = Compute('x^2');
$g = Graph($f,{ymin=>-10,ymax=>100});
$g2 = Graph('x^2/4',{ymin=>-1,ymax=>7,xmin=>3,xmax=>5});

Context()->texStrings;
BEGIN_TEXT
Here should be the graph of \(y = $f\): $BR
\{ $g->plot \} | \{ $g2->plot \} $PAR
END_TEXT
Context()->normalStrings;

ENDDOCUMENT(); # This should be the last executable line in the problem.

Examples

$graph = $f->graph(xmin=>-2, xmax=>7, color=>'red', weight=>2); 

$g1 = Compute('2x - 1')->graph; 

Methods

The Graph object has two methods:

 * $g->add($f2, color=>'blue'); 

$g->add('3xy - y^2'); The ->add method allows new MathOjbects<a href="http://aimwebwork-int.openwebwork.org/moodle/mod/wiki/view.php?id=22&page=MathOjbects"> ? </a>to be added to an existing graph.

 * $g->plot; 

The ->plot method produces a plot in the format appropriate to the situation. It may produce a PNG file and an <img> tag pointing to it. It may produce a .m file and an <applet> tag which uses it. It may produce TeX code (perhaps an eepic or tikz picture or an \includegraphic). Graph objects stringify by calling the ->plot method.


The . operator serves to 'join' two graphs -- the x, y and z ranges of the resulting graph are the smallest intervals which contain the ranges of the original graphs. The objects which were displayed on the original graphs are displayed on the new graph.

Examples

$g = $g1 . $g2; 

$g3 .= $f->graph; # This is equivalent to $g3->add($f); 

$g4 = $f->graph . $f2->graph . $f3->graph . Compute('x+2')->graph; 

For the future

Eventually, Graph objects should also be able to produce

• implicit plots
• contour plots
• parametric equations
• scatter plots (and various other statistical plots)
• differential equations plots.

Function options (perhaps we should use the word 'formula' here instead, since that is what they are):

* color
* style (dotted, solid, etc)

Graph Options:

* display
* bgcolor
* grid

A geometric class of objects that can be graphed, for example rectangles.