Enhancing VarSeq Customization and Automation with Visual Studio Code: A Guide to Evaluation and Reporting Scripting
Are you as excited as we are about the new automation and customization features we’ve been rolling out with VarSeq’s most recent release, VarSeq 2.3.0? Do your eyes light up at the prospect of automated integration of various data sources into VarSeq’s evaluation and reporting framework? Does your list of evaluation scripts you’d like to implement read something like an 8-year-old’s holiday wish list in terms of tone and ambition? Our Field Application Scientist team loves helping groups realize their customization needs, and there is nothing more satisfying than giving our customers the tools they need to fully capitalize on VarSeq’s capabilities. If you’d like us to watch you ride off into the scripting sunset with proud tears in our eyes, then allow me to introduce you to one of the hottest collaborations in the industry, VarSeq and Visual Studio Code (VSCode).
Most people with any kind of development experience will be familiar with VSCode, Microsoft’s popular and highly configurable source code editor. Those of you who have read any of my recent blogs or attended some of our webcasts referencing automation will know that I use the term “highly configurable” often and reverently enough to emulate some sort of bioinformatic incantation. This is precisely why VSCode and VarSeq work so well together. VSCode’s coding infrastructure allows VarSeq users to easily write, debug, and implement custom scripts for both automating VSClinical workflows and producing custom reports. I’m excited to provide an overview here of how our users can explore these capabilities.
There are two main avenues for interacting with VarSeq through VSCode, both of which are within the VSClinical evaluation and interpretation module. These avenues are (1) evaluation scripts, customizable scripts that allow users to import, export, and manipulate data within the VSClinical module, and (2) custom scripts within the VSClinical reporting section, which allow users to integrate VarSeq’s exports with external systems and augment the data being produced by evaluations performed in VSClinical. While evaluation scripts are currently only available in VSClinical AMP, our VSClinical ACMG users can look forward to analogous features that will be introduced in our next release of VarSeq. Custom report scripts, however, are currently available in both VSClinical ACMG and VSClinical AMP. Let’s take a look at these various points of ingress into VarSeq’s customizable workflows and explore how to implement and debug custom scripts with VSCode.
Evaluation scripts allow users to define routine workflows within VSClinical. These can be run through the VSClinical graphical user interface or implemented within VSPipeline command line scripts to provide GUI-less integration of automated workflows. Within VSClinical, evaluation scripts can be accessed and edited in the Evaluation tab of VSClinical (Figure 1). Clicking the blue plus button will open a list of available evaluation scripts. From here, the default shipped scripts can be added to evaluation, or users can opt to create a new script, which can be empty, or use an existing script as a starting point.
As an example, suppose we want to employ the Import TSO 500 Combined TSV default script. Adding it will render an executable copy of the script in the current workflow. In this case, clicking “run” opens a window that asks for an input TSV file (Figure 2). For most users, selecting the TSO 500 combined TSV and starting the script will be sufficient. For the more ambitious among our users, however, selecting the “Enable Debugger” option will display a help message with instructions to connect the selected script to VSCode’s debugger (Figure 3).
This process is interesting in itself. Simply by viewing what’s going on under the hood of these evaluation scripts, users can better understand how these processes are implemented. In this case, for instance, users can view (and edit) the thresholds for TMB (Figure 6) or explore some of the API functions used to interact with VSClinical AMP.
Unsurprisingly, however, the fun doesn’t stop there. With the debug dialogue opened in VSClinical and VSCode open, users can attach VSCode’s debugger to VarSeq and set breakpoints to better understand the included functions and debug any novel changes (Figure 7). Clicking “Attach to VarSeq” and then clicking run will run the script and produce any error messages or other output in VSCode’s terminal. In this case, we would have to specify an input file in the function arguments to produce an output. However, that doesn’t stop us from choosing breakpoints to explore the script’s state at any point. To create a breakpoint, simply click on the red dot that appears next to any line as you hover over the line in the margin (Figure 8).
The debug menu that appears at the top of the window when you run the debugger then allows you to step through your script from breakpoint to breakpoint (Figure 9). At each breakpoint, you can view the current variables on the left side of the screen.
Hopefully, the content of this blog has piqued the interest of current and future users without being too intimidating. The tools discussed here should be more than enough for those with scripting experience to get started and should also provide a useful starting point for those looking for help with scripting and automation within VarSeq and VSClinical. As always, the FAS team is at the disposal of our customers exploring new ways to improve their workflows. Please don’t hesitate to reach out to firstname.lastname@example.org if we can be of any assistance.