fragMap.py

Juan F. Santana, Ph.D. (juan-santana@uiowa.edu), University of Iowa, Iowa City, I.A.

David H. Price, Ph.D. (david-price@uiowa.edu), University of Iowa, Iowa City, I.A.

This improved fragMap program is simplified, more powerful, and runs faster than the original fragMap program. It requires fragMap.py and fragMap_associated_script.py to be in the same directory. The program requires Linux operating system and Python 3+. It will create fragment heatmaps from specific range of fragment sizes over a chosen genomic interval as described in Spector et al., 2022. This program replaces original fragMap program created by Mrutyunjaya Parida that was used to generate fragMaps in Spector et al., 2022, Ball et al., 2022a, Ball et al., 2022b, and Santana et al., 2022.

File requirements

The input regions file should be a six column, tab delimited bed file that contains chromosome, start and end positions as well as the strand information for each region. The regions can be of any length as long as it is an even number and the center is a feature under study (e.g. transcription start site).

chr6	142946246	142946446	Gene_A	255	-

The input fragments file should be a six column, tab delimited bed file that contains chromosome, start and end positions as well as the strand information for each fragment.

chr6	142946247	142946298	A00876:119:HW5F5DRXX:2:2207:29170:1157	255	-

Behavior

Generates a fragMap from specific range of fragment sizes over a chosen genomic interval.

Dependencies

Python libraries

Pandas: https://pypi.org/project/pandas/

Numpy: https://pypi.org/project/numpy/

Matplotlib: https://matplotlib.org/stable/users/installing/index.html

Pillow: https://pillow.readthedocs.io/en/stable/index.html

Program used to obtain the fragments overlapping the genomic intervals

bedtools: https://bedtools.readthedocs.io/en/latest/content/installation.html, developed by the Quinlan laboratory at the University of Utah.

Example of arguments

python3 fragMap.py <regions> \
                  <fragments> \
                  -r \
                  -b \
                  -y \
                  -x \
                  -g \
                  -o \


Example command usage: 
python3 fragMap.py plusminus1000_from_TSS_1000genes.bed \
                  PolII-DFF-ChIP-Seq.bed \
                  -o PolII /home/user/dir \
                  -r 20 400 \
                  -y 4 \
                  -g 0.5

Parameter description

Required arguments

regions: <str> Bed file of genomic regions of chosen length with the format described above

fragments: <str> Bed file of fragment positions with the format described above

-o: <str> <str> Image identifier and path to output directory, for example -o TBP /home/user/dir

-r: <int> <int> Range of fragment sizes, for example -r 20 400

Optional arguments

-b: <int> Sets the chosen value as black, default is largest number in the matrix

-y: <int> (value greater than or equal to 1) Horizontal lines/bp for each fragment length, default is 1

-x: <float> or <int> (value less than or equal to 1) Vertical lines/bp for each genomic interval displayed, for example -x 1 is one vertical line/bp; -x 0.1 is one vertical line/averaged 10 bp, default is 1

-g: <float> Gamma correction factor, default is 1 but 0.5 provides an image which is more interpretable by the human eye. For more information: https://en.wikipedia.org/wiki/Gamma_correction

Example output from Pol II DFF-Seq performed on HFF cells (Spector et al., 2022) over +/- 1,000 bp regions from the MaxTSS of 12,229 genes in HFF cells determined with PRO-Cap (Nilson et al., 2022):

PolII_fragMap_20-400_Max_68609_X_1_Y_4_Gamma_1.0

PolII_fragMap_20-400_Max_68609_X_1_Y_4_Gamma_0.5