You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
SMURF identifies significantly mutated genomic regions in a set of samples
4
+
SMURF identifies significantly mutated genomic regions in a set of samples.
5
5
6
6
Developed by Paul Guilhamon
7
7
@@ -11,6 +11,19 @@ Clone this repo via `git clone`.
11
11
12
12
The SNP147 annotation files from the [UCSC Table Browser](https://genome.ucsc.edu/cgi-bin/hgTables) are very large, so they are not included in this repository.
13
13
14
+
## Requirements
15
+
16
+
SMuRF is implemented in Bash and R; it runs on any platform with Bash (≥4.1.2), R (≥3.3.0) and BEDTools (≥2.23.0).
17
+
It requires the following R packages:
18
+
19
+
* GenomicRanges
20
+
* gtools
21
+
* gplots
22
+
* ggplot2
23
+
* data.table
24
+
* psych
25
+
* dplyr
26
+
14
27
# Usage
15
28
16
29
```shell
@@ -24,44 +37,46 @@ qsub smurf.sh \
24
37
-m [global|peak]
25
38
```
26
39
27
-
## Parameters
40
+
## Arguments
28
41
29
42
| Parameter | Description |
30
43
|-----------|-------------|
31
44
|`-o`| Output directory (absolute path) |
32
45
|`-f [vcf\|bam]`| Format chosen for input variants. **vcf**: individual VCF formatted files for each sample must be placed under a single directory. The full path to that directory is what should be supplied to the `-v` argument described below. **NOTE**: when using this option the sample names used for output files will be automatically generated from the names of the VCF files themselves: if the filename contains an underscore, then the sample name will be everything that comes before the underscore; otherwise the `.vcf` at the end of the filename will be clipped off and the rest will be used as as sample name. Do make sure your sample names do not become identical once the portion of the filename after the underscore is removed. **bed**: a single BED file containing all variants to be analysed. The format must be the following: `chr start stop name`. The full path to that bed file is what should be supplied to the `-v` argument described below. |
33
46
|`-v`| The input variants themselves; depending on the format chosen above, either the path to a directory containing individual VCF files OR the path to a single BED file. |
34
-
|`-g [hg19\|hg38]`| Genome build. This will determine the build of annotation files used by SMURF. Obviously, the input variants and input genomic regions should both be of the chosen build. |
35
47
|`-s [n\|c\|a\|o]`| SNP filter to apply to the input variants. **n**: no SNP filter, only blacklisted regions will be removed. **c**: blacklist + Common snps from dbSNP147 will be removed; *recommended option for most uses*. **a**: blacklist + all snps from dbSNP147 will be removed. Additionally, only when using the VCF files as input, the option `o` will be valid here, and will provide snp filtering as done by the previous version of SMURF: removal of any variant annotated to an rs ID within the VCF file. |
48
+
|`-p`| Promoter annotation file; those derived from Gencodev19 (human genome build hg19) and Gencodev24 (human genome build hg38) are provided in the SMuRF directory. These can be replaced with any annotation of your choice, but the output figures by SMuRF will automatically colour-code regions by either the gene name linked to a promoter region or the mention "DistalRE" for distal regulatory element, as this tool was originally designed to look for mutation-enriched non-coding regions. |
36
49
|`-r`| Genomic regions of interest that will be checked for significant enrichment of mutations. Must be supplied in the BED format specified by `-f`. The 4th column is required, but can be any string. Having the name there could make downstream analyses easier but isn't required by SMURF. |
37
-
|`-m [global\|peak]`| Method used to calculate the background mutation rate (BMR) in the binomial test. **global**: BMR is total number of mutations (across all samples) in regions divided by total bp in regions. **peak**: BMR is calculated based on which samples have mutations in that region. The individual sample BMR is calculated as for global, and the average of the BMRs for the samples represented in the peak is taken as the peak BMR. |
50
+
|`-m [allsamples\|regionsamples]`| Method used to calculate the background mutation rate (BMR) in the binomial test. **allsamples**: BMR is total number of mutations (across all samples) in regions divided by total bp in regions. **regionsamples**: BMR is calculated based on which samples have mutations in that region. The individual sample BMR is calculated as for global, and the average of the BMRs for the samples represented in the region is taken as the region BMR. |
38
51
39
52
## Input
40
53
41
-
* Variants file(s): These should contain variants of interest. SMURF has options for applying SNP and blacklist filtering but will not perform arbitrary quality filters. They should be in either VCF format as multiple files (1 per sample) under the same directory OR in BED format, with all mutations for all samples within the same file, and exactly 4 columns: chr/start/stop/name. **NOTE**: if using the BED format, keep one row per mutation per sample, ie: if a mutation is recurrent and found in multiple samples these should be placed on separate rows. Also note that the start and stop positions are the same; these correspond to the POS column of a VCF-formatted file (BED and VCF follow different numbering conventions). See format example below:
54
+
* Variants file(s): These should contain variants of interest. SMuRF has options for applying SNP filtering but will not perform arbitrary quality filters. They should be in either VCF format as multiple files (1 per sample) under the same directory OR in BED format, with all mutations for all samples within the same file, and exactly 4 columns: chr/start/stop/name.
55
+
**NOTE**: if using the BED format, keep one row per mutation per sample, ie: if a mutation is recurrent and found in multiple samples these should be placed on separate rows. Also note that the start and stop positions are NOT the same; the start column corresponds to the POS column of a VCF-formatted file minus 1; (BED and VCF follow different numbering conventions; see https://www.biostars.org/p/84686/ for more information).
56
+
See format example below:
42
57
43
-
| chr | start | end | name |
44
-
|-----|-------|-----|------|
45
-
| chr10 | 101776719 | 101776719 | Sample1 |
46
-
| chr10 | 101877882 | 101877882 | Sample2 |
47
-
| ... | ... | ... | ... |
58
+
| chr | start | end | name |
59
+
|-----|-------|-----|------|
60
+
| chr10 | 101776719 | 101776719 | Sample1 |
61
+
| chr10 | 101877882 | 101877882 | Sample2 |
62
+
| ... | ... | ... | ... |
48
63
49
-
* Genomic Regions: a BED file of genomic regions of interest. The format is `chr start stop name`. **Note**: the `name` column is required but can be any string; it is recommended to use it for the names of biological samples from which each genomic region was identified for easy traceback in downstream analyses, although this is not required for SMURF. These genomic regions and the variants specified above do not need to come from matched samples. Unlike the set of input variants above, it is important that the genomic regions be mutually exclusive. If in your cohort regions from two different samples overlap, they should be merged as one and the sample name column can have all the contributing sample names in a comma-separated list. See format example below:
64
+
* Genomic Regions: a BED file of genomic regions of interest. The format is chr/start/stop/name ; Note: the 'name' column is required but can be any string; it is recommended to use it for the names of biological samples from which each genomic region was identified for easy trace-back in downstream analyses, although this is not required for SMuRF. These genomic regions and the variants specified above do not need to come from matched samples. Unlike the set of input variants above, it is important that the genomic regions be mutually exclusive. If in your cohort regions from two different samples overlap, they should be merged as one and the sample name column can have all the contributing sample names in a comma-separated list.
* Annotation files: ENCODE blacklist, Gencode promoter annotation, and dbSNP sets (All and Common) for both hg19 and hg38 are provided within the annotation directory. The user on the cluster does not need to provide any of these.
58
-
*[Blacklist](https://sites.google.com/site/anshulkundaje/projects/blacklists) generated by Anshul Kundaje. They represent "artefact regions that tend to show artificially high signal (excessive unstructured anomalous reads mapping)".
73
+
* Annotation files: GENCODE promoter annotation, and dbSNP sets for both hg19 and hg38 are provided within the SMuRF directory.
59
74
* Promoter annotation: The Gencode set of TSS coordinates for each genome build (hg19: v19, hg38: v24) was downloaded from the UCSC table browser. Promoters were annotated from -2.5kb to +0.5kb around the TSS.
60
-
* SNPs: dbSNP sets v147 were downloaded from the UCSC table browser for each genome build. Two versions of the databases are available, "All" to filter out all known SNPs and "Common" to remove only those that have a minor allele frequency of >= 1%. This latter set might be of use if one wants to avoid removing potentially interesting somatic mutations that also appear as very rare polymorphisms in the population.
75
+
* SNPs: dbSNP sets v147 were downloaded from the UCSC table browser for each genome build. The "Common" version of the database is made available with the tool; this can be used to remove only those that have a minor allele frequency of >= 1%, of use if one wants to avoid removing potentially interesting somatic mutations that also appear as very rare polymorphisms in the population. The larger file containing all SNPs (including those found at frequency < 1% ) can be downloaded from the dbSNP website.
61
76
62
77
## Output
63
78
64
-
SMURF outputs a number of files, some for display and evaluation purposes, others as end results, and a final set for input into downstream tools, such as [C3D](https://github.com/LupienLabOrganization/C3D) or [GO](http://www.geneontology.org) annotation.
79
+
SMuRF outputs a number of files, some for display and evaluation purposes, others as end results, and a final set for input into downstream tools, such as [C3D](https://github.com/LupienLabOrganization/C3D) or [GO](http://www.geneontology.org) annotation.
65
80
66
81
### Results Files
67
82
@@ -78,15 +93,17 @@ SMURF outputs a number of files, some for display and evaluation purposes, other
78
93
79
94
| File | Description |
80
95
|------|-------------|
81
-
|`QQplot_Freq3.pdf`| self-explanatory |
82
-
|`barplot_mut_inRegions_Counts_and_Perc.pdf`| summary plots of the number of variants per sample and how many overlap with the provided genomic intervals |
83
-
|`Mutated_Regions_Freq3_qval0.05.pdf`| scatter plot of significantly mutated regions |
84
-
|`Mutated_Regions_Freq3_qval0.05_Promoters_VS_DistalREs.pdf`| same as above with added promoter/DistalRE annotation |
96
+
|`QQplot_Freq3.pdf`| Self-explanatory |
97
+
|`barplot_mut_inRegions_Counts_and_Perc.pdf`| Summary plots of the number of variants per sample and how many overlap with the provided genomic intervals |
98
+
|`Mutation_Rate_Plot_Freq3_qval0.05.pdf`| Scatter plot of significantly mutated regions:-log10(q-value) vs region mutation rate |
99
+
|`Mutation_Rate_Plot_Freq3_qval0.05_Promoters_VS_DistalREs.pdf`| Same as above with added promoter/DistalRE annotation |
100
+
|`Sample_Frequency_Plot_Freq3_qval0.05.pdf` and `Sample_Frequency_Plot_Freq3_qval0.05_Promoters_VS_DistalREs.pdf`| Same as the two above, but with the number of unique samples mutated in the region as the x-axis as opposed tot he mutation rate |
101
+
|`Sample_Frequency_Plot_Freq3_qval0.05_DistalREs.pdf` and `Sample_Frequency_Plot_Freq3_qval0.05_Promoters.pdf`| Same as `Sample_Frequency_Plot_Freq3_qval0.05_Promoters_VS_DistalREs.pdf` but separating out those regions annotated to promoters and DistalREs |
85
102
86
103
### Files for use in dowstream analyses
87
104
88
105
| File | Description |
89
106
|------|-------------|
90
-
|`Mutated_Regions_sigmut0.05_DistalRE_forc3d.bed`|significantly mutated regions annotated to enhancers, to use as input for C3D to identify downstream target promoters |
91
-
|`Mutated_Regions_sigmut0.05_DistalReAndProm.bed`|all significantly mutated regions; for use in GO applications for example, or TF motif enrichment |
92
-
|`Mutated_Regions_allmut_DistalREAndProm.bed`|all mutated regions |
107
+
|`Mutated_Regions_sigmut0.05_DistalRE_forc3d.bed`|Significantly mutated regions annotated to enhancers, to use as input for C3D to identify downstream target promoters |
108
+
|`Mutated_Regions_sigmut0.05_DistalReAndProm.bed`|All significantly mutated regions; for use in GO applications for example, or TF motif enrichment |
109
+
|`Mutated_Regions_allmut_DistalREAndProm.bed`|All mutated regions |
0 commit comments