Highlight points that match a field

[abought]

Per feature request by @amkwong

Purpose

We often want to connect data between layers. For example, click a point on an annotation track, and see how it lines up with the same set of points on an association plot.

This PR adds a controlled way for data layers to communicate with each other. It will only look at one field at a time, and the event can come from anywhere (including itself).

Summary of changes

• Fix a bug where events were fired more than once
• Introduce a new layout directive for data layers that allows a layer to render all points that match a specified value.

1. New directive: match: {send: fieldname, receive: fieldname }.
2. If a layer specifies match.send, then whenever a point is clicked, that layer will broadcast the value of that point for the specified field.
3. Any layer with match.receive will identify the points whose fieldname matches the broadcasted value. These points will be marked with a synthetic field, like lz_highlight_match (exact name TBD).
4. LocusZoom already has layout directives to control color, labels, etc, based on the value of a field. We have updated some old examples to demonstrate how the plot would update.

To do

• [x] Known issue: zombie tooltips are closed, but return after calling plot.applyState (not a regression, but this ticket makes it more obvious). destroyTooltip should probably also clear selection status from a point.
• [x] Provide a mechanism to clear the highlight when the element is de-selected
• [x] Basic ability for each layer to send/receive match events
• [ ] Document feature
• [ ] Render matching points in front (custom z-index) so they don't get hidden (*note: svg depends on insert order instead of z-index; may need to alter render logic)
• [x] Try feature out in a few use cases
• [x] Make the synthetic field name from match configurable/ intuitive
• [x] Design wart: the phewas scatter plot may not work very well
• [ ] Future: {from: [id]}: allow a layer to only apply to values from certain layers.
• [ ] Unit tests!!

Testing notes

Normally, data layers are isolated: changes to one layer do not affect others. This feature explicitly breaks that boundary: it allows one layer to trigger a full re-render of the plot.

Example to look at:

• GWAS catalog

Scenarios to watch for:

• Performance issues during re-render
• Using event signals, this allows a data layer to trigger its own re-render. Make sure there are adequate guards to prevent infinite loops.
• The PheWas scatter plot has a really quirky color behavior (object instead of list/primitive). It may need some tweaks to use this mechanism.

[abought]

Initial sketch of proposal, as discussed with @skybullbobby earlier.

This is the first draft of a general mechanism, showing the use of events + match + custom color directives.

One area of note: the PheWAS plots we are using depend on a custom layer (called category_scatter) with some weird behavior- in particular, it's not very good at handling custom point display options. That data layer may need some improvements to work with this new mechanism.

To try it out: npm install && npx gulp build Then open examples/gwas_catalog.html in your browser using a dev server of your choice. (your IDE may do that for you).

[abought]

I've updated this branch to work with how category_scatter specifies color options.

It changes the rules for how we identify color (one object of options---> array of multiple options), in a way that is more consistent with how all our other data layers work. But it should seamlessly be backwards compatible with older phewas_scatter usages. Let me know if there are bugs.

I'll work on adding unit tests next, and keep this bug open until we get some feedback from our internal beta testers.