TADCompare

https://dozmorovlab.github.io/TADCompare/
Admin
TADCompare is an R package for differential Topologically Associated Domain (TAD) detection between...
Tokens:13,535
Snippets:136
Trust Score:9.7
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install from GitHub

Source: https://dozmorovlab.github.io/TADCompare/index.html

Install the latest version of TADCompare directly from the GitHub repository.

```R
devtools::install_github('cresswellkg/TADCompare', build_vignettes = TRUE)
library(TADCompare)
```

--------------------------------

### GO Enrichment Output Example

Source: https://dozmorovlab.github.io/TADCompare/articles/Ontology_Analysis.html

Example output table showing ontology domains, descriptions, and p-values.

```text
##                Ontology                                          Description
## 1 GO Molecular Function                   gamma-glutamyltransferase activity
## 2 GO Biological Process                     glutathione biosynthetic process
## 3 GO Cellular Component         anchored to external side of plasma membrane
## 4 GO Cellular Component        intrinsic to external side of plasma membrane
## 5 GO Biological Process                         peptide biosynthetic process
## 6 GO Molecular Function transferase activity, transferring amino-acyl groups
##       P-value
## 1 0.001802360
## 2 0.002927596
## 3 0.003152529
## 4 0.004051881
## 5 0.004725996
## 6 0.004950625
```

--------------------------------

### Install TADCompare

Source: https://dozmorovlab.github.io/TADCompare/articles/Ontology_Analysis.html

Install the TADCompare package via BiocManager.

```R
BiocManager::install("TADCompare")
```

--------------------------------

### Install Dependencies

Source: https://dozmorovlab.github.io/TADCompare/index.html

Install required R packages from CRAN and ensure BiocManager is available.

```R
install.packages(c('dplyr', 'PRIMME', 'cluster', 'Matrix', 'magrittr', 'HiCcompare'))

if (!requireNamespace("BiocManager", quietly=TRUE))
    install.packages("BiocManager")
```

--------------------------------

### Load and inspect example contact matrices

Source: https://dozmorovlab.github.io/TADCompare/articles/TADCompare.html

Load built-in Rao contact matrices and inspect their dimensions and structure.

```R
# Get the rao contact matrices built into the package
data("rao_chr22_prim")
data("rao_chr22_rep")
# We see these are n x n matrices
dim(rao_chr22_prim)
```

```R
dim(rao_chr22_rep)
```

```R
# And, get a glimpse how the data looks like
rao_chr22_prim[100:105, 100:105]
```

--------------------------------

### ConsensusTADs Usage Example

Source: https://dozmorovlab.github.io/TADCompare/reference/ConsensusTADs.html

Example demonstrating how to load data and identify consensus TAD boundaries using a specified resolution.

```R
# Read in data
data("time_mats")
# Find consensus TAD boundaries
diff_list <- ConsensusTADs(time_mats, resolution = 50000)
```

--------------------------------

### Run TADCompare analysis

Source: https://dozmorovlab.github.io/TADCompare/reference/TADCompare.html

Example usage of TADCompare to find differential TADs between two datasets.

```R
# Read in data
data("rao_chr22_prim")
data("rao_chr22_rep")
# Find differential TADs
diff_frame <- TADCompare(rao_chr22_prim, rao_chr22_rep, resolution = 50000)
```

--------------------------------

### Analyze time-varying TAD boundaries

Source: https://dozmorovlab.github.io/TADCompare/reference/TimeCompare.html

Example usage of the TimeCompare function to identify TAD boundaries from a list of contact matrices.

```R
# Read in data
data("time_mats")
# Find time varying TAD boundaries
diff_list <- TimeCompare(time_mats, resolution = 50000)
```

--------------------------------

### Prepare matrices for visualization

Source: https://dozmorovlab.github.io/TADCompare/articles/TADCompare.html

Load contact matrices and calculate a scaling factor for global normalization.

```R
data("GM12878.40kb.raw.chr2")
data("IMR90.40kb.raw.chr2")
mtx1 <- GM12878.40kb.raw.chr2
mtx2 <- IMR90.40kb.raw.chr2
res <- 40000 # Set resolution
# Globally normalize matrices for better visual comparison (does not affect TAD calling)
mtx1_total <- sum(mtx1)
mtx2_total <- sum(mtx2)
(scaling_factor <- mtx1_total / mtx2_total)
```

--------------------------------

### Retrieve R Session Information

Source: https://dozmorovlab.github.io/TADCompare/articles/Ontology_Analysis.html

Displays the current R environment, including version, platform, and loaded packages.

```R
sessionInfo()
```

