Customizing VSClinical Reports with New Output Types

         September 23, 2021

Golden Helix VSClinical provides a guided workflow interface for following the ACMG and AMP guidelines to evaluate variants and CNVs for NGS tests. The output of this work is most often a lab-specific clinical report. Since it was introduced, we have provided a powerful Word-based templating system to allow labs to customize reports to include specific content and branding.

Recently we introduced new reports in the ACMG workflow that demonstrate the breadth and flexibility of this feature. Beyond the exact data provided by VSClinical, custom filter functions allow users to write their own JavaScript to manipulate, join and generate entirely new data and text that can further enhance and automate the report authoring process.

Although powerful, this capability has been limited to customizing the contents of a Word file. Sometimes, the next logical step for the VSClinical analysis result is not a Word file, but another file or target system: A database, LIMS, EMR, or even just a custom structured text file.

With the next version of VarSeq, we introduce VSClinical Custom Report Exports that will enable interfacing with any of these target systems.

Fully Customizable Exports

To support the existing custom “filter functions,” we have embedded into VarSeq a fully modern JavaScript runtime (based on the latest language specification ES6). Inside Word templating, the only JavaScript files interpreted are system and user-level “filter” scripts. These scripts define invokable functions that can be “called” using the template language of the Word Template files. The new Custom Report Exports leverages the same isolated and secure JavaScript runtime but from the context of a custom report folder in the “ReportTemplates” user location.

Use the new “[+]” link above the Report Exports list to create a new custom export.

Creating a new Custom Export

You can select from existing custom exports or use a system template as a starting point. The following system custom script report templates will be provided:

  • VCF Report Template: This custom script will write out to the report folder a VCF file that contains every variant in the evaluation set to be reported. It includes the specified classification and criteria as INFO fields.
  • Mendelian Disorder HTML Template: This custom script will write out a HTML file that very closely matches the content of the Word report Mendelian Disorder Template. It takes as input not only the report data, but other files in the custom report folder, including a HTML template file and a lab logo.

After selecting or creating a custom report script, clicking Run Script will generate the output based on the inputs. Like the Word template, the custom script can read the report data created from the current evaluation that includes the full output of following the VSClinical enabled workflows and selected guidelines. Calling Run Script first generates this file, saving an up-to-date copy in the report data folder as “{sample_name}.json.”

The custom script export tab of VSClinical reports, with a Mendelian Disorder HTML template selected.

Just like our Word templates, once you configure your custom script export once, the settings are saved as part of your project template and will be ready for your next sample and project.

Whenever the evaluation changes with new variants or updated workflow results, clicking Run Script will update the outputted file. In this case, because it is an HTML file, we can Preview the output directly in VSClinical.

Customizable Inputs and Outputs

The existing VSClinical export options include a single Word templated report and a PDF conversion of that report. Each of these can be thought of as a function that takes inputs and produces an output. The Word-based template looks like this:

  • Input: Report Data File
  • Input: Word Template File
  • Output: Report Word File

While this set of inputs and outputs makes sense for a fixed system, introducing user-defined functions creates new possibilities. We can now create a custom output that would be a valid input to our Word files! In fact, we have added explicit support for chaining multiple custom exports to get to this result. Finally, we automatically execute the dependency chain of the current export, allowing the reporting process to be as easy as clicking Render.

With the addition of including the Fetch API to perform network API requests as well as a new “table” API to read data from the project, the possibilities for enhancing existing Word templates and using custom scripts cover many requested use cases:

  • Pushing the results of an evaluation, including all classified variants and a final report state, directly to an internal service such as a LIMS system through a custom API
  • Enhancing the Word report with additional project data not included by default in the report data file. For example: per-sample QC flags from the CNV caller, or an additional custom VCF field from the upstream variant caller.
  • Pull in from an internal server additional non-NGS biomarker assay result for the current sample, such as IHC or FISH, to include in a comprehensive cancer report
  • Create a specifically formatted XML that includes not only the report evaluation data, but also matching records from a custom annotation track and a VSWarehouse catalog that has been added to the project

While we can enumerate examples that represent scenarios we have seen deployed in our customers’ laboratory environments, the possibilities are endless. Custom reports can include JavaScript libraries packaged as ES6 modules, enabling the use of the multitude of open-source packages out there to do common data manipulation operations such as parsing XML, working with network protocols, or templating files. In fact, we have bundled a few of these, including Handlebars and Lodash, into the system “libs” folder.

Suppose this topic is of interest to you. In that case, we will be having an upcoming webcast dedicated to reporting customization and the new custom script exports capabilities of the forthcoming VarSeq release. Sign up for this event here, limited space is available!

Leave a Reply

Your email address will not be published. Required fields are marked *