[rfr] Update PheWAS plot for new API

[abought]

Purpose

Expand the PheWAS plot example to work with the new API endpoint data sources, and to not rely on hardcoded tick mark labels.

Sample endpoint URL: http://portaldev.sph.umich.edu/api_internal_dev/v1/statistic/phewas/?filter=variant eq '10:114758349_C/T'&format=objects&build=GRCh37

This represents a new user-level feature to support T2D portal work, with a target external release date of Oct 1.

Summary of changes

PheWAS-related

• Expand phewas_scatter.html example plot with new variants
• Update the pheWAS datalayer to support a live API endpoint, and add JSON files of sample data for local development
• Add a new category_scatter plot type that can automatically generate tick marks and categories

Internal hooks/ functionality

• Add a shared helper for generating subclasses
  • Allow extending known layers through the singleton registry
• Add an htmlescape helper for XSS prevention on user-provided data
• Add hooks that allow resetting panel and data layer state (for "plot interesting data" links that reuse existing panels). Demonstrate use on phewas scatter page
• (tentative proposal) Allow data layers to suggest ticks to the panel (but retain default behavior in most cases). This would allow a data layer to coordinate properties, eg for tick colors to match the color of datapoints in the layer. The panel would still be the final arbiter of display properties and could ignore the data layer ticks if desired.

TODO/ Notes

• [x] Various TODOs inline (edge cases, data source configuration parameters, errors, styling, etc etc)

• [x] Evaluate migrating to more generic tick mark generation mechanisms in #112

• Unit tests

  • [x] Subclassing mechanism
  • [x] htmlescape helper
  • [x] Extension mechanism for layers
  • ~Possibly test tick generation mechanism~

• [x] Discuss tick proposal, and make categoryscatter only return ticks for x axis (durgh)

Known issues:

• [x] Incorporate better sidebar variants (Ryan will choose good demos)
• [x] Plot breaks with unhelpful "missing ID field" error if there are no PheWAS variants in this region (eg if payload.data = [])
• [x] When applying filters, only the first value is getting labeled, not all that apply
• [x] if you click a point to "pin" the tooltip, and then jump to another region, it looks like the tooltip keeps getting redrawn (probably should be cleared when panel switches, maybe that's just an issue with the quick loadPheWAS() thing - CONFIRMED issue in scatter plot example before changes too

[Frencil]

Tonight I've updated and solidified the tick generation pathways on #112. Here are some relevant parts of the diff:

• Unified generateTicks method on Panel
• Unit tests for generateTicks - These should demonstrate some basic approaches to all forms of tick generation, including binding to a data set, specifying a field within that data set, handling grouping and padding, etc.

[welchr]

In some cases it looks like it's labeling a point with the trait label, and in other cases it isn't. Example:

If you merge in my PR, the first example on the left sidebar will trigger the behavior, but the third link down will not.

[abought]

In some cases it looks like it's labeling a point with the trait label, and in other cases it isn't.

Yeah, this appears to be a regression. Labels are subject to filters (p>=20 as default threshold), but it seems to be labeling only the first.

[abought]

For the preview, I'm going to declare this branch complete as is and begin my own final round of QA + documentation work. Worlds of thanks to @pjvandehaar , @welchr , and @Frencil for feedback and helpful improvements.

If anyone has feedback before the end of the day let me know. Otherwise plan is to update app.js and merge this by COB today.

This PR contains testing for a lot of the new stuff, but I'll aim to fill in remaining gaps in test coverage later in the week, as schedule permits. My sincere apologies for the messy commit history, but the rebase looked even gnarlier.

[welchr]

Thanks to all of you for the hard work on this. It looks great. :) I don't think anyone here is a real commit history purist (other than maybe Peter...)

When I see it merge into master (or wait until you msg me the OK?) I'll send an email to the Broad folks.

Though I do have one question on that. Once it's merged into master, could you forward gh-pages up to master so I can point them to http://statgen.github.io/locuszoom/examples/phewas_scatter.html (instead of the quick dummy portaldev page I was using before)?

[abought]

Found one issue during my QA and fixed. I also did light regression testing of our other plot types.

Below are the release notes I put together, and I'll merge after my 2pm meeting. (AFAIK, only ChrisC has push access for the npm package, but that's in no way urgent)

LocusZoom 0.6.0 - Release notes

User-facing features

• PheWAS plots are now flexible and customizable
• New "category scatter" layer type can automatically find and plot groups in plot categorical data (such as PheWAS)
• PheWAS data sources can now talk to a real API, and examples include documentation on what is required for a plot to work.
• Add a new field filter, htmlescape, which is helpful when using data from other people in your custom plots

Internal improvements

• Most code now annotates JSDoc information about methods and input types. This internal documentation should help developers looking to extend and build on the core, at a level of detail beyond the traditional user-level documentation in our wiki. Feedback and improvements welcome!
• Better support for extending built-in functionality with custom code (new helpers for subclassing and DataLayers.extend())
• Add helper method plot.clearPanelData, which is useful when reloading data on the same page. (arguments/api may change slightly in the future)
• DataLayers can now communicate with the panel to generate custom tick marks for specific data. (if DataLayer subclass implements getTicks method). As used in category_scatter, this provides a way to customize plots during the rendering process, without needing to hardcode tick marks or add extensive boilerplate code in every similar plot.

Bugfixes

• Better error messages when API returns no data
• Fix issue with "plot interesting data" links, where plot behaved oddly when a different region was loaded (error messages and tooltips should now properly clear)

Possible breaking changes

• Most methods now better enforce data types, to help avoid subtle bugs. This means that a string ("10") and a number (10) are no longer considered interchangeable. Please check your layouts if you notice any issues.

[welchr]

I'm not actually sure if the Broad uses our npm package. My impression was they used code from our repository directly. We should probably update it regardless just in case anyone else may be using it.

@Frencil can you add Andy to the npm package so he can modify as needed?