```text
## R version 4.0.2 (2020-06-22)
## Platform: x86_64-apple-darwin17.0 (64-bit)
## Running under: macOS  10.16
## 
## Matrix products: default
## BLAS:   /Library/Frameworks/R.framework/Versions/4.0/Resources/lib/libRblas.dylib
## LAPACK: /Library/Frameworks/R.framework/Versions/4.0/Resources/lib/libRlapack.dylib
## 
## locale:
## [1] en_US.UTF-8/en_US.UTF-8/en_US.UTF-8/C/en_US.UTF-8/en_US.UTF-8
## 
## attached base packages:
## [1] parallel  stats4    stats     graphics  grDevices utils     datasets 
## [8] methods   base     
## 
## other attached packages:
## [1] rGREAT_1.20.0        GenomicRanges_1.40.0 GenomeInfoDb_1.24.2 
## [4] IRanges_2.22.2       S4Vectors_0.26.1     BiocGenerics_0.34.0 
## [7] TADCompare_1.1.1     dplyr_1.0.2          BiocStyle_2.16.1    
## 
## loaded via a namespace (and not attached):
##   [1] colorspace_2.0-0            rjson_0.2.20               
##   [3] ggsignif_0.6.0              ellipsis_0.3.1             
##   [5] rio_0.5.16                  CGHcall_2.50.0             
##   [7] rprojroot_2.0.2             DNAcopy_1.62.0             
##   [9] XVector_0.28.0              GlobalOptions_0.1.2        
##  [11] fs_1.5.0                    rstudioapi_0.13            
##  [13] ggpubr_0.4.0                listenv_0.8.0              
##  [15] HiCcompare_1.10.0           codetools_0.2-16           
##  [17] splines_4.0.2               R.methodsS3_1.8.1          
##  [19] impute_1.62.0               knitr_1.30                 
##  [21] Rsamtools_2.4.0             broom_0.7.2                
##  [23] R.oo_1.24.0                 pheatmap_1.0.12            
##  [25] BiocManager_1.30.10         compiler_4.0.2             
##  [27] backports_1.2.0             assertthat_0.2.1           
##  [29] Matrix_1.2-18               limma_3.44.3               
##  [31] htmltools_0.5.0             tools_4.0.2                
##  [33] gtable_0.3.0                glue_1.4.2                 
##  [35] GenomeInfoDbData_1.2.3      reshape2_1.4.4             
##  [37] Rcpp_1.0.5                  carData_3.0-4              
##  [39] Biobase_2.48.0              cellranger_1.1.0           
##  [41] pkgdown_1.6.1               vctrs_0.3.5                
##  [43] Biostrings_2.56.0           nlme_3.1-150               
##  [45] QDNAseq_1.24.0              xfun_0.19                  
##  [47] stringr_1.4.0               globals_0.13.1             
##  [49] openxlsx_4.2.3              lifecycle_0.2.0            
##  [51] gtools_3.8.2                rstatix_0.6.0              
##  [53] InteractionSet_1.16.0       future_1.20.1              
##  [55] zlibbioc_1.34.0             scales_1.1.1               
##  [57] ragg_0.4.0                  hms_0.5.3                  
##  [59] SummarizedExperiment_1.18.2 rhdf5_2.32.4               
##  [61] RColorBrewer_1.1-2          yaml_2.2.1                 
##  [63] curl_4.3                    memoise_1.1.0              
##  [65] gridExtra_2.3               ggplot2_3.3.2              
##  [67] CGHbase_1.48.0              stringi_1.5.3              
##  [69] desc_1.2.0                  zip_2.1.1                  
##  [71] BiocParallel_1.22.0         rlang_0.4.8                
##  [73] pkgconfig_2.0.3             systemfonts_0.3.2          
##  [75] matrixStats_0.57.0          bitops_1.0-6               
##  [77] evaluate_0.14               lattice_0.20-41            
##  [79] purrr_0.3.4                 Rhdf5lib_1.10.1            
##  [81] cowplot_1.1.0               tidyselect_1.1.0           
##  [83] parallelly_1.21.0           plyr_1.8.6                 
##  [85] magrittr_2.0.1              bookdown_0.21              
##  [87] R6_2.5.0                    generics_0.1.0             
##  [89] DelayedArray_0.14.1         pillar_1.4.7               
##  [91] haven_2.3.1                 foreign_0.8-80             
##  [93] mgcv_1.8-33                 abind_1.4-5                
##  [95] RCurl_1.98-1.2              tibble_3.0.4               
##  [97] future.apply_1.6.0          PRIMME_3.1-3               
##  [99] crayon_1.3.4                car_3.0-10                 
## [101] KernSmooth_2.23-18          rmarkdown_2.5              
## [103] GetoptLong_1.0.4            grid_4.0.2                 
## [105] readxl_1.3.1                data.table_1.13.2          
## [107] marray_1.66.0               forcats_0.5.0              
## [109] digest_0.6.27               tidyr_1.1.2                
## [111] R.utils_2.10.1              textshaping_0.2.1          
## [113] munsell_0.5.0
```

--------------------------------

### Load Required Libraries

Source: https://dozmorovlab.github.io/TADCompare/articles/Input_Data.html

Load the necessary packages for data manipulation and TAD analysis.

```R
library(dplyr)
```

```R
library(SpectralTAD)
library(TADCompare)
```

--------------------------------

### Visualize differential TAD boundaries

Source: https://dozmorovlab.github.io/TADCompare/reference/DiffPlot.html

Demonstrates the workflow of loading data, identifying differential TAD boundaries with TADCompare, and visualizing the results using DiffPlot.

```R
# Read in data
data("rao_chr22_prim")
data("rao_chr22_rep")
# Find differential TAD boundaries
tad_diff <- TADCompare(rao_chr22_prim, rao_chr22_rep, resolution = 50000)
# Create plot
DiffPlot(tad_diff,rao_chr22_prim, rao_chr22_rep, resolution = 50000, 
start_coord = 22050000, end_coord = 24150000)
```

--------------------------------

### Benchmark TADCompare runtime

Source: https://dozmorovlab.github.io/TADCompare/articles/Input_Data.html

Loads the microbenchmark library to evaluate performance across different matrix input types.

```R
library(microbenchmark)
```

--------------------------------

### Run TADCompare with Different Inputs

Source: https://dozmorovlab.github.io/TADCompare/articles/Input_Data.html

Execute TADCompare using sparse, NxN, and Nx(N+3) data structures.

```R
# Defining each function
# Sparse
sparse <- TADCompare(cont_mat1 = prim_sparse, cont_mat2 = rep_sparse, resolution = 50000)
# NxN
n_by_n <- TADCompare(cont_mat1 = prim_sparse, cont_mat2 = rep_sparse, resolution = 50000)
# Nx(N+3)
n_by_n_3 <- TADCompare(cont_mat1 = prim_n_n_3, cont_mat2 = rep_n_n_3, resolution = 50000)
```

