HOMER

Software for motif discovery and next-sequencing analysis

HOMER2

• First, HOMER2 expands the number of ways HOMER can consider background or control sequences when calculating DNA motif enrichment. Mainly, it can now randomly select from the genome or generate synthetic sequences that match positional k-mer content. This means that if your DNA sequences are anchored on a feature of interest, HOMER will attempt to account for lower-order (i.e. dinucleotide) sequence bias that might be present in your sequences. For example, if you have sequences centered on transcription start sites (TSS), certain nucleotides are likely to occur at certain positions, which may artificially increase the chance a given DNA motif will be recognized at that position. New background selection methods help address this concern, and provide tools to score the relative enrichment/depletion of motifs as a function of the motifs position in such sequences.

• Second, HOMER2 incorporates tools to help assess if DNA variants found at specific positions within a set of sequences tend to either enhance or diminish the predicted affinity of DNA motifs in association with a specific phenotype. For example, given two strains of mice and a set of TSSs that are specifically active in one strain versus the other, the program will assess if variants that enhance (or improve) the match for a given DNA motif are associated with an active (or inactive) phenotype.

Installation:

Specific Tools in HOMER2

The following three sections describe useful tools that are now part of HOMER2. One important note that applies to all of these tools - the sequences you analyze must all have the SAME LENGTH. The assumption for positional enrichment is that all of your sequences are anchored on some position or feature of interest such that there is a relationship between nucleotide 1, 2, 3, etc. across all of the input sequences.

homer2 background (basic tool to select or generate background sequences for sequence analysis tasks like motif enrichment)
createHomer2EnrichmentTable.pl (automate the creation of motif enrichment maps)
pacifierHomer2.pl (analysis of variants)

homer2 background

• Input sequences (either genomic positions or a FASTA file, MUST be the same length)
  
• Genome or other FASTA file to select background sequences from (technically optional as HOMER2 can create synthetic background sequences if desired).
• k = length of k-mer at each position to match sequence properties with (k=1 nucleotides, k=2 dinucleotides, k=3 trinucleotides, etc.)
  

Sample Data:

• tss.positions.200.txt - HOMER-style peak file similar to BED that contains regions centered on 155k TSS locations identified by csRNA-seq in U2OS cells in human [hg38]). The "200" refers to the fact that the regions are 200 bp long (centered on the TSS). Unzip it with gunzip before using it.
  
• hg38.fa - you can download this directly from UCSC using "wget https://hgdownload.soe.ucsc.edu/goldenPath/hg38/bigZips/hg38.fa.gz" and then unzipping the file with gunzip

homer2 bg -p tss.positions.200.txt -g hg38.fa -pkmer 2 -N 100000 -NN 100000000 -o output -allowTargetOverlap -allowBgOverlap

• <prefix>.info.txt - reports the command line options used and some basic information including actual number of sequences in output background set and the cumulative 'difference' or error in the background sequence properties and the target set.
• <prefix>.bg.positions.bed - tab-delimited BED format file with the genomic positions of all selected sequences
  
• <prefix>.bg.sequences.fasta - FASTA formatted file containing the selected background sequences
  
• <prefix>.bg.stats.txt - table containing the name of the background sequence, chromosome, position (min regardless of strand), strand, weight (1.0, not used), Profile Score (internal score, not used), GC%, and the internal bin ID the background was assigned from.
• <prefix>.bg.positions.bed, <prefix>.bg.sequences.fasta, and <prefix>.target.stats.txt provide the same information, but for the target sequences.
  

createHomer2EnrichmentTable.pl

• Input sequences (either genomic positions or a FASTA file, MUST be the same length)
  
• Genome or other FASTA file to select background sequences from (technically optional as HOMER2 can create synthetic background sequences if desired).
• k = length of k-mer at each position to match sequence properties with (k=1 nucleotides, k=2 dinucleotides, k=3 trinucleotides, etc.)
• HOMER motif(s) file to analyze

Resolution of analysis: By default it will analyze motif enrichment at each position using a 3bp window, but this can be customized using the -windows, -regions, and -positions arguments.

Sample Data:

• tss.positions.200.txt - Same as above, HOMER-style peak file similar to BED that contains regions centered on 155k TSS locations identified by csRNA-seq in U2OS cells in human [hg38]). The "200" refers to the fact that the regions are 200 bp long (centered on the TSS). Unzip it with gunzip before using it.
  
• hg38.fa - Same as above, you can download this directly from UCSC using "wget https://hgdownload.soe.ucsc.edu/goldenPath/hg38/bigZips/hg38.fa.gz" and then unzipping the file with gunzip.
• selected.motifs - HOMER-style motif file containing several commonly found motifs near TSS.
  

createHomer2EnrichmentTable.pl -o outputDirectory/ -strand separate -m selected.motifs -p tss.positions.200.txt -g hg38.fa -size 400 -windows 3 -pkmer 2 -allowTargetOverlap -allowBgOverlap

Note, the primary output file is summary.window3.logq.txt which described the positional enrichment of each motif (BH-corrected log10 q-values). These q-values are signed in the sense that positive log q-values imply positive enrichment, while negative q-values describe depletion of the motif relative to background at that position.

• cmd.txt - command line parameters used for the analysis.
  
• homerBg.* - several output files corresponding to the background selection that are generated by 'homer2 background' - see above.
  
• summary.windowN.logp.txt - natural log p-values for all motifs at each position evaluated with a given window size (default=3, i.e. +/- 1 bp).
• summary.windowN.logq.txt - base 10 log q-values (BH adjusted), and flipped.
  
