v0.13.0

This release is focused on improvements for performance and interactivity. It contains several changes of particular use when displaying a lot of data at once, as well as bugfixes and documentation that will help with generating highly customized plots.

New features

User facing

• The documentation has been completely overhauled. The wiki has been replaced with new public docs . This includes several newly written prose user guides (getting started, data, layouts, and interactivity) as well as deep developer documentation.
• "Standard" datasets like genes, recombination rate, and GWAS catalog will now fetch the newest data available from the UM PortalDev API, rather than hard-coding a specific (possibly outdated) dataset ID.
  • This will give your users a better LZ.js experience over time, even if you don't update your code very often.
• New data layer rendering options:
  • highlight_region (beta) draws one or more translucent rectangles to draw attention to a part of the plot.
  • lz-intervals-enrichment (beta) Renders categorical interval-based data in a shared area, with y-axis prioritized by pvalues from enrichment analysis.
  • All panels now show loading indicators at first render, enabled by default. This is controlled by the new panel_layout.show_loading_indicator option. It replaces the old imperative function call, panel.addBasicLoader.

Developer-friendly features

• New stable_choice scaling function allows predictable auto-coloring of items, especially categorical data. Unlike random selection, this will choose the same colors regardless of page reload or data order.
• Allow match and filter behavior to use field transforms and custom operators via the new LocusZoom.MatchFunctions plugin registry. This allows greater control over interactive functionality.
• Tooltip templates now support an optional {{#else}} block. This is useful for writing tooltips with toggle buttons: "show/hide label", "is ld reference variant", etc.
• Several new events have been added to identify when a widget has been used. See documentation for details.
  • Additionally, tooltips and widgets are now allowed to emit "custom" events not pre-defined to LocusZoom (the old behavior was restrictive- unrecognized events would not be fired)
  • This is useful for analytics (to find out which features of the plot are used most often). Many widgets can now fire additional events when they are used: widget_display_options_choice, widget_download_png, widget_download_svg, widget_filter_field_action, widget_set_state_choice

Internal improvements

• The rendering code has been refactored throughout LocusZoom to use fewer resources when rendering plots with a large number of elements. (eg many variants in a wide genomic region)
• Zooming in to a region plot will now use cached data instead of making an unnecessary network request. This means that zooming will be faster and more responsive.
• GWAS scatter plots may now hide some overlapping low-significance variants by default.
  • This is controlled by the options under scatter_layout.coalesce. This can reduce the number of points to render by 40-50% for a narrow region or noisy plot, and >90% for a GWAS with a few strong hits in a wide viewing region.
• Improved the coaccessibility/arc track demo with new highlighting marks and better demonstration of enhancer / promoter / target gene matching

Deprecations and breaking changes

• Tooltip templates no longer treat 0 values as truthy. To conditionally show a value (even if it is 0), use the new is_numeric transformation function: {{#if value|is_numeric}}...{{/if}}
  • This is slightly less convenient, but a lot less confusing.
• Renamed the "magic field" lz_highlight_match to lz_is_match to reflect that matching is useful for controlling a wide range of scalable presentation options. (this synthetic field can also be used for size, shape, or even filtering)
• The gene constraint tooltip will no longer contact an external API in cases where the query would return no data (eg, gnomAD limits queries to 25 elements and build GRCh37 only)
• Most datasets now use a new implementation of getCacheKey. Instead of caching when the region is an exact match, it now considers whether the requested chrom/start/end is a subset of the prior region.
• /shift-clicking/ on a plot element will no longer allow "multiselect". Few people used this feature. It can still be enabled manually, but is now turned off by default.
• Several little-used features have been moved to extensions, in order to make the library smaller for most users
  • Intervals data layer (lz-intervals-track)
  • Forest plot data layer (lz-forest-track)
• Removed the dimensions toolbar widget, as it was widely unused.
• Removed unused or confusing configuration options related to height and width, including proportional_*. Plot width is now controlled solely by plot_layout.width and height is now solely defined by sum(panel_layouts.height).
• Internal build changes may affect people using LocusZoom.js with extremely old web browser versions. If your deployment needs to support such users, you may need to add your own tooling. For everyone else, enjoy the 25% smaller file size.

Bugfixes

• Fixed issues that caused panels to become distorted when elements were resized (see "breaking changes" above)
• Fix issues with label display on scatter plots (double escaping of text + labels not removed on re-render)
• The LD reference variant will now be correctly marked as such, even if your dataset uses non-standard variant marker formats.
• Fix an issue with link behavior on data elements
• Initiating a match event will now cause tooltips on other panels to be removed, rather than reappearing as zombie elements
• Annotation tracks (like GWAS catalog) will now be better aligned with variants in the scatter plot