--------------------------------

### Prepare and inspect time-course data

Source: https://dozmorovlab.github.io/TADCompare/articles/TADCompare.html

Loads time-course contact matrices and inspects the data format.

```R
# Get the list of contact matrices
data("time_mats")
# Checking format
head(time_mats[[1]])
```

--------------------------------

### Benchmark TADCompare Performance

Source: https://dozmorovlab.github.io/TADCompare/articles/Input_Data.html

Compare execution times for different input formats using the microbenchmark package.

```R
# Benchmarking different parameters
bench <- microbenchmark(
# Sparse
sparse <- TADCompare(cont_mat1 = prim_sparse, cont_mat2 = rep_sparse, resolution = 50000),
# NxN
n_by_n <- TADCompare(cont_mat1 = rao_chr22_prim, cont_mat2 = rao_chr22_rep, resolution = 50000),
# Nx(N+3)
n_by_n_3 <- TADCompare(cont_mat1 = prim_n_n_3, cont_mat2 = rep_n_n_3, resolution = 50000), times = 5, unit = "s"
) 

summary_bench <- summary(bench) %>% dplyr::select(mean, median)
rownames(summary_bench) <- c("sparse", "n_by_n", "n_by_n_3")
summary_bench
```

--------------------------------

### Run TADCompare and Inspect Results

Source: https://dozmorovlab.github.io/TADCompare/articles/TADCompare.html

Perform differential analysis on contact matrices using pre-specified TAD boundaries and display the resulting TAD frame.

```R
# Running TADCompare with pre-specified TADs
TD_Compare = TADCompare(rao_chr22_prim, rao_chr22_rep, resolution = 50000, pre_tads = Combined_Bed)

# Returning the boundaries
head(TD_Compare$TAD_Frame)
```

--------------------------------

### TimeCompare(cont_mats, resolution, z_thresh = 2, window_size = 15, gap_thresh = 0.2, groupings = NULL)

Source: https://dozmorovlab.github.io/TADCompare/reference/TimeCompare.html

Identifies TAD boundaries from a list of contact matrices and classifies them based on temporal dynamics.

```APIDOC
## TimeCompare

### Description
Identifies all TAD boundaries from a list of contact matrices representing different time points and classifies them into six categories (Common, Dynamic, Early/Late Appearing, and Early/Late Disappearing).

### Parameters
- **cont_mats** (List) - Required - List of contact matrices in sparse 3 column, n x n, or n x (n+3) form.
- **resolution** (Numeric/String) - Optional - Resolution of the data. Default is "auto".
- **z_thresh** (Numeric) - Optional - Threshold for boundary score. Default is 3.
- **window_size** (Numeric) - Optional - Size of sliding window for TAD detection in bins. Default is 15.
- **gap_thresh** (Numeric) - Optional - Required percentage of non-zero entries to consider a region informative. Default is 0.2.
- **groupings** (Vector) - Optional - Vector defining groups of replicates at a given time point. Default is NULL.

### Value
A list containing:
- **TAD_Bounds** (Data frame) - Regions with a TAD boundary, individual scores, consensus scores, and boundary category.
- **All_Bounds** (Data frame) - Consensus scores for all regions.
- **Count_Plot** (Plot) - Prevalence of each boundary type.

### Example
```r
# Read in data
data("time_mats")
# Find time varying TAD boundaries
diff_list <- TimeCompare(time_mats, resolution = 50000)
```
```

--------------------------------

### Run TADCompare with pre-defined TADs

Source: https://dozmorovlab.github.io/TADCompare/index.html

Uses SpectralTAD to define TAD boundaries before running the comparison, then visualizes the results.

```R
# Call TADs using SpectralTAD
bed_coords1 = bind_rows(SpectralTAD(GM12878.40kb.raw.chr2, chr = "chr2", levels = 3))
bed_coords2 = bind_rows(SpectralTAD(IMR90.40kb.raw.chr2,   chr = "chr2", levels = 3))
# Placing the data in a list for the plotting procedure
Combined_Bed = list(bed_coords1, bed_coords2)

# Running TADCompare with pre-specified TADs
TD_Compare <-  TADCompare(GM12878.40kb.raw.chr2, IMR90.40kb.raw.chr2, resolution = 40000, pre_tads = Combined_Bed)

# Visualizing the results
DiffPlot(tad_diff    = TD_Compare, 
         cont_mat1   = GM12878.40kb.raw.chr2,
         cont_mat2   = IMR90.40kb.raw.chr2,
         resolution  = 40000,
         start_coord = 8000000,
         end_coord   = 16000000,
         pre_tad     = Combined_Bed,
         show_types  = FALSE, 
         point_size  = 5,
         palette     = "RdYlBu",
         rel_heights = c(1, 1))
```

--------------------------------

### Download .hic data files

Source: https://dozmorovlab.github.io/TADCompare/articles/Input_Data.html

Commands to retrieve .hic data files from the NCBI GEO repository using wget.

```bash
wget ftp://ftp.ncbi.nlm.nih.gov/geo/series/GSE63nnn/GSE63525/suppl/GSE63525_GM12878_insitu_primary_30.hic
wget ftp://ftp.ncbi.nlm.nih.gov/geo/series/GSE63nnn/GSE63525/suppl/GSE63525_GM12878_insitu_replicate.hic
```

--------------------------------

### Perform Ontology Analysis on TAD Boundaries

Source: https://dozmorovlab.github.io/TADCompare/articles/Ontology_Analysis.html

This workflow processes TAD boundary data, performs enrichment analysis via rGREAT, and formats the results into a summary table.

