Welcome to the Tangelo Web Framework!¶

Running the Test Suites¶

Tangelo comes with a battery of server and client tests. To run these, you can invoke the Grunt test task as follows:

grunt test

This runs both the server and client tests. Each test suite can be run on its own, with:

grunt test:server

and:

grunt test:client

Each of these produces a summary report on the command line. To view details such as individual test results, or details about code coverage, you can launch Tangelo to serve the HTML reports with the Grunt serve task:

grunt serve:test

and point a web browser at http://localhost:50047.

Configuration Options¶

The following tables, organized by section title, show what fields can be included in the configuration file, what they mean, and their default values if left unspecified.

Footnotes

systemd¶

systemd is a Linux service manager daemon for which a unit file corresponds to each service. Tangelo supplies such a unit file, along with supporting scripts, at /usr/share/tangelo/daemon/systemd. To install Tangelo as a service, the files in this directory need to be copied or symlinked to a location from which systemd can access them. An example follows, though your particular system may require some changes from what is shown here; see the systemd documentation for more information.

Go to the place where systemd unit files are installed:

cd /usr/lib/systemd/system

Place an appropriate symlink there:

sudo ln -s /usr/share/tangelo/daemon/systemd/system/tangelo@.service

Go to the systemd auxiliary scripts directory:

cd ../scripts

Install a symlink to the launcher script:

sudo ln -s /usr/share/tangelo/daemon/systemd/scripts/launch-tangelo.sh

Now you will be able to control Tangelo via the systemctl command. Note that the unit file defines Tangelo as an instantiated service, meaning that multiple Tangelo instances can be launched independently by specifying an instantiation name. For example:

sudo systemctl start tangelo@localhost:8080

will launch Tangelo to run on the localhost interface, on port 8080. The way this works is that systemctl takes the instantiation name (i.e., all the text after the @ symbol - localhost:8080) and passes it to launch-tangelo.sh. It in turn parses the hostname (localhost) and port number (8080) from the name, then launches Tangelo using whatever configuration file is found at /etc/tangelo.conf, but overriding the hostname and port with those parsed from the name. This allows for a unique name for each Tangelo instance that corresponds to its unique web interface.

Return Types¶

The type of the value returned from the run() function determines how Tangelo creates content for the associated web endpoint. Since web server communication occurs via textual data, all values returned by web services must eventually be converted to strings. By default, Tangelo accomplishes this by considering all such values to be JSON-encoded. For example, in the calculator example, the run() function returns Python int value 47; Tangelo takes this value and applies the standard function json.dump() to it, resulting in the string "47", which is delivered to the client for further processing. Similarly, a service that returns a Python dict value will be converted to a general JSON-object, making it easy to return structured information from any given web service.

This means that, in the most general case, you can create your own types, equipped with methods for JSON encoding them, and use those are direct return values (see the Python documentation for information on custom JSON encoding). Attempting to return a type that is not JSON-serializable results in a 400 error.

The only exception to the default conversion behavior is that if the service returns a string directly, this value will not be JSON encoded (which entails surrounding it with double-quotes), but simply passed along unchanged. This “escape hatch” enables a service to return any kind of data by encoding it as a string. The tangelo.content_type() utility function can be used to specify the intended type of the returned data. For instance, tangelo.content_type("text/plain") followed by return "hello, world" will result in a text result being sent to the client. More complex types are also possible; e.g., a service might compute a PNG image, then send the PNG data back as a string after calling tangelo.content_type("application/png").

Specifying a Custom Return Type Converter¶

Similarly to the tangelo.types() decorator mentioned above, services can specify a custom return type via the tangelo.return_type() decorator. It takes a single argument, a function to convert the object returned from the service function to a string or JSON-serializable value (see Return Types):

import tangelo

def excited(s):
    return s + "!!!"

@tangelo.return_type(excited)
def run(name):
    return "hello %s" % (name)

Given Data as an input, this service will return the string Hello Data!!! to the client.

A more likely use case for this decorator is special-purpose JSON converters, such as Pymongo’s bson.json_util.dumps() function, which can handle certain non-standard objects such as Python datetime objects when converting to JSON text.

Web Content¶

The directory foobar/web behaves much like any other static and dynamic content served by Tangelo. Content in this directory is served from a base URL of /plugin/foobar/ (where, foobar is the name of this plugin; however, see Configuration). For example, /plugin/foobar/foobar.js refers to the file of the same name in the web directory; this URL could be used by a web application to include this file in a <script> tag, etc. (see Serving Web Content for more information).

Dynamic web services also behave as elsewhere: the URL /plugin/foobar/foobar will cause Tangelo to run the code found in foobar.py and return it to the client, etc. (see Tangelo Web Services for more information).

Python Content¶

A plugin may also wish to export some Python code for use in web services. In the foobar plugin example, such content appears in foobar/python/__init__.py. This file, for example, might contain the following code:

