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

7 Function reference
 7.1 High-Level Public API
 7.2 Low-Level Public API
 7.3 Internal methods
 7.4 Representation wrapper

7 Function reference

7.1 High-Level Public API

7.1-1 Plot
‣ Plot( various )( function )

Returns: one of two things, documented below

If evaluated in a Jupyter Notebook, the result of this function, when rendered by that notebook, will run JavaScript code that generates and shows a plot in the output cell, which could be any of a wide variety of data visualizations, including bar charts, pie charts, scatterplots, etc. (To draw a vertex-and-edge graph, see PlotGraph (7.1-3) instead.)

If evaluated outside of a Jupyter Notebook, the result of this function is the name of a temporary file stored on disk in which HTML code for such a visualization has been written, and on which GAP has already invoked the user's default web browser. The user should see the visualization appear in the browser immediately before the return value is shown.

This function can take data in a wide variety of input formats. Here is the current list of acceptable formats:

# Plot the number of small groups of order n, from n=1 to n=50:
Plot( [1..50], NrSmallGroups );

# Plot how much Andrea has been jogging lately:
Plot( ["Jan","Feb","Mar"], [46,59,61],
      rec( title := "Andrea's Jogging", yaxis := "miles per month" ) );

7.1-2 ConvertDataSeriesForTool
‣ ConvertDataSeriesForTool( global variable )

The JupyterViz Package has a high-level API and a low-level API. The high-level API involves functions like Plot, which take data in a variety of convenient formats, and produce visualizations from them. The low-level API can be used to pass JSON data structures to JavaScript visualization tools in their own native formats for rendering. The high-level API is built on the low-level API, using key functions to do the conversion.

The conversion functions for plots are stored in a global dictionary in this variable. It is a GAP record mapping visualization tool names (such as plotly, etc., a complete list of which appears in Section 1.1) to conversion functions. Only those tools that support plotting data in the form of (x,y) pairs should be included. (For example, tools that specialize in drawing vertex-and-edge graphs are not relevant here.)

Each conversion function must behave as follows. It expects its input object to be a single data series, which will be a GAP record with three fields:

The output of the conversion function should be a GAP record amenable to conversion (using GapToJsonString from the json package) into JSON. The format of the JSON is governed entirely by the tool that will be used to visualize it, each of which has a different data format it expects.

Those who wish to install new visualization tools for plots (as discussed in Chapter 5) will want to install a new function in this object corresponding to the new tool. If you plan to do so, consider the source code for the existing conversion functions, which makes use of two useful convenince methods, JUPVIZFetchWithDefault (7.3-12) and JUPVIZFetchIfPresent (7.3-13). Following those examples will help keep your code consistent with existing code and as concise as possible.

7.1-3 PlotGraph
‣ PlotGraph( various )( function )

Returns: one of two things, documented below

If evaluated in a Jupyter Notebook, the result of this function, when rendered by that notebook, will run JavaScript code that generates and shows a graph in the output cell, not in the sense of coordinate axes, but in the sense of vertices and edges. (To graph a function or data set on coordinate axes, use Plot (7.1-1) instead.)

If evaluated outside of a Jupyter Notebook, the result of this function is the name of a temporary file stored on disk in which HTML code for such a visualization has been written, and on which GAP has already invoked the user's default web browser. The user should see the visualization appear in the browser immediately before the return value is shown.

This function can take data in a wide variety of input formats. Here is the current list of acceptable formats:

# Plot the subgroup lattice for a small group:
G := Group((1,2),(2,3));
PlotGraph( AllSubgroups(G), IsSubgroup );

# Plot a random graph on 5 vertices:
# (The results change from one run to the next, of course.)
PlotGraph( RandomMat(5,5) );

7.1-4 ConvertGraphForTool
‣ ConvertGraphForTool( global variable )

The JupyterViz Package has a high-level API and a low-level API. The high-level API involves functions like PlotGraph, which take data in a variety of convenient formats, and produce visualizations from them. The low-level API can be used to pass JSON data structures to JavaScript visualization tools in their own native formats for rendering. The high-level API is built on the low-level API, using key functions to do the conversion.