```R
# Read in time course data
data("time_mats")
# Identifying boundaries
results <- TimeCompare(time_mats, resolution = 50000)

# Pulling out the frame of TADs
TAD_Frame <- results$TAD_Bounds

# Getting coordinates for TAD boundaries and converting into bed format
Bound_List <- lapply(unique(TAD_Frame$Category), function(x) {
    TAD_Frame %>% filter((Category == x)) %>% mutate(chr = "chr22") %>% 
        dplyr::select(chr, Coordinate) %>% 
        mutate(start = Coordinate, end = Coordinate) %>% 
        dplyr::select(chr, start, end)
})

# Performing rGREAT analysis for each boundary Category
TAD_Enrich <- lapply(Bound_List, function(x) {
  getEnrichmentTables(submitGreatJob(x, request_interval = 1, version = "2.0"))
})

# Name list of data frames to keep track of which enrichment belongs to which
names(TAD_Enrich) <- unique(TAD_Frame$Category)

# Bind each category of pathway and create new column for each pathway
TAD_Enrich <- lapply(names(TAD_Enrich), function(x) {
  bind_rows(lapply(TAD_Enrich[[x]], function(y) {
    y %>% mutate(Category = x)
  }), .id = "source")
})

# Bind each boundary category together and pull out important variables
enrichment_table <- bind_rows(TAD_Enrich) %>% 
  dplyr::select(Ontology = source, Description = name, 
                `P-value` = Hyper_Raw_PValue, Category)

# Get the top enriched pathways
head(enrichment_table %>% dplyr::arrange(`P-value`))
```

```text
##                Ontology
## 1 GO Biological Process
## 2 GO Molecular Function
## 3 GO Biological Process
```

--------------------------------

### Prepare Hi-C Data Formats

Source: https://dozmorovlab.github.io/TADCompare/articles/Input_Data.html

Convert Hi-C matrices into sparse and Nx(N+3) formats required for TADCompare analysis.

```R
data("rao_chr22_rep")
# Converting to sparse
prim_sparse <- HiCcompare::full2sparse(rao_chr22_prim)
rep_sparse  <- HiCcompare::full2sparse(rao_chr22_rep)
# Converting to nxn+3
# Primary
prim_n_n_3 <- data.frame(chr = "chr22",
                         start = as.numeric(colnames(rao_chr22_prim)),
                         end = as.numeric(colnames(rao_chr22_prim))+50000, 
                         rao_chr22_prim)

# Replicate
rep_n_n_3 <- data.frame(chr = "chr22", 
                        start = as.numeric(colnames(rao_chr22_rep)),
                        end = as.numeric(colnames(rao_chr22_rep))+50000,
                        rao_chr22_rep)
```

--------------------------------

### TimeCompare()

Source: https://dozmorovlab.github.io/TADCompare/reference/index.html

Performs time-varying TAD boundary analysis.

```APIDOC
## TimeCompare()

### Description
Analyzes TAD boundary changes over time.
```

--------------------------------

### Inspect TAD_Frame output

Source: https://dozmorovlab.github.io/TADCompare/articles/TADCompare.html

Display the first few rows of the TAD_Frame data frame containing boundary information.

```R
head(results$TAD_Frame)
```

--------------------------------

### Convert and Load .cool Data

Source: https://dozmorovlab.github.io/TADCompare/articles/Input_Data.html

Reads converted .cool text files into R and transforms them into sparse 3-column matrices using the HiCcompare package.

```R
# Read in data
cool_mat1 <- read.table("Zuin.HEK293.50kb.Control.txt")
cool_mat2 <- read.table("Zuin.HEK293.50kb.Depleted.txt")

# Convert to sparse 3-column matrix using cooler2sparse from HiCcompare
sparse_mat1 <- HiCcompare::cooler2sparse(cool_mat1)
sparse_mat2 <- HiCcompare::cooler2sparse(cool_mat2)
```

--------------------------------

### Compare TAD boundary scores

Source: https://dozmorovlab.github.io/TADCompare/articles/TADCompare.html

Run TADCompare and visualize the results using DiffPlot.

```R
# Running TADCompare as-is
TD_Compare <- TADCompare(mtx1, mtx2, resolution = res)
# Running the plotting algorithm with pre-specified TADs
p <- DiffPlot(tad_diff    = TD_Compare, 
              cont_mat1   = mtx1,
              cont_mat2   = mtx2,
              resolution  = res,
              start_coord = start_coord,
              end_coord   = end_coord,
              show_types  = TRUE, 
              point_size  = 5,
              max_height  = 5,
              rel_heights = c(1, 2),
              palette     = "RdYlBu")
plot(p)
```

--------------------------------

### TADCompare()

Source: https://dozmorovlab.github.io/TADCompare/reference/index.html

Performs differential TAD boundary detection.

```APIDOC
## TADCompare()

### Description
Detects differential TAD boundaries between datasets.
```

--------------------------------

### Perform GO Enrichment on Shifted Boundaries

Source: https://dozmorovlab.github.io/TADCompare/articles/Ontology_Analysis.html

Analyze shifted TAD boundaries from differential analysis using rGREAT to retrieve enrichment tables.

