Contents


Package: nucleoSim
Authors: Rawane Samb [aut], Astrid Deschênes [cre, aut], Pascal Belleau [aut], Arnaud Droit [aut]
Version: 1.8.0
Compiled date: 2018-04-30
License: Artistic-2.0

1 Licensing and citing

This package and the underlying nucleoSim code are distributed under the Artistic license 2.0. You are free to use and redistribute this software.

If you use this package for a publication, we would ask you to cite the following:

Samb R, Khadraoui K, Belleau P, et al. (2015). “Using informative Multinomial-Dirichlet prior in a t-mixture with reversible jump estimation of nucleosome positions for genome-wide profiling.” Statistical Applications in Genetics and Molecular Biology. Volume 14, Issue 6, Pages 517–532, ISSN (Online) 1544-6115, ISSN (Print) 2194-6302, December 2015. doi: 10.1515/sagmb-2014-0098

Flores O et Orozco M (2011). “nucleR: a package for non-parametric nucleosome positioning.” Bioinformatics, 27, pp. 2149–2150. doi: 10.1093/bioinformatics/btr345

2 Introduction

nucleoSim can simulate datasets for nucleosomes experiments.

The nucleoSim package generates synthetic maps with sequences covering nucleosome regions as well as synthetic maps with forward and reverse reads (paired-end reads) emulating next-generation sequencing. Furthermore, synthetic hybridization data of “Tiling Arrays” can also be generated.

The nucleoSim package allows the user to introduce various ‘contaminants’ into the sequence datasets, such as fuzzy nucleosomes and missing nucleosomes, in order to be more realistic and to enable the evaluation of the influence of common ‘noise’ on the detection of nucleosomes.

The nucleoSim package has been largely inspired by the Generating synthetic maps section of the Bioconductor nucleR package (Flores et Orozco, 2011).

3 Loading nucleoSim package

As with any R package, the nucleoSim package should first be loaded with the following command:

library(nucleoSim)

4 Description

The packages can generate 2 types of synthetic data sets:

Synthetic Nucleosome Maps: A map with complete sequences covering the nucleosome regions

Synthetic Nucleosome Samples: A map with forward and reverse reads (paired-end reads) emulating those obtained using a next-generation sequencing technology on a nucleosome map

4.1 Synthetic Nucleosome Maps

A synthetic nucleosome map is a section of genome covered by a fixed number of nucleosomes. Each nucleosome being associated with a specific number of sequences. The parameters passed to the syntheticNucMapFromDist() function are going to affect the distribution of the nucleosomes, as well as, the sequences associated with each nucleosome.

Technically, the synthetic nucleosome map is separated into 3 steps:

1. Adding well-positioned nucleosomes

The synthetic nucleosome map is split into a fixed number of sections (wp.num) of equal length ((nuc.len + lin.len) bases). The center of the nucleosomes is positioned at a fixed number of bases from the beginning of each section (round(nuc.len/2) bases). Sequences are assigned, to each nucleosome, using an uniform distribution. The number of sequences, assigned to each nucleosome, can vary from 1 to max.cover. The distribution (distr), as well as the variance (wp.var) are used to add some fluctuation to the starting position of the sequences, which as a mean position corresponding to the starting position of a region. Some fluctuation of the length of the sequence is also added following a normal distribution with a fixed variance (len.var). The mean length of the sequences corresponds to the length of the nucleosomes (nuc.len).

2. Deleting some well-positioned nucleosomes

A fixed number of nucleosomes (wp.del) are deleted. Each nucleosome has an equal probability to be deleted. A nucleosome is considered deleted when all sequences associated with it are eliminated.

3. Adding fuzzy nucleosomes

A fixed number of fuzzy nucleosomes (fuz.num) are added. The position of the fuzzy nucleosomes is selected following an uniform distribution. Such as for the well-positioned nucleosomes, sequences are assigned, to each fuzzy nucleosome, using an uniform distribution. The number of sequences assigned can vary from 1 to max.cover. The distribution (distr), as well as the variance (wp.var) are used to add some fluctuation to the starting position of the sequences, which as a mean position corresponding to the starting position of a region. Some fluctuation of the length of the sequence is also added following a normal distribution with a fixed variance (len.var). The mean length of the sequences corresponds to the length of the nucleosomes (nuc.len).

4.1.1 Create a nucleosome map using syntheticNucMapFromDist()

This is an example showing how a synthetic nucleosome map can be generated.

