#! @Chapter Using the high-level API
#! @ChapterLabel high
#!
#! @Section Charts and Plots
#!
#! This section covers the <Ref Func="Plot"/> 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 <Ref Chap="Chapter_funcref"/>.
#!
#! To plot a list of numbers as a single data series, just pass the list to
#! <Ref Func="Plot"/>.
#!
#! @BeginLog
#! Plot( [ 6.2, 0.3, 9.1, 8.8 ] );
#! @EndLog
#! <Alt Only="LaTeX">
#! \begin{center}
#! \includegraphics[width=4in]{plot-1.png}
#! \end{center}
#! </Alt>
#! <Alt Only="HTML"><![CDATA[<img width="500" src="plot-1.png"/>]]></Alt>
#! <Alt Not="LaTeX HTML">Resulting image not shown here.</Alt>
#!
#! Notice that the default <Math>x</Math> values for the data are the
#! sequence <Code>[1..n]</Code>, where <Math>n</Math> is the length of the
#! data. You can specify the <Math>x</Math> values manually, like so:
#!
#! @BeginLog
#! Plot( [ 1 .. 4 ], [ 6.2, 0.3, 9.1, 8.8 ] );
#! @EndLog
#!
#! This is useful if you have a scatter plot of data to make, or if your
#! <Math>x</Math> values are not numbers at all.
#!
#! @BeginLog
#! Plot( [ "Mon", "Tue", "Wed", "Thu" ], [ 6.2, 0.3, 9.1, 8.8 ] );
#! @EndLog
#! <Alt Only="LaTeX">
#! \begin{center}
#! \includegraphics[width=4in]{plot-2.png}
#! \end{center}
#! </Alt>
#! <Alt Only="HTML"><![CDATA[<img width="500" src="plot-2.png"/>]]></Alt>
#! <Alt Not="LaTeX HTML">Resulting image not shown here.</Alt>
#!
#! It is also permissible to send in a list of <Math>(x,y)</Math> pairs
#! rather than placing the <Math>x</Math>s and <Math>y</Math>s in separate
#! lists. This would do the same as the previous:
#!
#! @BeginLog
#! Plot( [ [ "Mon", 6.2 ], [ "Tue", 0.3 ], [ "Wed", 9.1 ], [ "Thu", 8.8 ] ] );
#! @EndLog
#!
#! You can also pass a single-variable numeric function to have it plotted.
#!
#! @BeginLog
#! Plot( x -> x^0.5 );
#! @EndLog
#! <Alt Only="LaTeX">
#! \begin{center}
#! \includegraphics[width=4in]{plot-3.png}
#! \end{center}
#! </Alt>
#! <Alt Only="HTML"><![CDATA[<img width="500" src="plot-3.png"/>]]></Alt>
#! <Alt Not="LaTeX HTML">Resulting image not shown here.</Alt>
#!
#! It assumes a small domain of positive integers, which you can customize
#! as follows. Note that the <Math>x</Math> values are passed just as
#! before, but in place of the <Math>y</Math> values, we pass the function
#! that computes them.
#!
#! @BeginLog
#! Plot( [1..50], NrSmallGroups );
#! @EndLog
#! <Alt Only="LaTeX">
#! \begin{center}
#! \includegraphics[height=3in]{01plotfunction.png}
#! \end{center}
#! </Alt>
#! <Alt Only="HTML"><![CDATA[<img height="350" src="01plotfunction.png"/>]]></Alt>
#! <Alt Not="LaTeX HTML">Resulting image not shown here.</Alt>
#!
#! You can append a final parameter to the <Ref Func="Plot"/> 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 <Ref Sect="Section_plotopts"/> covers options in
#! detail; this is only a preview.
#!
#! @BeginLog
#! 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"
#! )
#! );
#! @EndLog
#! <Alt Only="LaTeX">
#! \begin{center}
#! \includegraphics[height=2.5in]{02plotoptions.png}
#! \end{center}
#! </Alt>
#! <Alt Only="HTML"><![CDATA[<img height="300" src="02plotoptions.png"/>]]></Alt>
#! <Alt Not="LaTeX HTML">Resulting image not shown here.</Alt>
#!
#! 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
#! <Math>n</Math> with the number of groups of order <Math>n</Math> for the
#! first 50 positive integers <Math>n</Math>.
#!
#! To do so, take each call you would make to <Ref Func="Plot"/> to make the
#! separate plots, and place those arguments in a list. Pass both lists to
#! <Ref Func="Plot"/> 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.
#!
#! @BeginLog
#! # 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 ) ) ]
#! );
#! @EndLog
#! <Alt Only="LaTeX">
#! \begin{center}
#! \includegraphics[height=3in]{03dataseries.png}
#! \end{center}
#! </Alt>
#! <Alt Only="HTML"><![CDATA[<img height="350" src="03dataseries.png"/>]]></Alt>
#! <Alt Not="LaTeX HTML">Resulting image not shown here.</Alt>
#!
#! 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.
#!
#! @BeginLog
#! 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 )
#! );
#! @EndLog
#! <Alt Only="LaTeX">
#! \begin{center}
#! \includegraphics[height=3in]{04charttypes.png}
#! \end{center}
#! </Alt>
#! <Alt Only="HTML"><![CDATA[<img height="350" src="04charttypes.png"/>]]></Alt>
#! <Alt Not="LaTeX HTML">Resulting image not shown here.</Alt>
#!
#! @Section Options for charts and plots
#! @SectionLabel plotopts
#!
#! The options record passed as the final parameter to <Ref Func="Plot"/>
#! (or as the final element in each list passed to <Ref Func="Plot"/>, if
#! you are plotting multiple series on the same plot) can have the following
#! entries.
#! <List>
#! <Item><Code>tool</Code> - the visualization tool to use to make
#! the plot, as a string. The default is "plotly". The full list
#! of tools is available in Section <Ref Sect="Section_term"/>.</Item>
#! <Item><Code>type</Code> - the type of chart, as a string, the
#! default for which is "line". Which types are available depends
#! on which tool you are using, though it is safe to assume that
#! most common chart types (line, bar, pie) are supported by all
#! tools. Section <Ref Sect="Section_tooldocs"/> contains links to
#! the documentation for each tool, so that you might see its
#! full list of capabilities.</Item>
#! <Item><Code>height</Code> - the height in pixels of the
#! visualization to produce. A sensible default is provided,
#! which varies by tool.</Item>
#! <Item><Code>width</Code> - the width in pixels of the
#! visualization to produce. If omitted, the tool usually fills
#! the width available. In a Jupyter Notebook output cell, this is
#! the width of the cell. A visualization shown outside of a Jupyter
#! notebook will take up the entire width of the web page in which
#! it is displayed.</Item>
#! <Item><Code>title</Code> - the title to place at the top of the
#! chart, as a string. Can be omitted.</Item>
#! <Item><Code>xaxis</Code> - the text to write below the
#! <Math>x</Math> axis, as a string. Can be omitted.</Item>
#! <Item><Code>yaxis</Code> - the text to write to the left of the
#! <Math>y</Math> axis, as a string. Can be omitted.</Item>
#! <Item><Code>name</Code> - this option should be specified in the
#! options object for each separate data series, as opposed to just once
#! for the entire plot. It assigns a string name to that data series,
#! typically included in the chart's legend.</Item>
#! </List>
#!
#! @Section Graphs
#!
#! This section covers the <Ref Func="PlotGraph"/> 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 <Ref Chap="Chapter_funcref"/>.
#!
#! You can make a graph by calling <Ref Func="PlotGraph"/> on a list of
#! edges, each of which is a pair (a list of length two).
#!
#! @BeginLog
#! PlotGraph( [ [ "start", "option1" ], [ "start", "option2" ],
#! [ "option1", "end" ], [ "option2", "end" ] ] );
#! @EndLog
#! <Alt Only="LaTeX">
#! \begin{center}
#! \includegraphics[height=1.5in]{graph-1.png}
#! \end{center}
#! </Alt>
#! <Alt Only="HTML"><![CDATA[<img height="180" src="graph-1.png"/>]]></Alt>
#! <Alt Not="LaTeX HTML">Resulting image not shown here.</Alt>
#!
#! Vertex names can be strings, as shown above, or any &GAP; data; they will
#! be converted to strings using <Code>PrintString</Code>. 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.
#!
#! @BeginLog
#! PlotGraph( [ 2 .. 10 ],
#! [ [ 2, 4 ], [ 2, 6 ], [ 2, 8 ], [ 2, 10 ],
#! [ 3, 6 ], [ 3, 9 ], [ 4, 8 ], [ 5, 10 ] ] );
#! @EndLog
#! <Alt Only="LaTeX">
#! \begin{center}
#! \includegraphics[height=3in]{graph-2.png}
#! \end{center}
#! </Alt>
#! <Alt Only="HTML"><![CDATA[<img height="350" src="graph-2.png"/>]]></Alt>
#! <Alt Not="LaTeX HTML">Resulting image not shown here.</Alt>
#!
#! 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.
#!
#! @BeginLog
#! G := Group( (1,2,3), (1,2) );
#! S := function ( H, G )
#! return IsSubgroup( G, H ) and H <> G;
#! end;
#! PlotGraph( AllSubgroups( G ), S );
#! @EndLog
#! <Alt Only="LaTeX">
#! \begin{center}
#! \includegraphics[height=2in]{graph-3.png}
#! \end{center}
#! </Alt>
#! <Alt Only="HTML"><![CDATA[<img height="240" src="graph-3.png"/>]]></Alt>
#! <Alt Not="LaTeX HTML">Resulting image not shown here.</Alt>
#!
#! 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 <Ref Func="PlotGraph"/>,
#! just as you could for <Ref Func="Plot"/>.
#!
#! @BeginLog
#! 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 ) );
#! @EndLog
#! <Alt Only="LaTeX">
#! \begin{center}
#! \includegraphics[height=2in]{graph-4.png}
#! \end{center}
#! </Alt>
#! <Alt Only="HTML"><![CDATA[<img height="240" src="graph-4.png"/>]]></Alt>
#! <Alt Not="LaTeX HTML">Resulting image not shown here.</Alt>
#!
#! The next section covers all options in detail.
#!
#! @Section Options for graphs
#! @SectionLabel graphopts
#!
#! The options record passed as the final parameter to
#! <Ref Func="PlotGraph"/> can have the following entries.
#! <List>
#! <Item><Code>tool</Code> - the visualization tool to use to make
#! the plot, as a string. The default is "cytoscape". The full
#! list of tools is available in Section
#! <Ref Sect="Section_term"/>.</Item>
#! <Item><Code>layout</Code> - the name of the layout algorithm to
#! use, as a string. Permitted values vary by tool. Currently
#! cytoscape supports "preset" (meaning you must have specified
#! the nodes' positions manually), "cose" (virtual-spring-based
#! automatic layout), "random", "grid", "circle", "concentric"
#! (multiple concentric circles), and "breadthfirst" (a
#! hierarchy).</Item>
#! <Item><Code>vertexwidth</Code> and <Code>vertexheight</Code> -
#! the dimensions of each vertex.</Item>
#! <Item><Code>vertexcolor</Code> - the color of the vertices in the
#! graph. This should be a string representing an HTML color,
#! such as "#ccc" or "red".</Item>
#! <Item><Code>edgewidth</Code> - the thickness of each edge.</Item>
#! <Item><Code>edgecolor</Code> - the color of each edge and its
#! corresponding arrow. This should be a string representing an
#! HTML color, such as "#ccc" or "red".</Item>
#! <Item><Code>directed</Code> - a boolean defaulting to false,
#! whether to draw arrows to visually indicate that the graph is
#! a directed graph</Item>
#! <Item><Code>arrowscale</Code> - a multiplier to increase or
#! decrease the size of arrows in a directed graph.</Item>
#! <Item><Code>height</Code> - the height in pixels of the
#! visualization to produce. A sensible default is provided,
#! which varies by tool.</Item>
#! <Item><Code>width</Code> - the width in pixels of the
#! visualization to produce. If omitted, the tool usually fills
#! the width available. In a Jupyter Notebook output cell, this is
#! the width of the cell. A visualization shown outside of a Jupyter
#! notebook will take up the entire width of the web page in which
#! it is displayed.</Item>
#! </List>
#!