• summary.bestIntervals.txt - Reports the positions with the best enrichment and depletion
• summary.fourier.txt - power spectrum analysis output for the interval [-120,-40] where we typically observe helical preferences in motifs near mammalian TSS.
  
• allmotifs.logp.txt - long form table that contains all of the enrichment data indexed by position and window size
• For each TF analyzed there are also specific files that contain motif frequencies per position, logp, etc. If motifs are analyzed for each strand separately, the negative strand motifs often contain the suffix "_2".
  

pacifierHomer2.pl

• Genome or other FASTA file to extract sequences from.
• HOMER motif(s) file to analyze
• Features file that specifies the positions of the anchor features (i.e. TSS positions) used in the analysis
• QTL file that specifies the location of variants along with information about how they relate to nearby features (i.e. are they associated with an active or repressive phenotype).
  

In practice, depending on what you're doing, it's best to think about how you can create a "Features" and "QTL" file for use with the program. There are ways to use a VCF along with regulated feature files below, but since that doesn't fit all situations, you may need to parse your data to work within the "Features" and "QTL" files described here:

Features File: This one is pretty simple, it should look like a tab-delimited HOMER peak file (more or less a bed file with column 1 being a unique identifier for the feature):

#phenotype_id   chr     start   end     strand
TSS-25650       chr1    46832095        46832095        -
TSS-122421      chr4    8911871 8911871 -
TSS-16113       chr2    148487278       148487278       +
...

QTL File: This is more complicated. The first column should show the variant (encoded by chr_position_ref_alt), the featureID (or phenotype_id), the relative distance of the feature, and then columns specifying information about the number of samples with the variant, total samples in the analysis, MAF of the variant, the p-value (if it a proper QTL analysis), and the slope. The slope is IMPORTANT - this specifies whether the variant is positively or negatively associated with the feature, and should be either a positive(+) or negative(-) value. The other parameters and relative value of the slope are not important, other than the program offers some control over filtering the table based on these values if they are present (i.e. if you want to run the analysis using only variant/qtls with specific scores).

#variant_id     phenotype_id    tss_distance    na_count        na_samples      maf     pvalue  slope
chr4_155831915_T_C      TSS-115727      216     NA      NA      NA      NA      1
chr13_63431468_C_G      TSS-69313       -236    NA      NA      NA      NA      -1
chr8_33641917_C_A       TSS-189725      -75     NA      NA      NA      NA      -1
...

pacifierHomer2.pl will also parse a VCF file to generate these files for you. For this you will need to the VCF file, and then two feature files (i.e. centered on TSS positions of interest) that represent features specifically active in the reference and features specifically active in the alternates. For example, in this example we are comparing C57Bl/6 and SPRET mice (two different strains), so we provide a VCF file that contains the SPRET variants (C57Bl/6 is the reference), and then two files containing the positions of the TSS that are more active in C57 and one with positions of TSS that are more active in SPRET. After the program is done running, there will be two files in the output folder called "qtlFeatures.tsv" and "qtls.tsv" which represent the two needed files above and can be used for subsequent analyses to speed things up (since the program won't need to match up TSS and variants again).

Example using a VCF and two regulation files (tss.UpC57.txt, tss.UpSPRET.txt).

pacifierHomer2.pl -g1 genomes/mm10.fa -vcf SPRET_EiJ.mgp.v5.snpsAndIndels.dbSNP142.filtered.mm10.vcf -p1 tss.UpC57.txt -p2 tss.UpSPRET.txt -start -200 -end 200 -step 10 -window 30 -m selected.motifs -o outputDirectory -snvOnly

Files to easily run the program again will be in outputDirectory/qtlFeatures.tsv and outputDirectory/qtls.tsv

Sample Data:

• mm10.fa - Similar to above, you can download this directly from UCSC using "wget https://hgdownload.soe.ucsc.edu/goldenPath/mm10/bigZips/mm10.fa.gz" and then unzipping the file with gunzip.
• selected.motifs - HOMER-style motif file containing several commonly found motifs near TSS.
• qtls.tsv - QTL file based on C57 and SPRET strain-specific TSS found in mouse macrophages
• qtlFeatures.tsv - Features file corresponding to the qtls.tsv file above.
  

pacifierHomer2.pl -g1 mm10.fa -qtl qtls.tsv -peaks qtlFeatures.tsv -m selected.motifs -o outputDirectory

Note, the primary output file is fdr.table.txt which described the positional enrichment of each motif (BH-corrected log10 q-values). These q-values are signed in the sense that positive log q-values imply that mutations that strengthen the motif are associated with activation (positive phenotypes), while negative log q-values describe imply mutations that strengthen the motif match are associated with repression (negative phenotypes).

• log.txt - command line parameters used for the analysis, along with some other parameters and filtering information.
  
• logp.table.txt - log10 p-values for all motifs at each position evaluated scored against the expected background.
• logp0.table.txt - log10 p-values for all motifs at each position evaluated scored against the expectation that the change in motif scores should be zero.
• fdr.table.txt -  log10 q-values for all motifs at each position evaluated scored against the expected background (BH-corrected).
• fdr0.table.txt - log10 q-values for all motifs at each position evaluated scored against the expectation that the change in motif scores should be zero (BH-corrected).
• scoreDiff.table.txt - Average difference in motif log odds score for each motif at each position.
• stats.tfs.txt - long form table that records the analysis results of each motif across each interval, reporting p-values, motif score differences, number of sites, etc.
• variantSummary.tsv - counts for each SNV change at each position in the data set (i.e. number of A->C changes at position -24).
• mutatedSites.txt - table of all mutated motifs, including positions, scores, sequences, etc.
• TF specific folders: Each TF will have it's own folder with motif specific information that is also summarized in the files above.