import helper

def even(n):
    return n % 2 == 0

When the foobar plugin is loaded by Tangelo, the contents of python/__init__.py are placed in a virtual package named tangelo.plugin.foobar. This enables web services to use the even() functions as in the following example:

import tangelo
import tangelo.plugin.foobar

def run(n):
    tangelo.content_type("text/plain")
    return "even" if tangelo.plugin.foobar.even(n) else "odd"

To export “submodules” that will appear in the tangelo.plugin.foobar namespace, note that __init__.py uses the import statement to cause the helper module to appear within its scope; this module can now be addressed with tangelo.plugin.foobar.helper, and any functions and data exported by helper will become available for use in web services as well.

The bundled bokeh plugin contains an example of exporting a decorator function using this technique.

Enabling Plugins¶

The Tangelo executable has an option --plugin-config that specifies a plugin configuration file. This defaults to /etc/tangelo/plugin.conf. The file is a YAML configuration file consisting of a list of objects, one for each plugin under consideration. The objects themselves are relatively simple:

- name: foobar
  enabled: true
  path: /path/to/foobar/plugin

- name: quux
  enabled: false
  path: path/to/quux

Each contains a required name property, an optional enabled boolean flag (which, if omitted, defaults to true), and a string path property describing where to find the plugin materials (i.e., the example directory shown above). Whenever this file changes and a client visits any plugin URL, Tangelo will compare the set of plugins enabled by the configuration file to the set of plugins currently enabled, and will load and unload plugins to bring the running plugins up to date. For example, if you edit the example file above to change quux‘s enabled flag to true, then visit /plugin, Tangelo will first load the quux plugin, then return a list of running plugins, which will now include quux. Conversely, if you also changed foobar‘s enabled flag to false (or comment out, or delete foobar‘s entire section), foobar will additionally be unloaded.

Plugin Setup¶

Some plugins may need to be set up before they can be properly used. Plugin setup consists of two steps: installing Python dependencies, if any, and consulting any informational messages supplied by the plugin.

In the example foobar plugin, note that the root directory includes a requirements.txt file. This is simply a pip requirements file declaring what Python packages the plugin needs to run. You can install these with a command similar to pip install -r foobar/requirements.txt.

Secondly, some plugins may require some other action to be taken before they work. The plugin authors can describe any such instructions in the info.txt file. After installing the requirements, you should read this file to see if anything else is required. For instance, a package may need to bootstrap after it’s installed by fetching further resources or updates from the web; in this case, info.txt would explain just how to accomplish this bootstrapping.

These steps constitute a standard procedure when retrieving a new plugin for use with your local Tangelo installation. For instance, if the foobar plugin resides in a GitHub repository, you would first find a suitable location on your local computer to clone that repository. Then you would invoke pip to install the required dependencies, then take any action specified by info.txt, and finally create an entry in the Tangelo plugin configuration file. When Tangelo is started (or when the plugin registry is refreshed), the new plugin will be running.

Configuring Plugins¶

The file foobar/config.yaml describes a YAML associative array representing the plugin’s configuration data. This is the same format as web service configurations (see Configuring Web Services), and can be read with the function tangelo.plugin_config().

Similarly, plugins also have a editable persistent store, accessed with the tangelo.plugin_store() function.

Both the configuration and the persistent store and passed as arguments to setup() and teardown() in the control module.

Loading a Plugin¶

Loading a plugin consists of the following actions:

1. The configuration is loaded from config.yaml.
2. An empty persistent store is created.
3. Any python content is set up by creating a virtual package called tangelo.plugin.<pluginname>, and exporting the contents of python/__init__.py to it.
4. The control.py module is loaded, and control.setup() is invoked, passing the configuration and fresh persistent store to it.
5. If setup() returns a result, the list of CherryPy apps expressed in the "apps" property of it are mounted.
6. The plugin name is added to the list of active plugins.

Steps 3, 4, and 5 are not taken if the corresponding content is not present. If any of those steps raises an exception, the exception is logged to disk and step 6 will not be taken (i.e., the plugin will not be loaded).

Unloading a Plugin¶

Unloading a plugins consists of the follow actions (which serve to undo the corresponding setup actions):

1. Any python content present in tangelo.plugin.<pluginname> is torn down by deleting the virtual package from the runtime.
2. Any CherryPy applications are unmounted.
3. If the control module contains a teardown() function, it is invoked, passing the configuration and persistent store to it.
4. The plugin name is removed from the list of active plugins.

If an exception occurs during step 3, the teardown() function will not finish executing, but step 4 will still be taken.

Tangelo¶

The Tangelo plugin simply serves the Tangelo clientside library files tangelo.js and tangelo.min.js. It also includes a “version” web service that simply returns, as plain text, the running server’s version number.