The conversion functions for graphs are stored in a global dictionary in this variable. It is a GAP record mapping visualization tool names (such as cytoscape, a complete list of which appears in Section 1.1) to conversion functions. Only those tools that support graphing vertex and edge sets should be included. (For example, tools that specialize in drawing plots of data stored as (x,y) pairs are not relevant here.)

Each conversion function must behave as follows. It expects its input object to be a single graph, which will be a GAP record with three fields:

The output of the conversion function should be a GAP record amenable to conversion (using GapToJsonString from the json package) into JSON. The format of the JSON is governed entirely by the tool that will be used to visualize it, each of which has a different data format it expects.

Those who wish to install new visualization tools for graphs (as discussed in Chapter 5) will want to install a new function in this object corresponding to the new tool. If you plan to do so, consider the source code for the existing conversion functions, which makes use of two useful convenince methods, JUPVIZFetchWithDefault (7.3-12) and JUPVIZFetchIfPresent (7.3-13). Following those examples will help keep your code consistent with existing code and as concise as possible.

7.1-5 PlotDisplayMethod
‣ PlotDisplayMethod( global variable )

The JupyterViz Package can display visualizations in three different ways, and this global variable is used to switch among those ways.

PlotDisplayMethod := PlotDisplayMethod_HTML;

Users of this package almost never need to alter the value of this variable because a sensible default is chosen at package loading time. If the JupyterViz Package is loaded after the JupyterKernel Package, it notices the presence of that package and leverage its tools to set up support for plotting in a Jupyter environment. Furthermore, it will initialize PlotDisplayMethod to PlotDisplayMethod_Jupyter (7.1-6), which is probably what the user wants. Note that if one calls LoadPackage("JupyterViz"); from a cell in a Jupyter notebook, this is the case that applies, because clearly in such a case, the JupyterKernel Package was already loaded.

If the JupyterViz Package is loaded without the JupyterKernel Package already loaded, then it will initialize PlotDisplayMethod to PlotDisplayMethod_HTML (7.1-8), which is what the user probably wants if using GAP from a terminal, for example. You may later assign PlotDisplayMethod to another value, but doing so has little purpose from the REPL. You would need to first load the JupyterKernel Package, and even then, all that would be produced by this package would be data structures that would, if evaluated in a Jupyter notebook, produce visualizations.

7.1-6 PlotDisplayMethod_Jupyter
‣ PlotDisplayMethod_Jupyter( global variable )

This global constant can be assigned to the global variable PlotDisplayMethod (7.1-5) as documented above. Doing so produces the following results.

7.1-7 PlotDisplayMethod_JupyterSimple
‣ PlotDisplayMethod_JupyterSimple( global variable )

This global constant can be assigned to the global variable PlotDisplayMethod (7.1-5) as documented above. Doing so produces the following results.

7.1-8 PlotDisplayMethod_HTML
‣ PlotDisplayMethod_HTML( global variable )

This global constant can be assigned to the global variable PlotDisplayMethod (7.1-5) as documented above. Doing so produces the following results.

7.2 Low-Level Public API

7.2-1 RunJavaScript
‣ RunJavaScript( script[, returnHTML] )( function )

Returns: one of two things, documented below

If run in a Jupyter Notebook, this function returns an object that, when rendered by that notebook, will run the JavaScript code given in script.

If run outside of a Jupyter Notebook, this function creates an HTML page containing the given script, an HTML element on which that script can act, and the RequireJS library for importing other script tools. It then opens the page in the system default web browser (thus running the script) and returns the path to the temporary file in which the script is stored.

In this second case only, the optional second parameter (which defaults to false) can be set to true if the caller does not wish the function to open a web browser, but just wants the HTML content that would have been displayed in such a browser returned as a string instead.

When the given code is run, the varible element will be defined in its environment, and will contain either the output element in the Jupyter notebook corresponding to the code that was just evaluated or, in the case outside of Jupyter, the HTML element mentioned above. The script is free to write to that element in both cases.

7.2-2 LoadJavaScriptFile
‣ LoadJavaScriptFile( filename )( function )

Returns: the string contents of the file whose name is given

Interprets the given filename relative to the lib/js/ path in the JupyterViz package's installation folder, because that is where this package stores its JavaScript libraries. A .js extension will be added to filename iff needed. A .min.js extension will be added iff such a file exists, to prioritize minified versions of files.