```R
library(rGREAT)
# Reading in data
data("rao_chr22_prim")
data("rao_chr22_rep")

# Performing differential analysis
results <- TADCompare(rao_chr22_prim, rao_chr22_rep, resolution = 50000)

# Saving the results into its own data frame
TAD_Frame <- results$TAD_Frame

# Filter data to only include complex boundaries enriched in the second
# contact matrix
TAD_Frame <- TAD_Frame %>% dplyr::filter((Type == "Shifted") & 
                                         (Enriched_In == "Matrix 2"))

# Assign a chromosome and convert to a bed format
TAD_Frame <- TAD_Frame %>% dplyr::select(Boundary) %>% mutate(chr = "chr22", 
    start = Boundary, end = Boundary) %>% dplyr::select(chr, start, end)

# Set up rGREAT job with default parameters
great_shift <- submitGreatJob(TAD_Frame, request_interval = 1, version = "2.0")

# Submit the job
enrichment_table <- getEnrichmentTables(great_shift)

# Subset to only include vital information
enrichment_table <- bind_rows(enrichment_table, .id = "source") %>% 
  dplyr::select(Ontology = source, Description = name, 
                `P-value` = Hyper_Raw_PValue)

# Print head organizaed by p-values
head(enrichment_table %>% dplyr::arrange(`P-value`))
```

--------------------------------

### Run TimeCompare analysis

Source: https://dozmorovlab.github.io/TADCompare/articles/TADCompare.html

Executes the TimeCompare function on sparse 3-column matrices with a specified resolution.

```R
time_var <- TimeCompare(time_mats, resolution = 50000)
```

--------------------------------

### Access time_mats dataset

Source: https://dozmorovlab.github.io/TADCompare/reference/time_mats.html

Load or reference the time_mats dataset in R.

```R
time_mats
```

--------------------------------

### DiffPlot()

Source: https://dozmorovlab.github.io/TADCompare/reference/index.html

Visualizes differential TAD boundaries.

```APIDOC
## DiffPlot()

### Description
Generates visualizations for differential TAD boundaries.
```

--------------------------------

### Inspect All Regions

Source: https://dozmorovlab.github.io/TADCompare/articles/TADCompare.html

Displays the first few rows of the All_Regions data frame, which includes every region of the genome.

```R
head(con_tads$All_Regions)
```

--------------------------------

### Run TADCompare with and without resolution

Source: https://dozmorovlab.github.io/TADCompare/articles/TADCompare.html

Execute the TADCompare function with a specified resolution or allow automatic estimation.

```R
results = TADCompare(rao_chr22_prim, rao_chr22_rep, resolution = 50000)
no_res = TADCompare(rao_chr22_prim, rao_chr22_rep)
```

--------------------------------

### Inspect all genomic regions

Source: https://dozmorovlab.github.io/TADCompare/articles/TADCompare.html

Displays the first few rows of the All_Bounds data frame, which includes all genomic regions regardless of TAD status.

```R
head(time_var$All_Bounds)
```

--------------------------------

### Inspect TAD boundaries

Source: https://dozmorovlab.github.io/TADCompare/articles/TADCompare.html

Displays the first few rows of the TAD_Bounds data frame containing detected TAD boundaries.

```R
head(time_var$TAD_Bounds)
```

--------------------------------

### Combine and Prepare TAD Boundaries

Source: https://dozmorovlab.github.io/TADCompare/articles/TADCompare.html

Aggregate the identified TAD boundaries into a list format for input into the TADCompare function.

```R
Combined_Bed = list(bed_coords1, bed_coords2)
```

--------------------------------

### DiffPlot(tad_diff, cont_mat1, cont_mat2, resolution, start_coord, end_coord, ...)

Source: https://dozmorovlab.github.io/TADCompare/reference/DiffPlot.html

Generates a ggplot visualization of differential TAD boundaries, comparing two contact matrices.

```APIDOC
## DiffPlot

### Description
Visualizes differential TAD boundaries, TAD scores, and differential TAD scores for a specified genomic region.

### Parameters
- **tad_diff** (object) - Required - Raw object output by TADCompare.
- **cont_mat1** (matrix/data.frame) - Required - First contact matrix in sparse 3-column, n x n, or n x (n+3) format.
- **cont_mat2** (matrix/data.frame) - Required - Second contact matrix in sparse 3-column, n x n, or n x (n+3) format.
- **resolution** (numeric) - Required - Resolution of the data.
- **start_coord** (numeric) - Required - Start coordinate of the region to plot.
- **end_coord** (numeric) - Required - End coordinate of the region to plot.
- **pre_tad** (list) - Optional - List of pre-defined TADs for drawing.
- **show_types** (logical) - Optional - If FALSE, excludes in-depth differential boundary types. Default: TRUE.
- **point_size** (numeric) - Optional - Size of boundary points on the heatmap. Default: 3.
- **max_height** (numeric) - Optional - Maximum height in bins for the heatmap. Default: 25.
- **rel_heights** (vector) - Optional - Relative sizes of heatmap and score panels. Default: c(2, 1).
- **palette** (string/vector) - Optional - Color palette name or vector of colors. Default: 'RdYlBu'.

### Returns
A ggplot object displaying the upper diagonal of both contact matrices with labeled differential boundaries and score panels.
```

--------------------------------

### Analyze extracted data with TADCompare

Source: https://dozmorovlab.github.io/TADCompare/articles/Input_Data.html

Load the extracted text files into R and execute the TADCompare function.

```r
#Read in data
primary = read.table('primary.chr22.50kb.txt', header = FALSE)
replicate = read.table('replicate.chr22.50kb.txt', header = FALSE)
#Run TADCompare
tad_diff=TADCompare(primary, replicate, resolution=50000)
```

--------------------------------

### Run TADCompare and DiffPlot with pre-specified TADs

Source: https://dozmorovlab.github.io/TADCompare/articles/TADCompare.html

Performs differential TAD analysis and visualizes the results using pre-specified TAD boundaries.

