| Title: | A/B compartment detection and differential analysis |
|---|---|
| Description: | HiCDOC normalizes intrachromosomal Hi-C matrices, uses unsupervised learning to predict A/B compartments from multiple replicates, and detects significant compartment changes between experiment conditions. It provides a collection of functions assembled into a pipeline to filter and normalize the data, predict the compartments and visualize the results. It accepts several type of data: tabular `.tsv` files, Cooler `.cool` or `.mcool` files, Juicer `.hic` files or HiC-Pro `.matrix` and `.bed` files. |
| Authors: | Kurylo Cyril [aut], Zytnicki Matthias [aut], Foissac Sylvain [aut], Maigné Élise [aut, cre] |
| Maintainer: | Maigné Élise <[email protected]> |
| License: | LGPL-3 |
| Version: | 1.15.1 |
| Built: | 2026-06-02 10:57:58 UTC |
| Source: | https://github.com/bioc/HiCDOC |
Detects compartments for each genomic position in each condition, and computes p-values for compartment differences between conditions.
detectCompartments( object, parallel = FALSE, kMeansDelta = NULL, kMeansIterations = NULL, kMeansRestarts = NULL, PC1CheckThreshold = NULL )detectCompartments( object, parallel = FALSE, kMeansDelta = NULL, kMeansIterations = NULL, kMeansRestarts = NULL, PC1CheckThreshold = NULL )
object |
A |
parallel |
Whether or not to parallelize the processing. Defaults to FALSE See 'Details'. |
kMeansDelta |
The convergence stop criterion for the clustering. When the centroids'
distances between two iterations is lower than this value, the clustering
stops. Defaults to |
kMeansIterations |
The maximum number of iterations during clustering. Defaults to
|
kMeansRestarts |
The amount of times the clustering is restarted. For each restart, the
clustering iterates until convergence or reaching the maximum number of
iterations. The clustering that minimizes inner-cluster variance is selected.
Defaults to |
PC1CheckThreshold |
The minimum percentage of variance that should be explained by
the first principal component of centroids to pass sanity check.
Defaults to |
To clusterize genomic positions, the algorithm follows these steps:
For each chromosome and condition, get the interaction vectors of each genomic position. Each genomic position can have multiple interaction vectors, corresponding to the multiple replicates in that condition.
For each chromosome and condition, use constrained K-means to clusterize the interaction vectors, forcing replicate interaction vectors into the same cluster. The euclidean distance between interaction vectors determines their similarity.
For each interaction vector, compute its concordance, which is the confidence in its assigned cluster. Mathematically, it is the log ratio of its distance to each centroid, normalized by the distance between both centroids, and min-maxed to a [-1,1] interval.
For each chromosome, compute the distance between all centroids and the centroids of the first condition. The cross-condition clusters whose centroids are closest are given the same cluster label. This results in two clusters per chromosome, spanning all conditions.
To match each cluster with an A or B compartment, the algorithm follows these steps:
For each genomic position, compute its self interaction ratio, which is the difference between its self interaction and the median of its other interactions.
For each chromosome, for each cluster, get the median self interaction ratio of the genomic positions in that cluster.
For each chromosome, the cluster with the smallest median self interaction ratio is matched with compartment A, and the cluster with the greatest median self interaction ratio is matched with compartment B. Compartment A being open, there are more overall interactions between distant genomic positions, so it is assumed that the difference between self interactions and other interactions is lower than in compartment B.
To find significant compartment differences across conditions, and compute their p-values, the algorithm follows three steps:
For each pair of replicates in different conditions, for each genomic position, compute the absolute difference between its concordances.
For each pair of conditions, for each genomic position, compute the median of its concordance differences.
For each pair of conditions, for each genomic position whose assigned compartment switches, rank its median against the empirical cumulative distribution of medians of all non-switching positions in that condition pair. Adjust the resulting p-value with the Benjamini–Hochberg procedure.
The parallel version of detectCompartments uses the
bpmapply function. Before to call the
function in parallel you should specify the parallel parameters such as:
On Linux:
multiParam <- BiocParallel::MulticoreParam(workers = 10)
On Windows:
multiParam <- BiocParallel::SnowParam(workers = 10)
And then you can register the parameters to be used by BiocParallel:
BiocParallel::register(multiParam, default = TRUE)
You should be aware that using MulticoreParam, reproducibility of the detectCompartments function using a RNGseed may not work. See this issue for more details.
A HiCDOCDataSet, with compartments, concordances, distances,
centroids, and differences.
data(exampleHiCDOCDataSet) ## Run all filtering and normalization steps (not run for timing reasons) # object <- filterSmallChromosomes(exampleHiCDOCDataSet) # object <- filterSparseReplicates(object) # object <- filterWeakPositions(object) # object <- normalizeTechnicalBiases(object) # object <- normalizeBiologicalBiases(object) # object <- normalizeDistanceEffect(object) # Detect compartments and differences across conditions object <- detectCompartments(exampleHiCDOCDataSet)data(exampleHiCDOCDataSet) ## Run all filtering and normalization steps (not run for timing reasons) # object <- filterSmallChromosomes(exampleHiCDOCDataSet) # object <- filterSparseReplicates(object) # object <- filterWeakPositions(object) # object <- normalizeTechnicalBiases(object) # object <- normalizeBiologicalBiases(object) # object <- normalizeDistanceEffect(object) # Detect compartments and differences across conditions object <- detectCompartments(exampleHiCDOCDataSet)
Removes chromosomes whose length (in number of positions) is smaller than the threshold.
filterSmallChromosomes(object, threshold = NULL)filterSmallChromosomes(object, threshold = NULL)
object |
A |
threshold |
The minimum length (number of positions) for a chromosome to be kept.
Defaults to |
A filtered HiCDOCDataSet.
filterSparseReplicates,
filterWeakPositions,
HiCDOC
data(exampleHiCDOCDataSet) object <- exampleHiCDOCDataSet chromosomes(object) object <- filterSmallChromosomes(object) chromosomes(object)data(exampleHiCDOCDataSet) object <- exampleHiCDOCDataSet chromosomes(object) object <- filterSmallChromosomes(object) chromosomes(object)
Removes chromosome replicates whose percentage of non-zero interactions is smaller than the threshold.
filterSparseReplicates(object, threshold = NULL)filterSparseReplicates(object, threshold = NULL)
object |
A |
threshold |
The minimum percentage of non-zero interactions for a chromosome replicate to
be kept. If a chromosome replicate's percentage of non-zero interactions is
lower than this value, it is removed. Defaults to
|
A filtered HiCDOCDataSet.
filterSmallChromosomes,
filterWeakPositions,
HiCDOC
data(exampleHiCDOCDataSet) object <- exampleHiCDOCDataSet object <- filterSparseReplicates(object)data(exampleHiCDOCDataSet) object <- exampleHiCDOCDataSet object <- filterSparseReplicates(object)
Removes weak genomic positions whose interactions average is lower than the threshold.
filterWeakPositions(object, threshold = NULL)filterWeakPositions(object, threshold = NULL)
object |
A |
threshold |
The minimum average interaction for a position to be kept. If a position's
average interaction with the entire chromosome is lower than this value in
any of the replicates, it is removed from all replicates and conditions.
Defaults to |
Detects weak genomic positions in each replicate, and removes them from all
replicates to guarantee comparability across conditions when calling
detectCompartments.
A filtered HiCDOCDataSet.
filterSmallChromosomes,
filterSparseReplicates,
HiCDOC
data(exampleHiCDOCDataSet) object <- exampleHiCDOCDataSet object <- filterWeakPositions(object)data(exampleHiCDOCDataSet) object <- exampleHiCDOCDataSet object <- filterWeakPositions(object)
Normalizes biological biases such as GC content and repeated regions. Uses the Knight-Ruiz balancing algorithm to transform interaction matrices into doubly stochastic matrices, with sum of each row and sum of each column equal to 1.
normalizeBiologicalBiases(object, parallel = FALSE)normalizeBiologicalBiases(object, parallel = FALSE)
object |
A |
parallel |
Should the normalization be run in parallel mode? Default to FALSE. |
A HiCDOCDataSet with normalized interactions.
filterSparseReplicates,
filterWeakPositions,
normalizeTechnicalBiases,
normalizeDistanceEffect,
HiCDOC
data(exampleHiCDOCDataSet) object <- exampleHiCDOCDataSet object <- filterSparseReplicates(object) object <- filterWeakPositions(object) object <- normalizeBiologicalBiases(object)data(exampleHiCDOCDataSet) object <- exampleHiCDOCDataSet object <- filterSparseReplicates(object) object <- filterWeakPositions(object) object <- normalizeBiologicalBiases(object)
Normalizes interactions by their "expected" value relative to the distance that separates their positions. The "expected" values are estimated with a loess regression on the proportion of interactions for each distance.
normalizeDistanceEffect(object, loessSampleSize = NULL, parallel = FALSE)normalizeDistanceEffect(object, loessSampleSize = NULL, parallel = FALSE)
object |
A |
loessSampleSize |
The number of positions used as a sample to estimate the effect of distance
on proportion of interactions. Defaults to
|
parallel |
Should the normalization be run in parallel mode? Default to FALSE. |
A HiCDOCDataSet with normalized interactions.
normalizeTechnicalBiases,
normalizeBiologicalBiases,
HiCDOC
data(exampleHiCDOCDataSet) object <- normalizeDistanceEffect(exampleHiCDOCDataSet)data(exampleHiCDOCDataSet) object <- normalizeDistanceEffect(exampleHiCDOCDataSet)
Normalizes technical biases such as sequencing depth by using a cyclic loess
to recursively normalize each pair of interaction matrices. Depends on
multiHiCcompare.
normalizeTechnicalBiases(object, parallel = FALSE, cyclicLoessSpan = NULL)normalizeTechnicalBiases(object, parallel = FALSE, cyclicLoessSpan = NULL)
object |
A |
parallel |
Logical. Whether or not to parallelize the processing. Defaults to FALSE |
cyclicLoessSpan |
A numeric value in between 0 and 1. The span for cyclic loess normalization.
This value is passed to |
If parallel = TRUE, the function
cyclic_loess
is launched in parallel mode, using bplapply
function. Before to call the function in parallel you should specify
the parallel parameters such as:
On Linux:
multiParam <- BiocParallel::MulticoreParam(workers = 10)
On Windows:
multiParam <- BiocParallel::SnowParam(workers = 10)
And then you can register the parameters to be used by BiocParallel:
BiocParallel::register(multiParam, default = TRUE)
A HiCDOCDataSet with normalized interactions.
filterSparseReplicates,
filterWeakPositions,
normalizeBiologicalBiases,
normalizeDistanceEffect,
HiCDOC
data(exampleHiCDOCDataSet) object <- filterSmallChromosomes(exampleHiCDOCDataSet) object <- filterSparseReplicates(object) object <- filterWeakPositions(object) # Not printing loess warnings for example purpose. # Results should be inspected if there is any. suppressWarnings( object <- normalizeTechnicalBiases(object) )data(exampleHiCDOCDataSet) object <- filterSmallChromosomes(exampleHiCDOCDataSet) object <- filterSparseReplicates(object) object <- filterWeakPositions(object) # Not printing loess warnings for example purpose. # Results should be inspected if there is any. suppressWarnings( object <- normalizeTechnicalBiases(object) )
Plots the result of the PCA on the compartments' centroids.
plotCentroids(object, chromosome, size = 2, checks = TRUE)plotCentroids(object, chromosome, size = 2, checks = TRUE)
object |
A |
chromosome |
A chromosome name or index in |
size |
Size of each point. Defaults to 2. |
checks |
Whether or not to add sanity checks messages on centroids. Default to TRUE. |
A ggplot.
data(exampleHiCDOCDataSetProcessed) plotCentroids(exampleHiCDOCDataSetProcessed, chromosome = 1)data(exampleHiCDOCDataSetProcessed) plotCentroids(exampleHiCDOCDataSetProcessed, chromosome = 1)
Plots the predicted compartments, along with their concordance in each replicate, and significant changes between experiment conditions.
plotCompartmentChanges( object, chromosome, threshold = 0.05, xlim = NULL, points = FALSE, checks = TRUE, colour = "gray90" )plotCompartmentChanges( object, chromosome, threshold = 0.05, xlim = NULL, points = FALSE, checks = TRUE, colour = "gray90" )
object |
A |
chromosome |
A chromosome name or index in |
threshold |
Significance threshold for the compartment changes. Defaults to 0.05. |
xlim |
A vector of the minimum and maximum positions to display. If NULL, displays all positions. Defaults to NULL. |
points |
Whether or not to add points to the concordances. Defaults to FALSE. |
checks |
Whether or not to add sanity checks messages. Default to TRUE. |
colour |
Border color for the compartments. Default to 'gray90'. 'NA' means no border. |
A ggplot.
data(exampleHiCDOCDataSetProcessed) plotCompartmentChanges(exampleHiCDOCDataSetProcessed, chromosome = 1)data(exampleHiCDOCDataSetProcessed) plotCompartmentChanges(exampleHiCDOCDataSetProcessed, chromosome = 1)
Plots the predicted compartments in each experiment condition.
plotCompartments(object, chromosome, xlim = NULL, colour = "gray90")plotCompartments(object, chromosome, xlim = NULL, colour = "gray90")
object |
A |
chromosome |
A chromosome name or index in |
xlim |
A vector of the minimum and maximum positions to display. If NULL, displays all positions. Defaults to NULL. |
colour |
Border color for the compartments. Default to 'gray90'. 'NA' means no border. |
A ggplot.
data(exampleHiCDOCDataSetProcessed) plotCompartments(exampleHiCDOCDataSetProcessed, chromosome = 1)data(exampleHiCDOCDataSetProcessed) plotCompartments(exampleHiCDOCDataSetProcessed, chromosome = 1)
Plots the distribution of concordance differences, which are the differences between concordances of each pair of replicates from different conditions. A concordance can be understood as a confidence in a genomic position's assigned compartment. Mathematically, it is the log ratio of a genomic position's distance to each compartment's centroid, normalized by the distance between both centroids, and min-maxed to a [-1,1] interval.
plotConcordanceDifferences(object)plotConcordanceDifferences(object)
object |
A |
A ggplot.
data(exampleHiCDOCDataSetProcessed) plotConcordanceDifferences(exampleHiCDOCDataSetProcessed)data(exampleHiCDOCDataSetProcessed) plotConcordanceDifferences(exampleHiCDOCDataSetProcessed)
Plots the concordances of each replicate in each experiment condition. A concordance can be understood as a confidence in a genomic position's assigned compartment. Mathematically, it is the log ratio of a genomic position's distance to each compartment's centroid, normalized by the distance between both centroids, and min-maxed to a [-1,1] interval.
plotConcordances( object, chromosome, xlim = NULL, threshold = 0.05, points = FALSE )plotConcordances( object, chromosome, xlim = NULL, threshold = 0.05, points = FALSE )
object |
A |
chromosome |
A chromosome name or index in |
xlim |
A vector of the minimum and maximum positions to display. If NULL, displays all positions. Defaults to NULL. |
threshold |
Significance threshold for the compartment changes. Defaults to 0.05. |
points |
Whether or not to add points to the concordances. Defaults to FALSE. |
A ggplot.
data(exampleHiCDOCDataSetProcessed) plotConcordances(exampleHiCDOCDataSetProcessed, chromosome = 1)data(exampleHiCDOCDataSetProcessed) plotConcordances(exampleHiCDOCDataSetProcessed, chromosome = 1)
Plots the distance effect on proportion of interactions. Each point is a cell in the interaction matrix, such that the x-axis is the distance with respect to the diagonal, the y-axis is number of counts. Dots are binned.
plotDistanceEffect( object, chromosome = NULL, transformX = "identity", transformY = "identity" )plotDistanceEffect( object, chromosome = NULL, transformX = "identity", transformY = "identity" )
object |
A |
chromosome |
Name (character) or index of the chromosome, if the plot should be restricted to only one chromosome. Default to NULL. |
transformX |
Transformation of the X axis. Default to "identity". See
|
transformY |
Transformation of the Y axis. Default to "identity". See
|
A ggplot.
data(exampleHiCDOCDataSet) plotDistanceEffect(exampleHiCDOCDataSet)data(exampleHiCDOCDataSet) plotDistanceEffect(exampleHiCDOCDataSet)
Plots the interaction matrices as heatmaps.
plotInteractions( object, chromosome, transform = NULL, colours = c(low = "#2c7bb6", mid = "#ffffbf", high = "#d7191c"), midpoint = 0 )plotInteractions( object, chromosome, transform = NULL, colours = c(low = "#2c7bb6", mid = "#ffffbf", high = "#d7191c"), midpoint = 0 )
object |
A |
chromosome |
A chromosome name or index in |
transform |
Transformation of the color scale. Default to NULL (no transformation). See
|
colours |
A character vector colours of length 3 to use for the gradient. See
|
midpoint |
midpoint value to be passed to |
A ggplot.
data(exampleHiCDOCDataSet) plotInteractions(exampleHiCDOCDataSet, chromosome = 1)data(exampleHiCDOCDataSet) plotInteractions(exampleHiCDOCDataSet, chromosome = 1)
Plots the boxplots of self interaction ratios, which are the differences between self interaction and median of other interactions for each genomic position. Since the A compartment is open with more interactions overall, it is assumed that self interaction ratios in compartment A are smaller than in compartment B.
plotSelfInteractionRatios(object, chromosome, checks = TRUE)plotSelfInteractionRatios(object, chromosome, checks = TRUE)
object |
A |
chromosome |
A chromosome name or index in |
checks |
Logical. Should sanity checks messages be printed on plot ? Default to TRUE. |
A ggplot.
data(exampleHiCDOCDataSetProcessed) plotSelfInteractionRatios(exampleHiCDOCDataSetProcessed, chromosome = 1)data(exampleHiCDOCDataSetProcessed) plotSelfInteractionRatios(exampleHiCDOCDataSetProcessed, chromosome = 1)