If the file has been loaded before in this GAP session, it will not be reloaded, but will be returned from a cache in memory, for efficiency.

If no such file exists, returns fail and caches nothing.

7.2-3 InstallVisualizationTool
‣ InstallVisualizationTool( toolName, script )( function )

Returns: boolean indicating success (true) or failure (false)

This function permits extending, at runtime, the set of JavaScript visualization tools beyond those that are built into the JupyterViz package.

The first argument must be the name of the visualization tool (a string, which you will later use in the tool field when calling CreateVisualization (7.2-5)). The second must be a string of JavaScript code that installs into window.VisualizationTools.TOOL_NAME_HERE the function for creating visualizations using that tool. It can also define other helper functions or make calls to window.requirejs.config. For examples of how to write such JavaScript code, see the chapter on extending this package in its manual.

This function returns false and does nothing if a tool of that name has already been installed. Otherwise, it installs the tool and returns true.

There is also a convenience method that calls this one on your behalf; see InstallVisualizationToolFromTemplate (7.2-4).

7.2-4 InstallVisualizationToolFromTemplate
‣ InstallVisualizationToolFromTemplate( toolName, functionBody[, CDNURL] )( function )

Returns: boolean indicating success (true) or failure (false)

This function is a convenience function that makes it easier to use InstallVisualizationTool (7.2-3); see the documentation for that function, then read on below for how this function makes it easier.

Most visualization tools do two things: First, they install a CDN URL into window.requirejs.config for some external JavaScript library that must be loaded in the client to support the given type of visualization. Second, they install a function as window.VisualizationTools.TOOL_NAME_HERE accepting parameters element, json, and callback, and building the desired visualization inside the given DOM element. Such code often begins with a call to require(['...'],function(library}{/*...*/})), but not always.

This function will write for you the boiler plate code for calling window.requirejs.config and the declaration and installation of a function into window.VisualizationTools.TOOL_NAME_HERE. You provide the function body and optionally the CDN URL. (If you provide no CDN URL, then no external CDN will be installed into requirejs.)

7.2-5 CreateVisualization
‣ CreateVisualization( data[, code] )( function )

Returns: one of two things, documented below

If run in a Jupyter Notebook, this function returns an object that, when rendered by that notebook, will produce the visualization specified by data in the corresponding output cell, and will also run any given code on that visualization.

If run outside of a Jupyter Notebook, this function creates an HTML page containing the visualization specified by data and then opens the page in the system default web browser. It will also run any given code as soon as the page opens. The data must be a record that will be converted to JSON using GAP's json package.

The second argument is optional, a string containing JavaScript code to run once the visualization has been created. When that code is run, the variables element and visualization will be in its environment, the former holding the output element in the notebook containing the visualization, and the latter holding the visualization element itself.

The data should have the following attributes.

CreateVisualization( rec(
    tool := "html",
    data := rec( html := "I am <i>SO</i> excited about this." )
), "console.log( 'Visualization created.' );" );

7.3 Internal methods

Using the convention common to GAP packages, we prefix all methods not intended for public use with a sequence of characters that indicate our particular package. In this case, we use the JUPVIZ prefix. This is a sort of "poor man's namespacing."

None of these methods should need to be called by a client of this package. We provide this documentation here for completeness, not out of necessity.

7.3-1 JUPVIZAbsoluteJavaScriptFilename
‣ JUPVIZAbsoluteJavaScriptFilename( filename )( function )

Returns: a JavaScript filename to an absolute path in the package dir

Given a relative filename, convert it into an absolute filename by prepending the path to the lib/js/ folder within the JupyterViz package's installation folder. This is used by functions that need to find JavaScript files stored there.

A .js extension is appended if none is included in the given filename.

7.3-2 JUPVIZLoadedJavaScriptCache
‣ JUPVIZLoadedJavaScriptCache( global variable )

A cache of the contents of any JavaScript files that have been loaded from this package's folder. The existence of this cache means needing to go to the filesystem for these files only once per GAP session. This cache is used by LoadJavaScriptFile (7.2-2).

7.3-3 JUPVIZFillInJavaScriptTemplate
‣ JUPVIZFillInJavaScriptTemplate( filename, dictionary )( function )

