4. Customizing Reports Templates

Reports are fully customizable and users with JavaScript development experience can extensively modify templates. In addition Golden Helix is happy to offer customization services. For more information contact your account manager.

To access the report template files click the Gear menu and select Open Report Template Folder. See Figure 4-1.

Template Selection

Figure 4-1: Opening the Report Template Folder.

Report templates consist of three main parts:

  • Layout Object: In the report.js file a variable layout is defined. This is a object which defines the form that is laid out in the report tab.
  • Template: Each template contains a template file which defines the layout of the rendered report. Handlebars is used as the templating language.
  • Render Function: The render function in report.js combines the information from the form and sources in VarSeq to create a context to pass to the compiled Handlebars template for rendering.

For additional information on Report Layouts please refer to the customization section of the VarSeq Manual

Adding New Data Fields to a Report Template

In this tutorial, we will illustrate how report templates are organized by creating two fields that will be added to the report input form and used in the final report. The two new fields will:

  • Create a new widget for an alphanumeric lab ID. This widget will autofill in the ID that will be defined in a TSV file used during the import process; and
  • Create a widget that will automatically pull in the phenotype field and corresponding OMIM gene ID from the OMIM-Variants annotation source in the project.

Adding a new Sample Input Data Field to the Report Template

There is a defined list of widgets that VarSeq includes that can be used to construct the report form. All of the available widgets can be found in the following image and are described in detail in the layout section of the manual. See Figure 4-2.

Widgets Available for Report Construction

Figure 4-2: Widgets Available for Report Construction.

To make adjustments to the report input form, we need to add widgets to the input form. We can do this by modifying the layout variable in the report.js file.

  • In VarSeq, click the Gear menu and select Open Report Template Folder. Open the report.js file in a text editor such as Notepad ++.
  • Scroll down to the reference section of the the report.js file and insert the following code block in the layout array between the ‘name’ id and ‘institution’ id. See Figure 4-3 and save changes before proceeding.
{
  id: 'labId',
  type: 'shortText',
  label: 'Identification Number',
  doc: 'Internal Reference Number',
  required: true,
  autoFill: function(project, input) {
    return _.get(project, 'samples.Current.importedId', '');
  }
},
Lab Id in Report Layout

Figure 4-3: Adding Lab ID to the report.js File.

Note that lodash’s get function tolerates null references and returns a default value rather than throwing a runtime error. In this case, our default value is simply the empty string.

Each item corresponds to a widget which will be created in the form. For additional information please refer to the manual.

Widgets share the following common properties:

  • id - used to retrieve data
  • label - provides a label in the input form
  • doc - help string displayed on hover of i icon in input form
  • type - defines the type of widget to be displayed using the following strings:
  • autoFill - function which returns a value to dynamically fill the widget’s input. Form has different parameters passed to it based on the context of the container for the widget.
    • variant or other non-sample context arguments include project, input, variant, thisForm, and varInput

Now that we have added this to our layout array, we now need to reload the report form by clicking on the Gear icon and selecting Reload Report Template. See Figure 4-4.

Gear Icon

Figure 4-4: Reloading the Report Template.

You should now see a new widget in your layout. See Figure 4-5.

Result of Lab ID

Figure 4-5: The New Identification Number in the Report Template.

Type the number 1074 in the Identification Number box and open the Developer JavaScript Console via the Gear Menu. Expand the console by clicking on the button on the lower left. In the console type:

> form.getInputData().reference.labId
JS Console

Figure 4-6: Retrieving an Object in the JavaScript Console.

You should see the text you just typed into the box in VarSeq. In fact all the input values are returned by the getInputData() function on the form object. Try typing:

> form.getInputData()

In the console you’ll see an navigable object containing your input values. Similarly, you can inspect the values in the template configuration dialog with the function getParamsData() and project specific data including annotations on the current variants with getProjectData().

So the next task is to get our labId into our template. To pass this value to the template, we bind it to the context which in turn is passed to the compiled template. For more information on how this process works refer to the Handlebars documentation.

To bind the value to the context, navigate to the render function in the report.js file. See Figure 4-7. After the line:

var ctx = _.extend(labeledInput, params);

Add:

ctx.labId = _.get(input, 'labRef.labId', '');

Once more save your changes to the report.js file before proceeding.

Render Function in Report.js

Figure 4-7: Adding a line to the Render Function in the report.js File.

This line assigns the output of lodash’s get function to the property labId on the ctx object. Now when the ctx object is passed as an argument to the compiled template in the line:

return template(ctx);

The labId property can be used in the template.

Note

When we have many items in a section and want to add them to the template without writing all the HTML by hand. We can use the eachInMap custom Handlebars helper that is in the report.js function. For additional information please see this additonal example.

When you press the Sync button to generate the report, you should see the text that you entered in the form as the last item in the Reference Information section in the generate report. See Figure 4-9.

Example Render Report

Figure 4-9: Rendered HTML Report with new Lab Identification Field.

Incorporating Project Data into the Report

Now lets create a new widget that will automatically pull in the phenotype field and corresponding OMIM gene ID from the OMIM-Variants annotation source in the project. See Figure 4-10.

OMIM in Variant Table

Figure 4-10: Information from OMIM-Variants that will be Incorporated into the Report.

First we will need to examine the identifier that corresponds to that data in the project by opening the JavaScript Development Console in VarSeq. To access the development console, click on the Gear icon and select Developer JavaScript Console. This will bring up a WebKit-like dev console.

  • Under the Console tab enter form.getProjectData()
  • Click the Object dropdown menu.
  • Click on the sources drop-down menu. This is an array which lists the objects in the variant table.
  • Click on the drop-down for number 14 to view the OMIM-Variants annotation source. Note the Key for the annotation source OMIM-Variants This is the value you’ll use in the report.js file to pull in information from your annotation source. See Figure 4-11.
  • Click on the fields drop-down. This is an array which lists the objects in the OMIM-Variants annotation source.