```R
# Placing the data in a list for the plotting procedure
Combined_Bed = list(bed_coords1, bed_coords2)

# Running TADCompare with pre-specified TADs
TD_Compare <-  TADCompare(mtx1, mtx2, resolution = res, pre_tads = Combined_Bed)
# Running the plotting algorithm with pre-specified TADs
p <- DiffPlot(tad_diff    = TD_Compare, 
              cont_mat1   = mtx1,
              cont_mat2   = mtx2,
              resolution  = res,
              start_coord = start_coord,
              end_coord   = end_coord,
              pre_tad     = Combined_Bed,
              show_types  = FALSE, 
              point_size  = 5,
              max_height  = 10,
              rel_heights = c(1.5, 2),
              palette     = "RdYlBu")
plot(p)
```

--------------------------------

### TADCompare(cont_mat1, cont_mat2, resolution, z_thresh, window_size, gap_thresh, pre_tads)

Source: https://dozmorovlab.github.io/TADCompare/reference/TADCompare.html

Identifies differential TAD boundaries between two contact matrices.

```APIDOC
## TADCompare

### Description
Identifies differential TAD boundaries between two contact matrices. It uses a novel boundary score metric to simultaneously identify TAD boundaries and test for the presence of differential boundaries.

### Parameters
- **cont_mat1** (matrix/data frame) - Required - Contact matrix in sparse 3 column, n x n, or n x (n+3) form.
- **cont_mat2** (matrix/data frame) - Required - Second contact matrix for differential comparison, same format as cont_mat1.
- **resolution** (string/numeric) - Optional - Resolution of the data. Default is "auto".
- **z_thresh** (numeric) - Optional - Threshold for differential boundary score. Default is 2.
- **window_size** (numeric) - Optional - Size of sliding window for TAD detection in bins. Default is 15.
- **gap_thresh** (numeric) - Optional - Required % of non-zero interaction frequencies for a bin to be included. Default is 0.2.
- **pre_tads** (list) - Optional - A list of pre-defined TADs for testing.

### Returns
- **TAD_Frame** (data.frame) - Data frame containing detected TAD boundaries and scores.
- **Boundary_Scores** (numeric) - Boundary scores for the entire genome.
- **Count_Plot** (plot) - Stacked barplot of the number of each type of TAD boundary called.

### Example
```R
data("rao_chr22_prim")
data("rao_chr22_rep")
diff_frame <- TADCompare(rao_chr22_prim, rao_chr22_rep, resolution = 50000)
```
```

--------------------------------

### TimeCompare(time_mats, resolution)

Source: https://dozmorovlab.github.io/TADCompare/index.html

Identifies regions with at least one TAD across at least four time points and classifies them into categories based on temporal changes.

```APIDOC
## TimeCompare

### Description
Identifies regions with at least one TAD across at least four time points and classifies each region into one of six categories (Dynamic, Highly Common, Early Appearing/Disappearing, and Late Appearing/Disappearing) based on temporal changes.

### Parameters
- **time_mats** (data) - Required - A set of contact matrices representing at least four time points.
- **resolution** (numeric) - Required - The resolution of the contact matrices.

### Return Value
A list containing 'TAD_Bounds', which includes coordinates, individual sample boundary scores, consensus boundary scores, and the assigned category for each region.
```

--------------------------------

### Run TADCompare on sparse matrices

Source: https://dozmorovlab.github.io/TADCompare/articles/Input_Data.html

Applies TADCompare across a list of sparse matrices using a specified resolution.

```R
diff_tads = lapply(names(sparse_mat1), function(x) {
  TADCompare(sparse_mat1[[x]], sparse_mat2[[x]], resolution = 50000)
})
```

--------------------------------

### Inspect Boundary_Scores output

Source: https://dozmorovlab.github.io/TADCompare/articles/TADCompare.html

Display the first few rows of the Boundary_Scores data frame containing comprehensive genomic region data.

```R
head(results$Boundary_Scores)
```

--------------------------------

### Extract chromosome data from .hic files

Source: https://dozmorovlab.github.io/TADCompare/articles/Input_Data.html

Use the straw utility to extract specific chromosome data at a defined resolution without normalization.

```bash
./straw NONE GSE63525_GM12878_insitu_primary_30.hic  22 22 BP 50000 > primary.chr22.50kb.txt
./straw NONE GSE63525_GM12878_insitu_replicate_30.hic  22 22 BP 50000 > replicate.chr22.50kb.txt
```

--------------------------------

### BibTeX Citation for TADCompare

Source: https://dozmorovlab.github.io/TADCompare/authors.html

Use this BibTeX entry to cite the TADCompare package in academic publications.

```bibtex
@Article{,
  title = {TADCompare: An R Package for Differential and Temporal Analysis of Topologically Associated Domains},
  author = {Kellen G. Cresswell and Mikhail G. Dozmorov},
  journal = {Frontiers in Genetics},
  year = {2020},
  volume = {11},
  number = {158},
  month = {Mar},
  url = {https://github.com/dozmorovlab/TADCompare},
  doi = {10.3389/fgene.2020.00158},
}
```

--------------------------------

### DiffPlot function signature

Source: https://dozmorovlab.github.io/TADCompare/reference/DiffPlot.html

Displays the required and optional parameters for the DiffPlot function.

```R
DiffPlot(
  tad_diff,
  cont_mat1,
  cont_mat2,
  resolution,
  start_coord,
  end_coord,
  pre_tad = NULL,
  show_types = TRUE,
  point_size = 3,
  max_height = 25,
  rel_heights = c(2, 1),
  palette = "RdYlBu"
)
```

--------------------------------

### Verify TAD boundaries

Source: https://dozmorovlab.github.io/TADCompare/articles/TADCompare.html

Check if pre-specified boundaries are correctly returned by the TADCompare output.

```R
table(TD_Compare$TAD_Frame$Boundary %in% bind_rows(Combined_Bed)$end)
```

--------------------------------

### ConsensusTADs(cont_mats, resolution, z_thresh = 3, window_size = 15, gap_thresh = 0.2)

