SoftwareDefinedBuildings/upmu-plotter

Name: upmu-plotter

Owner: Software Defined Buildings

Description: null

Created: 2014-08-11 15:56:19.0

Updated: 2015-04-19 18:05:44.0

Pushed: 2015-09-02 01:38:57.0

Homepage: null

Size: 1484

Language: JavaScript

GitHub Committers

UserMost Recent Commit# Commits

Other Committers

UserEmailMost Recent Commit# Commits

README

s3ui package

The “upmu-plotter” repository contains the “s3ui” package along with an example of how to use it.

The “s3ui” package defines the “s3plot” template, which contains a graphing utility that can be included in a Meteor application. Multiple instances of “s3plot” can be inserted into the same web page and will act independently of one another.

Instantiating a Graph

To insert a graph with full control available to the user, simply use the inclusion operator:

{{> s3plot}}

One can also instantiate the graph with paremeters, by wrapping the inclusion operator in a data context:

{{#with somecontext}}
    {{> s3plot}}
{{/with}}

If “somecontext” is an array (or array-like object) with an object at index 0, a function at index 1, and a function at index 2, the object at index 0 is interpreted as specifying parameters and the functions at indices 1 and 2 are interpreted as callback functions.

The object of parameters may have the following properties (all optional):

When the graph has been displayed, but before any interactivity is added, the first callback function is invoked with a single argument, namely the template instance. The callback function is the mechanism through which the template instance is made available. The template instance can be used to programmatically change the settings (useful when settings have been hidden from the user but still need to be manipulated) and even change some of the parameters the graph was instantiated with (see below). The first callback function can also be used to make simple changes to the DOM allowing for a customized layout.

The second callback function is called when the tree of streams is initialized, not fully loaded. Here, streams and settings can be selected programmatically.

The defaults for the callbacks are included in the global s3ui object as s3ui.default_cb1 and s3ui.default_cb2. The default first callback makes the left column in the default layout resizable. The default second callback reads the page's URL and executes a permalink if present. These callback functions can be overriden by instantiating the graph with different functions. If one desires to use options (see above) but keep the callback functions the same, one can simply put s3ui.default_cb1 and s3ui.default_cb2 into the array. One can also do a partial override, i.e. use a function that calls the default callback and does additional work.

Custom Layouts

Simply including the s3plot template provides a default layout, and the first callback function allows for simple layout changes (see above). But for more advanced layouts it may be easier to write the layout in HTML. Rather than including the s3plot template, one can create a custom template describing the preferred layout and call the s3ui.__init__ function on the template instance (the implicit parameter “this”) in Meteor's “rendered” callback.

To make creating the HTML layout easier, several sub-templates are included. They are:

These templates can be included in the custom template. But if you want a higher degree of customization, you can write your own template components from scratch (though be aware that the relative positioning of the components of the stream and axis legends may be necessary for the correctness of the graph). If you do not want all of the features of the graph, you must still include all of the components; use the appropriate parameters on instantiation to hide the components you do not need (see above).

As a rule of thumb, any element in the “s3plot” template that has a class not provided by Bootstrap contributes to the functioning of the graph in some way.

Programmatically Changing the Graph

The “idata” property of the template instance is an object that stores the instance fields of the object (i.e., the variables used by the graph to keep track of its internal state). The “imethods” property of the template instance contains bound methods that can be used to programmatically manipulate the state of the graph.

The bound methods provided are:

Permalinks

The permalink feature allows one to save the state of the graph and load it later using a generated permalink. To generate a permalink, click the “Generate Permalink” button on the graph UI.

If you would prefer to generate a permalink programmatically by specifying the settings of the graph rather than by creating the graph by hand, you should instead send a POST request to {domain}/s3ui_permalink. The payload of the POST request should be of the form

permalink_data={JSON}

where data specifying the settings of the graph are specified in {JSON}.

The permalink API allows three methods for specifying a permalink. A permalink may be specified as “fixed”, meaning that the start and end times are specified in the number of nanoseconds since the UNIX epoch (Jan 1, 1970, UTC). A permalink of type “now” always ends at the time the permalink is executed, and starts a fixed number of nanoseconds before that. Finally, a permalink of type “last” always ends at the last data point of the streams being displayed, and starts a fixed number of nanoseconds before that.

In order that the graph be displayed correctly, the final start and end times must be in the current UNIX epoch (i.e., Jan 01, 1970, UTC or later).

For the permalink, the following fields may be specified in the JSON object:

The axis objects require the following fields:

The objects specifying streams may have the following fields:

Below is an example of permalink data that uses a fixed window:

{
    "autoupdate" : true,
    "axes" : [
        {
            "axisname" : "y1", 
            "streams" : [
                "49129d4a-335e-4c81-a8a4-27f5d8c45646"
            ],
            "scale" : [
                -1,
                1
            ],
            "rightside" : false
        },
        {
            "axisname" : "y2",
            "streams" : [
                "571ce598-3ffd-499b-be6c-0df52e597c93"
            ],
            "scale" : [
                -2,
                2
            ],
            "rightside" : null
        }
    ],
    "end" : 1408234686223000000,
    "resetEnd" : 1408746931000000000,
    "resetStart" : 1377210944000000000,
    "start" : 1408234676466000000,
    "streams" : [
        {
            "stream" : "49129d4a-335e-4c81-a8a4-27f5d8c45646",
            "color" : "#000000"
        },
        {
            "stream" : "571ce598-3ffd-499b-be6c-0df52e597c93",
            "color" : "#0000FF"
        }
    ],
    "tz" : "America/Los_Angeles"
}

Below is an example of permalink data that uses a window of type “now” (a window of type “last” would be very similar):

{
    "autoupdate" : true,
    "axes" : [
        {
            "axisname" : "y1", 
            "streams" : [
                "49129d4a-335e-4c81-a8a4-27f5d8c45646"
            ],
            "scale" : [
                -1,
                1
            ],
            "rightside" : false
        },
        {
            "axisname" : "y2",
            "streams" : [
                "571ce598-3ffd-499b-be6c-0df52e597c93"
            ],
            "scale" : [
                -2,
                2
            ],
            "rightside" : null
        }
    ],
    "window_type" : "now",
    "window_width" : 60000000000,
    "resetEnd" : 1408746931000000000,
    "resetStart" : 1377210944000000000,
    "streams" : [
        {
            "stream" : "49129d4a-335e-4c81-a8a4-27f5d8c45646",
            "color" : "#000000"
        },
        {
            "stream" : "571ce598-3ffd-499b-be6c-0df52e597c93",
            "color" : "#0000FF"
        }
    ],
    "tz" : "America/Los_Angeles"
}
Restricting Stream Access

It is possible to restrict streams to be visible only by certain users. The is place is as follows: an account system is set up via Meteor's login system. In each user document is a field called “s3ui_tags”, which contains a list of tags corresponding to each user. Each tag is a token that represents certain streams. When the program requests stream metadata to build the stream tree, it sends the current user's tags along with the request. The program that returns the metadata is responsible for interpreting the tags and only revealing information about streams visible to users with those tags.

The s3ui package does not do any of the setup work to use Meteor's accounts system; doing so would preclude use of Meteor's accounts system for the s3ui plot in conjunction with other features.

That said, an example of an appropriate configuration may be found in the “lib” and “server” directories of the “upmuplot” Meteor project. The files here set up the user information to be read from the “server/account_list.json” file. The “users_to_add” property contains an object mapping usernames to objects containing the “password” in plaintext and “s3ui_tags” as an array of strings. The “users” property contains information about existing users; here, the password is not stored in plaintext. When Meteor, as configured in this repository, starts, it moves the users in “users_to_add” to “users”, hashing the passwords as appropriate, and updates Meteor's internal database of users according to changes made in the file.

Similarly, an example of a program to serve metadata requests is found in the python folder of this package (“metadata.py”). It reads the tag definitions from a file passed in as a command line argument (such as “tagconfig.json”). The file is expected to be a JSON document mapping each tag to an array of strings, each of which represents a prefix of paths of streams corresponding to that tag.

Examples of the two configuration files can be found in the appropriate directories of this repository. Once again, using these example programs to restrict stream access is by no means required; you may use any method you wish to add users to the Meteor.users repository as long as the “s3ui_tags” field in each user document is correct, you can interpret the tags to find out the streams they refer to in any way you want, and you can even choose to not restrict stream access at all.

If a user logs in or out while streams are selected, the plotting application will maintain the streams being plotted as far as possible, ensuring that the new user is still authorized to see those streams.

This work is supported by the National Institutes of Health's National Center for Advancing Translational Sciences, Grant Number U24TR002306. This work is solely the responsibility of the creators and does not necessarily represent the official views of the National Institutes of Health.