OMIM JS console

Figure 4-11: Browsing to the key in the JavaScript Console.

Now we will view and make note of the symbol for the Phenotype and OMIM Gene ID information.

  • Click on the drop-down for number 1 in the array to view the Phenotype and note the symbol.
  • Click on the drop-down for number 3 in the array to view the OMIM Gene ID and note the symbol. See Figure 4-12.
OMIM JS console

Figure 4-12: Browsing to the OMIM symbol in the JavaScript Console.

The identifiers in the symbol will be used to autofill the phenotype and OMIM Gene ID information from OMIM-Variants for each flagged variant. To demonstrate, in the console tab of the Developer JavaScript Console, enter form.getProjectData().

Now click on the Variants > 15193 > OMIM-Variants > 0 to browse to the information that corresponds to the Phenotype and the GeneOMIMID fields listed in OMIM-Variants database. See Figure 4-13.

Key JS Console

Figure 4-13: Browsing OMIM Identifiers in the JavaScript Console.

Now that we have the necessary identifiers we can add a widget to the input form. To add a widget to the report template we will add the corresponding Javascrpit object to the layout section of the report.js file.

  • In VarSeq, click the Gear menu and select Open Report Template Folder. Open the report.js file in a text editor such as Notepad ++.
  • Scroll down to the variants section of the report template and insert the following code block in the primary findings section between the ‘classification’ ID and ‘interpretation’ ID and save your changes. See Figure 4-14.
{
  id: 'phenotypecomment',
  label: 'Phenotype',
  type: 'richTextEdit',
  doc: 'Short comment to augment patient result',
  heightInLines: 1,
  autoFill: function(project, input, variant) {
           return  _.get(variant, ['OMIM-Variants', '0', 'Phenotype'], null);
         }
 },
Inserting Phenotype Comment in Report.js

Figure 4-14: Editing the layout section of the report.js file.

Note

When making changes to the Primary Findings and Secondary Findings section of the report template, you must reselect a variant set for the changes to take effect. See Figure 4-15.

  • Under the Primary Findings and Secondary Findings sections, reset each dropdown choice to Select a Variant Set.
Reselect Variants

Figure 4-15: Reselecting Variants in the Primary Findings Section.

  • Then, reload the report template by selecting the Gear Icon and selecting Reload Report Template. See Figure 4-4.
  • Now reselect the appropriate variant sets for each dropdown.

A new Phenotype field will now be located in the Primary Findings section of the report template. This will contain information autofilled from the Phenotype column in the OMIM-Variants annotation source. See Figure 4-16.

New Phenotype Field

Figure 4-16: New Phenotype field in the report template.

Now we can add a sentence which specifies the corresponding OMIM ID.
  • Open the report.js file and locate the phenotype ID code block recently created.
  • Edit the autofill function to the following code block.
{
  id: 'phenotypecomment',
  label: 'Phenotype',
  type: 'richTextEdit',
  doc: 'Short comment to augment patient result',
  heightInLines: 1,
  autoFill: function(project, input, variant) {
         var omimphenotpe = _.get(variant, ['OMIM-Variants', '0', 'Phenotype'], null);
         var omimgeneID = _.get(variant, ['OMIM-Variants', '0', 'GeneOMIMID'], null);
         return  omimphenotpe + ' - ' + 'The OMIM ID for this gene is' + omimgeneID
        }
 },

Now the Phenotype field in the report layout will return the phenotype information and corresponding OMIM gene ID. If there is no annotation information available for the variant, a null value will be returned. Save the report.js file and reload the report template in VarSeq by clicking on the Gear icon and select Reload Report Template. Refer to Figure 4-4.

As shown in Figure 4-15 you will need to reselect variants in the Primary Findings section of the report template for the changes to take effect.

Adding OMIM Gene ID to Phenotype Comment

Figure 4-17: OMIM ID Added to the Phenotype Field in the Report Template.

Adding a new Widget to the Rendered Report

After adding this to our layout array, we will next want to include this information in the rendered report. By adding the following line of code to the constructVariant function in the report.js file see Figure 4-18. We can insert the phenotype field into the rendered report. Be sure to save the report.js file and reload the report template in VarSeq for the change to take effect.

variant.phenotype = _.get(inputVariant, 'phenotypecomment', '');
Construct Variant

Figure 4-18: Adding the OMIM Phenotype and Gene ID to the ConstructVariant Function in the report.js file.

Next we need to decide which section of the rendered HTML report to insert the phenotype field. Since this is information about the variant, lets place this in the Variant interpretation section of the rendered report.

  • In VarSeq, click the Gear menu and select Open Report Template Folder.

    Open the template.tpl file in a text editor such as Notepad ++.

  • scroll down to the Individual Variant Interpretations section of the template.tpl file. See Figure 4-19

Modifying The Template

Figure 4-19: HTML Code Block Corresponding to the Individual Variant Interpretations Section in the Report Template.

Insert a Phenotype table header and phenotype table cell to the Individual Variant Interpretations table in the template.tpl file see Figure 4-20. This will add the information in the Phenotype field in the report layout to the rendered html report.

Final Result of Rendered Report.

Figure 4-20: Edited HTML code Block Resulting in a new Phenotype Field in the Individual variant Interpretations Section of the Rendered Report.