pVACview crashing/blanking out when uploading large metrics.json file (313MB+)

[bioaman]

I am experiencing an issue where pVACview fails to load the results for my tumor sample. Specifically, when I attempt to upload the TUMOR.MHC_I.all_epitopes.aggregated.metrics.json file, the page blanks out and becomes unresponsive.

As shown in the attached screenshot, the metrics JSON file is approximately 313,290 KB (313 MB), which seems to be exceeding the browser's memory or processing capacity for pVACview.

I have a few questions regarding how to resolve this:

Is there a recommended way to "slim down" or filter the metrics JSON file before uploading it to pVACview?

i tried to filter using python, but it's still reaching down to 110MB
even after i run binding filter and other various filtering, the aggregate TSV shortens in length but the .json file remains big only

[mhoang22]

hi,
are you running pvacview using the online web tool (https://pvacview.org/)?
if it is the case, could you try running pvacview locally (for example, using the app.R file, through Rstudio instead)?
( attaching instruction to launch pvacview R shiny app locally : https://pvactools.readthedocs.io/en/latest/pvacview/prerequisites.html )

the page can also blank out if the pvactools version of the json file doesnt match the pvactools version of the web tool. So it would be great if you launch pvacview using the app.R file. But if you have already tried loading the json file on pvacview while launching pvacview through app.R and that still doesnt work, please let us know.

[bioaman]

no i have been running pvac tool using conda R enviroment pvacview run /home/aman/Desktop/...

http://127.0.0.1:3333/

[susannasiebert]

You can control how many alternate candidates are included in the metrics.json file for each variant by adjusting the --aggregate-inclusion-binding-threshold (default: 5000) and --aggregate-inclusion-count-limit (default: 15). For HTMB cases reducing the --aggregate-inclusion-binding-thresholdto 2000 or 1000 can already significantly reduce the metrics.json file size. In order to apply this new threshold you will need to recreate the aggregate report file. You can do so by running the standalonepvacseq generate_aggregated_report` command with your all_epitopes.tsv file instead of running pVACseq from scratch.

Alternatively, you can split your all_epitopes.tsv file into multiple sets. E.g., one set could include all predictions for variants that were binned into the Poor tier and another set for everything else. If you then run pvacseq generate_aggregated_report on these subsetted files separately, the result files may be small enough for pVACview. Worst case, using a combination of both this approach and the adjusting the --aggregate-inclusion-binding-thresholdand--aggregate-inclusion-count-limit` may be necessary.

[bioaman]

Dear Susanne and the pVAC Team,

Thank you for your helpful suggestions regarding the --aggregate-inclusion-binding-threshold and the strategy of subsetting the all_epitopes.tsv.

https://pvactools.readthedocs.io/en/latest/pvacseq/filter_commands.html

While following the documentation for standalone filter commands on High Tumor Mutational Burden (HTMB) samples, I encountered a significant technical bottleneck that I would like to share with the team:

The Problem: Circular Bloat & Information Loss
Information Loss: When I recreated the aggregate report using filtered subsets to reduce file size, the Reference Proteome Similarity information was lost.

The Re-inflation Problem: When I attempted to re-run calculate_reference_proteome_similarity on those filtered results to regain the data, the tool generated a new Metrics JSON that returned to a massive size (~300MB+). It appears that adding similarity metrics triggers a broad inclusion of metadata that makes the file incompatible with browser-based pVACview sessions.

Filter Inconsistency: I also noted that the transcript_filter (TSL 1) occasionally allowed non-TSL 1 transcripts to persist, and the sequential standalone filtering process led to a higher-than-expected loss of "Pass" variants compared to the original aggregated logic.

To overcome this, I tried to filtering for post-processing that preserves the Reference Similarity data from the original run while achieving a manageable 3MB file size.

I would like to ask if you believe this alternate filtering method is acceptable,?

Step 1: The 4-in-1 Elite TSV Filter 

# Define your source file
ORIGINAL_AGG="TUMOR.MHC_I.all_epitopes.aggregated.tsv"

awk -F'\t' 'NR==1 || ($21 < 500 && $29 > 0.25 && $28 >= 10 && $26 > 0.25 && $25 > 1.0 && $15 == "1" && $30 == "Pass")' \
TUMOR.MHC_I.all_epitopes.aggregated.tsv > TUMOR.MHC_I.ELITE.tsv


Step 2: The JSON "Scalpel" (Python)

python3 -c '
import json
import csv

# 1. Map the Index IDs to keep from the TSV (Column 2)
ids_to_keep = set()
with open("TUMOR.MHC_I.ELITE.tsv", "r") as f:
    reader = csv.DictReader(f, delimiter="\t")
    for row in reader:
        ids_to_keep.add(row["Index"])

# 2. Filter the JSON while protecting global metadata
with open("TUMOR.MHC_I.all_epitopes.aggregated.metrics.json", "r") as f:
    data = json.load(f)

# Keep global metadata (strings/lists) + variant-specific dictionaries in our set
filtered_data = {k: v for k, v in data.items() if k in ids_to_keep or not isinstance(v, dict)}

# 3. Save the surgical result
with open("TUMOR.MHC_I.ELITE.metrics.json", "w") as f:
    json.dump(filtered_data, f)

print(f"Done! Created synced JSON for {len(ids_to_keep)} variants.")
'
------------------------------------------------
Filter	Logic	Column	Status
Binding Filter	IC50 MT < 500	$21	Included
Transcript Filter	TSL == "1"	$15	Included
Expression Filter	RNA Expr > 1.0	$25	Included
Coverage (RNA VAF)	RNA VAF > 0.25	$26	Included
Coverage (RNA Depth)	RNA Depth >= 10	$28	Included
Coverage (DNA VAF)	DNA VAF > 0.25	$29	Included
Final Quality Grade	Tier == "Pass"	$30	Included
---------------------------------------------------------------------

Do you think this post-processing approach is a valid alternative to the standard pipeline?

[susannasiebert]

Thank you for pointing out the issue with the reference proteome step. I forgot to mention that detail, my apologies. The reference proteome similarity step is indeed a limitation. Its long runtime and the amount of information it generates makes it prohibitive to run on the all_epitopes.tsv file so a rerun is indeed necessary after generating a new aggregated report file. I will make a mental note to update the documentation. Maybe a better long-term solution - for usability - is to allow users to re-run the reference proteome step as part of their aggregate report creation. I will discuss this with the team.

I would be interested in seeing your result files from before and after running the reference proteome step if that is something you would be willing and able to share. Maybe there is something we can do to prevent the reference proteome step from inflating the file size too much. We haven't noticed this issue on our end so it's something I would like to investigate more.

I think your solution sounds reasonable and is similar to my suggestion of subsetting your data - albeit as a post-processing step. This might be something we can integrate natively into pVACtools as well. I will also discuss this with the team.

Lastly, I wanted to address the issue you pointed out about the TSL hard-filter. If you are running with version 6.0 we now apply a transcript filter instead of a TSL-only filter. The --transcript-prioritization-strategy controls which criteria are considered when filtering/prioritizing transcripts. By default this is the mane_select status, the canonical status, and TSL. If a transcript is the MANE select transcript or the Canonical transcript but has a TSL not matching the --maximum-transcript-support-level, we still pass it. We change this filtering approach because we noticed that MANE select and canonical transcript were sometimes getting filtered out because they can have a TSL more than 1. However, these are high confidence transcripts so we wanted to have the ability to retain them. I'm happy to investigate any examples you may have where a non-TSL 1 candidate was retained.

Generally, we aim for the filtered.tsv file to return the same candidates that are in the Pass tier of the aggregated report but, as you noted, the sequence of running these filters doesn't always make that possible. Would you be able to share some examples where a Pass candidate did not make it through the hard filters?

[bioaman]

Potential problems with filtering and potential candiadate loss and suggetsion of alternate method.pptx

this is the version i am using currently
griffithlab/pvactools docker run MHC_Class_I$ pip show pvactools | grep Version

Version 6.0.3

Which would the Griffith Lab regard as the "gold standard" for clinical prioritization, Case 1 (Standard) or Case 2 (Manual Sync)? Losing potential neoantigens worries me.

A presentation and sample files showcasing these particular "vanishing" candidates are attached. I would like to know if using my "Step 2" method is acceptable. to control file size and capture the "Pass" tier.

I have directly compared two workflows in response to your interest in "before and after" files. When compared to my manual post-processing method, I am finding a discrepancy where the standard standalone filtering commands cause a significant loss of high-quality "Pass" candidates. Could you please tell me which outcome is "correct" from a biological standpoint?

filtering command case 1

`Step 1: Conservative Binding FilterThis step filters candidates based on affinity ($< 500\text{nM}$) and rank (top 1%).Bashdocker run --rm -it -v $(pwd):/data --user $(id -u):$(id -g) \
  griffithlab/pvactools:latest \
  pvacseq binding_filter \
    /data/TUMOR.MHC_I.all_epitopes.tsv \
    /data/TUMOR.MHC_I.conservative_binding.tsv \
    -b 500 \
    -p 1.0 \
    --percentile-threshold-strategy conservative \
    -m lowest

# Check the count:
wc -l TUMOR.MHC_I.conservative_binding.tsv
Step 2: Coverage Filter (QC Gate)This ensures variants have sufficient sequencing depth and variant allele frequency (VAF).Bashdocker run --rm -v $(pwd):/data --user $(id -u):$(id -g) \
  griffithlab/pvactools:latest \
  pvacseq coverage_filter \
    /data/TUMOR.MHC_I.conservative_binding.tsv \
    /data/TUMOR.MHC_I.conservative_coverage.tsv \
    --tdna-vaf 0.05 --tdna-cov 5 --trna-vaf 0 --trna-cov 0 --expn-val 0

# Check the count:
wc -l TUMOR.MHC_I.conservative_coverage.tsv
Step 3: Transcript Filter (TSL 1)Removes low-confidence isoforms to focus on high-quality biological transcripts.Bashdocker run --rm -v $(pwd):/data --user $(id -u):$(id -g) \
  griffithlab/pvactools:latest \
  pvacseq transcript_filter \
    /data/TUMOR.MHC_I.conservative_coverage.tsv \
    /data/TUMOR.MHC_I.conservative_tsl.tsv \
    --maximum-transcript-support-level 1

# Check the count:
wc -l TUMOR.MHC_I.conservative_tsl.tsv
Step 4: Final Aggregated ReportSimplifies the results into a one-line-per-epitope format for easier review.Bashdocker run --rm -it -v $(pwd):/data --user $(id -u):$(id -g) \
  griffithlab/pvactools:latest \
  pvacseq generate_aggregated_report \
    /data/TUMOR.MHC_I.conservative_tsl.tsv \
    /data/TUMOR.MHC_I.final.aggregated.tsv
Step 5: Reference Proteome SimilarityChecks for self-similarity to the wild-type proteome to minimize the risk of autoimmunity.Bashdocker run --rm -it --init \
  --memory="32g" --cpus="8" \
  -v $(pwd):/data \
  --user $(id -u):$(id -g) \
  griffithlab/pvactools:latest \
  pvacseq calculate_reference_proteome_similarity \
    /data/TUMOR.MHC_I.final.aggregated.tsv \
    /data/TUMOR.fasta \
    /data/TUMOR.MHC_I.final.aggregated.similarity.tsv \
    -m /data/TUMOR.MHC_I.all_epitopes.aggregated.metrics.json \
    --match-length 8 \
    -t 8
`

method 2

Step 1: The 4-in-1 Elite TSV Filter 

# Define your source file
ORIGINAL_AGG="TUMOR.MHC_I.all_epitopes.aggregated.tsv"

awk -F'\t' 'NR==1 || ($21 < 500 && $29 > 0.25 && $28 >= 10 && $26 > 0.25 && $25 > 1.0 && $15 == "1" && $30 == "Pass")' \
TUMOR.MHC_I.all_epitopes.aggregated.tsv > TUMOR.MHC_I.ELITE.tsv


Step 2: The JSON "Scalpel" (Python)

python3 -c '
import json
import csv

# 1. Map the Index IDs to keep from the TSV (Column 2)
ids_to_keep = set()
with open("TUMOR.MHC_I.ELITE.tsv", "r") as f:
    reader = csv.DictReader(f, delimiter="\t")
    for row in reader:
        ids_to_keep.add(row["Index"])

# 2. Filter the JSON while protecting global metadata
with open("TUMOR.MHC_I.all_epitopes.aggregated.metrics.json", "r") as f:
    data = json.load(f)

# Keep global metadata (strings/lists) + variant-specific dictionaries in our set
filtered_data = {k: v for k, v in data.items() if k in ids_to_keep or not isinstance(v, dict)}

# 3. Save the surgical result
with open("TUMOR.MHC_I.ELITE.metrics.json", "w") as f:
    json.dump(filtered_data, f)

print(f"Done! Created synced JSON for {len(ids_to_keep)} variants.")
'
------------------------------------------------
Filter	Logic	Column	Status
Binding Filter	IC50 MT < 500	$21	Included
Transcript Filter	TSL == "1"	$15	Included
Expression Filter	RNA Expr > 1.0	$25	Included
Coverage (RNA VAF)	RNA VAF > 0.25	$26	Included
Coverage (RNA Depth)	RNA Depth >= 10	$28	Included
Coverage (DNA VAF)	DNA VAF > 0.25	$29	Included
Final Quality Grade	Tier == "Pass"	$30	Included
---------------------------------------------------------------------

[susannasiebert]

The reason you are seeing a loss of candidates in your Case 1 run is that you are running the aggregate report creation on a pre-filtered file and that that pre-filtered file applies a stricter criteria than what is considered by default in pVACseq. The binding filter step also filters on the percentile. This is not a default in pVACseq and wasn't set in your initial pVACseq run and you are probably removing a lot of candidates that were still considered in your original Run

Your case 2 process is also much stricter than what pVACseq does by default. You filter on TSL==1, however the default in pVACseq is to consider the TSL, the mane select status, and the canonical status and when a transcript matches either of these criteria it is considered a good transcript. By applying a strict TSL==1 filter you are removing candidates resulting from canonical or mane select transcripts with a higher TSL.

That is not necessarily bad if you have a high tumor mutation burden case and you want to narrow down a long list of candidates to only the very best above and beyond what the defaults in pVACseq are. It really depends on your exact use case.

My suggest approach is a bit different than yours:

1. Get a list of all the Indexes from Tier==Pass variants from your aggregate report file from your original pVACseq run
2. Subset the all_epitopes.tsv file to get all neoantigen candidates where the Index column matches on of the ones in your list
3. Run the pvacseq generate_aggregated_report command on that subset from step 2. The result file should only have Tier==Pass entries. Adjust the --aggregate-inclusion-binding-threshold and --aggregate-inclusion-count-limit to reduce file size of the metrics.json file, if necessary.

Running the reference proteome step on the results from above should not be necessary since we already know that they don't have a reference proteome match because they were Tier==Pass in the original run. However, you can run it to double check your work.

These steps can be repeated for other tiers in case you'd like to explore candidates that are just slightly above your thresholds.

[malachig]

Hi @bioaman . Out of curiosity, how are you identifying somatic variants? What kind of tumor sample is this?

We have analyzed some very high TMG tumors (hypermutated tumor, cell lines, mouse tumors created by prolonged exposure to mutagens, etc.). But the size of your inputs sounds like it is maybe an order of magnitude higher that even these.

[bioaman]

@malachig Dear Prof. Malachi, Thank you for your continued feedback. The data in this study is derived from Whole Genome Sequencing (WGS) of renal cancer samples. The high variant count is maybe due to WGS. I am using Strelka, VarScan, and GATK MuTect2 for SNV/Indel detection. I have excluded Pindel and Manta due to complexities in merging structural variant callers. I have been following the pVACtools input preparation documentation closely to ensure compatibility.

[susannasiebert]

Version 6.1.0 has just been released and includes a new command pvacseq aggregate_report_filter that allows you to subset the aggregate report file and it's matching metrics.json file to only those entries matching a specific set of tiers (by default only Pass variants). Please give it a try and see if the resulting output files work for uploading into pVACview.

[malachig]

You say renal cancer samples. How many patients do you have? How many variant records are in each VCF file? How many that have a PASS VCF filter status and coding consequence according to VEP?

Having WGS instead of exome should not have that big an impact because it is only coding variants that are considered in pVACseq.

[bioaman]

Dear Professor Griffith,

Thank you for your guidance. I have pulled the statistics for the renal cancer samples as you suggested. For the current VCF (processed via VARSCAN,STRELKA,Mutect2/FilterMutectCalls), the metrics are as follows:

Total variant records: 12,419

PASS filter status: 12,419

Coding consequences (VEP): 12,308 (including missense, stop_gained, and frameshifts)

I realized that my initial approach was too manual and lacked stringent pre-filtering, which resulted in a very large number of variants being passed directly into pVACseq. I am currently working on transitioning to PVAC Cromwell/WDL-based workflow on my local system to automate this more effectively, though I am currently troubleshooting some environment-specific errors in the WDL execution.

I have two specific questions regarding the filtering logic:

Filtering Best Practices: Is there a standard recommended "prompt" or set of criteria you suggest for filtering the final VCF before running pVACseq to ensure only the most high-confidence neoantigen candidates are processed?

RNA Expression vs. Depth: I’ve noticed some instances where a very low RNA depth (e.g., a count of 1) results in a high TPM/expression value, causing these variants to rank highly in the final results. This makes me concerned about the reliability of those calls. Do you have a recommended minimum RNA read depth or VAF threshold to avoid these artifacts?

Bash

docker run --rm -it --init \

--memory="160g" --cpus="30" \

-v /home/aman/Desktop/renal/results/pvacseq_prep:/data \

-v /home/aman/Desktop/somatic_mutect2/supporting_files/refseq_protein_pvacref:/opt/pvacref \

--user $(id -u):$(id -g) \

griffithlab/pvactools:latest pvacseq run \

/data/SOMATIC_TXGXTN_ASER_VEP.vcf.gz \

TUMOR \

"HLA-A*11:01,HLA-B*35:05,HLA-B*40:01,HLA-C*04:01,HLA-C*07:02" \

MHCflurry MHCnuggetsI MHCnuggetsII NetMHC NetMHCpan PickPocket SMM SMMPMBEC DeepImmuno BigMHC_EL BigMHC_IM \

/data/filteringpvacresults500ic50_5inclusion \

--normal-sample-name NORMAL \

--phased-proximal-variants-vcf /data/phased_VEP.vcf.gz \

--iedb-install-directory /opt/iedb \

--pass-only \

--top-score-metric median \

-e1 8,9,10 -e2 15 \

--run-reference-proteome-similarity \

--allele-specific-anchors \

--peptide-fasta /opt/pvacref/Homo_sapiens.GRCh38.pep.all.fa.gz \

--problematic-amino-acids C \

-t 16 \

--binding-threshold 500 \

--percentile-threshold 1.0 \

--trna-vaf 0.05 \

--expn-val 1.0 \

--maximum-transcript-support-level 1 \

--aggregate-inclusion-binding-threshold 500 \

--aggregate-inclusion-count-limit 5

I am particularly confused regarding the final selection of neoantigens and would appreciate your insight on two points:

I plan to re-run this once my Cromwell setup is stable to ensure consistency. Thank you again for your time and help.

Best regards,

Aman