More flexible filtering and matching rules

[abought]

Ticket: #207

Purpose

The filtering and matching functionality provide a means for live, interactive updates to the plot. The initial design was very restrictive due to performance concerns, but as we make improvements to the internals, we can allow more complex comparisons.

Several use cases (eg #207) have emerged wherein people would like to have more control over what is rendered:

• [x] Click on a point in one layer, and hide (filter) any points that don't match that value (might be able to use lz_highlight_match already- test this!)
• [x] Set custom filters via an external widget, and update the plot without requiring access to deep internals (eg a less kludgy version of the setFilter api)
• [x] Allow matching between layers based on something other than exact match (eg makes it easier to compare datasets from different sources if the values differ only by notation: "ENSG001" could be allowed to equal "ENSG001.1" in Parul's coaccessibility data for easier connection of genes and coaccessibility tracks)

Summary of changes

• Imperative calls to layer.setFilters are deprecated in favor of the new LocusZoom.FilterFunctions registry. Its reign was brief. Having to dive into the internals will not be missed.
  • The new declarative API will allow custom filters to be combined with built-in options, rather than having to choose between a single custom function OR builtins.
• A new registry has been added (LocusZoom.Matchfunctions) that can be used to specify custom comparison operators for both match and filter functionality. Each registry entry is a function with the signature (item_value, other_value) => boolean.
  • Matches are no longer limited to exact comparisons (eg the match rule can be ("item > broadcast_value")).
• Match and filters can now perform comparisons on transformed values (eg fieldname|transformname), which allows cleanup of small differences between values (number to scientific notation, strip trailing characters or ENSG version IDs... etc)
• MILD BREAKING CHANGE: The "this is a match" marker field has been renamed from lz_highlight_match to lz_is_match. This reflects that matching functionality is generic and not just about highlighting. We will be documenting this feature more publicly starting in v0.13.0, and the API rename is intended to occur before widespread use.

Future goals

• Compare to collected user stories
• Allow a layer to receive and compare on more than one field using a list syntax similar to filters (receive: [{field: operator}] This would mean: 1 broadcast value, but more than one rule on how this datapoint matches.
  • I'm not sure I like this API: it's asymmetric (send 1, receive many), and the main use cases aren't very compelling. We should have a strong driving use case before going ahead with such a feature.
• Allow filter filter functions to access a parameter from plot.state (variable) instead of a constant value: "click on an association scatter point, and render only interval track rectangles that overlap that position"
  • The main use case would be filter-on-matching event. There are some footguns to doing this, so we will develop it only later in conjunction with a use case.

[Parul-Kudtarkar]

Excellent!! Looking forward to testing this feature :)