This is supplied as a plugin to avoid having to include the JavaScript files manually into every deployment of Tangelo. Instead, the files can be easily served directly from the plugin, thus retaining stable URLs across deployments.

Manifest

Docs¶

The Docs plugin serves the Tangelo documentation (the very documentation you are reading right now!). Again, this is to simplify deployments. The index is served at /plugin/docs and from there the index page links to all pages of the documentation.

Stream¶

It may be necessary to return an immense (or even infinite) amount of data from a web service to the client. However, this may take up so much time and memory that dealing with it becomes intractable. In such situations, the Stream plugin may be able to help.

import math
import tangelo

def prime(n):
    for i in xrange(2, int(math.floor(math.sqrt(num)+1))):
        if n % i == 0:
            return False
    return True

@tangelo.types(n=int)
def stream(n=2):
    for i in filter(prime, range(2, int(math.floor(math.sqrt(num)+1)))):
        if n % i == 0
            yield i

{"key": "3dffee9e03cef2322a2961266ebff104"}

VTKWeb¶

The VTKWeb plugin is able to run VTK Web programs and display the result in real time on a webpage. The interface is somewhat experimental at the moment and only supports running the program and interacting with it via the mouse. In a later version, the ability to call functions and otherwise interact with VTK Web in a programmatic way will be added.

In order to enable this funcationality, the plugin must be configured with a vtkpython option set to the full path to a vtkpython executable in a build of VTK.

Girder¶

Girder is an open-source, high-performance data management platform. The Girder plugin mounts a working instance of Girder in the plugin namespace so that its web client and REST API become available for use with Tangelo web applications.

When the plugin is loaded, /plugin/girder/girder will serve out the web frontend to Girder, while /plugin/girder/girder/api/v1 will point to the REST API documentation, as well as serving as the base URL for all API calls to Girder.

For more information about how to use Girder, see its documentation.

Config¶

Many web applications need to change their behavior depending on external resources or other factors. For instance, if an application makes use of a Mongo database, a particular deployment of that application may wish to specify just which database to use. To this end, the Config plugin works to provide a simple way to configure the runtime behavior of applications, by using a file containing a JSON object as a key-value store representing the configuration.

The plugin provides a web service at /plugin/config/config that simply parses a JSON file and returns a JSON object representing the contents of the file. The API is as follows:

• GET /plugin/config/config/<absolute>/<webpath>/<to>/<json>/<file>[?required]

If the path specified does not point to a static file, or does not contain a valid JSON object, the call will result in an HTTP 4xx error, with the body expressing the particular reason for the error in a JSON response. Otherwise, the service will parse the file and return the configuration object in the “result” field of the response.

If the file does not exist, then the behavior of the service depends on the presence of absence of the required parameter: when the call is made with the parameter, this results in a 404 error; otherwise, the service returns an empty object. This is meant to express the use case where an application can use a configuration file if specified, falling back on defaults if there is none.

The plugin also supplies a JavaScript plugin via /plugin/config/config.js; like other JavaScript plugin components, it provides a callback-based function that engages the service on the user’s behalf:

tangelo.plugin.config.config(url, [required, ]callback)¶

Arguments:	string (url) – An absolute or relative URL to the configuration file boolean (required) – A flag indicating whether the configuration file is required or not (default: false) function (callback(config)) – Callback invoked with configuration data when it becomes available

Engages the config service using the file specified by url, invoking callback with the configuration when it becomes available. The optional required flag, if set to true, causes callback to be invoked with undefined when the configuration file doesn’t exist; when set to false or not supplied, a non-existent configuration file results in callback being invoked with {}.

UI¶

The UI plugin contains some JQuery plugins useful for building a user interface as part of a web application.

$.controlPanel()¶

Constructs a control panel drawer from a <div> element. The div can contain any standard HTML content; when this plugin is invoked on it, it becomes a sliding drawer with a clickable handle that will disappear into the bottom of the window when closed.

This plugin can be used to maintain, e.g., visualization settings that affect what is seen in the main window.

$.svgColorLegend(cfg)¶

Arguments:

cfg.legend (string) – CSS selector for SVG group element that will contain the legend cfg.cmap_func (function) – A colormapping function to create color patches for the legend entries cfg.xoffset (integer) – How far, in pixels, to set the legend from the left edge of the parent SVG element. cfg.yoffset (integer) – How far, in pixels, to set the legend from the top edge of the parent SVG element. cfg.categories (string[]) – A list of strings naming the categories represented in the legend. cfg.height_padding (integer) – How much space, in pixels, to place between legend entries. cfg.width_padding (integer) – How much space, in pixels, to place between a color patch and its associated label cfg.text_spacing (integer) – How far, in pixels, to raise text labels (used to vertically center text within the vertical space occupied by a color patch). cfg.legend_margins (object) – An object with (optional) fields top, bottom, left, and right, specifying how much space, in pixels, to leave between the edge of the legend and the entries. cfg.clear (bool) – Whether to clear out the previous contents of the element selected by cfg.legend.

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.

