Quelle  _Chapter_Introduction.xml   Sprache: XML

<?xml version="1.0" encoding="UTF-8"?>

<!-- This is an automatically generated file. -->
<Chapter Label="Chapter_Introduction">
<Heading>Introduction</Heading>

<P/>
<Section Label="Section_purpose">
<Heading>Purpose</Heading>

<P/>
 Since 2017, it has been possible to use &GAP; in
 <URL Text="Jupyter">http://jupyter.org/</URL> through the
 <Package>JupyterKernel</Package> package.  Output was limited to the
 ordinary text output &GAP; produces; charts and graphs were not possible.
<P/>
 In 2018, Martins and Pfeiffer released <Package>francy</Package>
 (<URL Text="repository">https://github.com/mcmartins/francy</URL>,
 <URL Text="article">https://arxiv.org/abs/1806.08648</URL>), which lets
 users create graphs of a few types (vertices and edges, line chart, bar
 chart, scatter chart) in a Jupyter notebook.  It also allows the user to
 attach actions to the elements of these charts, which result in
 callbacks to &GAP; that can update the visualization.
<P/>
 This visualization package has different aims in three ways.  First, it
 can function either in a Jupyter notebook or directly from the &GAP;
 REPL on the command line.  Second, it aims to make a wider variety of
 visualizations accessible to &GAP; users.  Third, it does not provide
 tools for conveniently making such visualizations interactive.  Where
 the <Package>francy</Package> package excels at interactive
 visualizations, this package instead gives a broader scope of
 visualization tools and does not require Jupyter.
<P/>
 These goals are achieved by importing several existing JavaScript
 visualization toolkits and exposing them to &GAP; code, as described
 later in this manual.
<P/>
</Section>


<Section Label="Section_term">
<Heading>Terminology (What is a Graph?)</Heading>

<P/>
 There is an unfortunate ambiguity about the word "graph" in mathematics.
 It is used to mean both "the graph of a function drawn on coordinate
 axes" and "a collection of vertices with edges connecting them." This is
 particularly troublesome in a package like this one, where we will
 provide tools for drawing both of these things!  Consequently, we remove
 the ambiguity as follows.
<P/>
 We will say "charts and plots" to refer to the first concept (lines,
 curves, bars, dots, etc. on coordinate axes) and "graphs" (or sometimes
 "graph drawing") to refer only to the second concept (vertices and
 edges).  This convention holds throughout this entire document.
<P/>
 <Alt Only="LaTeX">
     \begin{center}
         \begin{tabular}{c c c}
         \includegraphics[height=1.6in]{squared-ints.png} & ~ &
         \includegraphics[height=1.6in]{random-graph-10.png} \\
         A plot or chart & & A graph
         \end{tabular}
     \end{center}
 </Alt>
 <Alt Only="HTML"><![CDATA[<table align="center" border=0><tr><td><img height="200" src="squared-ints.png"/></td><td><img height="200" src="random-graph-10.png"/></td></tr><tr><td>A plot or chart</td><td>A graph</td></tr></table>]]></Alt>
 <Alt Not="LaTeX HTML">Resulting images not shown here.</Alt>
<P/>
 To support both of these types of visualizations, this package imports
 a breadth of JavaScript visualization libraries (and you can extend it
 with more, as in Chapter <Ref Chap="Chapter_extend"/>).  We split them
 into the categories defined above.
<P/>
<Subsection Label="Chapter_Introduction_Section_Terminology_What_is_a_Graph_Subsection_Toolkits_for_drawing_charts_and_plots">
<Heading>Toolkits for drawing charts and plots</Heading>

<P/>
<List>
<Item>
<URL Text="AnyChart">https://www.anychart.com/</URL>
</Item>
<Item>
<URL Text="CanvasJS">https://canvasjs.com/</URL>
</Item>
<Item>
<URL Text="ChartJS">https://www.chartjs.org/</URL>
</Item>
<Item>
<URL Text="Plotly">https://plot.ly/</URL> (the default tool used when
    you call <Ref Func="Plot"/>)
</Item>
</List>
<P/>
</Subsection>


<Subsection Label="Chapter_Introduction_Section_Terminology_What_is_a_Graph_Subsection_Toolkits_for_drawing_graphs">
<Heading>Toolkits for drawing graphs</Heading>

<P/>
<List>
<Item>
<URL Text="Cytoscape">http://www.cytoscape.org/</URL> (the default
    tool used when you call <Ref Func="PlotGraph"/>)
</Item>
</List>
<P/>
</Subsection>


<Subsection Label="Chapter_Introduction_Section_Terminology_What_is_a_Graph_Subsection_General_purpose_tools_with_which_you_can_define_custom_visualizations">
<Heading>General purpose tools with which you can define custom visualizations</Heading>

<P/>
<List>
<Item>
<URL Text="D3">https://d3js.org/</URL>
</Item>
<Item>
Native HTML <Code>canvas</Code> element
</Item>
<Item>
Plain HTML
</Item>
</List>
<P/>
</Subsection>


</Section>


<Section Label="Chapter_Introduction_Section_The_high-level_API_and_the_low-level_API">
<Heading>The high-level API and the low-level API</Heading>

<P/>
 This package exposes the JavaScript tools to the &GAP; user in two ways.
<P/>
 Foundationally, a low-level API gives direct access to the JSON passed to
 those tools and to JavaScript code for manipulating the visualizations
 the tools create.  This is powerful but not convenient to use.
<P/>
 More conveniently, a high-level API gives two functions, one for creating
 plots and charts (<Ref Func="Plot"/>) and one for creating graphs
 (<Ref Func="PlotGraph"/>).  The high-level API should handle the vast
 majority of use cases, but if an option you need is not supported by it,
 there is still the low-level API on which you can fall back.
<P/>
</Section>


<Section Label="Chapter_Introduction_Section_Loading_the_package_in_Jupyter_or_otherwise">
<Heading>Loading the package (in Jupyter or otherwise)</Heading>

<P/>
 To import this package, use the following &GAP; command from the command
 line or from a cell in a Jupyter notebook running a &GAP; kernel.
<Example><![CDATA[
LoadPackage( "jupyterviz" );
]]></Example>


<P/>
 To see how to use the package, we recommend next reading Chapter
 <Ref Chap="Chapter_high"/> on the high-level API, and if you find it
 necessary, also Chapter <Ref Chap="Chapter_low"/> on the low-level API.
 Each chapter contains numerous examples of how to use the package.
<P/>
</Section>


</Chapter>