Merge branch 'release/0.13.0'

.eslintignore

@@ -5,7 +5,7 @@ dist/
 docs/
 jsdoc/
 node_modules/
-staticdata/
+examples/data/
 package.json
 
 # ESLint seems to ignore env overrides on single files (for the es6 parser) in same directory

.github/workflows/node.yml

@@ -22,7 +22,7 @@ jobs:
     steps:
     - uses: actions/checkout@v2
     - name: Use Node.js ${{ matrix.node-version }}
-      uses: actions/setup-node@v1
+      uses: actions/setup-node@v2
       with:
         node-version: ${{ matrix.node-version }}
     - name: Cache Node.js modules

README.md

@@ -1,14 +1,12 @@
 # LocusZoom
 
-LocusZoom is a Javascript/d3 embeddable plugin for interactively visualizing statistical genetic data from customizable
- sources.
+LocusZoom is a Javascript/d3 embeddable plugin for interactively visualizing statistical genetic data from customizable sources.
 
 ![Build Status](https://github.com/statgen/locuszoom/workflows/Unit%20tests/badge.svg?branch=develop)
 
 See [github.com/statgen/locuszoom/wiki](https://github.com/statgen/locuszoom/wiki) for full documentation and API reference.
 
-To see functional examples of plots generated with LocusZoom.js see [statgen.github.io/locuszoom](http://statgen.github.io/locuszoom/) 
-and [statgen.github.io/locuszoom/#examples](http://statgen.github.io/locuszoom/#examples).
+To see functional examples of plots generated with LocusZoom.js see [statgen.github.io/locuszoom](http://statgen.github.io/locuszoom/) and [statgen.github.io/locuszoom/#examples](http://statgen.github.io/locuszoom/#examples).
 
 ![LocusZoom.js Standard Association Plot](http://statgen.github.io/locuszoom/wiki_images/locuszoom_standard_association_plot_0.5.2.png)
 
@@ -27,42 +25,42 @@ The page you build that embeds the LocusZoom plugin must include the following r
 * `locuszoom.css`  
   This is the primary stylesheet. It is namespaced so as not to conflict with any other styles defined on the same page.
 
-Instead of copying the files to your project, we recommend using CDN links are for these resources (see [statgen.github.io/locuszoom/](http://statgen.github.io/locuszoom/)).
+Instead of copying the files to your project, **we recommend using CDN links are for these resources** (see [statgen.github.io/locuszoom/](http://statgen.github.io/locuszoom/)).
 
-*The above instructions describe using LocusZoom with pure JS and HTML. If you are using a module build system, LocusZoom supports usage via ES6 imports, eg `import LocusZoom from 'locuszoom';` and `import 'locuszoom/dist/locuszoom.css';`* 
+*The above instructions describe using LocusZoom with pure JS and HTML. If you are using a module build system, LocusZoom supports usage via ES6 imports, eg:* 
+
+```javascript
+import LocusZoom from 'locuszoom';
+import 'locuszoom/dist/locuszoom.css';
+```` 
 
 ### 2. Define Data Sources
 
-**Data Sources** is an object representing a collection of arbitrarily many sources from which data for the plot can 
-be requested. When adding sources to the collection they must be namespaced so that retrieving specific fields can be 
-done with respect to specific data sources.
+**Data Sources** is an object representing a collection of arbitrarily many sources from which data for the plot can be requested. When adding sources to the collection they must be namespaced so that retrieving specific fields can be done with respect to specific data sources.
 
 Here's an example of defining a data sources object for a remote API:
 
 ```javascript
 var data_sources = new LocusZoom.DataSources();
-data_sources.add("trait", ["AssociationLZ", { url: "http://server.com/api/", params: {source: 1} }]);
+data_sources.add("assoc", ["AssociationLZ", { url: "http://server.com/api/", params: {source: 1} }]);
 ```
 
-The above example adds an "AssociationLZ" data source (a predefined data source designed to make requests for 
-association data) with a defined URL. The namespace for this data source is "trait".
+The above example adds an "AssociationLZ" data source (a predefined data source designed to make requests for association data) with a defined URL. The namespace for this data source is "assoc".
 
 Data sources can also be local files:
 
 ```javascript
 data_sources = new LocusZoom.DataSources();
-data_sources.add("trait", ["AssociationLZ", { url: "file:///path/to/data.json" }]);
+data_sources.add("assoc", ["AssociationLZ", { url: "file:///path/to/data.json" }]);
 ```
 
-Refer to the [Data Sources Documentation](https://github.com/statgen/locuszoom/wiki/Data-Sources) for more information 
-on using predefined data sources or extending/creating custom data sources.
+Refer to the [Working with data guide](https://statgen.github.io/locuszoom/docs/guides/data_retrieval.html) for more information on using predefined data sources or extending/creating custom data sources.
 
 ### 3. Define a Layout
 
-**Layout** is a serializable object that describes the configuration of the LocusZoom plot, including what data will be
- pulled from the data sources and displayed in what way, along with visual characteristics like color and geometry.
+**Layout** is a serializable object that describes the configuration of the LocusZoom plot, including what data will be pulled from the data sources and displayed in what way, along with visual characteristics like color and geometry.
 
-A layout definition may look something like this:
+A layout definition may look something like this (simplified example; consult docs for details):
 
 ```javascript
 var layout = {
@@ -75,27 +73,23 @@ var layout = {
          {
            id: "association",
            type: "scatter",
-           fields: ["trait:position", "trait:pvalue"],
-           x_axis: { field: "trait:position" },
-           y_axis: { field: "trait:pvalue" }
+           fields: ["assoc:position", "assoc:pvalue"],
+           x_axis: { field: "assoc:position" },
+           y_axis: { field: "assoc:pvalue" }
          }
       ]
     }
   ]
 };
 ```
 
-The above example defines a basic plot that is 500 pixels on a side and has one panel with one scatter plot data layer
- that pulls in position and pvalue from the "trait" data source, mapping position to the x axis and pvalue to the y axis.
+The above example defines a basic plot that is 500 pixels on a side and has one panel with one scatter plot data layer that pulls in position and pvalue from the "trait" data source, mapping position to the x axis and pvalue to the y axis.
 
-The LocusZoom.js library provides several pre-defined layouts for entire plots and subdivisions of plots such as panels,
- data layers, tool tips, etc. Refer to the [Layout Documentation](https://github.com/statgen/locuszoom/wiki/Layout) 
- for more information.
+The LocusZoom.js library provides several pre-defined layouts for entire plots and subdivisions of plots such as panels, data layers, tool tips, etc. Refer to the [Layouts and visualization options guide](https://statgen.github.io/locuszoom/guides/rendering_layouts.html) for more information.
 
 ### 4. Put it Together with `LocusZoom.populate()`
 
-With includes included, data sources defined, and a layout defined, `LocusZoom.populate()` will accept a CSS selector 
-string to populate the first matching element with a plot.
+With includes included, data sources defined, and a layout defined, `LocusZoom.populate()` will accept a CSS selector string to populate the first matching element with a plot.
 
 A basic example may then look like this:
 
@@ -109,26 +103,26 @@ A basic example may then look like this:
     <div id="plot"></div>
     <script type="text/javascript">
       var data_sources = new LocusZoom.DataSources();
-      data_sources.add("trait", ["AssociationLZ", { url: "https://server.com/api/single/", params: {source: 1} }]);
+      data_sources.add("assoc", ["AssociationLZ", { url: "https://server.com/api/single/", params: {source: 1} }]);
       var layout = {
         width: 500,
-        height: 500,
         panels: [
           {
             id : "association",
+            height: 500,
             data_layers: [
               {
                 id: "association",
                 type: "scatter",
-                fields: ["trait:position", "trait:pvalue"],
-                x_axis: { field: "trait:position" },
-                y_axis: { field: "trait:pvalue" }
+                fields: ["assoc:position", "assoc:pvalue"],
+                x_axis: { field: "assoc:position" },
+                y_axis: { field: "assoc:pvalue" }
               }
             ]
           }
         ]
       };
-      var plot = LocusZoom.populate("#plot", data_sources, layout);
+      var plot = LocusZoom.populate("#lz-plot", data_sources, layout);
     </script>
   </body>
 </html>
@@ -138,41 +132,41 @@ A basic example may then look like this:
 
 #### Use a Predefined Layout
 
-The core LocusZoom library comes equipped with several predefined layouts, organized by type ("plot", "panel", 
-"data_layer", and "toolbar"). You can see what layouts are predefined by reading the contents of 
-`assets/js/app/Layouts.js` or in the browser by entering `LocusZoom.Layouts.list()` (or to list one specific type: 
-`LocusZoom.Layouts.list(type)`).
+The core LocusZoom library comes equipped with several predefined layouts, organized by type ("plot", "panel", "data_layer", and "toolbar"). You can see what layouts are predefined by reading the contents of `assets/js/app/Layouts.js` or in the browser by entering `LocusZoom.Layouts.list()` (or to list one specific type: `LocusZoom.Layouts.list(type)`).
 
 Get any predefined layout by type and name using `LocusZoom.Layouts.get(type, name)`.
+
+If your data matches the field names and formats of the [UMich PortalDev API](https://portaldev.sph.umich.edu/docs/api/v1/#overview-of-api-endpoints), these layouts will provide a quick way to get started. If your data obeys different format rules, customization may be necessary.
   
+See the [guide to working with layouts](https://statgen.github.io/locuszoom/docs/guides/rendering_layouts.html) for further details.
+
 #### Build a Layout Using Some Predefined Pieces
 
 `LocusZoom.Layouts.get(type, name)` can also be used to pull predefined layouts of smaller pieces, like data layers or 
 toolbars, into a custom layout:
 
 ```javascript
-var layout = {
+const layout = {
   width: 1000,
   height: 500,
   panels: [
-    LocusZoom.Layouts.get("panel","gwas"),
+    LocusZoom.Layouts.get("panel", "gwas"),
     {
       id: "custom_panel",
-      ...
+      ...options
     },
-    LocusZoom.Layouts.get("panel","genes")
-  ]
+    LocusZoom.Layouts.get("panel", "genes")
+  ],
   ...
 };
 ```
 
 #### Modify a Predefined Layout
 
-The `get()` function also accepts a partial layout to be merged with the predefined layout as a third argument, 
-providing the ability to use predefined layouts as starting points for custom layouts with only minor differences. Example:
+The `get()` function also accepts a partial layout to be merged with the predefined layout as a third argument, providing the ability to use predefined layouts as starting points for custom layouts with only minor differences. Example:
 
 ```javascript
-var changes = {
+const changes = {
   label_font_size: 20,
   transition: false
 };
@@ -181,41 +175,35 @@ LocusZoom.Layouts.get("data_layer", "genes", changes);
 
 #### Predefining State by Building a State Object
 
-**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 as a top-level parameter in the layout. For example:
+**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 as a top-level parameter in the layout. For example:
 
 ```javascript
-var layout = LocusZoom.Layouts.get('plot', 'standard_association', { state: { chr: 6, start: 20379709, end: 20979709 } })
+const layout = LocusZoom.Layouts.get('plot', 'standard_association', { state: { chr: 6, start: 20379709, end: 20979709 } })
 ```
 
 #### Predefining State With `data-region`
 
-You can also describe the locus query aspect of the State (chromosome, start, and end position) using a `data-region`
- attribute of the containing element before populating it, like so:
+You can also describe the locus query aspect of the State (chromosome, start, and end position) using a `data-region` attribute of the containing element before populating it, like so:
 
 ```html
-<div id="foo" data-region="10:114550452-115067678"></div>
+<div id="lz-plot" data-region="10:114550452-115067678"></div>
 ```
 
-When `LocusZoom.populate()` is executed on the element defined above it will automatically parse any `data-region` 
-parameter to convert those values into the initial state.
+When `LocusZoom.populate()` is executed on the element defined above it will automatically parse any `data-region` parameter to convert those values into the initial state.
 
 ## Development Setup
 
 ### Dependencies
 
-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:
+LocusZoom is an entirely client-side library designed to plug into arbitrary data sets, be they local files, APIs, or something else entirely. It has the following external dependencies:
 
-* [d3](http://d3js.org/) for a data visualization framework
+* [d3](http://d3js.org/) for data visualization
 
 ### Build System and Automated Testing
 
 LocusZoom is bundled using Webpack. To install all necessary dependencies for a development environment, run:
 
-```
+```bash
 $ npm install
 ```
 
@@ -225,7 +213,8 @@ Once complete run `npm run build` from the top of the application directory to r
 
 This build process will also write sourcemaps, to help with debugging code even in production environments.
 
-#### Other supported gulp commands:
+#### Other supported build commands:
+
 * `npm run test` - Run unit tests (optional: `npm run test:coverage` to output a code coverage report)
 * `npm run dev` - Automatically rebuild the library whenever code changes (development mode)
 * `npm run build` - Run tests, and if they pass, build the library for release
@@ -235,15 +224,14 @@ This build process will also write sourcemaps, to help with debugging code even
 
 #### Automated Testing
 
-LocusZoom uses [Mocha](https://mochajs.org/) for unit testing. Tests are located in the `test` subdirectory.
+LocusZoom uses [Mocha](https://mochajs.org/) for unit testing. Tests are located in the `test` subdirectory. Use `npm run test`.
 
-### Linting
-LocusZoom is also linted using 
-[ESLint](http://eslint.org/), the rules for which can be found in `.eslintrc`. This will run automatically as part of all new code commits, and during every build. 
+### Static analysis and code style
+LocusZoom runs code quality checks via [ESLint](http://eslint.org/), the rules for which can be found in `.eslintrc`. This will run automatically as part of all new code commits, and during every build. 
 
 ## Help and Support
 
-Full documentation can be found here: [github.com/statgen/locuszoom/wiki](https://github.com/statgen/locuszoom/wiki)
+Full documentation can be found here: [docs/](https://statgen.github.io/locuszoom/docs/)
 
 A LocusZoom discussion forum is available here: [groups.google.com/forum/#!forum/locuszoom](https://groups.google.com/forum/#!forum/locuszoom). 
 For the most effective help, please specify that your question  is about "LocusZoom.js".