Data¶

These functions provide transformations of common data formats into a common format usable by Tangelo plugins.

tangelo.plugin.data.tree(spec)¶

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.plugin.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:	spec.data (object) – The array of nodes. spec.id (Accessor) – An accessor for the ID of each node in the tree. spec.idChild (Accessor) – An accessor for the ID of the elements of the children array. spec.children (Accessor) – An accessor to retrieve the array of children for a node.

tangelo.plugin.data.distanceCluster(spec)¶

Arguments:	spec.data (object) – The array of nodes. spec.clusterDistance (number) – The radius of each cluster. spec.x (Accessor) – An accessor to the \(x\)-coordinate of a node. spec.y (Accessor) – An accessor to the \(y\)-coordinate of a node. spec.metric (function) – A function that returns the distance between two nodes provided as 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.plugin.data.distanceCluster( { data: data, clusterDistance: 5 } )
{
    singlets: [ data[2] ],
    clusters: [ [ data[0], data[1] ] ]
}

tangelo.plugin.data.smooth(spec)¶

Arguments:

spec.data (object) – An array of data objects. spec.x (Accessor) – An accessor to the independent variable. spec.y (Accessor) – An accessor to the dependent variable. spec.set (function) – A function to set the dependent variable of a data object. spec.kernel (string) – A string denoting a predefined kernel or a function computing a custom kernel. spec.radius (number) – The radius of the convolution. spec.absolute (bool) – Whether the radius is given in absolute coordinates or relative to the data extent. spec.sorted (bool) – Whether the data is presorted by independent variable, if not the data will be sorted internally. spec.normalize (bool) – Whether or not to normalize the kernel to 1.

Performs 1-D smoothing on a dataset by convolution with a kernel function. The mathematical operation performed is as follows:

\[\begin{split}y_i \leftarrow \sum_{\left|x_i - x_j\right|<R} K\left(x_i,x_j\right)y_j\end{split}\]

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\).

tangelo.plugin.data.bin(spec)¶

Arguments:	spec.data (object) – An array of data objects. spec.value (Accessor) – An accessor to the value of a data object. spec.nBins (integer) – The number of bins to create (default 25). spec.min (number) – The minimum bin value (default data minimum). spec.max (number) – The maximum bin value (default data maximum). spec.bins (object) – User defined bins to aggregate the data into.

Aggregates an array of data objects into a set of bins that can be used to draw a histogram. The bin objects returned by this method look as follows:

{
    "min": 0,
    "max": 1,
    "count": 5
}

A data object is counted as inside the bin if its value is in the half open interval [ min, max ); however for the right most bin, values equal to the maximum are also included. The default behavior of this method is two construct a new array of equally spaced bins between data’s minimum value and the data’s maximum value. If spec.bins is given, then the data is aggregated into these bins rather than a new set being generated. In this case, the bin objects are mutated rather a new array being created. In addition, the counters are not reset to 0, so the user must do so manually if the bins are reused over multiple calls.

Examples:

>>> tangelo.plugin.data.bin({
        data: [{"value": 0}, {"value": 1}, {"value": 2}],
        nBins: 2
    })
[
    {"min": 0, "max": 1, "count": 1},
    {"min": 1, "max": 2, "count": 2}
]

>>> tangelo.plugin.data.bin({
        data: [{"value": 1}, {"value": 3}],
        nBins: 2,
        min: 0,
        max: 4
    })
[
    {"min": 0, "max": 2, "count": 1},
    {"min": 2, "max": 4, "count": 1}
]

>>> tangelo.plugin.data.bin({
        data: [{"value": 1}, {"value": 3}],
        bins: [{"min": 0, "max": 2, "count": 1}, {"min": 2, "max": 10, "count": 0}]
    })
[
    {"min": 0, "max": 2, "count": 2},
    {"min": 2, "max": 10, "count": 1}
]

Mongo¶

This plugin provides a service that connects to a Mongo database and retrieves results based on the requested query. The API looks as follows:

• GET /plugin/mongo/mongo/<hostname>/<database>/<collection>?query=<query-string>&limit=<N>&fields=<fields-string>

query-string should be a JSON string describing a query object, while field-string should be a JSON string describing a list of fields to include in the results.

The service returns a JSON-encoded list of results from the database.

This plugin is under development, so the interface may change in the future in order to provide a more complete API.

Vis¶

The Vis plugin provides several JQuery widgets for visualization particular types of data using basic chart types.

Dendrogram. /plugin/vis/dendrogram.js provides the following JQuery widget:

$.dendrogram(spec)¶

Arguments:

spec.data (object) – A nested tree object where child nodes are stored in the children attribute. spec.label (accessor) – The accessor for displaying tree node labels. spec.id (accessor) – The accessor for the node ID. spec.nodeColor (accessor) – The accessor for the color of the nodes. spec.labelSize (accessor) – The accessor for the font size of the labels. spec.lineWidth (accessor) – The accessor for the stroke width of the node links. spec.lineColor (accessor) – The accessor for the stroke color of the node links. spec.nodeSize (accessor) – The accessor for the radius of the nodes. spec.labelPosition (accessor) – The accessor for the label position relative to the node. Valid return values are ‘above’ and ‘below’. spec.expanded (accessor) – The accessor to a boolean value that determines whether the given node is expanded or not. spec.lineStyle (string) – The node link style: ‘curved’ or ‘axisAligned’. spec.orientation (string) – The graph orientation: ‘vertical’ or ‘horizontal’. spec.duration (number) – The transition animation duration. spec.on (object) – An object of event handlers. The handler receives the data element as an argument and the dom node as this. If the function returns true, the default action is perfomed after the handler, otherwise it is prevented. Currently, only the ‘click’ event handler is exposed.

Constructs an interactive dendrogram.

resize()¶

Temporarily turns transitions off and resizes the dendrogram. Should be called whenever the containing dom element changes size.

Correlation Plot. /plugin/vis/correlationPlot.js provides this widget:

$.correlationPlot(spec)¶

Constructs a grid of scatter plots that are designed to show the relationship between different variables or properties in a dataset.

Arguments:

spec.variables (object[]) – An array of functions representing variables or properties of the dataset. Each of these functions takes a data element as an argument and returns a number between 0 and 1. In addition, the functions should have a label attribute whose value is the string used for the axis labels. spec.data (object[]) – An array of data elements that will be plotted. spec.color (accessor) – An accessor for the color of each marker. spec.full (bool) – Whether to show a full plot layout or not. See the images below for an example. This value cannot currently be changed after the creation of the plot.

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.

Timeline. /plugin/vis/timeline.js provides this widget:

$.timeline(spec)¶

Constructs a line plot with time on the x-axis and an arbitrary numerical value on the y-axis.

Arguments:	spec.data (object[]) – An array of data objects from which the timeline will be derived. spec.x (accessor) – An accessor for the time of the data. spec.y (accessor) – An accessor for the value of the data. spec.transition (number) – The duration of the transition animation in milliseconds, or false to turn off transitions.

xScale()¶

yScale()¶

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.

Node-link diagram. /plugin/vis/nodelink.js provides this widget:

$.nodelink(spec)¶

Arguments:

spec.data (object) – The node-link diagram data spec.nodeSize (accessor) – An accessor for the size of each node spec.nodeColor (accessor) – An accessor for the colormap category for each node spec.nodeLabel (accessor) – An accessor for each node’s text label spec.nodeCharge (accessor) – An access for each node’s simulated electrostatic charge spec.linkSource (accessor) – An accessor to derive the source node of each link spec.linkTarget (accessor) – An accessor to derive the target node of each link

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.

Mapping¶

In many cases, data has a geospatial component, for which some kind of map is a useful mode of visualization. The mapping plugin provides several options for visualization geolocation data, via the following JQuery widgets.

Geo dots. To plot location dots on a GeoJSON map, /plugin/mapping/geodots.js provides:

$.geodots(spec)¶

Arguments:	spec.worldGeometry (string) – A web path to a GeoJSON file spec.latitude (accessor) – An accessor for the latitude component spec.longitude (accessor) – An accessor for the longitude component spec.size (accessor) – An accessor for the size of each plotted circle spec.color (accessor) – An accessor for the colormap category for each plotted circle

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.

Geo node-link diagram. To plot a node-link diagram on a GeoJSON map, /plugin/mapping/geonodelink.js provides:

$.geonodelink(spec)¶

Arguments:

spec.data (object) – The encoded node-link diagram to plot spec.worldGeometry (string) – A web path to a GeoJSON file spec.nodeLatitude (accessor) – An accessor for the latitude component of the nodes spec.nodeLongitude (accessor) – An accessor for the longitude component of the nodes spec.nodeSize (accessor) – An accessor for the size of each plotted circle spec.nodeColor (accessor) – An accessor for the colormap category for each plotted circle spec.linkSource (accessor) – An accessor to derive the source node of each link spec.linkTarget (accessor) – An accessor to derive the target node of each link

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.

Map dots. To plot dots on a Google Map, /plugin/mapping/mapdots.js provides:

$.mapdots(spec)¶

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:	spec.data (object[]) – The list of dots to plot spec.latitude (accessor) – An accessor for the latitude component spec.longitude (accessor) – An accessor for the longitude component spec.size (accessor) – An accessor for the size of each plotted circle spec.color (accessor) – An accessor for the colormap category for each plotted circle

