Running PharmCAT

This will run the entire PharmCAT tool.

Requirements

You will need Java 14. This was developed and run on OpenJDK 14.

You can either build a fresh copy of the Jar file yourself or download a pre-compiled Jar file from our releases page.

PharmCAT takes VCF files as input.

Note: PharmCAT does not need a network connection during runtime. All data needed by PharmCAT is either supplied by the user on the command-line or self-contained.

⚠️ Please make sure you have read and undertand PharmCAT's VCF requirements.

Building (optional)

Checkout the repo and from the base repo directory run:

# ./gradlew shadowJar

This will build a "fat" jar with bundled dependencies in build/libs. You can use this jar file in the following section.

For more information on building PharmCAT, check Building PharmCAT.

Running

From the command line:

# java -jar <path_to_pharmcat_jar_file> -vcf <sample_file> -o <output_dir>

Where:

• -jar <path_to_jar_file> = required, the compiled PharmCAT Jar file
• -vcf <sample_file> = required, sample VCF file (:warning: Please read VCF requirements)
• -o <output_dir> = required, diretory path to write result files to
• -f <output_name> = optional, a base filename to use for output files (e.g. <output_name>.html)
• -a <outside_call_file> = optional, gene call TSV file from the an outside tool (like Astrolabe)
• -k = optional, keep the interim output files from the NamedAlleleMatcher
• -j = optional, flag to write reporter JSON data (will be <output_name>.report.json)
• -pj = optional, flag to write phenotyper JSON data (will be <output_name>.phenotyper.json)

Custom Data

PharmCAT includes the raw data it relies on. However, you can change this by using the following arguments:

• -na <definitions_dir> = optional, a directory containing allele definitions to use instead of the default packaged allele definitions

The latest version of the dosing guideline annotations can be downloaded from PharmGKB.

Running Individual Components

PharmCAT has multiple components that are run internally. Each of these components can be run individually if the output of the other components is not needed. Below are examples of how to run particular components.

Running the NamedAlleleMatcher

The NamedAlleleMatcher will match given sample VCF data to the named allele definitions in PharmCAT. This does not do anything with outside call data.

From the command line:

> java -cp <path_to_pharmcat_jar_file> org.pharmgkb.pharmcat.haplotype.NamedAlleleMatcher -vcf <vcf_file> -html <html_file>

Where:

• -vcf <sample_file> = required, sample VCF file
• -html <html_file> = optional, the HTML file to write the results to
• -json <json_file> = optional, the JSON file to write the results to

Custom Data

PharmCAT includes the raw data it relies on. However, you can change this by using the following arguments:

• -d <definitions_dir> = optional, a directory containing allele definitions to use instead of the default packaged allele definitions

Running the Phenotyper

The Phenotyper will take match or call data and return function and phenotype information for them.

There are two ways to run this. First option, you can run directly with VCF sample data:

> java -cp <path_to_pharmcat_jar_file> org.pharmgkb.pharmcat.phenotype.Phenotyper -vcf <vcf_file> -f <path_to_output_json>

Second option, you can run with output from the NamedAlleleMatcher:

> java -cp <path_to_pharmcat_jar_file> org.pharmgkb.pharmcat.phenotype.Phenotyper -c <call_file> -f <path_to_output_json>

Where:

• -vcf <sample_file> = sample VCF file
• -c <call_file> = JSON call data output from the NamedAlleleMatcher
• -f <path_to_output_json> = the path to an output JSON file
• -o <path_to_outside_call> = optional, a TSV of outside caller information

Running the Reporter

The reporter takes allele matcher and call data and finds drug annotations that are relevant to them. The annotations are compiled into JSON and HTML reports.

From the command line:

> java -cp <path_to_pharmcat_jar_file> org.pharmgkb.pharmcat.reporter.Reporter -c <call_file> -a <outside_call_file> -o <output_html>

Where:

• -c <call_file> = required, JSON result file from the NamedAlleleMatcher
• -o <output_html> = required, file path to write HTML result to
• -a <outside_call_file> = optional, gene call TSV file from an outside tool

Custom Data

PharmCAT includes the raw data it relies on. However, you can change this by using the following arguments:

• -g <guidelines_dir> = optional, directory containing JSON files of dosing guidelines instead of the default packaged guidelines

The latest version of the dosing guideline annotations can be downloaded from PharmGKB.