Contents

1 Version Info

R version: R Under development (unstable) (2023-10-22 r85388)
Bioconductor version: 3.19
Package version: 1.17.0

2 Introduction

Biological information encoded in the DNA sequence is often organized into independent modules or clusters. For instance, the eukaryotic system of expression relies on combinations of homotypic or heterotypic transcription factors (TFs) which play an important role in activating and repressing target genes. Identifying clusters of genomic features is a frequent task and includes application such as genomic regions enriched for the presence of a combination of transcription factor binding sites or enriched for the presence of mutations often referred as regions with increase mutational hotspots.

fcScan is designed to detect clusters of genomic features, based on user defined search criteria. Such criteria include:

fcScan is designed to handle large number of genomic features (i.e data generated by High Throughput Sequencing).

3 Dependencies

fcScan depends on the following packages:

4 Overview

Currently, fcScan has one main function, the getCluster function. Additional functionality will be added for future releases including cross-species identification of orthologous clusters.

5 Input arguments for getCluster

5.1 Input data (x)

The input for getCluster is given through the parameter x. This function accepts input in data frame, GRanges as well as vector of files in BED and VCF (compressed or not) formats. BED and VCF files are loaded by packages rtracklayer and VariantAnnotation respectively. There is no limit to the number of files the user can define.

When input is data frame or GRanges objects are given, they should contain the following “named” 5 columns:

  • seqnames : Contains the seqname name
  • start: Contains the start coordinates
  • end: Contains the end coordinates
  • strand: Contains the strand relative to each site
  • site : Contains the category name relative to genomic site
seqnames start end strand site
chr1 10 15 + a
chr1 17 20 + b
chr1 25 30 + b
chr1 27 35 + a
chr1 32 40 + c
chr1 41 48 + b

The seqnames, start and end columns define the name of the chromosome, the starting and ending position of the feature in the chromosome, respectively. The strand column defines the strand. The site column contains the ID of the site and will be used for clustering. The start and end columns are numeric while the remaining columns are characters.

Note: when input is data frame, the data is considered zero-based as in BED format.

5.2 Window Size (w)

Window size is set using w. It defines the maximum size of the clusters.

5.3 Condition (c)

The clustering condition c defines the number and name of genomic features to search for based on features names defined in the site column c = c("a" = 1, "b" = 2)
This searches for clusters with 3 sites, One a site and two b sites.

Another way of writing the condition, only if input is a vector to file paths, is the following x = ("a.bed", "b.bed"), c = c(1,2)
Given 2 files, a.bed and b.bed, this condition states that the user is looking for clusters made from 1 “a” site and 2 “b” sites. In this case, the order of sites defined in c is relative to the order of files.

When input is a data frame or GRanges object (instead of files), the user needs to explicitly define the site names along with the desired number relative to each site. For instance, giving the condition as c = c(1,2) for a data frame or GRanges is not allowed.

x = dataframe, c = c("a" = 1, "b" = 2) where a and b are valid site names in site column in the dataframe/GRanges

Users can exclude clusters containing a specific site(s). This is done by specifying zero 0 in the condition as c = c("a" = 1, "b" = 2, "c" = 0). In this case, any cluster(s) containing c site will be excluded even if it has 1 a and 2 b sites.

5.4 Seqnames (seqnames) and Strand (s).

By default, clustering will be performed on both strands and on all seqnames unless specified by the user using the s and seqnames arguments to limit the search on a specific strand and/or seqname.

Users can choose to cluster on one specific seqname (seqnames = "chr1"), or on several seqnames (seqnames = c("chr1","chr3","chr4"))
(Default for seqnames is NULL) meaning that clustering on all seqnames will be performed.

For s, the values allowed are:

  • + : Build clusters on positive strand
  • - : Build clusters on negative strand
  • * : Clusters are not strand specific
    (Default is set to *)

5.5 Overlap (overlap)

The gap/overlap between adjacent clusters, and not sites, can be controled using the overlap option. When overlap is a positive integer, adjacent clusters will be separated by a minimum of the given value. When overlap is negative, adjacent clusters will be allowed to overlap by a maximum of the given value. (Default is set to 0)

5.6 Greedy vs Non-Greedy (greedy)

greedy allows the user to control the number of genomic features found in clusters.

When greedy = FALSE, getCluster will build clusters having the required window size and will label TRUE the ones that contain the exact number of sites provided in the condition argument. Clusters having the user defined window size but not satisfying the condition will be labelled as FALSE.

When greedy = TRUE, additional sites defined in condition will be added to the cluster as long as the cluster size is below the defined window size. (Default is set to FALSE)

5.7 Order (order)