Source: https://dozmorovlab.github.io/TADCompare/reference/ConsensusTADs.html

Identifies consensus TAD boundaries from a list of contact matrices.

```APIDOC
## ConsensusTADs

### Description
Identifies consensus TAD boundaries across a list of contact matrices. It calculates a consensus boundary score to determine the likelihood of TAD boundaries across all input matrices.

### Parameters
- **cont_mats** (List) - Required - List of contact matrices in sparse 3 column, n x n, or n x (n+3) form.
- **resolution** (Numeric) - Optional - Resolution of the data. Defaults to "auto".
- **z_thresh** (Numeric) - Optional - Threshold for boundary score. Default is 3.
- **window_size** (Numeric) - Optional - Size of sliding window for TAD detection in bins. Default is 15.
- **gap_thresh** (Numeric) - Optional - Required percentage of non-zero entries to consider a region informative. Default is 0.2.

### Returns
- **Consensus** (Data frame) - Contains location of all consensus boundaries and individual sample scores.
- **All_Regions** (Data frame) - Contains consensus scores for all regions.

### Example
```R
data("time_mats")
diff_list <- ConsensusTADs(time_mats, resolution = 50000)
```
```

--------------------------------

### Call TADs using SpectralTAD

Source: https://dozmorovlab.github.io/TADCompare/articles/TADCompare.html

Identify TAD boundaries for primary and replicate contact matrices using the SpectralTAD algorithm.

```R
bed_coords1 = bind_rows(SpectralTAD::SpectralTAD(rao_chr22_prim, chr = "chr22", levels = 3))
```

```R
bed_coords2 = bind_rows(SpectralTAD(rao_chr22_rep,  chr = "chr22", levels = 3))
```

--------------------------------

### Rescale matrices and define coordinates

Source: https://dozmorovlab.github.io/TADCompare/articles/TADCompare.html

Adjust matrix values based on the scaling factor and define the genomic region of interest.

```R
# Rescale matrices depending on which matrix is smaller
if (mtx1_total > mtx2_total) {
  mtx2 <- mtx2 * scaling_factor
} else {
  mtx1 <- mtx1 * (1 / scaling_factor)
}
# Coordinates of interesting regions
start_coord <- 8000000
end_coord   <- 16000000
# Another interesting region
# start_coord <- 40000000
# end_coord   <- 48000000
```

--------------------------------

### Identify differential TADs with TADCompare

Source: https://dozmorovlab.github.io/TADCompare/index.html

Uses two contact matrices and a resolution to identify differential TAD boundaries.

```R
# Load example contact matrices
data("GM12878.40kb.raw.chr2")
data("IMR90.40kb.raw.chr2")

# Find differential TADs
TD_Compare <- TADCompare(GM12878.40kb.raw.chr2, IMR90.40kb.raw.chr2, resolution = 40000)
```

--------------------------------

### Call TADs using SpectralTAD

Source: https://dozmorovlab.github.io/TADCompare/articles/TADCompare.html

Calls TADs on contact matrices using the SpectralTAD algorithm.

```R
bed_coords1 = bind_rows(SpectralTAD(mtx1, chr = "chr2", levels = 3))
```

```R
bed_coords2 = bind_rows(SpectralTAD::SpectralTAD(mtx2, chr = "chr2", levels = 3))
```

--------------------------------

### Classify TAD regions with TimeCompare

Source: https://dozmorovlab.github.io/TADCompare/index.html

Identifies and categorizes TAD regions across multiple time points based on boundary scores.

```R
data("time_mats")
Time_Mats = TimeCompare(time_mats, resolution = 50000)
head(Time_Mats$TAD_Bounds)
```

--------------------------------

### ConsensusTADs()

Source: https://dozmorovlab.github.io/TADCompare/reference/index.html

Identifies consensus TAD boundaries.

```APIDOC
## ConsensusTADs()

### Description
Identifies consensus TAD boundaries from input data.
```

--------------------------------

### Inspect TAD boundary results

Source: https://dozmorovlab.github.io/TADCompare/index.html

Displays the head of the TAD_Frame data frame containing boundary scores and differential status.

```R
head(TD_Compare$TAD_Frame)

  Boundary  Gap_Score TAD_Score1 TAD_Score2     Differential Enriched_In             Type
1  8200000 -2.0245884 0.02537611   1.596684     Differential    Matrix 2             <NA>
2  8240000  0.8091967 2.08454863   1.258245 Non-Differential    Matrix 1 Non-Differential
3  8880000  2.1191814 3.44450158   1.471221     Differential    Matrix 1            Split
4  8960000 -1.6590363 0.46678509   1.712167 Non-Differential    Matrix 2 Non-Differential
5  9560000 -2.3232567 0.56031218   2.313139     Differential    Matrix 2            Merge
6  9600000  0.2375074 1.91851750   1.552303 Non-Differential    Matrix 1 Non-Differential
```

--------------------------------

### Run ConsensusTADs on contact matrices

Source: https://dozmorovlab.github.io/TADCompare/articles/TADCompare.html

Executes the ConsensusTADs function using built-in contact matrices at a specified resolution.

```R
# Get the rao contact matrices built into the package
data("time_mats")
# Running MultiCompare
con_tads <- ConsensusTADs(time_mats, resolution = 50000)
```

--------------------------------

### Display temporal boundary plot

Source: https://dozmorovlab.github.io/TADCompare/articles/TADCompare.html

Renders the stacked barplot showing the frequency of each temporal boundary type.

```R
time_var$Count_Plot
```

--------------------------------

### Inspect Consensus TADs

Source: https://dozmorovlab.github.io/TADCompare/articles/TADCompare.html

Displays the first few rows of the Consensus data frame containing consensus TAD regions.