Returns: a string containing the contents of the given template file, filled in using the given dictionary

A template file is one containing identifiers that begin with a dollar sign ($). For example, $one and $two are both identifiers. One "fills in" the template by replacing such identifiers with whatever text the caller associates with them.

This function loads the file specified by filename by passing that argument directly to LoadJavaScriptFile (7.2-2). If no such file exists, returns fail. Otherwise, it proceed as follows.

For each key-value pair in the given dictionary, prefix a $ onto the key, suffix a newline character onto the value, and then replace all occurrences of the new key with the new value. The resulting string is the result.

The newline character is included so that if any of the values in the dictionary contains single-line JavaScript comment characters (//) then they will not inadvertently affect later code in the template.

7.3-4 JUPVIZRunJavaScriptFromTemplate
‣ JUPVIZRunJavaScriptFromTemplate( filename, dictionary[, returnHTML] )( function )

Returns: the composition of RunJavaScript (7.2-1) with JUPVIZFillInJavaScriptTemplate (7.3-3)

This function is quite simple, and is just a convenience function. The optional third argument is passed on to RunJavaScript internally.

7.3-5 JUPVIZRunJavaScriptUsingRunGAP
‣ JUPVIZRunJavaScriptUsingRunGAP( jsCode[, returnHTML] )( function )

Returns: an object that, if rendered in a Jupyter notebook, will run jsCode as JavaScript after runGAP has been defined

There is a JavaScript function called runGAP, defined in the using-runGAP.js file distributed with this package. That function makes it easy to make callbacks from JavaScript in a Jupyter notebook to the GAP kernel underneath that notebook. This GAP function runs the given jsCode in the notebook, but only after ensuring that runGAP is defined globally in that notebook, so that jsCode can call runGAP as needed.

The optional third argument is passed on to RunJavaScript internally.

An example use, from JavaScript, of the runGAP function appears at the end of Section 4.3.

7.3-6 JUPVIZRunJavaScriptUsingLibraries
‣ JUPVIZRunJavaScriptUsingLibraries( libraries, jsCode[, returnHTML] )( function )

Returns: one of two things, documented below

If run in a Jupyter Notebook, this function returns an object that, when rendered by that notebook, will run jsCode as JavaScript after all libraries have been loaded (which typically happens asynchronously).

If run outside of a Jupyter Notebook, this function loads all the code for the given libraries from disk and concatenates them (with checks to be sure no library is loaded twice) followed by jsCode. It then calls RunJavaScript (7.2-1) on the result, to form a web page and display it to the user.

There are a set of JavaScript libraries stored in the lib/js/ subfolder of this package's installation folder. Neither the Jupyter notebook nor the temporary HTML files created from the command line know, by default, about any of those libraries. Thus this function is necessary so that jsCode can assume the existence of the tools it needs to do its job.

If the first parameter is given as a string instead of a list of strings, it is treated as a list of just one string.

The optional third argument is passed on to RunJavaScript internally.

JUPVIZRunJavaScriptUsingLibraries( [ "mylib.js" ],
    "alert( 'My Lib defines foo to be: ' + window.foo );" );
# Equivalently:
JUPVIZRunJavaScriptUsingLibraries( "mylib.js",
    "alert( 'My Lib defines foo to be: ' + window.foo );" );

7.3-7 JUPVIZMakePlotDataSeries
‣ JUPVIZMakePlotDataSeries( series )( function )

Returns: a record with the appropriate fields (x, y, options) that can be passed to one of the functions in ConvertDataSeriesForTool (7.1-2)

This function is called by Plot (7.1-1) to convert any of the wide variety of inputs that Plot (7.1-1) might receive into a single internal format. Then that internal format can be converted to the JSON format needed by any of the visualization tools supported by this package.

See the documentation for ConvertDataSeriesForTool (7.1-2) for more information on how that latter conversion takes place, and the format it expects.

7.3-8 JUPVIZMakePlotGraphRecord
‣ JUPVIZMakePlotGraphRecord( various )( function )

Returns: a record with the appropriate fields (vertices, edges, options) that can be passed to one of the functions in ConvertGraphForTool (7.1-4)

This function is called by PlotGraph (7.1-3) to convert any of the wide variety of inputs that PlotGraph (7.1-3) might receive into a single internal format. Then that internal format can be converted to the JSON format needed by any of the visualization tools supported by this package.

See the documentation for ConvertGraphForTool (7.1-4) for more information on how that latter conversion takes place, and the format it expects.

7.3-9 JUPVIZPlotDataSeriesList
‣ JUPVIZPlotDataSeriesList( series1, series2, series3... )( function )

Returns: a JupyterRenderable object ready to be displayed in the Jupyter Notebook

Because the Plot (7.1-1) function can take a single data series or many data series as input, it detects which it received, then passes the resulting data series (as an array containing one or more series) to this function for collecting into a single plot.

It is not expected that clients of this package will need to call this internal function.

7.3-10 JUPVIZRecordKeychainLookup
‣ JUPVIZRecordKeychainLookup( record, keychain, default )( function )

Returns: the result of looking up the chain of keys in the given record

In nested records, such as myRec:=rec(a:=rec(b:=5)), it is common to write code such as myRec.a.b to access the internal values. However when records are passed as parameters, and may not contain every key (as in the case when some default values should be filled in automatically), code like myRec.a.b could cause an error. Thus we wish to first check before indexing a record that the key we're looking up exists. If not, we wish to return the value given as the default instead.

This function accepts a record (which may have other records inside it as values), an array of strings that describe a chain of keys to follow inward (["a","b"] in the example just given), and a default value to return if any of the keys do not exist.

It is not expected that clients of this package will need to call this internal function. It is used primarily to implement the JUPVIZFetchWithDefault (7.3-12) function, which is useful to those who wish to extend the ConvertDataSeriesForTool (7.1-2) and ConvertGraphForTool (7.1-4) objects.

myRec := rec( height := 50, width := 50, title := rec(
  text := "GAP", fontSize := 20
) );
JUPVIZRecordKeychainLookup( myRec, [ "height" ], 10 );                # = 50
JUPVIZRecordKeychainLookup( myRec, [ "width" ], 10 );                 # = 50
JUPVIZRecordKeychainLookup( myRec, [ "depth" ], 10 );                 # = 10
JUPVIZRecordKeychainLookup( myRec, [ "title", "text" ], "Title" );    # = "GAP"
JUPVIZRecordKeychainLookup( myRec, [ "title", "color" ], "black" );   # = "black"
JUPVIZRecordKeychainLookup( myRec, [ "one", "two", "three" ], fail ); # = fail

7.3-11 JUPVIZRecordsKeychainLookup
‣ JUPVIZRecordsKeychainLookup( records, keychain, default )( function )

Returns: the result of looking up the chain of keys in each of the given records until a lookup succeeds

This function is extremely similar to JUPVIZRecordKeychainLookup (7.3-10) with the following difference: The first parameter is a list of records, and JUPVIZRecordKeychainLookup (7.3-10) is called on each in succession with the same keychain. If any of the lookups succeeds, then its value is returned and no further searching through the list is done. If all of the lookups fail, the default is returned.

It is not expected that clients of this package will need to call this internal function. It is used primarily to implement the JUPVIZFetchWithDefault (7.3-12) function, which is useful to those who wish to extend the ConvertDataSeriesForTool (7.1-2) and ConvertGraphForTool (7.1-4) objects.

myRecs := [
  rec( height := 50, width := 50, title := rec(
    text := "GAP", fontSize := 20
  ) ),
  rec( width := 10, depth := 10, color := "blue" )
];
JUPVIZRecordsKeychainLookup( myRecs, [ "height" ], 0 );              # = 50
JUPVIZRecordsKeychainLookup( myRecs, [ "width" ], 0 );               # = 50
JUPVIZRecordsKeychainLookup( myRecs, [ "depth" ], 0 );               # = 10
JUPVIZRecordsKeychainLookup( myRecs, [ "title", "text" ], "Title" ); # = "GAP"
JUPVIZRecordsKeychainLookup( myRecs, [ "color" ], "" );              # = "blue"
JUPVIZRecordsKeychainLookup( myRecs, [ "flavor" ], fail );           # = fail

7.3-12 JUPVIZFetchWithDefault
‣ JUPVIZFetchWithDefault( record, others, chain, default, action )( function )

Returns: nothing

This function is designed to make it easier to write new entries in the ConvertDataSeriesForTool (7.1-2) and ConvertGraphForTool (7.1-4) functions. Those functions are often processing a list of records (here called others) sometimes with one record the most important one (here called record) and looking up a chain of keys (using default just as in JUPVIZRecordKeychainLookup (7.3-10)) and then taking some action based on the result. This function just allows all of that to be done with a single call.

Specifically, it considers the array of records formed by Concatenation([record],others) and calls JUPVIZRecordsKeychainLookup (7.3-11) on it with the given chain and default. (If the chain is a string, it is automatically converted to a length-one list with the string inside.) Whatever the result, the function action is called on it, even if it is the default.

# Trivial examples:
myRec := rec( a := 5 );
myRecs := [ rec( b := 3 ), rec( a := 6 ) ];
f := function ( x ) Print( x, "\n" ); end;
JUPVIZFetchWithDefault( myRec, myRecs, "a", 0, f );       # prints 5
JUPVIZFetchWithDefault( myRec, myRecs, "b", 0, f );       # prints 3
JUPVIZFetchWithDefault( myRec, myRecs, "c", 0, f );       # prints 0
JUPVIZFetchWithDefault( myRec, myRecs, ["a","b"], 0, f ); # prints 0
# Useful example:
JUPVIZFetchWithDefault( primaryRecord, secondaryRecordsList,
  [ "options", "height" ], 400,
  function ( h ) myGraphJSON.height := h; end
);

See also JUPVIZFetchIfPresent (7.3-13).

7.3-13 JUPVIZFetchIfPresent
‣ JUPVIZFetchIfPresent( record, others, chain, action )( function )

Returns: nothing

This function is extremely similar to JUPVIZFetchWithDefault (7.3-12) with the following exception: No default value is provided, and thus if the lookup fails for all the records (including record and everything in others) then the action is not called.

Examples:

myRec := rec( a := 5 );
myRecs := [ rec( b := 3 ), rec( a := 6 ) ];
f := function ( x ) Print( x, "\n" ); end;
JUPVIZFetchIfPresent( myRec, myRecs, "a", 0, f );       # prints 5
JUPVIZFetchIfPresent( myRec, myRecs, "b", 0, f );       # prints 3
JUPVIZFetchIfPresent( myRec, myRecs, "c", 0, f );       # does nothing
JUPVIZFetchIfPresent( myRec, myRecs, ["a","b"], 0, f ); # does nothing

7.4 Representation wrapper

This code is documented for completeness's sake only. It is not needed for clients of this package. Package maintainers may be interested in it in the future.

The JupyterKernel package defines a method JupyterRender that determines how GAP data will be shown to the user in the Jupyter notebook interface. When there is no method implemented for a specific data type, the fallback method uses the built-in GAP method ViewString.

This presents a problem, because we are often transmitting string data (the contents of JavaScript files) from the GAP kernel to the notebook, and ViewString is not careful about how it escapes characters such as quotation marks, which can seriously mangle code. Thus we must define our own type and JupyterRender method for that type, to prevent the use of ViewString.

The declarations documented below do just that. In the event that ViewString were upgraded to more useful behavior, this workaround could probably be removed. Note that it is used explicitly in the using-library.js file in this package.

If this package is loaded without the JupyterKernel package having already been loaded, then the following functions and tools are not defined, because their definitions rely on global data made available by the JupyterKernel package.

7.4-1 JUPVIZIsFileContents
‣ JUPVIZIsFileContents( arg )( filter )

Returns: true or false

The type we create is called FileContents, because that is our purpose for it (to preserve, unaltered, the contents of a text file).

7.4-2 JUPVIZIsFileContentsRep
‣ JUPVIZIsFileContentsRep( arg )( filter )

Returns: true or false

The representation for the FileContents type

7.4-3 JUPVIZFileContents
‣ JUPVIZFileContents( arg )( operation )

A constructor for FileContents objects

Elsewhere, the JupyterViz package also installs a JupyterRender method for FileContents objects that just returns their text content untouched.

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

generated by GAPDoc2HTML