Running the PharmCAT Pipeline
For convenience, we have a single script (pharmcat_pipeline
) that simplifies the process of running the entire PharmCAT pipeline (the VCF Preprocessor and the core PharmCAT tool).
This script tries to keep things as simple as possible. If you need advanced features, you will need to run the individual parts of the pipeline directly.
Prerequisites
You must have both the VCF preprocessor and the core PharmCAT tool installed correctly. All the dependencies (python3, java, bcfools, bgzip) must already be in your PATH. If necessary, you can customize which versions of these dependencies to use using environment variables:
JAVA_HOME
- the directory where the version of Java you want to use is installedBCFTOOLS_PATH
- the full path to thebcftools
programBGZIP_PATH
- the full path to thebgzip
program
The pharmcat_pipeline
script is in the PharmCAT VCF Preprocessor tar file that's available on our releases page.
Usage
Standard use case:
# pharmcat_pipeline <vcf_file>
Details
usage: pharmcat_pipeline [-s <samples> | -S <txt_file>]
[-0]
[-matcher] [-ma] [-matcherHtml] [-research <type>]
[-phenotyper]
[-reporter] [-rs <sources>] [-re] [-reporterJson]
[-o <dir>] [-bf <name>] [-del]
[-cp <num processes>]
[-v] [-V]
input file or directory
options:
-h, --help Show this help message and exit
-v, --verbose Print more verbose messages
-V, --version Show program's version number and exit
Input arguments:
input file or directory
Path to a VCF file or a file of paths to VCF files (one file per line), sorted by
chromosome position.
-s <sample id>, --samples <samples>
A comma-separated list of sample.
-S <txt_file>, --sample-file <txt_file>
A file containing a list of samples, one sample per line.
Preprocessor arguments:
-0, --missing-to-ref Assume genotypes at missing PGx sites are 0/0. DANGEROUS!.
Named allele matcher arguments:
-matcher Run named allele matcher independently.
-ma, --matcher-all-results
Return all possible diplotypes, not just top hits.
-matcherHtml, --matcher-save-html
Save named allele matcher results as HTML.
-research <type>, --research-mode <type>
Comma-separated list of research features to enable: [cyp2d6, combinations]
Phenotyper arguments:
-phenotyper Run phenotyper independently.
Reporter arguments:
-reporter Run reporter independently.
-rs <sources>, --reporter-sources <sources>
Comma-separated list of sources to limit report to: [CPIC, DPWG]
-re, --reporter-extended
Output extended report.
-reporterJson, --reporter-save-json
Save reporter results as JSON.
Output arguments:
-o <dir>, --output-dir <dir>
Directory for outputs. Defaults to the directory of the input VCF.
-bf <name>, --base-filename <name>
Prefix for output files. Defaults to the same base name as the input.
-del, --delete-intermediate-pharmcat-files
Delete intermediate PharmCAT files (saved by default).
Concurrency/Memory arguments:
-cp <num processes>, --max-concurrent-processes <num processes>
The maximum number of processes to use when concurrent mode is enabled.
-cm <size>, --max-memory <size>
The maximum memory PharmCAT should use (e.g. "64G"). This is passed on to Java
using the -Xmx flag. Alternatively, set using the JAVA_MAX_HEAP environment
variable.
Inputs
- A VCF file
- can be single or multisample
- can be compressed (with gzip/bgzip)
- A text file containing a list of VCF file paths. Files should be listed one per line, sorted by chromosome position. Use this when data has been split among multiple files (e.g. VCF files from large cohorts, such as UK Biobank).
- A directory. The script will look for VCF files to process, and they will be treated individually.
If the provided VCF file contains multiple samples, you can limit which samples get processed with either the -s
or -S
flag.
Concurrent Processing
The script will automatically attempt to use concurrent processing if possible.
Outside Calls
If you need to provide outside calls, you can do so with the following file naming convention: <sample_id>.outside.tsv
. For example, if your sample is Sample_1
, then use Sample_1.outside.tsv
.
If you have a single sample VCF file, you can also just use the basename of the VCF file. For example, use mydata.outside.vcf
if you have a single sample VCF file called mydata.vcf
.
If you have a multisample VCF file, (e.g. multisample.vcf
) and have outside calls for Sample_1
, then can use multisample.Sample_1.outside.tsv
instead.
Naming Conventions
PharmCAT uses the following sub-extensions in filenames to indicate which part of the pipeline it comes from:
.preprocessed
.match
.phenotype
.report
These sub-extensions will be stripped off any filename to derive a base name for the file.
For example: the basename for mydata.preprocessed.vcf
is mydata
.
In addition, outside call files with a .outside
sub-extension will have the sub-extension stripped to derive the base name for the file.