Customizing VSClinical Reports

VSClinical includes a Word template system for creating customized clinical reports. There are three templates that ship with the ACMG workflow and two template that ship with the AMP workflow. These reports are designed to be the end-product of the clinical testing workflow and can be customized and specialized to each test and clinical lab.

The three templates that ship with the ACMG workflow are:
  • Gene Panel Template: Focus on a small set of genes, more compact representation
  • Trio Report Template: Focus on inheritance from parents to an affected proband
  • Mendelian Disorder Template: Whole genome/exome with expanded incidental findings
The two templates that ship with the AMP workflow are:
  • Cancer Report Template: Our standard clinical report for somatic variants and biomarkers
  • Cancer Drugs and Trials Template: Clinical report with additional support for drugs and clinical trials

The Inputs: Variants, Sample and Results

The report templates utilize data from throughout the VSClinical workflow. This data is assembled into a sample-specific JSON file that is then used to fill in the word template. This file contains information from each of the workflow tabs and consists of variants and CNVs that are selected for reporting with their selected report status, a phenotypes list, and a gene list. Also included are the sample data and the final result status as selected in the report tab. All this data can be reviewed, and much of it edited, from within the block editor of the report tab. Simply click on each section, and the right-hand bar block editor will switch to allow changes to the fields for that section.

The Outputs

There are several files created inside the project folder for the current sample when rendering a report. You also create and select an input Word-based “Report Template” file.

When you click “Render” on the report tab, the current sample evaluation state is saved to a per-sample JSON file. This file, along with the selected Word template file is used to create the report Word file using the sample as the file name. If changes to the evaluation are made, they will not appear in the report until it is rendered again.

You can see these files by clicking the down arrow on the right of the Wrod report item in the right-bar and selecting Open Output Location. The files are located under the report folder of the current project and are named based on the name of the sample in the evaluation.

If you are trying to edit a report template, for example, to add a new field, it can be useful to look at the JSON file containing the evaluation data to find the field name of the data you would like to add to your report (see below). Once you know the name of the field you want, adding it to your report template is easy. If we wanted to add a top-level field like 'signedOffBy' to our report, we would simply insert it into our Word template file surrounded by brackets, {signedOffBy}.

Customizing Templates

After selecting one of our shipped templates as a starting point, it is easy to start customizing your template to fit your specific needs. Editing a report template is as straightforward as editing a Word file! When editing your template, you can do things like updating text or styling, removing unwanted sections, or even copying sections from another template.

Report Render Errors

Don’t worry about making a mistake when editing templates, we will provide useful error messages when rendering if anything goes wrong.

Report Render Error

Scopes and Conditions in Templates

What if you want to add a field that is embedded within some other object? For example, let’s say we wanted to add the ‘patientName’ field from the ‘sampleState’ object. Before we can include the patient’s name, we have to open the sample state scope. This is done by surround the scope name, preceded by a #, with brackets {#sampleState}. Once the sampleState scope is open, the patientName field can be referenced normally. The scope should be closed when no more fields are needed. This is done with a forward slash surrounded by brackets {/}.

Another useful tool available to you when customizing your templates is the ability to conditionally include content in your report. This is done the same way as opening a scope, using an expression or variable preceded by #. If the expression or variable evaluates as true the conditional scope will be included, and if it evaluates as false the scope will be omitted.

If you would like an alternate section to be displayed in the case of a false value, you can invert the expression or variable using ^ instead of #. Meaning if the conditional scope evaluates to false it will be included and vice versa. A great example of this can be seen in the results section of our Trio Report Template.

Loops and Variable Length Content

