### Setup PharmCAT Docs

Source: https://github.com/pharmgkb/pharmcat/wiki/Deploy-Prototype-Website

Installs project dependencies for the documentation. This command only needs to be run once.

```shell
make setup
```

--------------------------------

### Install Node.js Packages

Source: https://github.com/pharmgkb/pharmcat/wiki/Releasing-PharmCAT

Run this command to install the necessary Node.js packages for PharmCAT development.

```bash
yarn install
```

--------------------------------

### Install Preprocessor Requirements

Source: https://github.com/pharmgkb/pharmcat/wiki/Testing

Install the necessary Python modules for the Preprocessor before running tests. This involves installing requirements for both the preprocessor and its tests.

```bash
pip3 install -r preprocessor/requirements.txt
pip3 install -r preprocessor/tests/requirements.txt
```

--------------------------------

### Install PharmCAT via Automated Installer

Source: https://context7.com/pharmgkb/pharmcat/llms.txt

Use this script to download dependencies and install PharmCAT in the current directory. Ensure Python 3.10.14+ is available for VCF Preprocessor requirements.

```bash
curl -fsSL https://get.pharmcat.org | bash
```

```bash
pip3 install -r requirements.txt
```

--------------------------------

### PharmCAT Input File Example (Text)

Source: https://github.com/pharmgkb/pharmcat/blob/development/docs/using/Calling-CYP2D6.md

This is an example of a single PharmCAT-ready input file for CYP2D6, generated after processing the StellarPGx output. Each sample will have a similar file.

```text
CYP2D6	*71/*2x2
```

--------------------------------

### View Single-Sample Preprocessed VCF (Sample 2)

Source: https://github.com/pharmgkb/pharmcat/blob/development/docs/using/VCF-Preprocessor.md

Example of a single-sample preprocessed VCF file for 'Sample_2', generated using the -ss flag.

```bash
$ cat test_2.Sample_2.preprocessed.vcf
<...header truncated...>
#CHROM  POS     ID      REF     ALT     QUAL    FILTER  INFO    FORMAT  Sample_2
chr1    97740410        rs72549309      GATGA   G       .       PASS    PX=DPYD       GT      0/1
chr2    233760233       rs3064744       CAT     C,CATATAT,CATAT .       PASS    PX=UGT1A1 GT      2/1
chr10   94942205        rs1304490498    CAATGGAAAGA     C       .       PASS    PX=CYP2C9     GT      0/1
chr13   48037825        rs777311140     C       CGCGG   .       PASS    PX=NUDT15     GT      0/1
chr19   38499644        rs121918596     TGGA    T       .       PASS    PX=RYR1       GT      0/1
```

--------------------------------

### View Single-Sample Preprocessed VCF (Sample 1)

Source: https://github.com/pharmgkb/pharmcat/blob/development/docs/using/VCF-Preprocessor.md

Example of a single-sample preprocessed VCF file for 'Sample_1', generated using the -ss flag.

```bash
$ cat test_2.Sample_1.preprocessed.vcf
<...header truncated...>
#CHROM	POS	ID	REF	ALT	QUAL	FILTER	INFO	FORMAT	Sample_1
chr1    97740410        rs72549309      GATGA   G       .       PASS    PX=DPYD       GT      1/0
chr2    233760233       rs3064744       CAT     C,CATATAT,CATAT .       PASS    PX=UGT1A1 GT      3/2
chr10   94942205        rs1304490498    CAATGGAAAGA     C       .       PASS    PX=CYP2C9     GT      1/0
chr13   48037825        rs777311140     C       CGCGG   .       PASS    PX=NUDT15     GT      1/0
chr19   38499644        rs121918596     TGGA    T       .       PASS    PX=RYR1       GT      1/0
```

--------------------------------

### Optitype Output Example

Source: https://github.com/pharmgkb/pharmcat/blob/development/docs/using/Calling-HLA.md

This is an example of the raw TSV output from the Optitype program, showing HLA allele calls and associated read counts.

```text
	A1	A2	B1	B2	C1	C2	Reads	Objective
0	A*32:01	A*68:03	B*07:02	B*35:01	C*07:02	C*07:02	10191.0	9915.832999999959
```

--------------------------------

### StellarPGx Output File Example (Text)

Source: https://github.com/pharmgkb/pharmcat/blob/development/docs/using/Calling-CYP2D6.md

This is an example of the raw output format from StellarPGx for CYP2D6 calls. PharmCAT requires this to be converted into individual files per sample.

```text
HG00436	*71/*2x2
HG01086	[*1/*31]	Possible novel allele or suballele present: interpret with caution; experimental validation and expert review through PharmVar is recommended
HG01190	*5/*68+*4
NA07048	*139/*4
NA18545	*36+*10/*36+*10
NA21105	*111/*3
```

