Plotting Data

Once you have a server, you can use it to create visualizations. Here we describe the three most common ways: directly from the server, from a client library, or from the REST API.

From the server

Navigate to your lightning host, and create a new session. Then, click “create visualization”

Select the “line” type, and enter {"series": [1, 1, 2, 3, 5, 8]}. NOTE: the data must be a properly formed JSON object.

Submit the form and you should see a line plot of that data.

To create a choropleth map, select “map” type and enter {"regions": ["MI", "NY", "NM"], "values": [0.6, 0.3, 0.2]}. This should create a map of the United States showing Michigan, New York, and New Mexico filled in at different color scales.

From a client

The client libraries make it easy to generate visualizations straight your favorite data analysis environment, including from within interactive notebooks. This is the most common way to generate visualizations.

We'll walk through an example using the Python client, see the section on clients read about the other client libraries.

To install the Python client from PyPi, just call

$ pip install lightning-python

Then, in Python, import the library and instantiate a lightning object:

from lightning import Lightning
lgn = Lightning()

By default the client assumes that the host is at http://localhost:3000; if you want to use a remote server pass it in during instantiation, as in

lgn = Lightning(host='')


lgn = Lightning(host='')

Once you have instantiated the lightning object, try generating a line plot

viz = lgn.line([1, 1, 2, 3, 5, 8])

and a line plot should be displayed in your browser.

To read more about the Python client see the clients page, or visit the client documentation.

Using the REST API

It's also possible to generate visualizations directly using Lightning's REST API.

First create a session to post visualizations to:

curl http://localhost:3000/sessions \
  -d name="my session"

This will return a response including a JSON representation of the session you've just created. e.g.

    "name":"my session",

Then create a visualization using the returned id of the session:

curl http://localhost:3000/sessions/06a214f3-6de2-46d3-9a8a-ec5764c481ff \
  -d type="line" \
  -d data='{"series": [1, 2, 3, 4, 5]}'

Sharing visualizations

Lightning makes it easy to share your visualizations with others.


The easiest place to find all of these links is through the "Actions" menu in the web interface, however most of the API clients also expose convenience methods to quickly retrieve them.

NOTE - the actions menu on the public server offers a limited set of options because of security implications. To access all options run your own server.

For example, the following shows how to access these links through the python client:

Each visualization can also display a custom markdown description field. This can be edited directly through the web interface or via an api client. Here is an example using the public server and the python client:

which produces


Lightning provides permalinks for each visualization that can easily be embedded on other sites (particularly these are meant to be embedded using iframes).

To embed a visualization, use the url format


To determine the ID of the visualization, navigate to the visualization’s permalink and inspect the URL, or if using python

viz = lgn.line([1,1,2,3,5,8])

Then embed the visualization in your own webpage with

<iframe src=”http://host/visualizations/vid/iframe” width="N PIXELS" height="N PIXELS" >

making sure to replace host and vid with the proper values.

For example:

is produced by the following

<iframe src="" width="300" height="300" >


If you prefer to use pym.js we offer an endpoint for that as well:


the child script is automatically initialized, so you only have to worry about setting up the parent.

For example:

Importing Custom Visualization Types

Use the web interface to import custom visualizations. Custom visualizations are installed via npm, you simply need to know the name of the module that you want to import. To search for available modules use this link to find npm modules tagged with "lightning-visualization"

Plotting a custom visualization from the API client

Creating a visualization with this new custom type is similar to creating any other type of plot.

from lightning import Lightning
from numpy import random
lgn = Lightning()

data = random.random(100)

# typical plot

# custom plot
lgn.plot(data, type='my-custom-lightning-viz')

Developing Custom Visualization Types

In addition to Lightning’s core visualization types, users can easily develop their own plots, either by modifying the existing ones, or designing visualizations from scratch. This section serves as a walkthrough to create a custom visualization. At their core custom visualizations are simply npm modules conforming to a certain specifications.

To facilitate the development of these modules, we provide a yeoman generator. The generator can be found on github here. To install the generator run the following commands (must have node installed):

$ [sudo] npm install -g yo # install yeoman
$ [sudo] npm install -g generator-lightning-viz

After installing the generator you can use it to scaffold out a custom visualization:

$ mkdir my-custom-lightning-viz
$ cd my-custom-lightning-viz
$ yo lightning-viz

The yo lightning-viz command tells yeoman to build out the skeleton of a lightning visualization in the current directory. You should now have a folder with the following structure:

You'll notice the following components:

  • README- contains info about your visualization
  • data/- a special folder for including sample datasets and a thumbnail image of the visualization
  • index.js- the javascript entry point, you shouldn't need to touch this file
  • package.json- the npm specification for your package. If the visualization has any external dependencies, e.g. d3.js they should be listed here.
  • src/- the folder with the source code. View the index.js file here to start editing the visualization.


This is the main file for your visualization. (note: because this is simply an npm module you are free to structure the files however you like, just make sure that the module exports a LightningVisualization object):

var LightningVisualization = require('lightning-visualization');
var _ = require('lodash');

 * Uncomment this code to require an optional stylesheet
// var fs = require('fs');
// var styles = fs.readFileSync(__dirname + '/styles/style.css');

 * Extend the base visualization object
var Visualization = LightningVisualization.extend({
    getDefaultOptions: function() {
         * If the visualization takes options provide sensible
         * defaults here.
        return {
    init: function() {
         * FILL IN Add any logic for initializing the visualization
         * the following are available:
         * this.width - visualization container width
         * this.height - visualization container height
         * this.el - visualization container dom node
         * - visualization data (that has been passed through the formatData function)
         * this.options - options that have been passed to the visualization
     * optionally pass a string of CSS styles 
    // styles: styles,
    render: function() {
         * FILL IN Render the visualization
         * FILL IN Get data / selector from and this.selector
    formatData: function(data) {
         * Format your data from a raw JSON blob
        return data;
    updateData: function(formattedData) { = formattedData;
         * FILL IN Re-render your visualization
    appendData: function(formattedData) {    
         * FILL IN Update to include the newly formatted data
         * FILL IN Re-render the visualization

module.exports = Visualization;

Adding external dependencies

To include a dependency on a third party library (e.g. d3.js, react, etc.) you can install them via npm. Note that the visualizations are compiled via browserify, so any 3rd party library must be browserify compatible.

To install and save a dependency simultaneously, use the following command inside the top level of your custom viz folder:

$ npm install --save 

This library can now be required in your javascript code. To learn more about browserify visit

Developing and testing locally

To test a custom visualization locally, you must first notify npm that it is available on your filesystem. To do this run:

$ npm link .

from inside the root of your custom viz folder:

The visualization can imported or previewed in lightning. Use the "preview" option while developing to see changes:

Once you are happy with the visualization import it into lightning. You can then start plotting data with this visualization type.

Sharing your code with others

To allow others to use your visualization, publish it to npm. First make sure that you are logged in to your npm account (the same command can also be used to create an account):

$ npm adduser

Then create a tag with a new version number. NPM has a tool to do this automatically:

$ npm version patch # options are major, minor, or patch

The major|minor|patch options correspond to X.Y.Z in the semantic versioning system. Your package starts at 0.0.0 so e.g. a major version bump would be 1.0.0 but a patch version bump would be 0.0.1. This version number is stored in the package.json file.

Then push the change to git and publish to npm

$ git push origin master --tags # only do this if you are using git for version control 
$ npm publish .

That's it!