GeoJS Map. GeoJS is an open-source visualization-centric mapping library. Tangelo provides some JQuery plugins to replicate the above mapping use cases with GeoJS.

GeoJS map. To use a GeoJS map instance as a plugin, /plugin/mapping/geojsMap.js provides:

$.geojsMap(spec)¶

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:	spec.zoom (integer) – The initial zoom level of the map.

The widget also contains the following public methods for drawing on the map.

latlng2display(points)¶

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:	point (geo.latlng) – The world coordinate(s) to be converted

display2latlng(points)¶

This is the inverse of latlng2display returning an array of geo.latlng objects.

Arguments:	point (object) – The world coordinate(s) to be converted

svg()¶

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.

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.

GeoJS dots. To plot dots on a GeoJS map, /plugin/mapping/geojsdots.js provides:

$.geojsdots(spec)¶

Arguments:	spec.data (object[]) – The list of dots to plot spec.latitude (accessor) – An accessor for the latitude component spec.longitude (accessor) – An accessor for the longitude component spec.size (accessor) – An accessor for the size of each plotted circle spec.color (accessor) – An accessor for the colormap category for each plotted circle

This plugin is similar to $.mapdots(), but plots the dots using the geojsMap plugin.

For a demonstration of this plugin, see the geojsdots example.

Bokeh¶

Bokeh is a Python plotting library that can display interactive graphics on the web. Tangelo provides seamless integration with Bokeh via the Bokeh plugin. This plugin provides a Python decorator for use with web service functions that invoke the Bokeh module to construct a visualization, and a JavaScript function to smoothly transition the results of such a service into a web application.

@tangelo.plugin.bokeh.bokeh(plot_object)¶

Parameters:	plot_object (PlotObject) – A Bokeh PlotObject instance representing the plot to be displayed
Return type:	dict – A Python dict containing a div and a script for embedded the plot in a webpage

This decorator transforms the output of a web service that computes a Bokeh plot to a form that can be handled by the browser. It works by converting the plot object into the web components necessary to render it. When the decorator is used, an ajax call to the service results in a dict of two fields: script and div. If the div is embedded in the DOM, and the script after it so that it executes, the plot will appear in the page.

Rather than perform the task of setting up the div and script manually, the following JQuery widget, found in /plugin/bokeh/bokeh.js, can help:

$.bokeh(cfg)¶

Arguments:	string (cfg.url) – The URL of a web service returning a PlotObject

When invoked on a DOM element, the URL is retrieved; the expected data should be in the format described by :py:decorator:`tangelo.plugin.bokeh.bokeh` above. The DOM element then receives both the div and script content returned by the service, causing the interactive Bokeh plot to begin running in the target DOM element.

An example application can be found at /plugin/bokeh/examples/scatter/index.html.

Preparing the Stage¶

Tangelo will need to be running in order for the application to work. The quickstart instructions will be sufficient (see Quick Start):

tangelo

