LocusZoom is a Javascript/d3 embeddable plugin for interactively visualizing statistical genetic data from customizable sources.
See API Reference if already up and running or the introduction below.
The page you build that embeds the LocusZoom plugin must include the following resources:
-
locuszoom.vendor.min.js
This file contains the concatenated vendor libraries. You can alternatively include d3 and Q from other sources, so long as they are included before including LocusZoom files. -
locuszoom.app.jsORlocuszoom.app.min.js
This is the primary application logic. It should only be included after the vendor dependencies have been included. -
locuszoom.css
This is the primary stylesheet. It is namespaced so as not to conflict with any other styles defined on the same page.
Creating a LocusZoom plot requires only one initialization value: Data Sources. This is an objects that describes where data comes from and how to get it. Defining Data Sources can be done as follows:
var datasource = (new LocusZoom.DataSources()).addSource("base",["AssociationLZ", "http://myapi.com/"]);Presently only HTTP/S endpoints are supported for data sources. See Issue #38 for discussion on adding support for local file data sources.
With includes included and data sources defined LocusZoom.populate() will accept a CSS selectors string to populate the first matching element with a plot.
This basic example, with a functioning data source, would generate a page with the default LocusZoom layout:
<html>
<head>
<script src="locuszoom.vendor.min.js" type="text/javascript"></script>
<script src="locuszoom.app.js" type="text/javascript"></script>
<link rel="stylesheet" type="text/css" href="locuszoom.css"/>
</head>
<body>
<div id="plot"></div>
<script type="text/javascript">
var datasource = (new LocusZoom.DataSources()).addSource("base",["AssociationLZ", "http://myapi.com/"]);
var plot = LocusZoom.populate("#plot", datasource);
</script>
</body>
</html>A Layout is a serializable JSON object that describes how a LocusZoom plot will present data. This includes things like chart types and colors, dimensions for visual elements and regions of the plot, etc.
If not supplied, a built-in DefaultLayout will be used. Any layout supplied will be merged with the DefaultLayout, so tweaking the default plot is as easy as only describing the values to change. For instance, to get a default plot with specific dimensions:
var layout = { width: 1024, height: 768 };
var plot = LocusZoom.populate("#plot", datasource, layout); A State is a serializable JSON object that describes orientation to specific data from data sources, and specific interactions with the layout. This can include a specific query against various data sources or pre-selecting specific elements. Essentially, the State object is what tracks these types of user input under the hood in LocusZoom, and it can be predefined at initialization.
var state = { chr: 6, start: 20379709, end: 20979709 };
var plot = LocusZoom.populate("#plot", datasource, layout, state); Refer to demo.html to see a more sophisticated example of how to embed LocusZoom into a page, including adding other HTML elements to provide interactivity.
You can also describe the locus query aspect of the State (chromosome, start, and end position) using a data-region attribute of the continaing element before populating it, like so:
<div id="foo" data-region="10:114550452-115067678"></div>LocusZoom.populate() will only populate the first matching HTML element for the provided selector string. To populate all matching elements for a single selector string use LocusZoom.populateAll() like so:
<div class="plot" id="plot_1"></div>
<div class="plot" id="plot_2"></div>
<div class="plot" id="plot_3"></div>
<script type="text/javascript">
var datasource = (new LocusZoom.DataSources()).addSource("base",["AssociationLZ", "http://myapi.com/"]);
var lz[] = LocusZoom.populateAll(".plot", datasource);
</script>LocusZoom is an entirely client-side application designed to plug into arbitrary data sets, be they local files, APIs, or something else entirely. It has the following vendor dependencies:
NOTE: should.min.js appears in the vendor source directory along with source files for d3 and Q, but should is only required in this way for the automated testing suite. It is not included in the final build.
The application is built using Gulp. Gulp and all necessary Gulp plug-ins can be installed for this project using npm and the following commands:
$ npm install gulp gulp-util gulp-watch gulp-concat gulp-uglify gulp-mocha gulp-sass gulp-wrap yargs
$ npm install mocha should jsdom mocha-jsdom
Once complete run or gulp from the top of the application directory to run all tests and build the following files:
locuszoom.app.js- A concatenated app file suitable for use in developmentlocuszoom.app.min.js- A concatenated and minified app file suitable for use in productionlocuszoom.vendor.min.js- A concatenated vendor file suitable for use as a single vendor include in either development or production (contains d3 and Q)locuszoom.css- A generated CSS file for all LocusZoom styles
gulp watch- Watch for any changes to app .js, .scss, or test source files to trigger another full buildgulp test- Just run the testsgulp js- Build app and vendor js files (runs tests and aborts if tests fail)gulp app_js- Build app js files (runs tests and aborts if tests fail)gulp vendor_js- Build vendor js filegulp css- Build CSS file
Append --force to the end of any gulp command that runs the automated testing suite to force the creation of locuszoom.app.js and locuszoom.app.min.js even when the tests fail. This can be useful during active development as sometimes debugging can be led from either the output of automated tests or inspection of an active plugin.
This flag is particularly useful with the watch command:
$ gulp watch --force
The above command with enter forced-watch-mode, which will detect any changes to app .js or .scss files, as well as test files, and run a new build. If errors are encountered in the tests they will be reported, but locuszoom.app.js and locuszoom.app.min.js will still be generated and gulp will not exit but return to watch mode. This is an effective way to have automatic continuous builds while developing both the application and its tests.
LocusZoom uses Mocha for unit testing. Tests are located in the test subdirectory, with a one-to-one mapping of test files to app files.
Note that the plugins used by gulp in this project require Node.js version 4.x or higher.
All app-specific javascript files should be developed in strict mode. LocusZoom is also linted using ESLint, the rules for which can be found in .eslintrc.