--------------------------------

### Run PharmCAT with Default Output

Source: https://github.com/pharmgkb/pharmcat/blob/development/docs/using/Running-PharmCAT.md

This example shows the default behavior of PharmCAT, where output files are named based on the input VCF and saved in the same directory.

```bash
java -jar pharmcat.jar -vcf /tmp/sample1.vcf
Saving named allele matcher JSON results to /tmp/sample1.match.json
Saving phenotyper JSON results to /tmp/sample1.phenotype.json
Saving reporter HTML results to /tmp/sample1.report.html
```

--------------------------------

### Set up PharmCAT Scripts Environment

Source: https://github.com/pharmgkb/pharmcat/blob/development/docs/using/Multi-Sample-Analysis.md

This command demonstrates how to create and activate a Conda environment for running PharmCAT scripts. Ensure you have Conda installed.

```shell
# the yaml file is under the PharmCAT/src/scripts/ folder
conda env create -f pharmcat_scripts.yaml
conda activate pharmcat_scripts

```

--------------------------------

### View Preprocessed Multi-Sample VCF

Source: https://github.com/pharmgkb/pharmcat/blob/development/docs/using/VCF-Preprocessor.md

Example of the content of the preprocessed multi-sample VCF file generated by the VCF Preprocessor.

```bash
$ cat test_2.preprocessed.vcf
<...header truncated...>
#CHROM	POS	ID	REF	ALT	QUAL	FILTER	INFO	FORMAT	Sample_1	Sample_2
chr1    97740410        rs72549309      GATGA   G       .       PASS    PX=DPYD       GT      1/0	0/1
chr2    233760233       rs3064744       CAT     C,CATATAT,CATAT .       PASS    PX=UGT1A1 GT      3/2	2/1
chr10   94942205        rs1304490498    CAATGGAAAGA     C       .       PASS    PX=CYP2C9     GT      1/0	0/1
chr13   48037825        rs777311140     C       CGCGG   .       PASS    PX=NUDT15     GT      1/0	0/1
chr19   38499644        rs121918596     TGGA    T       .       PASS    PX=RYR1       GT      1/0	0/1
```

--------------------------------

### Install/Update Make on Mac

Source: https://github.com/pharmgkb/pharmcat/wiki/Testing

Use this command to install or update the 'make' utility on macOS if you have Homebrew installed. PharmCAT requires make version 3.82 or higher.

```bash
brew install make
```

--------------------------------

### Outside Call Format Example: Diplotype Only

Source: https://context7.com/pharmgkb/pharmcat/llms.txt

Example of an outside calls file specifying only the diplotype for a gene. Lines starting with # are comments.

```text
# outside_calls.tsv — tab-separated, lines starting with # are comments
# Column order: gene  [diplotype]  [phenotype]  [activity_score]
#
# Diplotype only:
CYP2D6	*1/*3
```

--------------------------------

### Deploy Website with Surge

Source: https://github.com/pharmgkb/pharmcat/wiki/Deploy-Prototype-Website

Deploys the built website to Surge.sh. Replace `<subdomain>.surge.sh` with your desired subdomain (e.g., `<your_userid>-pcat.surge.sh`). You will be prompted to sign in to Surge.

```shell
surge _site --domain <subdomain>.surge.sh
```

--------------------------------

### Command-Line Usage for Optitype to PharmCAT Script

Source: https://github.com/pharmgkb/pharmcat/blob/development/docs/using/Calling-HLA.md

Examples of how to execute the Python script from the command line, specifying the sample ID and the input TSV file path.

```console
python3 Optitype_to_PharmCAT.py <sample_ID> <input file path or input file>
python3 Optitype_to_PharmCAT.py test_sample test_sample_results.tsv
```

--------------------------------

### Install PharmCAT via Curl

Source: https://github.com/pharmgkb/pharmcat/blob/development/docs/using/Setup-PharmCAT.md

Use this command to install PharmCAT on Mac or Unix systems. It checks for required dependencies and installs PharmCAT in the current directory.

```bash
curl -fsSL https://get.pharmcat.org | bash
```

--------------------------------

### Run PharmCAT with Sample Metadata

Source: https://github.com/pharmgkb/pharmcat/blob/development/docs/using/Running-PharmCAT.md

Provide sample metadata using a TSV file to influence PharmCAT's processing.

```bash
java -jar pharmcat.jar -vcf /tmp/sample.vcf -sm /path/to/sample_metadata.tsv
```

--------------------------------

### Consecutive Homozygous Reference Genotypes

Source: https://github.com/pharmgkb/pharmcat/blob/development/docs/using/VCF-Requirements.md

