v0.14.0

💣 This release makes many internal changes to how LocusZoom retrieves and uses data. It is primarily aimed at simplifying existing features for new and future LocusZoom.js users. If you are upgrading from a prior version, we have tried to provide a guide to what has changed, but read the notes carefully. 💣

The new version provides new functionality that should make it easier to create custom plots from various types of file. Some minor display changes have also been added to improve the appearance and readability of figures.

New features

• Built in parsers and a new "Tabix Tracks Demo" make it easier to generate plots from tabix files for GWAS, BED, and user-provided LD, without manually creating a JSON file or loading the data into an API first. This should make it easier to get started with small in house datasets!
• Developer-focused internal changes make some aspects of generating plots less confusing. The README and getting started guide have also been revised to reflect current usage.
• Both GWAS and PheWAS layouts will now try to render points with an up/down triangle to indicate direction of effect, when possible. Internally this uses the new effect_direction ScaleFunction, inspired by PheWeb.
• Default plot font sizes have been increased by 20-40%, to help readability in publications/presentations
• New more compact LD "ribbon" legend
• (from LZ 0.13.x) New "turbo" color scheme provides better support for colorblind users (or black and white printing)

Internal improvements

• Plots can now switch between different view regions more quickly, thanks to a new multi-value LRU cache that can eliminate unnecessary network requests
• TabixUrlSource now accepts a pre-made reader instance . This is useful for sites that want to validate file contents before adding the file to the plot.
• Data layers now accept a template expression for id_field. This means that data elements can be uniquely identified as a combination of several fields. This eliminates the need to add "synthetic" unique ID fields in plots like phewas or coaccessibility, where no single datum field would have been globally unique. This also means that certain tooltip and mouse behaviors will be more stable as the user pans and zooms.

Deprecations and major breaking changes

We generally try to avoid issuing breaking changes, but after 5+ years of LocusZoom.js, we are doing some tidying to make custom and interactive usages easier. Please consult the updated documentation and guides, and let us know if any important information is missing after the rewrite!

Layout syntax

• Namespaces have been redesigned as the central mechanism for plotting two datasets with one reusable layout.
  • The difference between "abstract" and "concrete" layouts has been eliminated. Syntax like Layouts.get(..., {unnamespaced: true}) or some_value: '{{{{namespace[assoc}}afield}}' is no longer necessary. All layers will now refer to fields by an internal name that is easier to read, write, and remember: assoc:afield.
  • Useful migration regex: replace \{\{namespace\[(\w+)\]\}\} with $1:
• New data_operations make it possible to mix-and-match different datasets, by moving the join logic from adapter to the point where the data is used (the data layer).
  • This replaces the old combineChainBody method of adapters. Closely coupling the act of retrieval (API) to the join logic (display) made it hard to use data fetched from a different location.
  • This also makes it much easier for a single API call to be displayed in several different ways throughout the plot.
• The data_layer.fields array property has been removed completely. Many people wanted to customize their data with just one extra field, and manually updating the contract of expected data proved cumbersome.
• Panel layouts must now provide an explicit id (no longer optional). Most layouts already did this.
• subscribeToData call signature has changed. It now accepts either an explicit specification of what data is requested, or else the name of a data layer ("give me exactly what is being used to draw something that is already specified elsewhere"). See docs for details.
• Removed old aliases for things that were renamed in prior versions: all references to dashboard.components now use toolbar.widgets

Adapters

• Adapters have been completely rewritten in a more functional style, making them easier to understand and debug. Many methods have been renamed slightly to reflect that they have a different call signature. Almost all custom adapter subclasses will need to update their code.
  • Example: getURL(state, chain, fields) is now _getURL(request_options); annotateData(records, chain) is now _annotateRecords(records, request_options), etc.
• The concept of the data chain has been eliminated; it was confusing and made it hard to use the same data in two different ways.
  • New "data operations", like "joins", specify how to connect two datasets at the point where the data is used, rather than when the data is first retrieved. The adapter method combineChainBody has been totally removed in favor of data_layer.data_operations. Several join functions are provided by default.
  • If your request depends on a prior request (like "LD for a particular GWAS variant"), a new dependency resolver has been introduced. See the guides/tutorials describing data_operations: [{type: 'fetch', from: ['assoc', 'ld(assoc)']}] for details of how to specify dependent requests.
