callBinary: callBinary

In selinj/chromswitch: An R package to detect chromatin state switches from epigenomic data

callBinary

Description

One of two main functions in the chromswitch package, this function detects a switch in chromatin state in one or more regions given ChIP-seq peak calls for one mark, executing the entire algorithm from preprocessing to evaluating the clustering results, using the binary strategy.

Usage

callBinary(query, metadata, peaks, filter = FALSE,
  filter_columns = NULL, filter_thresholds = NULL, reduce = TRUE,
  gap = 300, p = 0.4, n_features = FALSE, heatmap = FALSE,
  titles = NULL, outdir = NULL, optimal_clusters = TRUE,
  estimate_state = FALSE, test_condition = NULL, BPPARAM = bpparam())

Arguments

query	GRanges list containing one or more genomic regions of interest in which to call a switch. The output dataframe will contain one row per region in query.
metadata	A dataframe with at least two columns: "Sample" which stores the sample IDs, "Condition", which stores the biological condition labels of the samples
peaks	List of GRanges objects storing peak calls for each sample, where element names correspond to sample IDs
filter	(Optional) logical value, filter peaks based on thresholds on peak statistics? Default: FALSE. The filter step is described in filterPeaks.
filter_columns	If filter is TRUE, a chracter vector corresponding to names of columns in the peak metadata by which to filter peaks. If filter is FALSE, not used.
filter_thresholds	If filter is TRUE, a numeric vector corresponding to lower cutoffs applied to metadata columns in order to filter peaks. Provide one per column specified in filter_columns, in the same order. If filter is FALSE, not used.
reduce	(Optional) logical value, if TRUE, reduce gaps between nearby peaks in the same sample. See more at reducePeaks. Default: TRUE
gap	(Optional) If reduce is TRUE, numeric value, specifying the threshold distance for merging. Peaks in the same sample which are within this many bp of each other will be merged. Default: 300
p	Numeric value in [0, 1] giving the fraction of reciprocal overlap to require. Default: 0.4
n_features	(Optional) Logical value indicating whether to include a column "n_features" in the output storing the number of features in the feature matrix constructed for the region, which may be useful for understanding the behaviour of the binary strategy for constructing feature matrices. Default: FALSE
heatmap	(Optional) Logical value, plot the heatmap corresponding to the hierarchical clustering result? Default: FALSE
titles	(Optional) if heatmap is TRUE, a character vector of the same length as query, specifying the title to use when plotting each heatmap (e.g. a gene name), also reused as the prefix of the name of the file where the heatmap is saved. By default, the title is the genomic coordinates of the region in the form "chrN:start-end"
outdir	(Optional) if heatmap is TRUE, the name of the directory where heatmaps should be saved
optimal_clusters	(Optional) Logical value indicate whether to cluster samples into two groups, or to find the optimal clustering solution by choosing the set of clusters which maximizes the Average Silhouette width. Default: TRUE.
estimate_state	(Optional) Logical value indicating whether to include a column "state" in the output specifying the estimated chromatin state of a test condition. The state will be on of "ON", "OFF", or NA, where the latter results if a binary switch between the conditions is unclear. Default: FALSE.
test_condition	(Optional) If estimate_state is TRUE, string specifying one of the two biological condtions in metadata$Condition for which to estimate chromatin state.
BPPARAM	(Optional) instance of BiocParallel:BiocParallelParam used to determine the back-end used for parallel computations when performing the analysis on more than one region.

Details

This strategy constructs a sample-by-feature matrix to use as input for hierarchical clustering by first assembling the set of unique peaks observed in the region across samples. Then for each unique peak, we model the presence or absence of that peak in each sample, resulting in a binary feature matrix.

Value

Data frame with one row per region in query. Contains the coordinates of the region, the number of inferred clusters, the computed cluster validity statistics, and the cluster assignment for each sample.

Examples

samples <- c("E068", "E071", "E074", "E101", "E102", "E110")
bedfiles <- system.file("extdata", paste0(samples, ".H3K4me3.bed"),
package = "chromswitch")
Conditions <- c(rep("Brain", 3), rep("Other", 3))

metadata <- data.frame(Sample = samples,
    H3K4me3 = bedfiles,
    Condition = Conditions,
    stringsAsFactors = FALSE)

regions <- GRanges(seqnames = c("chr19", "chr19"),
    ranges = IRanges(start = c(54924104, 54874318),
                                end = c(54929104, 54877536)))

callBinary(query = regions, metadata = metadata, peaks = H3K4me3,
           BPPARAM = BiocParallel::SerialParam())

selinj/chromswitch documentation built on Jan. 27, 2024, 12:36 p.m.