```R
head(con_tads$Consensus)
```

--------------------------------

### Verify identical results

Source: https://dozmorovlab.github.io/TADCompare/articles/TADCompare.html

Compare the Diff_Loci output between two TADCompare runs to ensure consistency.

```R
identical(results$Diff_Loci, no_res$Diff_Loci)
```

--------------------------------

### Visualize TAD comparison results

Source: https://dozmorovlab.github.io/TADCompare/index.html

Plots the differential TAD results for a specific genomic region.

```R
# Visualizing the results
DiffPlot(tad_diff    = TD_Compare, 
         cont_mat1   = GM12878.40kb.raw.chr2,
         cont_mat2   = IMR90.40kb.raw.chr2,
         resolution  = 40000,
         start_coord = 8000000,
         end_coord   = 16000000,
         show_types  = TRUE, 
         point_size  = 5,
         palette     = "RdYlBu",
         rel_heights = c(1, 2))
```

--------------------------------

### Process HiC-Pro files for TADCompare

Source: https://dozmorovlab.github.io/TADCompare/articles/Input_Data.html

Reads HiC-Pro matrix and bed files, converts them to a compatible bedpe format, and executes TADCompare for each chromosome.

```R
# Read in both files
mat1 <- read.table("sample1_100000.matrix")
bed1 <- read.table("sample1_100000_abs.bed")

# Matrix 2

mat2 <- read.table("sample2_100000.matrix")
bed2 <- read.table("sample2_100000_abs.bed")

# Convert to modified bed format
sparse_mats1 <- HiCcompare::hicpro2bedpe(mat1,bed1)
sparse_mats2 <- HiCcompare::hicpro2bedpe(mat2,bed2)

# Remove empty matrices if necessary
# sparse_mats$cis = sparse_mats$cis[sapply(sparse_mats, nrow) != 0]


# Go through all pairwise chromosomes and run TADCompare
sparse_tads = lapply(1:length(sparse_mats1$cis), function(z) {
  x <- sparse_mats1$cis[[z]]
  y <- sparse_mats2$cis[[z]]
  
  #Pull out chromosome
  chr <- x[, 1][1]
  #Subset to make three column matrix
  x <- x[, c(2, 5, 7)]
  y <- y[, c(2, 5, 7)]
  #Run SpectralTAD
  comp <- TADCompare(x, y, resolution = 100000)
  return(list(comp, chr))
})

# Pull out differential TAD results
diff_res <- lapply(sparse_tads, function(x) x$comp)
# Pull out chromosomes
chr      <- lapply(sparse_tads, function(x) x$chr)
# Name list by corresponding chr
names(diff_res) <- chr
```

--------------------------------

### Access and plot count plot

Source: https://dozmorovlab.github.io/TADCompare/articles/TADCompare.html

Retrieve the ggplot2 object from the results and render the plot.

```R
p <- results$Count_Plot
class(p)
```

```R
plot(p)
```

--------------------------------

### Accessing the rao_chr22_prim dataset

Source: https://dozmorovlab.github.io/TADCompare/reference/rao_chr22_prim.html

Use this identifier to load or reference the chromosome 22 contact matrix in R.

```R
rao_chr22_prim

rao_chr22_prim
```

--------------------------------

### Accessing the rao_chr22_rep dataset

Source: https://dozmorovlab.github.io/TADCompare/reference/rao_chr22_rep.html

Use this identifier to load or reference the chromosome 22 contact matrix data within the package.

```R
rao_chr22_rep

rao_chr22_rep
```

--------------------------------

### ConsensusTADs(time_mats, resolution)

Source: https://dozmorovlab.github.io/TADCompare/index.html

Identifies TAD boundaries consistently defined across multiple contact matrices using a consensus boundary score.

```APIDOC
## ConsensusTADs

### Description
Uses a consensus boundary score to identify TAD boundaries consistently defined across an unlimited number of replicates, time points, or conditions.

### Parameters
- **time_mats** (data) - Required - A set of contact matrices.
- **resolution** (numeric) - Required - The resolution of the contact matrices.

### Return Value
A list containing 'Consensus', which includes coordinates, individual sample boundary scores, and the calculated consensus boundary score.
```

--------------------------------

### TimeCompare function signature

Source: https://dozmorovlab.github.io/TADCompare/reference/TimeCompare.html

The function signature for TimeCompare, detailing available parameters and default values.

```R
TimeCompare(
  cont_mats,
  resolution,
  z_thresh = 2,
  window_size = 15,
  gap_thresh = 0.2,
  groupings = NULL
)
```

--------------------------------

### Identify consensus TADs with ConsensusTADs

Source: https://dozmorovlab.github.io/TADCompare/index.html

Calculates consensus boundary scores to identify TADs consistently defined across multiple samples or conditions.

```R
data("time_mats")
con_tads = ConsensusTADs(time_mats, resolution = 50000)
head(con_tads$Consensus)
```

--------------------------------

### ConsensusTADs Function Signature

Source: https://dozmorovlab.github.io/TADCompare/reference/ConsensusTADs.html

The function signature for identifying consensus TAD boundaries with configurable thresholds and window sizes.

```R
ConsensusTADs(
  cont_mats,
  resolution,
  z_thresh = 3,
  window_size = 15,
  gap_thresh = 0.2
)
```

--------------------------------

### TADCompare function signature

Source: https://dozmorovlab.github.io/TADCompare/reference/TADCompare.html

The primary function signature for identifying differential TAD boundaries.

```R
TADCompare(
  cont_mat1,
  cont_mat2,
  resolution = "auto",
  z_thresh = 2,
  window_size = 15,
  gap_thresh = 0.2,
  pre_tads = NULL
)
```
Tokens:
Raw