wp.num           <- 20         ### Number of well-positioned nucleosomes
wp.del           <- 5          ### Number of well-positioned nucleosomes to delete
wp.var           <- 30         ### variance associated with the starting 
                               ###   position of the sequences of the 
                               ###   well-positioned nucleosomes
fuz.num          <- 5          ### Number of fuzzy nucleosomes
fuz.var          <- 50         ### Variance associated with the starting 
                               ###   positions of the sequences for the 
                               ###   fuzzy nucleosomes
max.cover        <- 70         ### Maximum sequences associated with one 
                               ###   nucleosome (default: 100)
nuc.len          <- 147        ### Length of the nucleosome (default: 147)
len.var          <- 12         ### variance associated with the length of 
                               ###   the sequences (default: 10)
lin.len          <- 20         ### Length of the DNA linker (default: 20)
distr            <- "Normal"   ### Type of distribution to use

rnd.seed         <- 210001     ### Set seed when result needs to be reproducible
        
#### Create a synthetic nucleosome map
nucleosomeMap <- syntheticNucMapFromDist(wp.num=wp.num, wp.del=wp.del, 
                        wp.var=wp.var, fuz.num=fuz.num, fuz.var=fuz.var, 
                        max.cover=max.cover, nuc.len=nuc.len, len.var=len.var, 
                        lin.len=lin.len, rnd.seed=rnd.seed, distr=distr)

#### The start positions of all well-positioned nucleosomes
nucleosomeMap$wp.starts
##  [1]    1  168  335  502  836 1003 1170 1504 1671 2005 2506 2673 2840 3007
## [15] 3174

#### The number of sequences associated with each well-positioned nucleosome
nucleosomeMap$wp.nreads
##  [1] 69 54 59 36 66 20 65 60 69 65 42  5 23 39 48

#### IRanges object containing all sequences for the well-positioned nucleosomes
head(nucleosomeMap$wp.reads, n = 2)
## IRanges object with 2 ranges and 0 metadata columns:
##           start       end     width
##       <integer> <integer> <integer>
##   [1]         3       148       146
##   [2]        -1       152       154

#### The start positions of all fuzzy nucleosomes
nucleosomeMap$fuz.starts
## [1]  444 1911  987 3266 2524

#### The number of sequences associated with each fuzzy nucleosome
nucleosomeMap$fuz.nreads
## [1] 60 38 22 35 57

#### A IRanges object containing all sequences for the fuzzy nucleosomes
head(nucleosomeMap$fuz.reads, n = 2)
## IRanges object with 2 ranges and 0 metadata columns:
##           start       end     width
##       <integer> <integer> <integer>
##   [1]       450       601       152
##   [2]       442       587       146

#### A IRanges object containing all sequences for all nucleosomes
head(nucleosomeMap$syn.reads, n = 2)
## IRanges object with 2 ranges and 0 metadata columns:
##           start       end     width
##       <integer> <integer> <integer>
##   [1]         3       148       146
##   [2]        -1       152       154

The synthetic nucleosome map can easily be visualized using plot() function. On the graph, each nucleosome is located on the graph using the coordonnates:

(x,y) = (the central position of the nucleosome, the number of sequences associated with the nucleosome)

#### Create visual representation of the synthetic nucleosome map
plot(nucleosomeMap, xlab="Position", ylab="Coverage")

4.1.2 Simulate hybridization data of Tiling Arrays

The syntheticNucMapFromDist() function contains an option (as.ratio) which enable the simulation of hybridization data of “Tiling Arrays”. The data are generated by calculating the ratio between the nucleosome map and a control map of random sequences created using a uniform distribution. The control map simulates a DNA randomly fragmented sample.

This is an example showing how a synthetic nucleosome map can be generated.

as.ratio         <- TRUE       ### Activate the simulation of hybridization data
rnd.seed         <- 212309     ### Set seed when result needs to be reproducible
        
#### Create a synthetic nucleosome map with hybridization data
nucleosomeMapTiling <- syntheticNucMapFromDist(wp.num=10, wp.del=2, wp.var=20, 
                                    fuz.num=1, fuz.var=32, max.cover=50,
                                    nuc.len=145, len.var=3, lin.len=40, 
                                    rnd.seed=rnd.seed, as.ratio=as.ratio,
                                    distr="Uniform")