The order option defines the desired order of the sites within identified clusters. For instance, order = c("a","b","b") will search for clusters containing 1 a and 2 b sites and checks if they are in the specified order. Clusters with 1 a and 2 b sites that do not contain the specified order will be rejected. When greedy is set to TRUE, order can be satisfied if a subcluster contains the desired order. For example if a cluster has a, a, b, b, b sites, it satisfies the required order (a, b, b) and therefore will be considered as a correct cluster . (Default is set to NULL)

5.8 Sites Orientation (site_orientation)

The site_orientation option defines the orientation or strandness of sites in the found clusters. This option cannot be used if order is NULL. site_orientation should be specified for each site in order. For instance, if order = c("a","b","b"), we can define site_orientation for each site respectively as follow: site_orientation = c("+","-","-"). The cluster will be correct if it satisfies the required order and sites orientation. (Default is set to NULL)

5.9 Distance between sites in clusters (site_overlap)

The site_overlap option defines the maximum or minimum distance allowed between sites in the cluster. When site_overlap is a positive integer, sites within a cluster should have minimum distance and above, then the cluster is considered TRUE cluster. When site_overlap is a negative integer, sites within a cluster should have max distance and below, then the cluster is considered TRUE cluster. When site_overlap is zero, distance between sites is not taken into consideration. (Default is set to 0)

5.10 Clustering option (cluster_by)

The cluster_by option allows the usage of different ways in scanning for sites. Using this option, scanning does not ‘jump’ clusters found. cluster_by can be startsEnds, endsStarts, starts, ends, or middles. If we choose startsEnds, the clustering begins at the start of the first site and it ends at the end of the last site within the window size. If we choose endsStarts, scanning begins at the end of the first site and it ends at the start of the last site within the window size. if we choose starts, the clustering begins at the start of the first site and it ends at the start of the last site within the window size. if we choose ends, the clustering begins at the end of the first site and it ends at the end of the last site within the window size. Also, if we choose middles, the clustering begins at the middle of the first site and it ends at the middle of the last site within the window size. (Default is set to startsEnds)

5.11 Overlapping Clusters option (allow_clusters_overlap)

The allow_clusters_overlap allows the user whether to include overlapping clusters or not. (Default is set to FALSE)

5.12 Include partially overlapping sites (include_partial_sites)

This option can be only used in case where the “cluster_by” choosen is “startsEnds” or “ends”, otherwise it is ignored. If it is set to TRUE, partially overlapping sites within window size (at the end of the cluster) are allowed. However, if it is set to FALSE, partially overlapping sites are not included in the cluster found. (Default is set to FALSE)

5.13 Control addition of partially overlapping sites (partial_overlap_percentage)

This option allows the user to choose which partially overlapping site are included. The amount of overlap between the last site found and the window size controls the addition or removal of those sites. For example, if partial_overlap_percentage is set to 0.6, this means that the window size should overlap this site by 60% of its size. However, if it fails, this site won’t be included in the cluster found. This option can be only used in case where the “cluster_by” chosen is “startsEnds” or “ends”, otherwise it is ignored. (Default is set to NULL)

5.14 Multi-threading (threads)

This option allows to distribute the run over multiple threads. It is recommended to use multiple threads when the input dataset is large. When threads is set to 0, getCluster reserves the adequate number of threads and performs the run. This will dramatically increase the speed of getCluster. The user can choose the number of threads between 1 and the maximum number of available threads. (Default is set to 1)

5.15 Verbose (verbose)

The verbose option allows the printing of additional messages and the list of clusters that failed for lack of correct combination of sites. This option is used mainly for debugging purposes. (Default is set to FALSE)

6 Output of getCluster

The output of getCluster is a GRanges object with fields:

The algorithm returns all clusters containing the correct count of sites/features, unless verbose is set to TRUE. If the combination, overlap and order options are satisfied, the cluster is considered a TRUE cluster.

The status of a cluster can be either PASS, excludedSites, orderFail, siteOrientation or siteOverlap PASS is a cluster that satisfied the desired combination, overlap, order and sites orientation. orderFail is a cluster that had the required combination but did not satisfy the required order of sites. excludedSites is a cluster that had the required combination and order but it has one or more sites to exclude. siteOrientation is a cluster that had the required combination and order but it has one or more sites with different orientation than requested. siteOverlap is a cluster that meets all the requirements but the distance between its sites is not respected.

NOTE: If the user is using greedy = FALSE and order contains values more than in the condition parameter (c), an error will be raised. However, if greedy = TRUE, then using order with more values than the condition parameter is allowed since the cluster may contain more sites than the required c condition as long as the window size is satisfied.

