Generating IGV screenshots for tumor and control BAM files 

Click here to access the repository. 

This script was developed to automatically generate IGV snapshots showing aligned reads from tumor and matched WBC BAM files side by side. It creates an IGV batch script that can be executed in command-line IGV to produce individual images for all variants listed in a given file.

1. Input File Requirements

The script requires a CSV file containing variant information. This file must include at least the following columns:

• Chrom 

• Position

• Gene

• Protein_annotation – variant annotation (e.g. p.R132H)

• Sample_name_t – tumor sample name

• Sample_name_n – matched WBC sample name

It is important that none of these columns contain values with spaces. For example  in the protein  annotation column  avoid "Missense p.L463V" and instead use  "Missense-p.L463V". Please avoid using underscores. If running in unpaired mode (tumor only or control only), the file should instead contain a single Sample_name column and optionally Path_bam if absolute paths are already specified.

2. Typical Use Cases

a. Tumor + WBC Paired BAMs

If you want to visualize both tumor and matched WBC BAMs for each variant:

python make_igv_snapshots.py \

  --path_variants /path/to/variants.csv \

  --PATH_batch /path/to/output_batch.txt \

  --DIR_snapshots /path/to/snapshots \

  --prefix "" \

  --suffix .bam \

  --given_range 100

• --path_variants: Absolute path to the CSV containing variant information.

• --PATH_batch: Absolute path to the output IGV batch script (will be created automatically).

• --DIR_snapshots: Directory where the PNG snapshots will be saved.

• --prefix and --suffix: Optional arguments to add common path strings (e.g. /data/bams/ or .bam) if you only have the sample names annotated in the variants file.

• --given_range: Genomic window (in bp) to visualize around each variant (default = 200 bp).

b. Unpaired BAMs

If you only have WBC (or any single-source) BAMs:

python make_igv_snapshots.py \

  --path_variants /path/to/wbc_variants.csv \

  --PATH_batch /path/to/output_batch_wbc.txt \

  --DIR_snapshots /path/to/snapshots_wbc \

  --unpaired \

  --given_range 150

Adding --unpaired instructs the script to only load a single BAM per sample.

3. How the Script Works

For each variant entry in the provided CSV file, the script:

1. Builds BAM file paths using optional prefix/suffix strings, unless you already have the BAM path in your CSV file.

2. Determines genomic coordinates based on the specified position and range.

3. Writes a complete IGV batch command sequence to the specified output file.

4. Creates the snapshot directory (if it doesn’t already exist) and  generates a snapshot filename based on the gene, protein annotation, chromosomal position, and sample name.

Example snapshot name:

TP53_p.R248Q_chr17_7579472_Patient123.png

At the end of the run, the script prints the exact IGV command needed to execute the batch file. Running this command in the terminal will automatically launch IGV, load the specified BAM files, navigate to each variant position, and save all corresponding snapshots to the chosen directory. You can also manually run the batch script inside IGV. Note that the batch file will be overwritten each time you run the script. If IGV fails to find a BAM file, double-check that the prefix and suffix arguments correctly match your file paths. The script assumes hg38 as the reference genome; modify the line inside the code if using another reference build.  Below is an example of how a snapshot with tumor-normal matched BAM files may look like. Presence of the indel in both analytes is indicative of clonal hematopoiesis.