GAP (JupyterViz) - Chapter 7: Function reference

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

[MathJax off]

7 Function reference
7.1 High-Level Public API
7.1-1 Plot
7.1-2 ConvertDataSeriesForTool
7.1-3 PlotGraph
7.1-4 ConvertGraphForTool
7.1-5 PlotDisplayMethod
7.1-6 PlotDisplayMethod_Jupyter
7.1-7 PlotDisplayMethod_JupyterSimple
7.1-8 PlotDisplayMethod_HTML
7.2 Low-Level Public API
7.2-1 RunJavaScript
7.2-2 LoadJavaScriptFile
7.2-3 InstallVisualizationTool
7.2-4 InstallVisualizationToolFromTemplate
7.2-5 CreateVisualization
7.3 Internal methods
7.3-1 JUPVIZAbsoluteJavaScriptFilename
7.3-2 JUPVIZLoadedJavaScriptCache
7.3-3 JUPVIZFillInJavaScriptTemplate
7.3-4 JUPVIZRunJavaScriptFromTemplate
7.3-5 JUPVIZRunJavaScriptUsingRunGAP
7.3-6 JUPVIZRunJavaScriptUsingLibraries
7.3-7 JUPVIZMakePlotDataSeries
7.3-8 JUPVIZMakePlotGraphRecord
7.3-9 JUPVIZPlotDataSeriesList
7.3-10 JUPVIZRecordKeychainLookup
7.3-11 JUPVIZRecordsKeychainLookup
7.3-12 JUPVIZFetchWithDefault
7.3-13 JUPVIZFetchIfPresent
7.4 Representation wrapper
7.4-1 JUPVIZIsFileContents
7.4-2 JUPVIZIsFileContentsRep
7.4-3 JUPVIZFileContents

### 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:

- If `X` is a list of \(x\) values and `Y` is a list of \(y\) values then `Plot(X,Y)` plots them as ordered pairs.

- If `X` is a list of \(x\) values and `f` is a GAP function that can be applied to each \(x\) to yield a corresponding \(y\), then `Plot(X,f)` computes those corresponding \(y\) values and plots everything as ordered pairs.

- If `P` is a list of \((x,y)\) pairs then `Plot(P)` plots those ordered pairs.

- If `Y` is a list of \(y\) values then `Plot(Y)` assumes the corresponding \(x\) values are 1, 2, 3, and so on up to the length of `Y`. It then plots the corresponding set of ordered pairs.

- If `f` is a GAP function then `Plot(f)` assumes that `f` requiers integer inputs and evaluates it on a small domain (1 through 5) of \(x\) values and plots the resulting \((x,y)\) pairs.

- In any of the cases above, a new, last argument may be added that is a GAP record (call it `R`) containing options for how to draw the plot, including the plot type, title, axes options, and more. Thus the forms `Plot(X,Y,R)`, `Plot(X,f,R)`, `Plot(P,R)`, `Plot(Y,R)`, and `Plot(f,R)` are all acceptable. (For details, see `ConvertDataSeriesForTool` (7.1-2).)

- If `A1` is a list of arguments fitting any of the cases documented above (such as `[X,f]`) and `A2` is as well, and so on through `An`, then `Plot(A1,A2,...,An)` creates a combination plot with all of the data from each of the arguments treated as a separate data series. If the arguments contain conflicting plot options (e.g., the first requests a line plot and the second a bar chart) then the earliest option specified takes precedence.

    # 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:

- `x` - a list of \(x\) values for the plot

- `y` - the corresponding list of \(y\) values for the same plot

- `options` - another (inner) GAP record containing any of the options documented in Section 2.2.

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:

- If `V` is a list and `E` is a list of pairs of items from `V` then `PlotGraph(V,E)` treats them as vertex and edge sets, respectively.

- If `V` is a list and `R` is a GAP function then `PlotGraph(V,R)` treats `V` as the vertex set and calls `R(v1,v2)` for every pair of vertices (in both orders) to test whether there is an edge between them. It exepcts `R` to return boolean values.

- If `E` is a list of pairs then `PlotGraph(E)` treats `E` as a list of edges, inferring the vertex set to be any vertex mentioned in any of the edges.

- If `M` is a square matrix then `PlotGraph(M)` treats `M` as an adjacency matrix whose vertices are the integers 1 through \(n\) (the height of the matrix) and where two vertices are connected by an edge if and only if that matrix entry is positive.

- In any of the cases above, a new, last argument may be added that is a GAP record containing options for how to draw the graph, such as the tool to use. For details on the supported options, see `ConvertGraphForTool` (7.1-4).

    # 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:

- `vertices` - a list of vertex names for the graph. These can be any GAP data structure and they will be converted to strings with `PrintString`. The one exception is that you can give each vertex a position by making it a record with three entries: `name`, `x`, and `y`. In this way, you can manually lay out a graph.

- `edges` - a list of pairs from the `vertices` list, each of which represents an edge

- `options` - a GAP record containing any of the options documented in Section 2.4.

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.

- Functions such as `Plot` (7.1-1), `PlotGraph` (7.1-3), and `CreateVisualization` (7.2-5) will return objects of type `JupyterRenderable`, which is defined in the JupyterKernel Package.

- Such objects, when rendered in a Jupyter cell, will run a block of JavaScript contained within them, which will create the desired visualization.

- Such scripts tend to request additional information from GAP as they are running, by using calls to the JavaScript function `Jupyter.kernel.execute` defined in the notebook. Such calls are typically to fetch JavaScript libraries needed to create the requested visualization.

- Visualizations produced this way will not be visible if one later closes and then reopens the Jupyter notebook in which they are stored. To see the visualizations again, one must re-evaluate the cells that created them, so that the required libraries are re-fetched from the GAP Jupyter kernel.

##### 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.

- Functions such as `Plot` (7.1-1), `PlotGraph` (7.1-3), and `CreateVisualization` (7.2-5) will return objects of type `JupyterRenderable`, which is defined in the JupyterKernel Package.

- Such objects, when rendered in a Jupyter cell, will run a block of JavaScript contained within them, which will create the desired visualization.

- Such scripts will be entirely self-contained, and thus will not make any additional requests from the GAP Jupyter kernel. This makes such objects larger because they must contain all the required JavaScript visualization libraries, rather than being able to request them as needed later.

- Visualizations produced this way will be visible even if one later closes and then reopens the Jupyter notebook in which they are stored, because all the code needed to create them is included in the output cell itself, and is re-run upon re-opening the notebook.

##### 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.

- Functions such as `Plot` (7.1-1), `PlotGraph` (7.1-3), and `CreateVisualization` (7.2-5) will return no value, but will instead store HTML (and JavaScript) code for the visualization in a temporary file on the filesystem, then launch the operating system's default web browser to view that file.

- Such files are entirely self-contained, and require no GAP session to be running to continue viewing them. They can be saved anywhere the user likes for later viewing, printing, or sharing without GAP.

- Visualizations produced this way will not be visible if one later closes and then reopens the Jupyter notebook in which they are stored. To see the visualizations again, one must re-evaluate the cells that created them, so that the required libraries are re-fetched from the GAP Jupyter kernel.

#### 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.

- `tool` (required) - the name of the visualization tool to use. Currently supported tools are listed in Section 1.2 and links to their documentation are given in Section 3.4.

- `data` (required) - subobject containing all options specific to the content of the visualization, often passed intact to the external JavaScript visualization library. You should prepare this data in the format required by the library specified in the `tool` field, following the documentation for that library, linked to in Section 3.4.

- `width` (optional) - width to set on the output element being created

- `height` (optional) - similar, but height

    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