7 Example on Clustering

Example using getCluster:

getCluster looks for desired genomic regions of interest like transcription factor binding sites, within a window size and specific condition.

This function accepts a data frame and GRanges object. getCluster also accepts BED or VCF (or mix of both) files as input. The output of getCluster is a GRanges object that contains the genomic coordinates (seqnames, ranges and strand) and three metadata columns:

  1. sites: contains clusters of sites that conforms with the condition c specified in getCluster.

  2. isCluster: TRUE if the cluster found conform with the condition c and the order (if indicated in condition) and FALSE if the cluster fails to conform with the condition or order.

  3. status: PASS if isCluster equals TRUE. However, if isCluster is FALSE, status shows why the found cluster is not a TRUE cluster. If the order of sites is not respected in the found cluster, status would return OrderFail. in Addition, if the cluster found contains non desired sites, it returns excludedSites. Moreover, if the sites orientation is not respected in found cluster, status would return siteOrientation. Finally , if the distance between sites in the cluster found does not conform to the condition specified by the user, status would return siteOverlap.

In this example, we ask getCluster to look for clusters that contains one site “s1”, one site “s2” and zero “s3” sites. In addition, we requested clusters to have sites in the order s1,s2 and having orientation “+”,“+” respectively with minimum distance between sites of 2bp.

x1 = data.frame(seqnames = rep("chr1", times = 17),
    start = c(1,10,17,25,27,32,41,47,60,70,87,94,99,107,113,121,132),
    end = c(8,15,20,30,35,40,48,55,68,75,93,100,105,113,120,130,135),
    strand = c("+","+","+","+","+","+","+","+","+",
        "+","+","+","+","+","+","+","-"),
    site = c("s3","s1","s2","s2","s1","s2","s1","s1","s2","s1","s2",
        "s2","s1","s2","s1","s1","s2"))

clusters = getCluster(x1, w = 20, c = c("s1" = 1, "s2" = 1, "s3" = 0), 
    greedy = TRUE, order = c("s1","s2"), site_orientation=c("+","+"), 
    site_overlap = 2, verbose = TRUE)
#> 17  entries loaded 
#> Running getCluster using 1 threads
#> Time difference of 0.2321353 secs

clusters
#> GRanges object with 9 ranges and 3 metadata columns:
#>       seqnames    ranges strand |       sites isCluster          status
#>          <Rle> <IRanges>  <Rle> | <character> <logical>     <character>
#>   [1]     chr1      2-20      * |    s3,s1,s2     FALSE   excludedSites
#>   [2]     chr1     11-30      * |    s1,s2,s2      TRUE            PASS
#>   [3]     chr1     33-48      * |       s2,s1     FALSE       orderFail
#>   [4]     chr1     48-68      * |       s1,s2      TRUE            PASS
#>   [5]     chr1    88-105      * |    s2,s2,s1     FALSE       orderFail
#>   [6]     chr1    95-113      * |    s2,s1,s2     FALSE     siteOverlap
#>   [7]     chr1   100-120      * |    s1,s2,s1     FALSE     siteOverlap
#>   [8]     chr1   108-120      * |       s2,s1     FALSE       orderFail
#>   [9]     chr1   122-135      * |       s1,s2     FALSE siteOrientation
#>   -------
#>   seqinfo: 1 sequence from an unspecified genome; no seqlengths

Another example but using GRanges as input: in this example, we ask getCluster to look for clusters that contains one site s1 and two sites s2 within a window size of 25 bp. Also, we requested clusters to be searched as + strand.

suppressMessages(library(GenomicRanges))

x = GRanges(
    seqnames = Rle("chr1", 16),
    ranges = IRanges(start = c(10L,17L,25L,27L,32L,41L,47L,
        60L,70L,87L,94L,99L,107L,113L,121L,132L),
    end = c(15L,20L,30L,35L,40L,48L,55L,68L,75L,93L,100L,105L,
        113L,120L,130L,135L)),
    strand = Rle("+",16),
    site = c("s1","s2","s2","s1","s2","s1","s1","s2",
        "s1","s2","s2","s1","s2","s1","s1","s2"))
    
clusters = getCluster(x, w = 25, c = c("s1"=1,"s2"=2), s = "+")
#> 16  entries loaded 
#> Running getCluster using 1 threads
#> Time difference of 0.1575594 secs

clusters
#> GRanges object with 2 ranges and 3 metadata columns:
#>       seqnames    ranges strand |       sites isCluster      status
#>          <Rle> <IRanges>  <Rle> | <character> <logical> <character>
#>   [1]     chr1     10-30      + |    s1,s2,s2      TRUE        PASS
#>   [2]     chr1    87-105      + |    s2,s2,s1      TRUE        PASS
#>   -------
#>   seqinfo: 1 sequence from an unspecified genome; no seqlengths