This should launch Tangelo on localhost, port 8080 (also known as http://localhost:8080/).

Next we need a place to put the files for the application. We will serve the application out of your home directory - recall that Tangelo serves user content from the tangelo_html subdirectory:

cd ~
mkdir tangelo_html
cd tangelo_html

It is a good practice to house each application in its own subdirectory - this keeps things organized, and allows for easy development of web applications in source control systems such as GitHub:

mkdir reverser
cd reverser

Supposing your user name is crusher, visiting http://localhost:8080/~crusher/reverser in a web browser should at this point show you a directory listing of no entries. Let’s fix that by creating some content.

HTML¶

The first step is to create a web page. In a text editor, open a file called index.html and copy in the following:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

<!DOCTYPE html>
<title>Reverser</title>

<!-- Boilerplate JavaScript -->
<script src=http://code.jquery.com/jquery-1.11.0.min.js></script>
<script src=/js/tangelo.js></script>

<!-- The app's JavaScript -->
<script src=myapp.js></script>

<!-- A form to submit the text -->
<h2>Reverser</h2>
<div class=form-inline>
    <input id=text type=text>
    <button id=go class="btn btn-class">Go</a>
</div>

<!-- A place to show the output -->
<div id=output></div>

This is a very simple page, containing a text field (with ID text), a button (ID go), and an empty div element (ID output). Feel free to reload the page in your browser to see if everything worked properly.

Next we need to attach some behaviors to these elements.

JavaScript¶

We want to be able to read the text from the input element, send it to the server, and do something with the result. We would like to do this whenever the “Go” button is clicked. The JavaScript to accomplish this follows - place this in a file named myapp.js (to reflect the script tag in line 9 of index.html):

1
2
3
4
5
6
7
8

$(function () {
    $("#go").click(function () {
        var text = $("#text").val();
        $.getJSON("myservice?text=" + encodeURIComponent(text), function (data) {
            $("#output").text(data.reversed);
        });
    });
});

Several things are happening in this short bit of code, so let’s examine them one by one. Line 1 simply makes use of the jQuery $() function, which takes a single argument: a function to invoke with no arguments when the page content is loaded and ready.

Line 2 uses the “CSS selector” variant of the $() function to select an element by ID - in this case, the “go” button - and attach a behavior to its “click” callback.

Line 3 - the first line of the function executed on button click - causes the contents of of the text input field to be read out into the variable text.

Line 4 uses the jQuery convenience function $.getJSON() to initiate an ajax request to the URL http://localhost:8080/~crusher/reverser/myservice, passing in the text field contents as a query argument. When the server has a response prepared, the function passed as the second argument to $.getJSON() will be called, with the response as the argument.

Line 5 makes use of this response data to place some text in the blank div. Because $.getJSON() converts the server response to a JSON object automatically, we can simply get the reversed word we are looking for in data.reversed. The output div in the webpage should now be displaying the reversed word.

The final component of this application is the server side processing itself, the service named myservice.

Python¶

The Python web service will perform a reversal of its input. The following Python code accomplishes this (save it in a file named myservice.py, again, to reflect the usage of that name in the myapp.js above):

def run(text=""):
    return {"reversed": text[::-1]}

This short Python function uses a terse array idiom to reverse the order of the letters in a string. Note that a string goes into this function from the client (i.e., the call to $.getJSON is line 4 of myapp.js), and a Python dict comes out. The dict is automatically converted to JSON-encoded text, which the $.getJSON() function automatically converts to a JavaScript object, which is finally passed to the anonymous function on line 4 of myapp.js.

Tying it All Together¶

The application is now complete. Once more refresh the page at http://localhost:8080/~crusher/reverser/, type in your favorite word, and click the “Go” button. If all goes well, you should see your favorite word, reversed, below the text input field!

Discussion¶

Of course, we did not need to bring the server into this particular example, since JavaScript is perfectly suited to reversing words should the need arise. However, this example was meant to demonstrate how the three pieces - content, dynamic clientside behavior, and serverside processing - come together to implement a full, working web application.

Now imagine that instead of reversing the word, you wanted to use the word as a search index in a database, or to direct the construction of a complex object, or to kick off a large, parallel processing job on a computation engine, or that you simply want to use some Python library that has no equivalent in the JavaScript world. Each of these cases represents some action that is difficult or impossible to achieve using clientside JavaScript. By writing Tangelo web services you can enrich your application by bringing in the versatility and power of Python and its libraries.

Indentation¶

Indentation is used to provide visual cues about the syntactic scope containing particular line of code. Good indentation practice dramaticaly improves code readability.

Four-space indentation. Each additional indentation level shall be exactly four spaces.

Indentation policy. The following structures shall require incrementing the indentation level:

Statements belonging to any block.

Chained function calls:

obj.call1()
    .call2()
    .call3();

Properties in a literal object:

obj = {
    prop1: 10,
    prop2: 3
};

Curly bracket placement. The left curly bracket that introduces a new indentation level shall appear at the end of the line that uses it; the right curly bracket that delimits the indented statements shall appear on the line following the last indented statement, at the decremented indentation:

[some statement...] {
                    ^
    .
    .
    .
}
^

Naming¶

Use camelCase for visualization, property, method, and local variable names.

Curly brackets¶

JavaScript uses curly brackets to delimit blocks. Blocks are required by the language when functions are defined. They are also required for executing more than one statement within control flow constructs such as if and while. While the option exists not to use curly brackets for a single statement in such cases, that practice can lead to errors (when, e.g., a new feature requires the single statement to be replaced by several statements).

Always use blocks in control flow statements. Every use of control flow operators (if, while, do) shall use curly brackets for its associated statement block, even if only a single statement appears therein.

Space placement¶

Parentheses are required in several places in JavaScript. Proper space placement can help make such constructs more readable.

Keyword-condition separation. A single space shall appear in the following situations.

Between a control-flow operator and its parenthesized condition:

if (condition...) {
  ^

Between a parenthesized condition and its following curly bracket:

if (condition...) {
                 ^

Between a function argument list and its following curly bracket:

function foobar(x, y, z) {
                        ^

Between the function keyword and the argument list, in anonymous functions:

f = function (a, b) {
            ^

After every comma.

On either side of a binary operator:

x = 3 + 4;
     ^ ^

Extraneous spaces. The last character in any given line shall not be a space.

Blank lines. Blank lines should be used to set apart sequences of statements that logically belong together.

Chained if/else-if/else statements¶

A common programming pattern is to test a sequence of conditions, selecting a single action to take when one of them is satisfied. In JavaScript, this is accomplished with an if block followed by a number of else if blocks, followed by an else block. try catch blocks have a similar syntax.

Single line else if, else, and catch. The else if, else, and catch keyword phrases shall appear on a single line, with a right curly bracket on their left and a left curly bracket on their right:

if (condition) {
    action();
} else if {
    other_action();
} else {
    default_action();
}

new Array and new Object¶

The new keyword is problematic in JavaScript. If it is omitted by mistake, the code will run without error, but will not do the right thing. Furthermore, built in constructors like Array and Object can be reimplemented by other code.

Use [] and {}. All construction of arrays and objects shall use the literal [] and {} syntax. The sequence of statements x = [];, then x.length = N; shall replace new Array(N).

JSLint directives¶

JSLint reads two special comments appearing at the top of files it is working on. The first appears in the following form:

/*jslint browser: true */

and specifies options to JSLint. Because Tangelo is a web project, every JavaScript file should have the comment that appears above as the first line. The other recognized directive in the global name list:

/*globals d3, $, FileReader */

This directive prevents JSLint from complaining that the listed names are global variables, or undefined. It is meant for valid names, such as standard library objects or linked libraries used in the file.

Lexical scopes¶

JavaScript has only two scope levels: global and function. In particular, blocks following, e.g., for and if statements do not introduce an inner scope. Despite this fact, JavaScript allows for variables to be declared within such blocks, causing seasoned C and C++ programmers to assume something false about the lifetime of such variables.

Single var declaration. Every function shall contain a single var declaration as its first statement, which shall list every local variable used by that function, listed one per line.

function foobar(){
    var width,
        height,
        i;
    .
    .
    .
}

This declaration statement shall not include any initializers (this promotes clearer coding, as the “initializers” can be moved below the declaration, and each one can retain its own comment to explain the initialization).

Global variables. Global variables shall not be used, unless as a namespace-like container for variables and names that would otherwise have to be global. When such namespace-like containers are used in a JavaScript file, they shall appear in the JSLint global name specifier.

Strict Mode¶

JavaScript has a “strict mode” that disallows certain actions technically allowed by the language. These are such things as using variables before they are defined, etc. It can be enabled by including "use strict"; as the first statement in any function:

function foobaz() {
    "use strict";

    .
    .
    .
}

Strict mode functions. All functions shall be written to use strict mode.

Basic Options¶

• data - The data associated with the visualization, normally an array.
• width, height - The width and height of the visualization, in pixels. If omitted, the visualization should resize to fit the DOM element.

Visualization Mapping Options¶

The following options are optional, but if your visualization is able to map data element properties to visual attributes like size, color, and label, you should use this standard naming convention. If you have multiple sets of visual elements (such as nodes and links in a graph), prefix these attributes as appropriate (e.g. nodeSize, nodeStrokeWidth).

• size - The size of the visual element as a number of pixels. For example, if drawing a square for each data element, the squares should have sizes equal to the square-root of what the size option returns for each data element.
• color - The main color of the visual element, specified as a CSS color string.
• symbol - The symbol to use for the visual element. This should use D3’s standard set of symbol names.
• label - The label for the visual element (a string).
• stroke - The color of the stroke (outline) of the visual element specified in pixels.
• strokeWidth - The width of the stroke of the visual element in pixels.
• opacity - The opacity of the entire visual element, as a number between 0 to 1.

AccessorSpec¶

Each visual mapping should take an AccessorSpec for a value. Accessor specifications work much like DataRef specs do in Vega, though they also allow programmatic ways to generate arbitrary accessors and scales.

• function (d) { ... } - The most general purpose way to generate a visual mapping. The argument is the data element and the return value is the value for the visual property.
• {value: v} - Sets the visual property to the same constant value v for all data elements.
• {index: true} - Evaluates to the index of the data item within its array.
• {field: "dot.separated.name"} - Retrieves the specified field or subfield from the data element and passes it through the visualization’s default scale for that visual property. Unlike Vega, fields from the original data do not need to be prefixed by "data.". The special field name "." refers to the entire data element.
• {field: "dot.separated.name", scale: ScaleSpec} - Overrides the default scale using a scale specification. Set scale to tangelo.identity to use a field directly as the visual property.
• {} - The undefined accessor. This is a function that, if called, throws an exception. The function also has a property undefined set to true. This is meant as a stand-in for the case when an accessor must be assigned but there is no clear choice for a default. It is also used when creating Tangelo jQuery widgets to mark a property as being an accessor. Calling tangelo.accessor() with no arguments also results in an undefined accessor being created and returned.

ScaleSpec¶

A scale specification defines how to map data properties to visual properties. For example, if you want to color your visual elements using a data field continent containing values such as North America, Europe, Asia, etc. you will need a scale that maps North America to "blue", Europe to "green", etc. Vega has a number of built-in named scales that together define the ScaleSpec. In Tangelo, a ScaleSpec may also be an arbitrary function.