Goto Chapter: Top 1 2 3 4 5 6 7 Ind
 [Top of Book]  [Contents]   [Previous Chapter]   [Next Chapter] 

2 Using the high-level API
 2.1 Charts and Plots
 2.2 Options for charts and plots
 2.3 Graphs
 2.4 Options for graphs

2 Using the high-level API

2.1 Charts and Plots

This section covers the Plot (7.1-1) function in the high-level API, which is used for showing charts and plots. If invoked in a Jupyter Notebook, it will show the resulting visualization in the appropriate output cell of the notebook. If invoked from the GAP command line, it will use the system default web browser to show the resulting visualization, from which the user can save a permanent copy, print it, etc. This section covers that function through a series of examples, but you can see full details in the function reference in Chapter 7.

To plot a list of numbers as a single data series, just pass the list to Plot (7.1-1).

Plot( [ 6.2, 0.3, 9.1, 8.8 ] );

Notice that the default x values for the data are the sequence [1..n], where n is the length of the data. You can specify the x values manually, like so:

Plot( [ 1 .. 4 ], [ 6.2, 0.3, 9.1, 8.8 ] );

This is useful if you have a scatter plot of data to make, or if your x values are not numbers at all.

Plot( [ "Mon", "Tue", "Wed", "Thu" ], [ 6.2, 0.3, 9.1, 8.8 ] );

It is also permissible to send in a list of (x,y) pairs rather than placing the xs and ys in separate lists. This would do the same as the previous:

Plot( [ [ "Mon", 6.2 ], [ "Tue", 0.3 ], [ "Wed", 9.1 ], [ "Thu", 8.8 ] ] );

You can also pass a single-variable numeric function to have it plotted.

Plot( x -> x^0.5 );

It assumes a small domain of positive integers, which you can customize as follows. Note that the x values are passed just as before, but in place of the y values, we pass the function that computes them.

Plot( [1..50], NrSmallGroups );

You can append a final parameter to the Plot (7.1-1) command, a record containing a set of options. Here is an example of using that options record to choose the visualization tool, title, and axis labels. Section 2.2 covers options in detail; this is only a preview.

Plot( [1..50], n -> Length( DivisorsInt( n ) ),
      rec(
          tool := "chartjs",
          title := "Number of divisors of some small integers",
          xaxis := "n",
          yaxis := "number of divisors of n"
      )
);

You can also put multiple data series (or functions) on the same plot. Let's pretend you wanted to compare the number of divisors of n with the number of groups of order n for the first 50 positive integers n.

To do so, take each call you would make to Plot (7.1-1) to make the separate plots, and place those arguments in a list. Pass both lists to Plot (7.1-1) to combine the plots, as shown below. You can put the options record in either list. Options specified earlier take precedence if there's a conflict.

# We're combining Plot( [1..50], NrSmallGroups );
# with Plot( [1..50], n -> Length( DivisorsInt( n ) ) );
# and adding some options:
Plot(
    [ [1..50], NrSmallGroups,
      rec( title := "Comparison", tool := "anychart" ) ],
    [ [1..50], n -> Length( DivisorsInt( n ) ) ]
);

The default plot type is "line", as you've been seeing in the preceding examples. You can also choose "bar", "column", "pie", and others. Let's use a pie chart to show the relative sizes of the conjugacy classes in a group.

G := Group( (1,2,3,4,5,6,7), (1,2) );;
CCs := List( ConjugacyClasses( G ), Set );;
Plot(
    # x values are class labels; we'll use the first element in the class
    List( CCs, C -> PrintString( C[1] ) ),
    # y values are class sizes; these determine the size of pie slices
    List( CCs, Length ),
    # ask for a pie chart with enough height that we can read the legend
    rec( type := "pie", height := 500 )
);

2.2 Options for charts and plots

The options record passed as the final parameter to Plot (7.1-1) (or as the final element in each list passed to Plot (7.1-1), if you are plotting multiple series on the same plot) can have the following entries.

2.3 Graphs

This section covers the PlotGraph (7.1-3) function in the high-level API, which is used for drawing graphs. If invoked in a Jupyter Notebook, it will show the resulting visualization in the appropriate output cell of the notebook. If invoked from the GAP command line, it will use the system default web browser to show the resulting visualization. This section covers that function through a series of examples, but you can see full details in the function reference in Chapter 7.

You can make a graph by calling PlotGraph (7.1-3) on a list of edges, each of which is a pair (a list of length two).

PlotGraph( [ [ "start", "option1" ], [ "start", "option2" ],
             [ "option1", "end" ], [ "option2", "end" ] ] );

Vertex names can be strings, as shown above, or any GAP data; they will be converted to strings using PrintString. As you can see, the set of vertices is assumed to be the set of things mentioned in the edges. But you can specify the vertex set separately.

For example, if you wanted to graph the divisibility relation on a set of integers, some elements may not be included in any edge.

PlotGraph( [ 2 .. 10 ],
           [ [ 2, 4 ], [ 2, 6 ], [ 2, 8 ], [ 2, 10 ],
             [ 3, 6 ], [ 3, 9 ], [ 4, 8 ], [ 5, 10 ] ] );

But for anything other than a small graph, specifying the vertex or edge set manually may be inconvenient. Thus if you have a vertex set, you can create the edge set by passing a binary relation as a GAP function. Here is an example to create a subgroup lattice.

G := Group( (1,2,3), (1,2) );
S := function ( H, G )
    return IsSubgroup( G, H ) and H <> G;
end;
PlotGraph( AllSubgroups( G ), S );

But all three of the graphs just shown would be better if they had directed edges. And we might want to organize them differently in the view, perhaps even with some colors, etc. To this end, you can pass an options parameter as the final parameter to PlotGraph (7.1-3), just as you could for Plot (7.1-1).

G := Group( (1,2,3), (1,2) );
S := function ( H, G )
    return IsSubgroup( G, H ) and H <> G;
end;
PlotGraph( AllSubgroups( G ), S,
    rec( directed := true, layout := "grid", arrowscale := 3 ) );

The next section covers all options in detail.

2.4 Options for graphs

The options record passed as the final parameter to PlotGraph (7.1-3) can have the following entries.

 [Top of Book]  [Contents]   [Previous Chapter]   [Next Chapter] 
Goto Chapter: Top 1 2 3 4 5 6 7 Ind

generated by GAPDoc2HTML