These examples illustrate consecutive homozygous reference genotypes and their interpretation regarding INDELs. Example 1 does not rule out small deletions, while Example 2 explicitly states the lack of an insertion or deletion.

```text
# example 1
chr2	233760233	.	C	<NON_REF>	.	.	.	GT	0/0
chr2	233760234	.	A	<NON_REF>	.	.	.	GT	0/0
chr2	233760235	.	T	<NON_REF>	.	.	.	GT	0/0
```

```text
# example 2
chr2	233760233	.	CAT	C	.	.	.	GT	0/0
chr2	233760233	.	C	CAT	.	.	.	GT	0/0
```

--------------------------------

### Run Preprocessor Tests

Source: https://github.com/pharmgkb/pharmcat/wiki/Testing

Execute the tests for the Preprocessor component using the 'make test-preprocessor' command.

```bash
make test-preprocessor
```

--------------------------------

### Unwanted VCF Deletion Format Example

Source: https://github.com/pharmgkb/pharmcat/blob/development/docs/using/VCF-Requirements.md

This example illustrates an unwanted format for deletions that PharmCAT does not process correctly.

```text
#CHROM	POS	ID	REF	ALT	QUAL	FILTER	INFO	FORMAT	SAMPLE
chr10	94942212	.	AGAAATGGAA	.	.	PASS	do-not-want	GT	0/1
```

--------------------------------

### PharmCAT Pipeline Output Example

Source: https://github.com/pharmgkb/pharmcat/blob/development/docs/using/index.md

This is an example of the expected output when the PharmCAT pipeline successfully processes a VCF file.

```text
PharmCAT version: {{site.pharmcat_version}}

Processing data/sample.vcf ...

Running PharmCAT...
Checking files...
* Found 1 VCF file
Saving named allele matcher JSON results to /pharmcat/data/sample.match.json
Saving phenotyper JSON results to /pharmcat/data/sample.phenotype.json
Saving reporter HTML results to /pharmcat/data/sample.report.html

Done.
```

--------------------------------

### Download FASTQ Files

Source: https://github.com/pharmgkb/pharmcat/blob/development/docs/using/Calling-HLA.md

Use wget to download the compressed FASTQ files for both forward and reverse reads. Ensure both files are downloaded for complete sample data.

```console
wget ftp://ftp.sra.ebi.ac.uk/vol1/fastq/SRR711/SRR711355/SRR711355_1.fastq.gz
wget ftp://ftp.sra.ebi.ac.uk/vol1/fastq/SRR711/SRR711355/SRR711355_2.fastq.gz
```

--------------------------------

### Example Preprocessed VCF Output

Source: https://github.com/pharmgkb/pharmcat/blob/development/docs/using/VCF-Preprocessor.md

This is an example of the PharmCAT-ready VCF file generated by the preprocessor. Note the chr2 variant and the PX=UGT1A1 annotation.

```bash
$ cat test_1.preprocessed.vcf
<...header truncated...>
#CHROM	POS	ID	REF	ALT	QUAL	FILTER	INFO	FORMAT	Sample_1
chr2	233760233	rs3064744	CAT	C,CATATAT,CATAT	.	PASS	PX=UGT1A1	3/2
```

--------------------------------

### Outside Call Format Example: Gene Duplication

Source: https://context7.com/pharmgkb/pharmcat/llms.txt

Example of an outside calls file using gene duplication syntax for CYP2D6.

```text
# Gene duplication syntax (CYP2D6):
CYP2D6	*2x2/*4
```

--------------------------------

### Outside Call Format Example: Combination Call

Source: https://context7.com/pharmgkb/pharmcat/llms.txt

Example of an outside calls file using combination call syntax for a gene.

```text
# Combination call syntax:
CYP2B6	*1/[*6 + *8]
```

--------------------------------

### Java Code Formatting Example

Source: https://github.com/pharmgkb/pharmcat/wiki/Java-Coding-Conventions

Demonstrates standard Java formatting with 2-space indentation and K&R style braces. Braces are mandatory for all conditionals.

```java
public String doSomething(String str, Iterator itr) throws Exception {

  if (str == null) {
    complain("str is null!");
  } else {
    System.out.println(str);
  }
  while (itr.hasNext()) {
    String val = (String)itr.next();
    System.out.println(val);
  }
  return "Done!";
}
```

--------------------------------

### Run PharmCAT Pipeline in Docker (Interactive)

Source: https://github.com/pharmgkb/pharmcat/blob/development/docs/using/PharmCAT-in-Docker.md

Example of running the PharmCAT pipeline on a VCF file from within an interactive Docker session. The data path is mounted, and commands are entered directly after the prompt.