#### Control sequences for hybridization data (only when as.ratio = TRUE)
head(nucleosomeMapTiling$ctr.reads, n=4)
## IRanges object with 4 ranges and 0 metadata columns:
##           start       end     width
##       <integer> <integer> <integer>
##   [1]        33       195       163
##   [2]       821      1022       202
##   [3]       705       832       128
##   [4]      1399      1461        63

#### Ratio for hybridization data (only when as.ratio = TRUE)
head(nucleosomeMapTiling$syn.ratio, n=4)
## numeric-Rle of length 4 with 1 run
##   Lengths: 4
##   Values : 0

#### Create visual representation of the synthetic nucleosome map
plot(nucleosomeMapTiling)

4.2 Synthetic Nucleosome Samples

A synthetic nucleosome sample is a map with forward and reverse reads (paired-end reads) emulating those obtained using a next-generation sequencing technology. It is created using the same first 3 steps than the synthetic nucleosome map. However, some new steps are present:

1. Adding well-positioned nucleosomes

The synthetic nucleosome map is split into a fixed number of sections (wp.num) of equal length ((nuc.len + lin.len) bases). The center of the nucleosomes are positioned at a fixed number of bases from the beginning of each section (round(nuc.len/2) bases). Paired-end reads are assigned, to each nucleosome, using an uniform distribution. The number of paired-end reads, assigned to each nucleosome, can vary from 1 to max.cover. The distribution (distr), as well as the variance (wp.var) are used to add some fluctuation to the starting position of the forward reads, which as a mean position corresponding to the starting position of a region. Some fluctuation of the distance between start positions of paired-end reads is added following a normal distribution with a fixed variance (len.var). The mean distance between start positions of paired-end reads corresponds to the length of the nucleosomes (nuc.len).

2. Deleting some well-positioned nucleosomes

A fixed number of nucleosomes (wp.del) are deleted. Each nucleosome has an equal probability to be deleted. A nucleosome is considered deleted when all paired-end reads associated with it are eliminated.

3. Adding fuzzy nucleosomes

A fixed number of fuzzy nucleosomes (fuz.num) are added. The position of the fuzzy nucleosomes is selected following an uniform distribution. Such as for the well-positioned nucleosomes, reads are assigned, to each fuzzy nucleosome, using an uniform distribution. The number of paired-end reads assigned can vary from 1 to max.cover. The distribution (distr), as well as the variance (wp.var) are used to add some fluctuation to the starting position of the forward reads, which as a mean position corresponding to the starting position of a region. Some fluctuation of the distance between start positions of paired-end reads is also added following a normal distribution with a fixed variance (len.var). The mean distance between start positions of paired-end reads corresponds to the length of the nucleosomes (nuc.len). All reads have a fixed length (read.len).

4. Adding an offset

An offset (offset) is added to all nucleosomes and reads positions to ensure that all values are positive (mainly pertinent for reads).

4.2.1 Create a nucleosome sample using syntheticNucReadsFromDist()

This function needs information about the nucleosomes and their distribution to generate a nucleosome sample. The output is of class syntheticNucMap.

wp.num           <- 30            ### Number of well-positioned nucleosomes
wp.del           <- 10            ### Number of well-positioned nucleosomes 
                                  ###   to delete
wp.var           <- 30            ### variance associated with the starting 
                                  ###   positions of the sequences for the 
                                  ###   well-positioned nucleosomes
fuz.num          <- 10            ### Number of fuzzy nucleosomes
fuz.var          <- 50            ### Variance associated with the starting 
                                  ###   positions of the sequences for the 
                                  ###   fuzzy nucleosomes
max.cover        <- 90            ### Maximum paired-end reads associated with 
                                  ###   one nucleosome (default: 100)
nuc.len          <- 147           ### Length of the nucleosome (default: 147)
len.var          <- 12            ### variance associated with the distance 
                                  ###   between start positions of 
                                  ###   paired-end reads (default: 10)
lin.len          <- 20            ### Length of the DNA linker (default: 20)
read.len         <- 45            ### Length of the generated forward and 
                                  ###   reverse reads (default: 40)
distr            <- "Uniform"     ### Type of distribution to use
offset           <- 10000         ### The number of bases used to offset 
                                  ###   all nucleosomes and reads

rnd.seed         <- 202           ### Set seed when result needs to be 
                                  ###   reproducible
        