Another useful feature of our report templating system is the ability to display variable-length content. For example, you can have a section repeated for each reported variant or CNV. Or you can have a table be filled with a variable number of rows based on the contents of the report. Looping through a variable-length list is done in much the same way as opening a scope or including a conditional section. For example, if you would like to loop through the 'variants' list, use {#variants} to open the section and {/} to end the section. The section will be repeated in the rendered report for each item in the list. The scope is also opened for the contents of each of those items.

Custom Logic with Inline Filters

There is one more great tool at your disposal when customizing report templates. That is the use of filters. They are incredibly useful and are used throughout the shipped templates. Filters can be used to modify or manipulate data in a variety of ways and can also be used to include dynamic auto-filled text in your reports. There are a variety of system filters already included and used in our shipped templates, but you can also define your own custom filters to suit your needs. Filters are in fact just javascript functions that take data from the template and can be defined to return any transformation or expression based on that data. Filters are called using | after a value or object. For example, {#testResult|isPositive} takes the value testResult and passes it to the filter isPositive. The isPositive function then returns true if the input value is considered positive, and false otherwise.

Another example is {#variants|relevantVariants} which takes the list variants and passes them to the filter relevantVariants. This function then returns a new list that does not include variants that have been set as 'Do Not Report'

To create your own filter functions, first, open the filters location. This can be found under the word template drop-down in the right-hand bar of the report tab. Then simply add your functions to either acmg.js or cancer.js depending on which VSClinical workflow you are using.

For inspiration on how to use filter functions, it may be useful to look at our existing system files. These can be found by going to Open System Filters Location menu of the arrow menu on the Word item in the right-bar. Here there will be the files acmg.js, cancer.js, and utils.js which contains filter functions specific to the ACMG workflow, the Cancer workflow, and both workflows, respectively. We describe these functions in more detail below.

System Filter Functions Reference

The system provided filter functions are quite readable, but for quick reference, we provide documentation on the name of the filter, what it expects as parameters and what it returns. Note the first input parameter to the function is automatically the variable before the | character. If you want to pass in additional arguments, you provide them after the filter function name by adding a colon, and then the argument in quotes. For example, to format a DOB and provide a default value, you could use dob|dateYYMMDD:'Unknown'.

ACMG System Filter Functions

function isMonogenicDiseaseVariant(variant)
Parameters:
  • variant: A single variant object

Returns a boolean value describing whether the variant is a monogenic disease variant based on the variant’s inheritance and zygosity.

function getIncidentalVariants(variants)
Parameters:
  • variants: An array of variant objects

Returns the input list of variants filtered to those which have reportSection set to ‘secondary findings.’

function countIncidentalVariants(variants)
Parameters:
  • variants: An array of variant objects

Returns an int equal to the number of variants with reportSection set to ‘secondary findings.’

function hasIncidentalFindings(report)
Parameters:
  • report: The report state object

Returns an int equal to the sum of incidental variants and incidental cnvs in the report state.

function incidentalFindingsSummary(report)
Parameters:
  • report: The report state object

Returns text describing the number of variants in gene(s) associated with a disorder that is unrelated to the samples reported phenotype.

function getCarrierStatusVariants(variants)
Parameters:
  • variants: An array of variant objects

Returns the input list of variants filtered to those which are incidental and not monogenic disease variants.

function includeCarrierStatus(report)
Parameters:
  • report: The report state object

Returns an int equal to the sum of the number of carrier status variants and the number of carrier status cnvs in the report state.

function getMonogenicDiseaseVariants(variants)
Parameters:
  • variants: An array of variant objects

Returns the input list of variants filtered to those which are incidental and monogenic disease variants.

function isMonogenicDiseaseCnv(cnv)
Parameters:
  • cnv: A single cnv object

Returns a boolean value describing whether the cnv is a monogenic disease cnv based on the cnv’s inheritance and call state.

function getCarrierStatusCnvs(cnvs)
Parameters:
  • cnvs: An array of cnv objects

Returns the input list filtered to incidental cnvs which are not monogenic disease cnvs.

function getMonogenicDiseaseCnvs(cnvs)
Parameters:
  • cnvs: An array of cnv objects

Returns the input list filtered to incidental cnvs which are monogenic disease cnvs.

function sortByPathogenicity(variants)
Parameters:
  • variants: An array of variant objects

Returns the input list of variants sorted from most pathogenic to least pathogenic based on their set classification.

function relevantVariants(variants)
Parameters:
  • variants: An array of variant objects

Returns the input list of variants filtered to those which have reportSection set to ‘Primary Findings.’

function hasRelevantVariants(variants)
Parameters:
  • variants: An array of variant objects

Returns a boolean based on whether there are relevant variants in the list.

function hasRelevantMutations(report)
Parameters:
  • report: The report state object

Returns a boolean based on whether there are relevant variants or cnvs in the report.

function monogenicDiseaseVariants(variants)
Parameters:
  • variants: An array of variant objects

Returns the input list of variants filtered to those which are incidental and monogenic disease variants.

function countMonogenicDiseaseVariants(variants)
Parameters:
  • variants: An array of variant objects

Returns an int equal to the number of variants which are incidental and monogenic disease variants.

function monogenicDiseaseSummary(report)
Parameters:
  • report: The report state object

Returns text describing the presence of any variants or cnvs in genes associated with a dominant disorder unrelated to the samples phenotype.

function carrierStatusVariants(variants)
Parameters:
  • variants: An array of variant objects

Returns the input list of variants filtered to those which are incidental and not monogenic disease variants.

function countCarrierStatusVariants(variants)
Parameters:
  • variants: An array of variant objects

Returns an int equal to the number of variants which are incidental and not monogenic disease variants.

function carrierStatusSummary(report)
Parameters:
  • report: The report state object

Returns text describing the presence of any variants or cnvs in genes associated with a recessive disorder unrelated to the samples phenotype.

function relevantVariantsSummary(variants)
Parameters:
  • variants: An array of variant objects

Returns an int equal to the number of variants which have report section set to ‘Primary Findings’.

function relevantVariantsSummary(report)
Parameters:
  • report: The report state object

Returns text describing the number and genes of variants and cnvs in the report state that have their report section set to ‘Primary Findings’.

function relevantCnvsSummary(cnvs)
Parameters:
  • cnvs: An array of cnv objects

Returns text describing the number and genes of cnvs in the report state that have their report section set to ‘Primary Findings’.

function relevantCnvs(cnvs)
Parameters:
  • cnvs: An array of cnv objects

Returns the input list of cnvs filtered to those which have their report section set to ‘reporting’

function countRelevantCnvs(cnvs)
Parameters:
  • cnvs: An array of cnv objects

Returns an int equal to the number of cnvs which have their report section set to ‘reporting’

function monogenicDiseaseCnvs(cnvs)
Parameters:
  • cnvs: An array of cnv objects

Returns the input list of cnvs filtered to those which are incidental and monogenic disease cnvs.

function countMonogenicDiseaseCnvs(cnvs)
Parameters:
  • cnvs: An array of cnv objects

Returns an int equal to the number of cnvs which are incidental and monogenic disease cnvs.

function carrierStatusCnvs(cnvs)
Parameters:
  • cnvs: An array of cnv objects

Returns the input list of cnvs filtered to those which are incidental and are not monogenic disease cnvs.

function countCarrierStatusCnvs(cnvs)
Parameters:
  • cnvs: An array of cnv objects

Returns an int equal to the number of cnvs which are incidental and are not monogenic disease cnvs.

function relevantGenes(genes)
Parameters:
  • genes: An array of gene objects

Returns the input list filtered to those genes which have a relevanceToPatient value other than ‘not evaluated.’

function hasRelevantGenes(input)
Parameters:
  • input: An array of gene objects

Returns a boolean value based on the presence of genes which have a relevanceToPatient value other than ‘not evaluated.’

function getSimpleExons(cnv)
Parameters:
  • cnv: A single cnv object

Returns a string describing the exons spanned by the input cnv.

function getRelevantGenes(geneListDetails)
Parameters:
  • geneListDetails: An array of gene details objects

Returns a string of comma-separated genes which have non-zero values for either primaryCount or reportedCount.

function hasMotherData(sampleState)
Parameters:
  • sampleState: A sample state object

Returns a boolean value describing the presence of a motherPatientName or motherSampleName in the sample state object.

function hasFatherData(sampleState)
Parameters:
  • sampleState: A sample state object

Returns a boolean value describing the presence of a fatherPatientName or fatherSampleName in the sample state object.

function versionedSourceSummary(versionedSources)
Parameters:
  • versionedSources: A list of versioned source objects

Returns text describing the list of sources used for the interpretation.

AMP System Filter Functions

function joinBiomarkersWithVariants(biomarkers, variants)
Parameters:
  • biomarkers: An array of biomarker objects
  • variants: An array of variant objects

Returns the array of biomarkers with the matching variant object added under .variant.

function biomarkersWithApprovedDrugs(biomarkers, drugs, trials)
Parameters:
  • biomarkers: An array of biomarker objects
  • drugs: An array of drug objects
  • trials: An array of trial objects

Returns a list of biomarkers with references to FDA approved drugs along with relate trials.

function hasBiomarkersWithApprovedDrugs(biomarkers, drugs, trials)
Parameters:
  • biomarkers: An array of biomarker objects
  • drugs: An array of drug objects
  • trials: An array of trial objects

Returns a boolean value based on the presence of biomarkers which have FDA approved drugs.

function isTierOne(tier)
Parameters:
  • tier: An string representing a biomarker evidence tier

Returns a boolean value of true if the string inlcudes Tier I - Level and false otherwise.

function biomarkersResistance(biomarkers)
Parameters:
  • biomarkers: An array of biomarker objects

Returns the input list filtered to those biomarkers which have drug resistance evidence.

function hasBiomarkersResistance(biomarkers)
Parameters:
  • biomarkers: An array of biomarker objects

Returns a boolean based on the presence of drug resistance evidence in any of the input biomarkers.

function biomarkersPrognostic(biomarkers)
Parameters:
  • biomarkers: An array of biomarker objects

Returns the input list filtered to those biomarkers which have prognostic evidence.

function hasBiomarkersPrognostic(biomarkers)
Parameters:
  • biomarkers: An array of biomarker objects

Returns a boolean based on the presence of prognostic evidence in any of the input biomarkers.

function biomarkersDiagnostic(biomarkers)
Parameters:
  • biomarkers: An array of biomarker objects

Returns the input list filtered to those biomarkers which have diagnostic evidence.

function hasBiomarkersDiagnostic(biomarkers)
Parameters:
  • biomarkers: An array of biomarker objects

Returns a boolean based on the presence of diagnostic evidence in any of the input biomarkers.

function biomarkerEvidenceTier(biomarker)
Parameters:
  • biomarker: A single biomarker object

Returns a string representation of the highest tier of evidence present in the biomarker object.

function hasInterpretation(section)
Parameters:
  • section: A biomarker evidence section object

Returns a boolean value of true if the section has a non-empty interpretation, and false otherwise.

function biomarkerIsTierOne(biomarker)
Parameters:
  • biomarker: A single biomarker object

Returns a boolean value of true if the biomarker’s strongest evidence is Tier I and false otherwise.

function biomarkerIsTierTwo(biomarker)
Parameters:
  • biomarker: A single biomarker object

Returns a boolean value of true if the biomarker’s strongest evidence is Tier II and false otherwise.

function biomarkerIsTierThree(biomarker)
Parameters:
  • biomarker: A single biomarker object

Returns a boolean value of true if the biomarker’s strongest evidence is Tier III and false otherwise.

function biomarkerVariant(biomarker, variants)
Parameters:
  • biomarker: A single biomarker object
  • variants: An array of variant objects

Returns the variant object matching the input biomarker.

function germlineVariants(variants)
Parameters:
  • variants: An array of variant objects

Returns the input list filtered to variants with the type germline.

function hasGermlineVariants(variants)
Parameters:
  • variants: An array of variant objects

Returns a boolean value of true if the input list contains variants with the type germline, and false otherwise.

Util System Filter Functions

function round2(value, suffix='')
Parameters:
  • value: A number value to be rounded
  • suffix(optional): A string to be appended to the rounded number

Returns a string representing the value rounded to two digits, and followed by the suffix.

function formatPercent(percent)
Parameters:
  • percent: A number value to be formatted

Returns a string representing the value rounded to two digits followed by ‘%’ if the input value is a number, and “” otherwise.

function notEmpty(value)
Parameters:
  • value: A value to be checked

Returns a boolean value of true if the input is non-null and has length greater than 0. Returns false otherwise.

function dateLong(dateString, defaultValue = '')
Parameters:
  • dateString: A string representing a date
  • defaultValue(optional): A default string to be returned if dateString is empty

Returns a string representation of dateString similar to “Wed, December 19, 2012”. Or if dateString is empty returns defaultValue instead.

function dateYYMMDD(dateString, defaultValue = '')
Parameters:
  • dateString: A string representing a date
  • defaultValue(optional): A default string to be returned if dateString is empty

Returns a string representation of dateString formatted as “YYYY-MM-DD”. Or if dateString is empty returns defaultValue instead.

function dateEU(dateString)
Parameters:
  • dateString: A string representing a date

Returns a string representation of dateString formatted as “M.DD.YYYY”. Or if dateString is empty returns dateString instead.

function convertToPercent(value)
Parameters:
  • value: A number value

Returns a string representing the value multiplied by 100, rounded to two digits, and followed by ‘%’ if the input value is a number, and “” otherwise.

function commaJoin(value)
Parameters:
  • value: A list of strings

Returns a string representing each value of the input list separated by ‘, ‘.

function precision(value, precision = 2)
Parameters:
  • value: A number value
  • precision(optional): The number of digits to cut the number off at

Returns value rounded to the number of digits specified by precision.

function prettyRound(value, precision)
Parameters:
  • value: A number value
  • precision: The number of digits to cut the number off at

Returns value rounded to the number of significant digits specified by precision. This is a better function to use for displaying percentages like allele frequencies that can be quite small and still need to be represented accurately and not rounded down to 0 while also not trailing on with too much precision.

function capitalize(s)
Parameters:
  • s: A string value

Returns the input string with the first character capitalized.

function titleCaseString(s)
Parameters:
  • s: A string value

Returns the input string with the first character of each word capitalized and the rest of the word lowercase.

function defaultValue(value, default)
Parameters:
  • value: A value to be evaluated
  • default: a value to be returned if value is empty

Returns value if it is not null or empty, and returns default otherwise.

function clean(value)
Parameters:
  • value: Any value

Returns value if it is not null or empty, and returns "" otherwise.

function isPositive(result)
Parameters:
  • result: A report result string

Returns a boolean value of true if the result is equal to "Positive" and false otherwise.

function isNegative(result)
Parameters:
  • result: A report result string

Returns a boolean value of true if the result is equal to "Negative" and false otherwise.

function isNotEvaluated(result)
Parameters:
  • result: A report result string

Returns a boolean value of true if the result is equal to "Not evaluated" and false otherwise.

function isInconclusive(result)
Parameters:
  • result: A report result string

Returns a boolean value of true if the result is equal to "Inconclusive" and false otherwise.

function cleanFields(obj)
Parameters:
  • obj: Any object

Returns the input object with clean() called on all fields.

function intToString(value)
Parameters:
  • value: A number from 1 to 9

Returns a word representation of the input number.

function formatFrequency(ac, an)
Parameters:
  • ac: A number representing affected alleles
  • an: A number representing total alleles

Returns a string of the format ac/an (af%) where af is the calculated allele frequency.

function formatSize(size)
Parameters:
  • size: A number representing a number of base pairs

Returns a string with the size of the mutation followed by a suffix of “bp”, “Kb”, or “Mb”.

function emailLink(email)
Parameters:
  • email: A string representing an email

Returns an html string of a hyperlink to the input email.

function arrayToTable(array, width)
Parameters:
  • array: An array
  • width: A number representing the size of each row

Returns a two dimensional array which is the input array split into rows of length width.

function isPathogenic(classification)
Parameters:
  • classification: A classification string

Returns a boolean value of true if the input classification includes “pathogenic” and false otherwise.

function isBenign(classification)
Parameters:
  • classification: A classification string

Returns a boolean value of true if the input classification includes “benign” and false otherwise.

function isUncertain(classification)
Parameters:
  • classification: A classification string

Returns a boolean value of true if the input classification does not include “benign” or “pathogenic” and false otherwise.

function formatCoverageStatistics(coverageSummary)
Parameters:
  • coverageSummary: A coverage summary object

Returns the input coverageSummary object with fields rounded to two decimal places.

function formatFailedTargets(failedTargets)
Parameters:
  • failedTargets: An array of target objects

Returns a string containing each input target’s gene name and region separated by commas.

function analyzedGenes(geneSummary)
Parameters:
  • geneSummary: An array gene objects

Returns a string containing each input gene’s gene name and transcript id separated by commas.

function identifierList(variant)
Parameters:
  • variant: A variant object

Returns a string containing hyperlinks to the variant’s rsid, clinVar, and cosmic pages separated by commas.

function vus(variants)
Parameters:
  • variants: An array of variant objects

Returns the input list filtered to those variants which have type “vus” or reportSection set to “uncertain significance”.

function countVus(variants)
Parameters:
  • variants: An array of variant objects

Returns a number representing the count of VUS variants in the input list.

function buildLocation(variantOrCnv)
Parameters:
  • variantOrCnv: A variant or cnv object

Returns a string describing the chromosome and genomic position of the input if possible, and “No Location” otherwise.

function dateYear(dateString)
Parameters:
  • dateString: A date string

Returns a string describing only the year of the input date string.

function pubmedReferences(citations)
Parameters:
  • citations: An array of citation objects

Returns a filtered array of pubmed citation objects including a hyperlink to the pubmed page for each.

function hasPubmedReferences(citations)
Parameters:
  • citations: An array of citation objects

Returns a boolean value of true if the input list contains any pubmed citations and false otherwise.

function clinicalReferences(citations)
Parameters:
  • citations: An array of citation objects

Returns a filtered array of clinical trials citation objects including a hyperlink to the clinical trials page for each.

function hasClinicalReferences(citations)
Parameters:
  • citations: An array of citation objects

Returns a boolean value of true if the input list contains any clinical trials citations and false otherwise.

function omimId(cnv)
Parameters:
  • cnv: A cnv object

Returns the omim gene id for the input cnv’s primary gene.

function clinGenGene(cnv)
Parameters:
  • cnv: A cnv object

Returns the clinGen dosage gene name for the input cnv’s primary gene.

function omimReference(omimId)
Parameters:
  • omimId: A string representing an omim id

Returns a string containing a hyperlink to the input omim id.

function clingenReference(clingenId)
Parameters:
  • clingenId: A string representing a clinGen id

Returns a string containing a hyperlink to the input clinGen id.