8 Session Info

sessionInfo() 
#> R Under development (unstable) (2023-10-22 r85388)
#> Platform: x86_64-pc-linux-gnu
#> Running under: Ubuntu 22.04.3 LTS
#> 
#> Matrix products: default
#> BLAS:   /home/biocbuild/bbs-3.19-bioc/R/lib/libRblas.so 
#> LAPACK: /usr/lib/x86_64-linux-gnu/lapack/liblapack.so.3.10.0
#> 
#> locale:
#>  [1] LC_CTYPE=en_US.UTF-8       LC_NUMERIC=C              
#>  [3] LC_TIME=en_GB              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       
#> 
#> time zone: America/New_York
#> tzcode source: system (glibc)
#> 
#> attached base packages:
#> [1] stats     graphics  grDevices utils     datasets  methods   base     
#> 
#> other attached packages:
#> [1] GenomicRanges_1.55.0 IRanges_2.37.0       S4Vectors_0.41.0    
#> [4] fcScan_1.17.0        BiocStyle_2.31.0    
#> 
#> loaded via a namespace (and not attached):
#>  [1] tidyselect_1.2.0            dplyr_1.1.3                
#>  [3] blob_1.2.4                  filelock_1.0.2             
#>  [5] Biostrings_2.71.1           bitops_1.0-7               
#>  [7] fastmap_1.1.1               RCurl_1.98-1.12            
#>  [9] BiocFileCache_2.11.0        VariantAnnotation_1.49.0   
#> [11] GenomicAlignments_1.39.0    XML_3.99-0.14              
#> [13] digest_0.6.33               lifecycle_1.0.3            
#> [15] KEGGREST_1.43.0             RSQLite_2.3.1              
#> [17] magrittr_2.0.3              compiler_4.4.0             
#> [19] rlang_1.1.1                 sass_0.4.7                 
#> [21] progress_1.2.2              tools_4.4.0                
#> [23] utf8_1.2.4                  yaml_2.3.7                 
#> [25] rtracklayer_1.63.0          knitr_1.44                 
#> [27] prettyunits_1.2.0           S4Arrays_1.3.0             
#> [29] bit_4.0.5                   curl_5.1.0                 
#> [31] DelayedArray_0.29.0         xml2_1.3.5                 
#> [33] plyr_1.8.9                  abind_1.4-5                
#> [35] BiocParallel_1.37.0         BiocGenerics_0.49.0        
#> [37] grid_4.4.0                  stats4_4.4.0               
#> [39] fansi_1.0.5                 iterators_1.0.14           
#> [41] biomaRt_2.59.0              SummarizedExperiment_1.33.0
#> [43] cli_3.6.1                   rmarkdown_2.25             
#> [45] crayon_1.5.2                generics_0.1.3             
#> [47] httr_1.4.7                  rjson_0.2.21               
#> [49] DBI_1.1.3                   cachem_1.0.8               
#> [51] stringr_1.5.0               zlibbioc_1.49.0            
#> [53] parallel_4.4.0              AnnotationDbi_1.65.0       
#> [55] BiocManager_1.30.22         XVector_0.43.0             
#> [57] restfulr_0.0.15             matrixStats_1.0.0          
#> [59] vctrs_0.6.4                 Matrix_1.6-1.1             
#> [61] jsonlite_1.8.7              bookdown_0.36              
#> [63] hms_1.1.3                   bit64_4.0.5                
#> [65] GenomicFeatures_1.55.0      foreach_1.5.2              
#> [67] jquerylib_0.1.4             glue_1.6.2                 
#> [69] codetools_0.2-19            stringi_1.7.12             
#> [71] GenomeInfoDb_1.39.0         BiocIO_1.13.0              
#> [73] tibble_3.2.1                pillar_1.9.0               
#> [75] rappdirs_0.3.3              htmltools_0.5.6.1          
#> [77] BSgenome_1.71.0             GenomeInfoDbData_1.2.11    
#> [79] R6_2.5.1                    dbplyr_2.3.4               
#> [81] doParallel_1.0.17           evaluate_0.22              
#> [83] lattice_0.22-5              Biobase_2.63.0             
#> [85] png_0.1-8                   Rsamtools_2.19.0           
#> [87] memoise_2.0.1               bslib_0.5.1                
#> [89] Rcpp_1.0.11                 SparseArray_1.3.0          
#> [91] xfun_0.40                   MatrixGenerics_1.15.0      
#> [93] pkgconfig_2.0.3