• Adapter options are now specified as top-level keys, instead of inside a nested key calledparams: {}. Existing sample code to create a plot will need to revise usages of DataSources.add().
• Adapters will usually return all the fields from the API.
  • All pre-defined data layer layouts now contain an _auto_fields variable that defines what information a layer expects. At the time of render, a user-friendly error message will warn if the server fails to provide expected fields.
  • If you use LD information, rename ld:isrefvar to lz_is_ld_refvar and ld:state to ld:correlation. The new names for "auto-generated" properties better reflect what is actually coming back from the API, and make the code far easier to understand.
• Any data source specified in data_layer.namespaces will now trigger a network request for data. This is different than the previous behavior, where a different property ("fields") had to also be mutated
  • People really liked adding custom fields/ data to the plot, but no one ever remembered to update data_layer.fields. This lead to a lot of confusion when their data failed to appear.

Other

• Many private variables were renamed in LocusZoom plot and panel internals. This should make the console debugging experience nicer, by hiding things that were not useful to most developers.

Bugfixes:

• If the user selects an LD refvar, ignore the choice when switching to another region far from that variant.
• Cached adapter data now does a better job of isolating each individual layer that uses the data. This is especially noteworthy in, eg, StaticSource
• Fix an issue where plot would be sized incorrectly when initially drawn in a hidden area (like collapsible or tab widgets). Plot will now resize to fit available space when the area is un-collapsed.
• Fix broken rendering of intervals (eg BED tracks) if they had very narrow markings
• Increase spacing around axis labels (so that plots look good with logp > 1000; previously, 4-digit numbers overlapped with the label)

v0.14.0-beta.4

Minor bugfix for LD reference variants, and performance improvements for responsive resize.

v0.14.0-beta.2

• More concise and readable plots
• Includes all changes from previous beta. See updated release notes at: #259 (comment)

v0.14.0-beta.1

See in progress release notes for details. This release contains a number of breaking changes and internal improvements to how data is retrieved. It also makes it easier to use tabix datasets to plot your own data without transforming to an intermediate file format, and adds user-facing enhancements like direction of effect indicators on GWAS and PheWAS plot (when beta and se are provided)

v0.13.4

LD is now shown using a new color schema, "Turbo", to replace the old rainbow palette. The new color scheme is designed to have better contrast and support for colorblind users.

v0.13.3

• Allow legends to be updated after initial render, solely by altering layout options
• (provisional) New LocusZoom.Layouts.query_attrs and LocusZoom.Layouts.mutate_attrs helper functions provide a more convenient way to customize nested layouts, or to modify all tracks with the same kind of data at once (like a plot with 3 gwas scatter plots)

v0.13.2

• Bugfix for incorrect positioning of plot "curtain" error messages
• New renameFields helper function for working with layouts and field names (recursively renames a field anywhere it is used)

v0.13.1

Minor bugfixes

• Fix an issue with annotation track display and positioning
• Improve documentation for CDN loading of CSS, which will help avoid problems when saving images in certain situations

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

v0.13.0-beta.4

• Simplify height and layout logic for smoother resize behavior
  • Fix bugs where adding/removing panels causes other panels to distory
  • Remove unused proportional_origin.* and proportional_* layout options
  • Simplify redundant or confusing config options: All panels are now assumed to have the same width (plot.width governs width, and panel.width was removed), and the height is only controlled by panel heights (removed plot.height)
• Allow match and filter behavior to use field transforms and custom operators via the new LocusZoom.MatchFunctions plugin registry
• Rename lz_highlight_match to lz_is_match to reflect the fact that matching controls more than style
• New stable_choice scale function allows autogenerating color and layout options that are the same every time page is loaded
• Remove dimensions toolbar widget, which was widely unused
• Use cached data on zoom in (this may affect custom sources that previously relied on getUrl = getCacheKey)