```console
# docker run --rm -v /path/to/data:/pharmcat/data -it pgkb/pharmcat
/pharmcat > pharmcat_pipeline /pharmcat/data/sample.vcf
PharmCAT version: {{site.pharmcat_version}}

Processing /pharmcat/data/sample.vcf ...

Running PharmCAT...
Checking files...
* Found 1 VCF file
Saving named allele matcher JSON results to /pharmcat/data/sample.match.json
Saving phenotyper JSON results to /pharmcat/data/sample.phenotype.json
Saving reporter HTML results to /pharmcat/data/sample.report.html

Done.
/pharmcat >
```

--------------------------------

### Outside Call Format Example: Single Allele

Source: https://context7.com/pharmgkb/pharmcat/llms.txt

Example of an outside calls file specifying a single allele for a monoploid gene.

```text
# Single allele (monoploid gene):
MT-RNR1	1555A>G
```

--------------------------------

### Install Python Dependencies

Source: https://github.com/pharmgkb/pharmcat/blob/development/docs/using/Setup-PharmCAT.md

Install the Python dependencies required by the PharmCAT Preprocessor using pip. This can be done within a virtual environment or globally.

```bash
pip3 install -r requirements.txt
```

--------------------------------

### Build PharmCAT Website

Source: https://github.com/pharmgkb/pharmcat/wiki/Deploy-Prototype-Website

Compiles the static site for the PharmCAT documentation. This is a necessary step before deployment.

```shell
make build
```

--------------------------------

### Run VCF Preprocessor (31 processors)

Source: https://github.com/pharmgkb/pharmcat/blob/development/docs/using/Runtime-Cost.md

Command to run the VCF Preprocessor script. This was documented before multi-sample VCF support was default. Use this when processing single-sample VCFs or when specific preprocessor configurations are needed.

```bash
python3 "$VCF_PREPROCESS_SCRIPT" -vcf "$INPUT_VCF" -refFna "$REF_SEQ" -refVcf "$REF_PGX_VCF" -o "$PREPROCESSED_VCF_OUTPUT_DIR"/ -c
```

--------------------------------

### VCF Deletion Format Example

Source: https://github.com/pharmgkb/pharmcat/blob/development/docs/using/VCF-Requirements.md

PharmCAT expects deletions to have an anchoring base in both REF and ALT sequences. This example shows the desired format for a deletion.

```text
#CHROM	POS	ID	REF	ALT	QUAL	FILTER	INFO	FORMAT	SAMPLE
chr10	94942212	.	AAGAAATGGAA	A	.	PASS	desired-deletion-format	GT	0/1
```

--------------------------------

### PharmCAT Pipeline Input JSON Example

Source: https://github.com/pharmgkb/pharmcat/blob/development/dockstore/pipeline/README.md

A sample JSON file demonstrating the structure and parameters required for the PharmCAT pipeline. Customize values like 'vcf_file' and 'sample_ids' according to your data.

```json
{
  "pharmcat_pipeline.vcf_file": "gs://your-bucket/path/to/your.vcf",
  "pharmcat_pipeline.sample_ids": "",
  "pharmcat_pipeline.sample_file": null,
  "pharmcat_pipeline.missing_to_ref": false,
  "pharmcat_pipeline.absent_to_ref": false,
  "pharmcat_pipeline.unspecified_to_ref": false,
  "pharmcat_pipeline.no_gvcf_check": false,
  "pharmcat_pipeline.retain_specific_regions": false,
  "pharmcat_pipeline.reference_regions": null,
  "pharmcat_pipeline.run_matcher": false,
  "pharmcat_pipeline.matcher_all_results": false,
  "pharmcat_pipeline.matcher_save_html": false,
  "pharmcat_pipeline.research_mode": "",
  "pharmcat_pipeline.run_phenotyper": false,
  "pharmcat_pipeline.run_reporter": false,
  "pharmcat_pipeline.reporter_sources": "",
  "pharmcat_pipeline.reporter_extended": false,
  "pharmcat_pipeline.reporter_save_html": true,
  "pharmcat_pipeline.reporter_save_json": false,
  "pharmcat_pipeline.reporter_save_calls_only_tsv": false,
  "pharmcat_pipeline.base_filename": "",
  "pharmcat_pipeline.delete_intermediate_files": false,
  "pharmcat_pipeline.max_concurrent_processes": 1,
  "pharmcat_pipeline.max_memory": "4G"
}
```

--------------------------------

### Run Optitype Nextflow Pipeline

Source: https://github.com/pharmgkb/pharmcat/blob/development/docs/using/Calling-HLA.md

Submit the Nextflow pipeline with the input sample sheet, output directory, and a profile for containerization (e.g., singularity). Other profiles like Docker and Conda are also available.

```console
nextflow run nf-core/hlatyping --input /path/to/file/sample_sheet.csv --outdir results -profile singularity
```