The Tangelo clientside library (tangelo.js) contains many functions to help create rich web applications for performing visualization and other tasks. The library is conceptually split up into several sections, reviewed here.
The core functions represent basic support for creating web applications.
Returns a string representing Tangelo’s current version number. See A Note on Version Numbers for more information on Tangelo version numbers.
Return type: | string |
---|
Throws a JavaScript error containing a message, and optionally the name of the reporting module. For example, the call tangelo.fatalError("mymodule", "You can't divide by zero!"); produces a JavaScript Error exception with the message [mymodule] You can’t divide by zero!
Arguments: |
|
---|
Returns a function that raises a fatal error telling the user about missing JavaScript requirements needed to run some functionality.
Generally, when it is detected that the requirements for some function are incomplete, the function can be implemented with tangelo.unavailable() in order to produce a useful error message at runtime.
Example:
if (!foobar) {
coolLib.awesomeFeature = tangelo.unavailable({
plugin: "coolLib.awesomeFeature",
required: "foobar"
});
}
Note that the cfg.required may also be a list of strings, if there are multiple requirements.
Arguments: |
|
---|
Determines if requiredVersion represents a Tangelo version that is compatible with the current version. The notion of compatibility comes from Tangelo’s semantic versioning (see A Note on Version Numbers for more information) and works as follows:
Development versions are compatible if all components match. That is to say, the major and minor versions, the patchlevel (if any), and the tag text must all match.
Unstable versions (those with major version 0) are compatible if the major version numbers are both 0 and the minor version numbers match.
Release versions (those with major version greater than zero) are compatible if the major version numbers match, and the required version’s minor version number is at most to Tangelo’s minor version number. In case the minor version numbers are equal, the required patchlevel must be at most equal to Tangelo’s patchlevel as well.
These rules ensure that the required API is the same as the API exported by Tangelo.
Arguments: |
|
---|---|
Return type: | boolean |
The utility functions provide services that may be useful or convenient in many kinds of web applications.
Loads the JSON file found at webpath asynchronously, then invokes callback, passing the JSON data, a status flag, and any error string that may have occurred, when the content is ready.
This function can be used to perform static configuration of a deployed web application. For example, the JSON file might list databases where application data is stored.
Arguments: |
|
---|
Generates a identifier made up of n randomly chosen lower and upper case letters, guaranteed to be unique during the run of a single web application.
This function can be useful when designing plugins that create DOM elements that need to be referenced in a reliable way later. The unique identifiers that come from this function can be used in the id attribute of such elements.
Be careful about calling this function with a small n - for example, a sequence of 52 calls to tangelo.uniqueID(1) would take longer and longer to randomly generate each single-letter string, while the 53rd call would enter an infinite loop. This is an extremely unlikely scenario but it bears to keep it in mind.
Arguments: |
|
---|---|
Return type: | string |
Returns an object whose key-value pairs are the query arguments passed to the current web page.
This function may be useful to customize page content based on query arguments, or for restoring state based on configuration options, etc.
Return type: | object |
---|
Returns true is value is a number and false otherwise.
Arguments: |
|
---|---|
Return type: | boolean |
Returns true is value is a boolean and false otherwise.
Arguments: |
|
---|---|
Return type: | boolean |
Returns true is value is an array and false otherwise.
Arguments: |
|
---|---|
Return type: | boolean |
Returns true is value is an object and false otherwise.
Arguments: |
|
---|---|
Return type: | boolean |
Returns true is value is a string and false otherwise.
Arguments: |
|
---|---|
Return type: | boolean |
Returns true is value is a function and false otherwise.
Arguments: |
|
---|---|
Return type: | boolean |
Computes an absolute web path for webpath based on the current location. If webpath is already an absolute path, it is returned unchanged; if relative, the return value has the appropriate prefix computed and prepended.
Arguments: |
|
---|---|
Return type: | string |
Returns an accessor function that behaves according to the accessor specification spec. Accessor functions generally take as input a JavaScript object, and return some value that may or may not be related to that object. For instance, tangelo.accessor({field: "mass"}) returns a function equivalent to:
function (d) {
return d.mass;
}
while tangelo.accessor({value: 47}) return a constant function that returns 47, regardless of its input.
As a special case, if spec is missing, or equal to the empty object {}, then the return value is the undefined accessor, which simply raises a fatal error when called.
For more information of the semantics of the spec argument, see Accessor Specifications.
These functions, in the tangelo.data namespace, provide transformations of common data formats into a common format usable by Tangelo plugins.
Converts an array of nodes with ids and child lists into a nested tree structure. The nested tree format with a standard children attribute is the required format for other Tangelo functions such as $.dendrogram().
As an example, evaluating:
var tree = tangelo.data.tree({
data: [
{name: "a", childNodes: [{child: "b", child: "c"}]},
{name: "b", childNodes: [{child: "d"}]},
{name: "c"},
{name: "d"}
],
id: {field: "name"},
idChild: {field: "child"},
children: {field: "childNodes"}
});
will return the following nested tree (note that the original childNodes attributes will also remain intact):
{
name: "a",
children: [
{
name: "b",
children: [
{
name: "d"
}
]
},
{
name: "c"
}
]
}
Arguments: |
|
---|
Arguments: |
|
---|
Groups an array of nodes together into clusters based on distance according to some metric. By default, the 2D Euclidean distance, \(d(a, b) = \sqrt{(a\mathord{.}x - b\mathord{.}x)^2 + (a\mathord{.}y - b\mathord{.}y)^2}\), will be used. One can override the accessors to the \(x\) and \(y\)-coordinates of the nodes via the spec object. The algorithm supports arbitrary topologies with the presence of a custom metric. If a custom metric is provided, the x/y accessors are ignored.
For each node, the algorithm searches for a cluster with a distance spec.clusterDistance. If such a cluster exists, the node is added otherwise a new cluster is created centered at the node. As implemented, it runs in \(\mathcal{O}(nN)\) time for \(n\) nodes and \(N\) clusters. If the cluster distance provided is negative, then the algorithm will be skipped and all nodes will be placed in their own cluster group.
The data array itself is mutated so that each node will contain a cluster property set to an array containing all nodes in the local cluster. For example, with clustering distance 5 the following data array
>>> data
[
{ x: 0, y: 0 },
{ x: 1, y: 0 },
{ x: 10, y: 0 }
]
will become
>>> data
[
{ x: 0, y: 0, cluster: c1 },
{ x: 1, y: 0, cluster: c1 },
{ x: 10, y: 0, cluster: c2 }
]
with
>>> c1
[ data[0], data[1] ]
>>> c2
[ data[2] ]
In addition, the function returns an object with properties singlets and clusters containing an array of nodes in their own cluster and an array of all cluster with more than one node, respectively. As in the previous example,
>>> tangelo.data.distanceCluster( { data: data, clusterDistance: 5 } )
{
singlets: [ data[2] ],
clusters: [ [ data[0], data[1] ] ]
}
Arguments: |
|
---|
Performs 1-D smoothing on a dataset by convolution with a kernel function. The mathematical operation performed is as follows:
for \(R=\) spec.radius and \(K=\) spec.kernel. Predefined kernels can be specified as strings, these include:
- box: simple moving average (default),
- gaussian: gaussian with standard deviation spec.radius/3.
The function returns an array of numbers representing the smoothed dependent variables. In addition if spec.set was given, the input data object is modified as well. The set method is called after smoothing as follows:
set.call(data, y(data[i]), data[i], i),
and the kernel is called as:
kernel.call(data, x(data[i]), x(data[j]), i, j).
The default options called by
smooth({ data: data })
will perform a simple moving average of the data over a window that is of radius \(0.05\) times the data extent. A more advanced example
smooth({
data: data,
kernel: 'gaussian',
radius: 3,
absolute: true,
sorted: false
})
will sort the input data and perform a gaussian smooth with standard deviation equal to \(1\).
The Streaming API allows for the handling of web services that yield parts of their output a piece at a time. This is useful for handling very large data streams, but could also be used for purposes such as informing a web application of different phases of its execution, etc. The streaming functions are found in the tangelo.stream namespace.
See Streaming for a full discussion on how streaming works.
Asynchronously retrieves a JSON-encoded list of all stream keys, then invokes callback, passing the keys in as a JavaScript list of strings.
Arguments: |
|
---|
Asynchronously invokes the web service at webpath - which should initiate a stream by returning a Python iterable object from its run() method - then invokes callback, passing it the stream key associated with the new stream.
This callback might, for example, log the key with the application so that it can be used later, possibly via calls to tangelo.stream.query() or tangelo.stream.run():
tangelo.stream.start("myservice", function (key) {
app.key = key;
});
Arguments: |
|
---|
Runs the stream keyed by key for one step, then invokes callback with the result. If there is an error, callback is instead invoked passing undefined as the first argument, and the error as the second.
Arguments: |
|
---|
Runs the stream keyed by key continuously until it runs out, or there is an error, invoking callback with the results each time. The delay parameter expresses in milliseconds the interval between when a callback returns, and when the stream is queried again.
The behavior of callback can influence the future behavior of this function. If callback returns a value, and the value is a
Other return types will simply be ignored.
Arguments: |
|
---|
Deletes the stream keyed by key. The optional callback is a function that is invoked with an error object is something went wrong during the delete operation, or no arguments if the delete was successful.
Arguments: |
|
---|
Tangelo offers native support for VTK Web processes. These functions help to launch, manage, query, and terminate such processes.
Asynchronously retrieves a list of VTK Web process keys, and invokes callback with the list.
Arguments: |
|
---|
Retrieves a status report about the VTK Web process keyed by key, then invokes callback with it when it becomes available.
The report is a JavaScript object containing a status field indicating whether the request succeeded (“complete”) or not (“failed”). If the status is “failed”, the reason field will explain why.
A successful report will contain a process field that reads either “running” or “terminated”. For a terminated process, the returncode field will contain the exit code of the process.
For running processes, there are additional fields: port, reporting the port number the process is running on, and stdout and stderr, which contain a list of lines coming from those two output streams.
This function may be useful for debugging an errant VTK Web script.
Attempts to launch a new VTK Web process by running a Python script found at cfg.url, passing cfg.argstring as commandline arguments to the launcher script. If successful, the streaming image output will be sent to the first DOM element matching the CSS selector given in cfg.viewport, which should generally be a div element.
After the launch attempt succeeds or fails, callback is invoked, passing the process key as the first argument, and the error object describing any errors that occurred as the second (or undefined if there was no error).
Arguments: |
|
---|
Attempts to terminate the VTK Web process keyed by key. If there is a callback, it will be invoked with the key of the terminated process, the DOM element that was the viewport for that process, and an error (if any). The key is passed to the callback in case this function is called several times at once, and you wish to distinguish between the termination of different processes. The DOM element is passed in case you wish to change something about the appearance of the element upon termination.
Arguments: |
|
---|
Tangelo defines several jQuery plugins to provide convenient behaviors or to implement common visualization methods. See Creating jQuery Widgets for more information.
Constructs an SVG color legend in the g element specified by cfg.legend, mapping colors from the elements of cfg.categories through the function cfg.cmap_func.
Arguments: |
|
---|
Arguments: |
|
---|
Constructs an interactive dendrogram.
Temporarily turns transitions off and resizes the dendrogram. Should be called whenever the containing dom element changes size.
Constructs a map from a GeoJSON specification, and plots colored SVG dots on it according to spec.data.
spec.worldGeometry is a web path referencing a GeoJSON file. spec.data is an array of JavaScript objects which may encode geodata attributes such as longitude and latitude, and visualization parameters such as size and color, while spec.latitude, spec.longitude, and spec.size are accessor specifications describing how to derive the respective values from the data objects. spec.color is an accessor deriving categorical values to put through a color mapping function.
For a demonstration of this plugin, see the geodots example.
Arguments: |
|
---|
Constructs a map from a GeoJSON specification, and plots a node-link diagram on it according to spec.data. This plugin produces similar images as $.geodots() does.
spec.worldGeometry is a web path referencing a GeoJSON file.
spec.data is an object containing two fields: nodes and links. The nodes field contains an array of JavaScript objects of the exact same structure as the spec.data array passed to $.geodots(), encoding each node’s location and visual properties.
The links field contains a list of objects, each encoding a single link by specifying its source and target node as an index into the nodes array. spec.linkSource and spec.linkTarget are accessors describing how to derive the source and target values from each of these objects.
The plugin draws a map with nodes plotted at their specified locations, with the specified links drawn as black lines between the appropriate nodes.
For a demonstration of this plugin, see the geonodelink example.
Arguments: |
|
---|
This plugin performs the same job as $.geodots(), but plots the dots on an interactive Google Map rather than a GeoJSON map. To this end, there is no need for a “worldGeometry” argument, but the data format and other arguments remain the same.
For a demonstration of this plugin, see the mapdots example.
Arguments: |
|
---|
This plugin provides a low level interface to the geojs mapping library. For a simple example of using this plugin, see the geojsMap example.
Arguments: |
|
---|
The widget also contains the following public methods for drawing on the map.
Converts a point or points in latitude/longitude coordinates into screen pixel coordinates. This function takes in either a geo.latlng object or an array of such objects. It always returns an array of objects with properties:
- x the horizontal pixel coordinate
- y the vertical pixel coordinate
Arguments: |
|
---|
This is the inverse of latlng2display returning an array of geo.latlng objects.
Arguments: |
|
---|
Returns an svg DOM element contained in the geojs map. This element directly receives mouse events from the browser, so you can attach event handlers to svg elements as if the map were not present. You can call stopPropagation to customize user intaraction and to prevent mouse events from reaching the map.
Returns the geojs map object for advanced customization.
Users of this plugin should attach a handler to the draw event that recomputes the pixel coordinates and redraws the svg elements. The plugin will trigger this event whenever the map is panned, zoomed, or resized.
This plugin is similar to $.mapdots(), but plots the dots using the geojsMap plugin.
For a demonstration of this plugin, see the geojsdots example.
Arguments: |
|
---|
Constructs an interactive node-link diagram. spec.data is an object with nodes and links fields, each of which is a list of objects. The nodes list objects specify the nodes’ visual properties, while the links list simply specifies the nodes at the end of each link, as indices into the nodes list.
The accessors spec.linkSource and spec.linkTarget specify how to extract the source and target information from each link object, while spec.nodeSize and spec.nodeColor specify how to extract these visual properties from the node objects, much as in the $.geonodelink() plugin. spec.nodeCharge specifies the simulated electrostatic charge on the nodes, for purposes of running the interactive node placement algorithm (see the D3 documentation for more information). Finally, spec.nodeLabel is an accessor describing what, if any, text label should be attached to each node.
Arguments: |
|
---|
Constructs a grid of scatter plots that are designed to show the relationship between different variables or properties in a dataset.
Arguments: |
|
---|
An example of a full correlation plot layout. All variables are shown on the horizontal and vertical axes.
An example of a half correlation plot layout. Only the upper left corner of the full layout are displayed.
Constructs a line plot with time on the x-axis and an arbitrary numerical value on the y-axis.
Arguments: |
|
---|
These return a d3 linear scale representing the transformation from plot coordinates to screen pixel coordinates. They make it possible to add custom annotations to the plot by appending an svg element to the d3.select(‘.plot’) selection at the coordinates returned by the scales.