General Usage#
Input#
For all data types, chromTools complete takes as input a set of aligned browser extensible data (BED) files. The BED format is a concise and flexible way to represent genomic features and annotations. The format supports up to 12 columns, but for chromTools complete only the first 4 are required.
Required columns#
chrom - The name of the chromosome. This column is required.
start - The zero-based starting position of the feature in the chromosome. The first base in a chromosome is numbered 0. The start position in each BED feature is therefore interpreted to be 1 greater than the start position listed in the feature. For example, start=9, end=20 is interpreted to span bases 10 through 20,inclusive. This column is required.
end - The one-based ending position of the feature in the chromosome. The end position in each BED feature is one-based. See example above. This column is required.
name - Defines the name of the BED feature, in this case the readname. This column is required.
Example pipeline and input file#
A typical pipeline prior to using chromTools complete might be:
raw data > qc > alignment > bamToBed
Resulting in an aligned BED input file, e.g.:
chr1 10060 10160 SIM:chr1:10060:141:0:303:312/1 31 +
chr1 10061 10161 SIM:chr1:10061:151:0:127:706/2 30 +
chr1 10102 10202 SIM:chr1:10060:141:0:303:312/2 31 -
chr1 10113 10213 SIM:chr1:10061:151:0:127:706/1 30 -
chr1 10141 10241 SIM:chr1:10141:177:0:628:797/1 34 +
chr1 10219 10319 SIM:chr1:10141:177:0:628:797/2 34 -
chr1 10234 10334 SIM:chr1:10234:185:0:691:1077/2 34 +
chr1 10285 10385 SIM:chr1:10285:157:0:141:974/1 34 +
chr1 10320 10420 SIM:chr1:10234:185:0:691:1077/1 34 -
chr1 10330 10430 SIM:chr1:10330:135:0:97:369/2 30 +
chr1 10343 10443 SIM:chr1:10285:157:0:141:974/2 34 -
chr1 10366 10466 SIM:chr1:10330:135:0:97:369/1 30 -
Note
The command will fail if you try to use peak-called BED files!
Output#
The outputs from the various steps of chromTools complete are created in the following directory structure, within the --outdir parameter.
<outdir>
├── 1_subsample/
│ ├── downsampled.0.bed
│ └── ...
├── 2_binarise/
│ ├── 0_chr1_binary.txt
│ └── ...
├── completeness.txt
├── completeplot.jpg
├── mm.txt
└── mmplot.jpg
Downsampled files are generated in <outdir>/1_subsample/ and binarised files in <outdir>/2_binarise/.
Information on how to interpret the output plots, completeplot.jpg and mmplot.jpg can be found in interpretation.
Basic usage#
$ chromTools complete \
--files/-f <reads.bed> \
--control/-c <controlreads.bed> \
--increment/-i <int> \
--outdir/-o <outdir> \
--genome/-g <genome> \
--gsize <int> \
--seed/-s <int> \
--paired \
--force-overwrite
Required parameters#
--files/-f <reads.bed>: BED files of the dataset. Must be aligned files. Should include full path to file.
Optional parameters#
--control/-c <controlreads.bed>: Optional flag containing BED-formatted control files. Must include full path. If unspecified, flag is set to FALSE.
--outdir/-o <outdir>: Path to output directory where structure <outdir>/1_subsample/ <outdir>/2_binarise/ and output files will be created. Directory will be created if it does not exist. Default: current working directory.
--increment/-i <int>: Amount of reads/read pairs by which to incrementally subsample. e.g. If left to default the whole dataset will be subsampled to 50000000, 100000000, 150000000 etc. Default: 50000000.
--genome/-g: A two column tab delimited file with the first column being the chromosome and the second being the chromosome length. Genome assemblies hg18, hg19, hg38, mm9, mm10, rn5, rn6, danRer7, danRer10, dm3, dm6, ce6, and ce10 can be accessed by their genome assembly name (e.g. hg19). For other assemblies these can be obtained with the fetchChromSizes script available from the UCSC browser http://hgdownload.cse.ucsc.edu/admin/exe/ specifying the desired assembly and redirecting the output to a text file. Default: hg38.
--gsize <int>: Size of genome using. Required if specifying own genome chromosome length file. Default: FALSE
--seed <int>: The seed used for initiating randomization operations. Default: randomly generated.
--paired: If specified, data will be treated as paired end. Default: FALSE.
--force-overwrite: If specified, files and directories in outdir will be overwritten. Default: FALSE.
Example Usage#
In the repository are the test files test_s1.bed and test_s2.bed which we will use as input in this toy example.
$ head(test_s1.bed)
chr1 10060 10160 SIM:chr1:10060:141:0:303:312/1 31 +
chr1 10061 10161 SIM:chr1:10061:151:0:127:706/2 30 +
chr1 10102 10202 SIM:chr1:10060:141:0:303:312/2 31 -
chr1 10113 10213 SIM:chr1:10061:151:0:127:706/1 30 -
chr1 10141 10241 SIM:chr1:10141:177:0:628:797/1 34 +
chr1 10219 10319 SIM:chr1:10141:177:0:628:797/2 34 -
chr1 10234 10334 SIM:chr1:10234:185:0:691:1077/2 34 +
chr1 10285 10385 SIM:chr1:10285:157:0:141:974/1 34 +
chr1 10320 10420 SIM:chr1:10234:185:0:691:1077/1 34 -
chr1 10330 10430 SIM:chr1:10330:135:0:97:369/2 30 +
$ head(test_s2.bed)
chr1 10048362 10048462 SIM:chr1:10048296:165:0:290:850/2 42 -
chr1 10048389 10048489 SIM:chr1:10048389:152:0:6:1502/1 42 +
chr1 10048411 10048511 SIM:chr1:10048341:169:0:24:239/1 42 -
chr1 10048442 10048542 SIM:chr1:10048389:152:0:6:1502/2 42 -
chr1 10048465 10048565 SIM:chr1:10048465:149:0:502:195/1 42 +
chr1 10048471 10048571 SIM:chr1:10048471:139:0:482:347/2 42 +
chr1 10048502 10048602 SIM:chr1:10048502:168:0:759:1475/2 42 +
chr1 10048511 10048611 SIM:chr1:10048471:139:0:482:347/1 42 -
chr1 10048515 10048615 SIM:chr1:10048465:149:0:502:195/2 42 -
chr1 10048571 10048671 SIM:chr1:10048502:168:0:759:1475/1 42 -
Once chromTools has been installed, the following command can be run. As this is paired data we are specifying the --paired flag. Make sure you are in the directory where the test files are located.
$ chromTools complete -f test_s1.bed test_s2.bed --outdir tmp/ --increment 25 --genome hg37 --paired
This will create the directory tmp/ and subdirectories within this and provide an output for interpretation.
Interpretation#
In the output two plots are generated, mmplot.jpg and completeplot.jpg.
completeplot shows the proportion of marks found, plotted against the read number.
mmplot gives an indication of the saturation point of the dataset, i.e. the proportion of marks present. The more complete a dataset is, the more accurate this will be. It also gives an indication of the read number at which the proportion is roughly half of the saturation point
In this plot, you can see an example of a complete dataset. Here, the proportion of marks has reached a plateau where even with the addition of more reads, there is not an increase in information. Therefore, this indicates that the dataset represents the totality of possible marks.
By contrast, in the plot below you can see that with each incremental increase in reads, there is an almost equivalent gain in information, with no indication of saturation. This therefore indicates that this dataset is incomplete.