#### Create Uniform sample
nucleosomeSample <- syntheticNucReadsFromDist(wp.num=wp.num, wp.del=wp.del, 
                        wp.var=wp.var, fuz.num=fuz.num, fuz.var=fuz.var, 
                        max.cover=max.cover, nuc.len=nuc.len, len.var=len.var, 
                        read.len=read.len, lin.len=lin.len, rnd.seed=rnd.seed, 
                        distr=distr, offset=offset)

#### The central position of all well-positioned nucleosomes with the
#### number of paired-end reads each associated with each one
head(nucleosomeSample$wp, n = 2)
##   nucleopos nreads
## 1     10075     12
## 2     10242     61

#### The central position of all fuzzy nucleosomes with the
#### number of paired-end reads each associated with each one
head(nucleosomeSample$fuz, n = 2)
##   nucleopos nreads
## 1     10167     56
## 2     14073     38

#### A data.frame with the name of the synthetic chromosome, the starting 
#### position, the ending position and the direction of all forward and
#### reverse reads
head(nucleosomeSample$dataIP, n = 2)
##             chr start   end strand ID
## 1 chr_SYNTHETIC  9973 10018      + 12
## 2 chr_SYNTHETIC  9987 10032      +  4

The synthetic nucleosome sample can easily be visualized using plot() function. On the graph, each nucleosome is located on the graph using the coordinates:

(x,y) = (the central position of the nucleosome, the number of paired-end reads associated with the nucleosome)

#### Create visual representation of the synthetic nucleosome sample
plot(nucleosomeSample, xlab="Position", ylab="Coverage (number of reads)")

4.2.2 Create a nucleosome sample using syntheticNucReadsFromMap()

A synthetic nucleosome sample can be created using a nucleosome map. The nucleosomes and reads present in the nucleosome map will be added an offset. Forward and reverse reads will also be generated. The output is of class syntheticNucMap.


#### A nucleosome map has already been created 
class(nucleosomeMap)
## [1] "syntheticNucMap"

#### 
read.len    <- 45   ### The length of the reverse and forward reads
offset      <- 500  ### The number of bases used to offset all nucleosomes and reads

#### Create nucleosome sample
nucleosomeSampleFromMap <- syntheticNucReadsFromMap(nucleosomeMap, 
                                        read.len=read.len, offset=offset)

#### A data.frame with the name of the synthetic chromosome, the starting 
#### position, the ending position and the direction of all forward and
#### reverse reads
head(nucleosomeSampleFromMap$dataIP, n = 2)
##             chr start end strand ID
## 1 chr_SYNTHETIC   490 535      + 10
## 2 chr_SYNTHETIC   490 535      + 23

5 Session info

Here is the output of sessionInfo() on the system on which this document was compiled:

## R version 3.5.0 (2018-04-23)
## Platform: x86_64-pc-linux-gnu (64-bit)
## Running under: Ubuntu 16.04.4 LTS
## 
## Matrix products: default
## BLAS: /home/biocbuild/bbs-3.7-bioc/R/lib/libRblas.so
## LAPACK: /home/biocbuild/bbs-3.7-bioc/R/lib/libRlapack.so
## 
## locale:
##  [1] LC_CTYPE=en_US.UTF-8       LC_NUMERIC=C              
##  [3] LC_TIME=en_US.UTF-8        LC_COLLATE=C              
##  [5] LC_MONETARY=en_US.UTF-8    LC_MESSAGES=en_US.UTF-8   
##  [7] LC_PAPER=en_US.UTF-8       LC_NAME=C                 
##  [9] LC_ADDRESS=C               LC_TELEPHONE=C            
## [11] LC_MEASUREMENT=en_US.UTF-8 LC_IDENTIFICATION=C       
## 
## attached base packages:
## [1] stats     graphics  grDevices utils     datasets  methods   base     
## 
## other attached packages:
## [1] nucleoSim_1.8.0 knitr_1.20      BiocStyle_2.8.0
## 
## loaded via a namespace (and not attached):
##  [1] Rcpp_0.12.16        bookdown_0.7        IRanges_2.14.0     
##  [4] digest_0.6.15       rprojroot_1.3-2     backports_1.1.2    
##  [7] stats4_3.5.0        magrittr_1.5        evaluate_0.10.1    
## [10] stringi_1.1.7       S4Vectors_0.18.0    rmarkdown_1.9      
## [13] tools_3.5.0         stringr_1.3.0       parallel_3.5.0     
## [16] xfun_0.1            yaml_2.1.18         compiler_3.5.0     
## [19] BiocGenerics_0.26.0 htmltools_0.3.6