pVACcompare

pVACcompare is a file comparison suite built for comparing results generated by pVACtools or the GriffithLab immuno pipeline. Comparison can be specified for MHC Class I results, MHC Class II results, or both. In its current state the following files are included in the comparison:

• log/inputs.yml
• all_epitopes.tsv
• all_epitopes.aggregated.tsv
• all_epitopes.aggregated.tsv.reference_matches
• all_epitopes.aggregated.metrics.json (inputs only)

Installation

pVACcompare is written for Linux, other operating systems have not been tested. pVACcompare has been tested with Python 3.9 and 3.10. Other versions may work, but have not been tested.

Dependencies

To install dependencies navigate inside the repository after cloning and run:

pip3 install -r requirements.txt

Usage

pVACcompare offers several parameters that allow the user to have control of the comparisons. Running the following in the terminal will display the help menu with all of the available parameters and options:

python3 run.py -h

An example of running the tool likes like the following:

python3 run.py --pvactools_release --output_dir path/to/output/directory --mhc_class 1 --aggregated_columns 'Best Peptide', 'Best Transcript' version1/result version2/result

Note: You must specify if the results are from pVACtools or the immuno pipeline. All columns specified must be in quotes and comma separated. If you do not specify MHC Class, the tool will include both in the report. A list of available columns is displayed in the help menu.

The above command will perform a MHC Class I output comparison between two result folders generated by pVACtools only with the specified columns included in the aggregated tsv comparison. Columns for the unaggregated tsv comparison and reference match tsv comparison were not specified, so the default columns will be used. Results will be generated in the specified output directory. If an output directory is not specified, one will be created inside pvaccompare/.

Viewing Results

After completing a run, a results folder containing the JSON files generated by the tool will be created in the output directory. pVACcompare provides an organized HTML report for efficient parsing and visualization of results. To view the HTML report:

1. Navigate to the pvaccompare/ directory.
2. Run the following command to start the local server:

python3 server.py

3. The server will output a link where you can access the report. Open this link in your browser to view the available results.
   
   Once on the report page:
   • Select the results directory you'd like to explore.
   • To return to the directory selection screen, click pVACcompare in the navigation bar.