Package 'HiCBricks'

Description

Brick_add_ranges loads a GRanges object into the Brick store.

Usage

Brick_add_ranges(
    Brick,
    ranges,
    rangekey,
    resolution = NA,
    all_resolutions = FALSE,
    num_cpus = 1
)

Arguments

Details

With this function it is possible to associate other ranges objects with the Brick store. If metadata columns are present, the are also loaded into the Brick store. Although not explicitly asked for, the metadata columns should not be of type list as this may create complications down the line. We ask for ranges objects, so if the same ranges object is later retrieved two additional columns will be present. These are the strand and width columns that are obtained when a ranges is converted into a data.frame. Users can ignore these columns.

Value

Returns TRUE if completed successfully.

Examples

Bintable.path <- system.file(file.path("extdata", "Bintable_100kb.bins"), 
package = "HiCBricks")

out_dir <- file.path(tempdir(), "add_ranges_test")

dir.create(out_dir)

My_BrickContainer <- Create_many_Bricks(BinTable = Bintable.path, 
    bin_delim = " ", output_directory = out_dir, file_prefix = "Test",
    experiment_name = "Vignette Test", resolution = 100000,
    remove_existing = TRUE)

Chrom <- c("chrS","chrS","chrS","chrS","chrS")
Start <- c(10000,20000,40000,50000,60000)
End <- c(10001,20001,40001,50001,60001)
Test_ranges <- Brick_make_ranges(chrom = Chrom, start = Start, end = End)
Brick_add_ranges(Brick = My_BrickContainer, ranges = Test_ranges,
rangekey = "test_ranges", all_resolutions = TRUE)

Description

Brick_call_compartments identifies compartments in Hi-C data. Reference Lieberman-Aiden et al. 2009.

Usage

Brick_call_compartments(Brick, chr, resolution)

Arguments

Value

A dataframe containing the chromosome genomic coordinates and the first three principal components.

Examples

Bintable.path <- system.file(file.path("extdata", "Bintable_100kb.bins"), 
package = "HiCBricks")

out_dir <- file.path(tempdir(), "get_vector_val_test")
if(!file.exists(out_dir)){
    dir.create(out_dir)
}

My_BrickContainer <- Create_many_Bricks(BinTable = Bintable.path, 
    bin_delim = " ", output_directory = out_dir, file_prefix = "Test",
    experiment_name = "Vignette Test", resolution = 100000,
    remove_existing = TRUE)

Matrix_file <- system.file(file.path("extdata", 
"Sexton2012_yaffetanay_CisTrans_100000_corrected_chr2L.txt.gz"), 
package = "HiCBricks")

Brick_load_matrix(Brick = My_BrickContainer, chr1 = "chr2L", 
chr2 = "chr2L", matrix_file = Matrix_file, delim = " ", 
remove_prior = TRUE, resolution = 100000)

Compartments_df <- Brick_call_compartments(Brick = My_BrickContainer, 
chr = "chr2L", resolution = 100000)

Description

Brick_export_to_sparse will accept as input an object of class BrickContainer, a string of length 1 as resolution and a path specifying the output file to write. It writes the content of the all loaded Brick objects as a upper triangle sparse matrix (col > row) containing non-zero values.

Usage

Brick_export_to_sparse(
    Brick,
    out_file,
    remove_file = FALSE,
    resolution,
    sep = " "
)

Arguments

Value

Returns a data.frame corresponding to the head of the output file

Examples

Bintable.path <- system.file(file.path("extdata", "Bintable_100kb.bins"), 
package = "HiCBricks")

out_dir <- file.path(tempdir(), "write_file")
dir.create(out_dir)

My_BrickContainer <- Create_many_Bricks(BinTable = Bintable.path, 
  bin_delim = " ", output_directory = out_dir, file_prefix = "Test",
  experiment_name = "Vignette Test", resolution = 100000,
  remove_existing = TRUE)

Matrix_file <- system.file(file.path("extdata", 
"Sexton2012_yaffetanay_CisTrans_100000_corrected_chr2L.txt.gz"), 
package = "HiCBricks")

Brick_load_matrix(Brick = My_BrickContainer, chr1 = "chr2L", 
chr2 = "chr2L", matrix_file = Matrix_file, delim = " ", 
remove_prior = TRUE, resolution = 100000)

Brick_export_to_sparse(Brick = My_BrickContainer, 
out_file = file.path(out_dir, "example_out.txt"), 
resolution = 100000)

Description

Brick_fetch_range_index constructs a ranges object using Brick_make_ranges, creates an overlap operation using GenomicRanges::findOverlaps, where the constructed ranges is the subject and the Hi-C experiment associated binning table is the query. The return of this object is a list of ranges with their corresponding indices in the binning table.

Usage

Brick_fetch_range_index(
    Brick = NA,
    chr = NA,
    start = NA,
    end = NA,
    names = NA,
    resolution = NA,
    type = "any"
)

Arguments

Value

Returns a GenomicRanges object of same length as the chr, start, end vectors provided. The object is returned with an additional column, Indexes. Indexes is a column of class IRanges::IntegerList, which is part of the larger IRanges::AtomicList superset. This "Indexes" column can be accessed like a normal GRanges column with the additional list accessor [[]] in place of the normal vector accessor [].

Examples

Bintable.path <- system.file(file.path("extdata", "Bintable_100kb.bins"), 
package = "HiCBricks")

out_dir <- file.path(tempdir(), "fetch_range_index_test")
dir.create(out_dir)

My_BrickContainer <- Create_many_Bricks(BinTable = Bintable.path, 
  bin_delim = " ", output_directory = out_dir, file_prefix = "Test",
  experiment_name = "Vignette Test", resolution = 100000,
  remove_existing = TRUE)

Chrom <- c("chr2L","chr2L")
Start <- c(1,40000)
End <- c(1000000,2000000)

Test_Run <- Brick_fetch_range_index(Brick = My_BrickContainer, 
chr = Chrom, start = Start, end = End, resolution = 100000)
Test_Run$Indexes[[1]]

Description

Brick_fetch_row_vector will fetch any given rows from a matrix. If required, the rows can be subsetted on the columns and transformations applied. Vice versa is also true, wherein columns can be retrieved and rows subsetted.

Usage

Brick_fetch_row_vector(
    Brick,
    chr1,
    chr2,
    resolution,
    by = c("position", "ranges"),
    vector,
    regions = NULL,
    force = FALSE,
    flip = FALSE,
    FUN = NULL
)

Arguments

Value

Returns a list of length vector. Each list element will be of length chr2 binned length or if regions is present the corresponding region length. This may differ based on the operations with FUN.

See Also

Brick_get_matrix_within_coords to get matrix by using matrix genomic coordinates, Brick_get_values_by_distance to get values separated at a certain distance, Brick_fetch_row_vector to get values in a certain row/col and subset them, Brick_get_matrix to get matrix by using matrix coordinates.

Examples

Bintable.path <- system.file(file.path("extdata", "Bintable_100kb.bins"), 
package = "HiCBricks")

out_dir <- file.path(tempdir(), "get_row_vector_test")
dir.create(out_dir)

My_BrickContainer <- Create_many_Bricks(BinTable = Bintable.path, 
  bin_delim = " ", output_directory = out_dir, file_prefix = "Test",
  experiment_name = "Vignette Test", resolution = 100000,
  remove_existing = TRUE)

Matrix_file <- system.file(file.path("extdata", 
"Sexton2012_yaffetanay_CisTrans_100000_corrected_chr2L.txt.gz"), 
package = "HiCBricks")

Brick_load_matrix(Brick = My_BrickContainer, chr1 = "chr2L", 
chr2 = "chr2L", matrix_file = Matrix_file, delim = " ", 
remove_prior = TRUE, resolution = 100000)

Coordinate <- c("chr2L:1:100000","chr2L:100001:200000")
Test_Run <- Brick_fetch_row_vector(Brick = My_BrickContainer,
chr1 = "chr2L", chr2 = "chr2L", resolution = 100000, 
by = "ranges", vector = Coordinate,
regions = c("chr2L:1:1000000", "chr2L:40001:2000000"))

Description

Brick_get_bintable makes a call to Brick_get_ranges to retrieve the binning table of the associated Brick store. This is equivalent to passing the argument rangekey = "bintable" in Brick_get_ranges

Usage

Brick_get_bintable(Brick, chr = NA, resolution = NA)

Arguments

Value

Returns a GRanges object containing the binning table associated to the Brick store.

See Also

Brick_get_ranges

Examples

Bintable.path <- system.file(file.path("extdata", "Bintable_100kb.bins"), 
package = "HiCBricks")

out_dir <- file.path(tempdir(), "list_get_bintable_test")
dir.create(out_dir)

My_BrickContainer <- Create_many_Bricks(BinTable = Bintable.path, 
    bin_delim = " ", output_directory = out_dir, file_prefix = "Test",
    experiment_name = "Vignette Test", resolution = 100000,
    remove_existing = TRUE)

Brick_get_bintable(Brick = My_BrickContainer, resolution = 100000)

Description

Brick_get_chrominfo fetches the associated chrominfo table for the Brick it is associated to.

Usage

Brick_get_chrominfo(Brick, resolution = NA)

Arguments

Value

A three column data.frame containing chromosomes, nrows and length.

chromosomes corresponds to all chromosomes in the provided bintable.

nrows corresponds to the number of entries in the bintable or dimension for that chromosome in a Hi-C matrix.

Length is the total bp length of the same chromosome (max value for that chromosome in the bintable).

Examples

Bintable_path <- system.file(file.path("extdata", "Bintable_100kb.bins"), 
package = "HiCBricks")

out_dir <- file.path(tempdir(), "HiCBricks_chrominfo_test")

dir.create(out_dir)

My_BrickContainer <- Create_many_Bricks(BinTable = Bintable_path, 
bin_delim=" ", remove_existing=TRUE, output_directory = out_dir, 
file_prefix = "HiCBricks_vignette_test", resolution = 100000,
experiment_name = "HiCBricks vignette test")

Brick_get_chrominfo(Brick = My_BrickContainer, resolution = 100000)

Description

Brick_get_entire_matrix will return the entire matrix for the entire chromosome pair provided an object of class BrickContainer, and values for chr1, chr2 and resolution values.

Usage

Brick_get_entire_matrix(Brick, chr1, chr2, resolution)

Arguments

Value

Returns an object of class matrix with dimensions corresponding to chr1 binned length by chr2 binned length.

Examples

Bintable.path <- system.file(file.path("extdata", "Bintable_100kb.bins"), 
package = "HiCBricks")

out_dir <- file.path(tempdir(), "get_vector_val_test")
if(!file.exists(out_dir)){
    dir.create(out_dir)
}

My_BrickContainer <- Create_many_Bricks(BinTable = Bintable.path, 
    bin_delim = " ", output_directory = out_dir, file_prefix = "Test",
    experiment_name = "Vignette Test", resolution = 100000,
    remove_existing = TRUE)

Matrix_file <- system.file(file.path("extdata", 
"Sexton2012_yaffetanay_CisTrans_100000_corrected_chr2L.txt.gz"), 
package = "HiCBricks")

Brick_load_matrix(Brick = My_BrickContainer, chr1 = "chr2L", 
chr2 = "chr2L", matrix_file = Matrix_file, delim = " ", 
remove_prior = TRUE, resolution = 100000)

Entire_matrix <- Brick_get_entire_matrix(Brick = My_BrickContainer, 
chr1 = "chr2L", chr2 = "chr2L", resolution = 100000)

Description

Brick_get_matrix will fetch a matrix subset between row values ranging from min(x_coords) to max(x_coords) and column values ranging from min(x_coords) to max(x_coords)

Usage

Brick_get_matrix(
    Brick,
    chr1,
    chr2,
    x_coords,
    y_coords,
    resolution,
    force = FALSE,
    FUN = NULL
)

Arguments

Value

Returns a matrix of dimension x_coords length by y_coords length. This may differ based on the operations with FUN.

See Also

Brick_get_matrix_within_coords to get matrix by using matrix genomic coordinates, Brick_get_values_by_distance to get values separated at a certain distance, Brick_fetch_row_vector to getvalues in a certain row/col and subset them, Brick_get_vector_values to get values using matrix coordinates.

Examples

Bintable.path <- system.file(file.path("extdata", "Bintable_100kb.bins"), 
package = "HiCBricks")

out_dir <- file.path(tempdir(), "get_matrix_test")
dir.create(out_dir)

My_BrickContainer <- Create_many_Bricks(BinTable = Bintable.path, 
    bin_delim = " ", output_directory = out_dir, file_prefix = "Test",
    experiment_name = "Vignette Test", resolution = 100000,
    remove_existing = TRUE)

Matrix_file <- system.file(file.path("extdata", 
"Sexton2012_yaffetanay_CisTrans_100000_corrected_chr2L.txt.gz"), 
package = "HiCBricks")

Brick_load_matrix(Brick = My_BrickContainer, chr1 = "chr2L", 
chr2 = "chr2L", matrix_file = Matrix_file, delim = " ", 
remove_prior = TRUE, resolution = 100000)

Brick_get_matrix(Brick = My_BrickContainer, chr1 = "chr2L", chr2 = "chr2L",
x_coords = c(1:10), y_coords = c(1:10), resolution = 100000)

Description

Brick_get_matrix_mcols will get the specified matrix metadata column for a chr1 vs chr2 Hi-C data matrix. Here, chr1 represents the rows and chr2 represents the columns of the matrix. For cis Hi-C matrices, where chr1 == chr2, chr2_bin_coverage and chr2_col_sums equals chr1_bin_coverage and chr1_row_sums respectively.

Usage

Brick_get_matrix_mcols(
    Brick,
    chr1,
    chr2,
    resolution,
    what = c("chr1_bin_coverage", "chr2_bin_coverage", "chr1_row_sums", "chr2_col_sums")
)

Arguments

Details

These metadata columns are:

• chr1_bin_coverage: Percentage of rows containing non-zero values

• chr2_bin_coverage: Percentage of columns containing non-zero values

• chr1_row_sums: Total signal (if normalised) or number of reads (if counts) in each row.

• chr2_col_sums: Total signal (if normalised) or number of reads (if counts) in each column.

Value

Returns a 1xN dimensional vector containing the specified matrix metric

Examples

Bintable.path <- system.file(file.path("extdata", "Bintable_100kb.bins"), 
package = "HiCBricks")

out_dir <- file.path(tempdir(), "get_matrix_mcols_test")
dir.create(out_dir)

My_BrickContainer <- Create_many_Bricks(BinTable = Bintable.path, 
    bin_delim = " ", output_directory = out_dir, file_prefix = "Test",
    experiment_name = "Vignette Test", resolution = 100000,
    remove_existing = TRUE)

Matrix_file <- system.file(file.path("extdata", 
"Sexton2012_yaffetanay_CisTrans_100000_corrected_chr2L.txt.gz"), 
package = "HiCBricks")

Brick_load_matrix(Brick = My_BrickContainer, chr1 = "chr2L", 
chr2 = "chr2L", matrix_file = Matrix_file, delim = " ", 
remove_prior = TRUE, resolution = 100000)

Brick_get_matrix_mcols(Brick = My_BrickContainer, chr1 = "chr2L", 
chr2 = "chr2L", resolution = 100000, what = "chr1_bin_coverage")

Description

Brick_get_matrix_within_coords will fetch a matrix subset after creating an overlap operation between both regions and the bintable associated to the Brick store. This function calls Brick_get_matrix.

Usage

Brick_get_matrix_within_coords(
    Brick,
    x_coords,
    y_coords,
    resolution,
    force = FALSE,
    FUN = NULL
)

Arguments

Value

Returns a matrix of dimension x_coords binned length by y_coords binned length. This may differ based on FUN.

See Also

Brick_get_matrix to get matrix by using matrix coordinates, Brick_get_values_by_distance to get values separated at a certain distance, Brick_fetch_row_vector to get values in a certain row/col and subset them, Brick_get_vector_values to get values using matrix coordinates.

Examples

Bintable.path <- system.file(file.path("extdata", "Bintable_100kb.bins"), 
package = "HiCBricks")

out_dir <- file.path(tempdir(), "get_matrix_coords_test")
dir.create(out_dir)

My_BrickContainer <- Create_many_Bricks(BinTable = Bintable.path, 
    bin_delim = " ", output_directory = out_dir, file_prefix = "Test",
    experiment_name = "Vignette Test", resolution = 100000,
    remove_existing = TRUE)

Matrix_file <- system.file(file.path("extdata", 
"Sexton2012_yaffetanay_CisTrans_100000_corrected_chr2L.txt.gz"), 
package = "HiCBricks")

Brick_load_matrix(Brick = My_BrickContainer, chr1 = "chr2L", 
chr2 = "chr2L", matrix_file = Matrix_file, delim = " ", 
remove_prior = TRUE, resolution = 100000)

Brick_get_matrix_within_coords(Brick = My_BrickContainer,
x_coords = "chr2L:1:1000000",
y_coords = "chr2L:1:1000000",
resolution = 100000)

Brick_get_matrix_within_coords(Brick = My_BrickContainer,
x_coords = "chr2L:1:1000000",
y_coords = "chr2L:1:1000000",
resolution = 100000,
FUN = mean)

Description

Brick_get_ranges will get a ranges object if present in the Brick store and return a GRanges object.

Usage

Brick_get_ranges(Brick = NA, chr = NA, rangekey = NA, resolution = NA)

Arguments

Details

If a rangekey is present, the ranges will be retrieve and a GRanges constructed. Metadata columns will also be added. If these are rangekeys other than "Bintable", and had been added using Brick_add_ranges the width and Strand columns may appear as metadata columns. These will most likely be artifacts from converting the original ranges object to a data.frame.

Value

Returns a GRanges object with the associated metadata columns that may have been present in the Ranges object.

Examples

Bintable.path <- system.file(file.path("extdata", "Bintable_100kb.bins"), 
package = "HiCBricks")

out_dir <- file.path(tempdir(), "list_get_ranges_test")

dir.create(out_dir)

My_BrickContainer <- Create_many_Bricks(BinTable = Bintable.path, 
    bin_delim = " ", output_directory = out_dir, file_prefix = "Test",
    experiment_name = "Vignette Test", resolution = 100000,
    remove_existing = TRUE)

Brick_get_ranges(Brick = My_BrickContainer, chr = "chr2L", 
rangekey = "Bintable", resolution = 100000)

Description

Brick_get_values_by_distance can fetch values with or without transformation or subsetted by a certain distance. Please note, this module is not an iterable module.

Usage

Brick_get_values_by_distance(
    Brick,
    chr,
    distance,
    resolution,
    constrain_region = NULL,
    batch_size = 500,
    FUN = NULL
)

Arguments

Value

Returns a numeric vector of length N depending on the presence of constrain_region, FUN and distance from the main diagonal.

See Also

Brick_get_matrix_within_coords to get matrix by using matrix coordinates, Brick_fetch_row_vector to get values in a certain row/col and subset them, Brick_get_vector_values to get values using matrix coordinates, Brick_get_matrix to get matrix by using matrix coordinates.

Examples

Bintable.path <- system.file(file.path("extdata", "Bintable_100kb.bins"), 
package = "HiCBricks")

out_dir <- file.path(tempdir(), "val_by_dist_test")
dir.create(out_dir)

My_BrickContainer <- Create_many_Bricks(BinTable = Bintable.path, 
    bin_delim = " ", output_directory = out_dir, file_prefix = "Test",
    experiment_name = "Vignette Test", resolution = 100000,
    remove_existing = TRUE)

Matrix_file <- system.file(file.path("extdata", 
"Sexton2012_yaffetanay_CisTrans_100000_corrected_chr2L.txt.gz"), 
package = "HiCBricks")

Brick_load_matrix(Brick = My_BrickContainer, chr1 = "chr2L", 
chr2 = "chr2L", matrix_file = Matrix_file, delim = " ", 
remove_prior = TRUE, resolution = 100000)

Brick_get_values_by_distance(Brick = My_BrickContainer, chr = "chr2L",
distance = 0, resolution = 100000)

Failsafe_median <- function(x){
     x[is.nan(x) | is.infinite(x) | is.na(x)] <- 0
     return(median(x))
}

Brick_get_values_by_distance(Brick = My_BrickContainer, chr = "chr2L", 
resolution = 100000, distance = 4, FUN = Failsafe_median)

Description

Brick_get_vector_values is the base function being used by all other matrix retrieval functions.

Usage

Brick_get_vector_values(
    Brick,
    chr1,
    chr2,
    resolution,
    xaxis,
    yaxis,
    FUN = NULL,
    force = FALSE
)

Arguments

Value

Returns a vector of length yaxis if length of xaxis is 1. Else returns a matrix of dimension xaxis length by yaxis length.

Note

Whatever the length of xaxis or yaxis may be, the coordinates under consideration will range from min(xaxis) to max(xaxis) on the rows or min(yaxis) to max(yaxis) on the columns.

Examples

Bintable.path <- system.file(file.path("extdata", "Bintable_100kb.bins"), 
package = "HiCBricks")

out_dir <- file.path(tempdir(), "get_vector_val_test")

if(!file.exists(out_dir)){
    dir.create(out_dir)
}

My_BrickContainer <- Create_many_Bricks(BinTable = Bintable.path, 
    bin_delim = " ", output_directory = out_dir, file_prefix = "Test",
    experiment_name = "Vignette Test", resolution = 100000,
    remove_existing = TRUE)

Matrix_file <- system.file(file.path("extdata", 
"Sexton2012_yaffetanay_CisTrans_100000_corrected_chr2L.txt.gz"), 
package = "HiCBricks")

Brick_load_matrix(Brick = My_BrickContainer, chr1 = "chr2L", 
chr2 = "chr2L", matrix_file = Matrix_file, delim = " ", 
remove_prior = TRUE, resolution = 100000)

Brick_get_vector_values(Brick = My_BrickContainer, chr1 = "chr2L",
chr2 = "chr2L", resolution = 100000, xaxis = c(1:10), yaxis = c(1:10))

Description

Brick_list_matrices will list all chromosomal pair matrices from the Brick store, with their associated filename, value range, done status and sparse

Usage

Brick_list_matrices(
    Brick,
    chr1 = NA,
    chr2 = NA,
    resolution = NA,
    all_resolutions = FALSE
)

Arguments

Value

Returns a data.frame object with columns chr1, chr2 corresponding to chromosome pairs, and the associated attributes. filename corresponds to the name of the file that was loaded for the pair. min and max specify the minimum and maximum values in the matrix, done is a logical value specifying if a matrix has been loaded and sparsity specifies if a matrix is defined as a sparse matrix.

Examples

Bintable.path <- system.file(file.path("extdata", "Bintable_100kb.bins"), 
package = "HiCBricks")

out_dir <- file.path(tempdir(), "list_matrices_test")

dir.create(out_dir)

My_BrickContainer <- Create_many_Bricks(BinTable = Bintable.path, 
    bin_delim = " ", output_directory = out_dir, file_prefix = "Test",
    experiment_name = "Vignette Test", resolution = 100000,
    remove_existing = TRUE)

Brick_list_matrices(Brick = My_BrickContainer, chr1 = "chr2L", 
chr2 = "chr2L", resolution = 100000)

Description

Brick_get_matrix_mcols will list the names of all matrix metadata columns.

Usage

Brick_list_matrix_mcols()

Value

Returns a vector containing the names of all matrix metadata columns

Examples

Bintable.path <- system.file(file.path("extdata", "Bintable_100kb.bins"), 
package = "HiCBricks")

out_dir <- file.path(tempdir(), "list_matrix_mcols_test")
dir.create(out_dir)

My_BrickContainer <- Create_many_Bricks(BinTable = Bintable.path, 
    bin_delim = " ", output_directory = out_dir, file_prefix = "Test",
    experiment_name = "Vignette Test", resolution = 100000,
    remove_existing = TRUE)

Brick_list_matrix_mcols()

Description

Brick_list_mcool_normalisations lists the names available for accessing the various normalisation factors in an mcool file. Please note, this only lists the mapping of the columns to their respective names. It does not check for the availability of that particular column in the mcool file

Usage

Brick_list_mcool_normalisations(names.only = FALSE)

Arguments

Value

A named vector listing all possible normalisation factors.

Examples

Brick_list_mcool_normalisations()

Description

Brick_list_mcool_resolutions lists all available resolutions in the mcool file.

Usage

Brick_list_mcool_resolutions(mcool)

Arguments

Value

A named vector listing all possible resolutions in the file.

Examples

## Not run: 
require(curl)
out_dir <- file.path(tempdir(),"mcool_test_dir")
dir.create(path = out_dir)

curl_download(url = paste("https://data.4dnucleome.org/",
"files-processed/4DNFI7JNCNFB/",
"@download/4DNFI7JNCNFB.mcool", sep = ""),
destfile = file.path(out_dir,"H1-hESC-HiC-4DNFI7JNCNFB.mcool"))

mcool <- file.path(out_dir,"H1-hESC-HiC-4DNFI7JNCNFB.mcool")

Brick_list_mcool_resolutions(mcool)


## End(Not run)

Description

Brick_list_rangekeys lists the names of all ranges associated to a Brick.

Usage

Brick_list_rangekeys(Brick, resolution = NA, all_resolutions = FALSE)

Arguments

Value

A one dimensional character vector of length x specifying the names of all ranges currently present in the file.

Examples

Bintable.path <- system.file(file.path("extdata", "Bintable_100kb.bins"), 
package = "HiCBricks")

out_dir <- file.path(tempdir(), "list_rangekeys_test")

dir.create(out_dir)

My_BrickContainer <- Create_many_Bricks(BinTable = Bintable.path, 
    bin_delim = " ", output_directory = out_dir, file_prefix = "Test",
    experiment_name = "Vignette Test", resolution = 100000,
    remove_existing = TRUE)

Brick_list_rangekeys(Brick = My_BrickContainer, resolution = 100000)

Description

Brick_list_ranges_mcols will list the metadata columns of the specified ranges if it is present in the Brick store.

Usage

Brick_list_ranges_mcols(Brick, rangekey = NULL, resolution = NA)

Arguments

Value

if no metadata columns are present, NA. If metadata columns are present, a data.frame object containing the name of the ranges and the associated metadata column name.

Examples

Bintable.path <- system.file(file.path("extdata", "Bintable_100kb.bins"), 
package = "HiCBricks")

out_dir <- file.path(tempdir(), "list_ranges_mcols_test")

dir.create(out_dir)

My_BrickContainer <- Create_many_Bricks(BinTable = Bintable.path, 
    bin_delim = " ", output_directory = out_dir, file_prefix = "Test",
    experiment_name = "Vignette Test", resolution = 100000,
    remove_existing = TRUE)

Brick_list_ranges_mcols(Brick = My_BrickContainer, rangekey = "Bintable",
resolution = 100000)

Description

Load a NxN dimensional sub-distance cis matrix into the Brick store.

Usage

Brick_load_cis_matrix_till_distance(
    Brick = NA,
    chr = NA,
    resolution = NA,
    matrix_file,
    delim = " ",
    distance,
    remove_prior = FALSE,
    num_rows = 2000,
    is_sparse = FALSE,
    sparsity_bins = 100
)

Arguments

Value

Returns TRUE if all went well.

Examples

Bintable.path <- system.file(file.path("extdata", "Bintable_100kb.bins"), 
package = "HiCBricks")

out_dir <- file.path(tempdir(), "matrix_load_dist_test")
dir.create(out_dir)

My_BrickContainer <- Create_many_Bricks(BinTable = Bintable.path, 
  bin_delim = " ", output_directory = out_dir, file_prefix = "Test",
  experiment_name = "Vignette Test", resolution = 100000,
  remove_existing = TRUE)

Matrix_file <- system.file(file.path("extdata", 
"Sexton2012_yaffetanay_CisTrans_100000_corrected_chr2L.txt.gz"), 
package = "HiCBricks")

Brick_load_cis_matrix_till_distance(Brick = My_BrickContainer, 
chr = "chr2L", resolution = 100000, matrix_file = Matrix_file, 
delim = " ", distance = 30, remove_prior = TRUE)

Description

Read an mcool contact matrix coming out of 4D nucleome projects into a Brick store.

Usage

Brick_load_data_from_mcool(
    Brick,
    mcool,
    resolution = NULL,
    matrix_chunk = 2000,
    cooler_read_limit = 1e+07,
    remove_prior = FALSE,
    norm_factor = "Iterative-Correction"
)

Arguments

Value

Returns TRUE if all went well.

See Also

Create_many_Bricks_from_mcool to create matrix from an mcool file, Brick_list_mcool_resolutions to list available resolutions in an mcool file, Brick_list_mcool_normalisations to list available normalisation factors in the mcool file.

Examples

## Not run: 

require(curl)
out_dir <- file.path(tempdir(),"mcool_load_test")
dir.create(path = out_dir)
curl_download(url = paste("https://data.4dnucleome.org/",
"files-processed/4DNFI7JNCNFB/",
"@download/4DNFI7JNCNFB.mcool", sep = ""),
destfile = file.path(out_dir,"H1-hESC-HiC-4DNFI7JNCNFB.mcool"))

mcool <- file.path(out_dir,"H1-hESC-HiC-4DNFI7JNCNFB.mcool")

My_BrickContainer <- Create_many_Bricks_from_mcool(
output_directory = out_dir,
file_prefix = "Test",
mcool = mcool,
resolution = 50000,
experiment_name = "A random 4DN dataset")

Brick_load_data_from_mcool(Brick = My_BrickContainer, mcool = mcool,
resolution = 50000, matrix_chunk = 2000, remove_prior = TRUE,
norm_factor = "Iterative-Correction")


## End(Not run)

Description

Brick_load_data_from_sparse loads data from a table like file, such as sparse matrices.

Usage

Brick_load_data_from_sparse(
    Brick,
    table_file,
    delim = " ",
    resolution = NULL,
    batch_size = 1e+06,
    matrix_chunk = 2000,
    col_index = c(1, 2, 3),
    remove_prior = FALSE
)

Arguments

Value

A dataframe containing the chromosome genomic coordinates and the first three principal components.

Examples

## Not run: 
Bintable.path <- system.file(file.path("extdata", "Bintable_100kb.bins"), 
package = "HiCBricks")

out_dir <- file.path(tempdir(), "get_vector_val_test")
if(!file.exists(out_dir)){
    dir.create(out_dir)
}

My_BrickContainer <- Create_many_Bricks(BinTable = Bintable.path, 
    bin_delim = " ", output_directory = out_dir, file_prefix = "Test",
    experiment_name = "Vignette Test", resolution = 100000,
    remove_existing = TRUE)

Matrix_file <- system.file(file.path("extdata", 
"Sexton2012_yaffetanay_CisTrans_100000_corrected_chr2L.txt.gz"), 
package = "HiCBricks")

Brick_load_matrix(Brick = My_BrickContainer, chr1 = "chr2L", 
chr2 = "chr2L", matrix_file = Matrix_file, delim = " ", 
remove_prior = TRUE, resolution = 100000)

Brick_export_to_sparse(Brick = My_BrickContainer, 
out_file = file.path(out_dir, "example_out.txt"), 
remove_file = TRUE, sep = " ", 
resolution = 100000)

Brick_load_data_from_sparse(Brick = My_BrickContainer, 
table_file = file.path(out_dir, "example_out.txt"), 
delim = " ", resolution = 100000, col_index = c(3,4,5))
    

## End(Not run)

Description

Load a NxM dimensional matrix into the Brick store.

Usage

Brick_load_matrix(
    Brick = NA,
    chr1 = NA,
    chr2 = NA,
    resolution = NA,
    matrix_file = NA,
    delim = " ",
    remove_prior = FALSE,
    num_rows = 2000,
    is_sparse = FALSE,
    sparsity_bins = 100
)

Arguments

Value

Returns TRUE if all went well.

Examples

Bintable.path <- system.file(file.path("extdata", "Bintable_100kb.bins"), 
package = "HiCBricks")

out_dir <- file.path(tempdir(), "matrix_load_test")
dir.create(out_dir)

My_BrickContainer <- Create_many_Bricks(BinTable = Bintable.path, 
    bin_delim = " ", output_directory = out_dir, file_prefix = "Test",
    experiment_name = "Vignette Test", resolution = 100000,
    remove_existing = TRUE)

Matrix_file <- system.file(file.path("extdata", 
"Sexton2012_yaffetanay_CisTrans_100000_corrected_chr2L.txt.gz"), 
package = "HiCBricks")

Brick_load_matrix(Brick = My_BrickContainer, chr1 = "chr2L", 
chr2 = "chr2L", matrix_file = Matrix_file, delim = " ", 
remove_prior = TRUE, resolution = 100000)

Description

Local_score_differentiator calls topologically associated domains on Hi-C matrices. Local score differentiator at the most fundamental level is a change point detector, which detects change points in the directionality index using various thresholds defined on a local directionality index distributions. The directionality index (DI) is calculated as defined by Dixon et al., 2012 Nature. Next, the difference of DI is calculated between neighbouring bins to get the change in DI distribution in each bin. When a DI value goes from a highly negative value to a highly positive one as expected to occur at domain boundaries, the ensuing DI difference distribution becomes a very flat distribution interjected by very large peaks signifying regions where such a change may take place. We use two difference vectors, one is the difference vector between a bin and its adjacent downstream bin and another is the difference between a bin and its adjacent upstream bin. Using these vectors, and the original directionality index, we define domain borders as outliers.

Usage

Brick_local_score_differentiator(
    Brick,
    chrs = NULL,
    resolution = NA,
    all_resolutions = FALSE,
    min_sum = -1,
    di_window = 200L,
    lookup_window = 200L,
    tukeys_constant = 1.5,
    strict = TRUE,
    fill_gaps = TRUE,
    ignore_sparse = TRUE,
    sparsity_threshold = 0.8,
    remove_empty = NULL,
    chunk_size = 500,
    force_retrieve = TRUE
)

Arguments

Details

To define an outlier, fences are first defined. The fences are defined using tukeys_constant x inter-quartile range of the directionality index. The upper fence used for detecting domain starts is the 75th quartile + (IQR x tukeys_constant), while the lower fence is the 25th quartile - (IQR x tukeys_constant). For domain starts the DI difference must be greater than or equal to the upper fence, it must be greater than the DI and the DI must be a finite real value. If strict is TRUE, DI will also be required to be greater than 0. Similarly, for domain ends the DI difference must be lower than or equal to the lower fence, it must be lower than the DI and the DI must be a finite real value. If strict is TRUE, DI will also be required to be lower than 0.

After defining outliers, each domain start will be associated to its nearest downstream domain end. If fill_gaps is defined as TRUE and there are domain ends which remain unassociated to a domain start, These domain ends will be associated to the bin adjacent to their nearest upstream domain end. This associations will be marked by metadata columns, gap.fill= 1 and level = 1.

This function provides the capability to call very accurante TAD definitions in a very fast way.

Value

A ranges object containing domain definitions. The starts and ends of the ranges coincide with the starts and ends of their contained bins from the bintable.

Examples

Bintable.path <- system.file(file.path("extdata", "Bintable_100kb.bins"), 
package = "HiCBricks")

out_dir <- file.path(tempdir(), "lsd_test")
dir.create(out_dir)

My_BrickContainer <- Create_many_Bricks(BinTable = Bintable.path, 
    bin_delim = " ", output_directory = out_dir, file_prefix = "Test",
    experiment_name = "Vignette Test", resolution = 100000,
    remove_existing = TRUE)

Matrix_file <- system.file(file.path("extdata", 
"Sexton2012_yaffetanay_CisTrans_100000_corrected_chr3R.txt.gz"), 
package = "HiCBricks")

Brick_load_matrix(Brick = My_BrickContainer, chr1 = "chr3R", 
chr2 = "chr3R", matrix_file = Matrix_file, delim = " ",
remove_prior = TRUE, resolution = 100000)

TAD_ranges <- Brick_local_score_differentiator(Brick = My_BrickContainer, 
chrs = "chr3R", resolution = 100000, di_window = 10, lookup_window = 30, 
strict = TRUE, fill_gaps = TRUE, chunk_size = 500)

Description

Brick_make_ranges creates a GRanges object from the provided arguments

Usage

Brick_make_ranges(chrom, start, end, strand = NA, names = NA)

Arguments

Value

A GenomicRanges object with the previous sort order being preserved

Examples

Chrom <- c("chrS","chrS","chrS","chrS","chrS")
Start <- c(10000,20000,40000,50000,60000)
End <- c(10001,20001,40001,50001,60001)
Test_ranges <- Brick_make_ranges(chrom = Chrom, start = Start, end = End)

Description

Return the dimensions of a matrix

Usage

Brick_matrix_dimensions(Brick, chr1, chr2, resolution = NA)

Arguments

Value

Returns the dimensions of a Hi-C matrix for any given chromosome pair.

Examples

Bintable.path <- system.file(file.path("extdata", "Bintable_100kb.bins"), 
package = "HiCBricks")

out_dir <- file.path(tempdir(), "matrix_dimension_test")
dir.create(out_dir)

My_BrickContainer <- Create_many_Bricks(BinTable = Bintable.path, 
    bin_delim = " ", output_directory = out_dir, file_prefix = "Test",
    experiment_name = "Vignette Test", resolution = 100000,
    remove_existing = TRUE)

Matrix_file <- system.file(file.path("extdata", 
"Sexton2012_yaffetanay_CisTrans_100000_corrected_chr2L.txt.gz"), 
package = "HiCBricks")

Brick_load_matrix(Brick = My_BrickContainer, chr1 = "chr2L", 
chr2 = "chr2L", matrix_file = Matrix_file, delim = " ", 
remove_prior = TRUE, resolution = 100000)

Brick_matrix_dimensions(Brick = My_BrickContainer, chr1 = "chr2L", 
chr2 = "chr2L", resolution = 100000)

Description

Matrices are created when the bintable is loaded and the chromosome names are provided. If a user is in doubt regarding whether a matrix is present or not it is useful to check this function. If the Bintable did not contain a particular chromosome, any matrices for that chromosome would not be present in the file

Usage

Brick_matrix_exists(Brick, chr1, chr2, resolution = NA)

Arguments

Value

Returns a logical vector of length 1, specifying if the matrix exists or not.

Examples

Bintable.path <- system.file(file.path("extdata", "Bintable_100kb.bins"), 
package = "HiCBricks")

out_dir <- file.path(tempdir(), "matrix_exists_test")
dir.create(out_dir)

My_BrickContainer <- Create_many_Bricks(BinTable = Bintable.path, 
    bin_delim = " ", output_directory = out_dir, file_prefix = "Test",
    experiment_name = "Vignette Test", resolution = 100000,
    remove_existing = TRUE)

Matrix_file <- system.file(file.path("extdata", 
"Sexton2012_yaffetanay_CisTrans_100000_corrected_chr2L.txt.gz"), 
package = "HiCBricks")

Brick_load_matrix(Brick = My_BrickContainer, chr1 = "chr2L", 
chr2 = "chr2L", matrix_file = Matrix_file, delim = " ", 
remove_prior = TRUE, resolution = 100000)

Brick_matrix_exists(Brick = My_BrickContainer, chr1 = "chr2L", 
chr2 = "chr2L", resolution = 100000)

Description

Return the filename of the loaded matrix

Usage

Brick_matrix_filename(Brick, chr1, chr2, resolution = NA)

Arguments

Value

Returns a character vector of length 1 specifying the filename of the currently loaded matrix.

Examples

Bintable.path <- system.file(file.path("extdata", "Bintable_100kb.bins"), 
package = "HiCBricks")

out_dir <- file.path(tempdir(), "matrix_filename_test")
dir.create(out_dir)

My_BrickContainer <- Create_many_Bricks(BinTable = Bintable.path, 
    bin_delim = " ", output_directory = out_dir, file_prefix = "Test",
    experiment_name = "Vignette Test", resolution = 100000,
    remove_existing = TRUE)

Matrix_file <- system.file(file.path("extdata", 
"Sexton2012_yaffetanay_CisTrans_100000_corrected_chr2L.txt.gz"), 
package = "HiCBricks")

Brick_load_matrix(Brick = My_BrickContainer, chr1 = "chr2L", 
chr2 = "chr2L", matrix_file = Matrix_file, delim = " ", 
remove_prior = TRUE, resolution = 100000)

Brick_matrix_filename(Brick = My_BrickContainer, chr1 = "chr2L", 
chr2 = "chr2L", resolution = 100000)

Description

Check if a matrix has been loaded for a chromosome pair.

Usage

Brick_matrix_isdone(Brick, chr1, chr2, resolution = NA)

Arguments

Value

Returns a logical vector of length 1, specifying if a matrix has been loaded or not.

Examples

Bintable.path <- system.file(file.path("extdata", "Bintable_100kb.bins"), 
package = "HiCBricks")

out_dir <- file.path(tempdir(), "matrix_isdone_test")
dir.create(out_dir)

My_BrickContainer <- Create_many_Bricks(BinTable = Bintable.path, 
    bin_delim = " ", output_directory = out_dir, file_prefix = "Test",
    experiment_name = "Vignette Test", resolution = 100000,
    remove_existing = TRUE)

Matrix_file <- system.file(file.path("extdata", 
"Sexton2012_yaffetanay_CisTrans_100000_corrected_chr2L.txt.gz"), 
package = "HiCBricks")

Brick_load_matrix(Brick = My_BrickContainer, chr1 = "chr2L", 
chr2 = "chr2L", matrix_file = Matrix_file, delim = " ", 
remove_prior = TRUE, resolution = 100000)

Brick_matrix_isdone(Brick = My_BrickContainer, chr1 = "chr2L", 
chr2 = "chr2L", resolution = 100000)

Description

Check if a matrix for a chromosome pair is sparse.

Usage

Brick_matrix_issparse(Brick, chr1, chr2, resolution = NA)

Arguments

Value

Returns a logical vector of length 1, specifying if a matrix was loaded as a sparse matrix.

Examples

Bintable.path <- system.file(file.path("extdata", "Bintable_100kb.bins"), 
package = "HiCBricks")

out_dir <- file.path(tempdir(), "matrix_issparse_test")
dir.create(out_dir)

My_BrickContainer <- Create_many_Bricks(BinTable = Bintable.path, 
    bin_delim = " ", output_directory = out_dir, file_prefix = "Test",
    experiment_name = "Vignette Test", resolution = 100000,
    remove_existing = TRUE)

Matrix_file <- system.file(file.path("extdata", 
"Sexton2012_yaffetanay_CisTrans_100000_corrected_chr2L.txt.gz"), 
package = "HiCBricks")

Brick_load_matrix(Brick = My_BrickContainer, chr1 = "chr2L", 
chr2 = "chr2L", matrix_file = Matrix_file, delim = " ", 
remove_prior = TRUE, resolution = 100000)

Brick_matrix_issparse(Brick = My_BrickContainer, chr1 = "chr2L", 
chr2 = "chr2L", resolution = 100000)

Description

If values beyond a certain distance were not loaded in the matrix, this distance parameter is useful. This package by default will check this param to make sure that it is not returning non-existent data.

Usage

Brick_matrix_maxdist(Brick, chr1, chr2, resolution = NA)

Arguments

Details

Brick_matrix_maxdist will return this parameter.

Value

Returns an integer vector of length 1, specifying the maximum distance loaded for that matrix

Examples

Bintable.path <- system.file(file.path("extdata", "Bintable_100kb.bins"), 
package = "HiCBricks")

out_dir <- file.path(tempdir(), "matrix_maxdist_test")
dir.create(out_dir)

My_BrickContainer <- Create_many_Bricks(BinTable = Bintable.path, 
    bin_delim = " ", output_directory = out_dir, file_prefix = "Test",
    experiment_name = "Vignette Test", resolution = 100000,
    remove_existing = TRUE)

Matrix_file <- system.file(file.path("extdata", 
"Sexton2012_yaffetanay_CisTrans_100000_corrected_chr2L.txt.gz"), 
package = "HiCBricks")

Brick_load_matrix(Brick = My_BrickContainer, chr1 = "chr2L", 
chr2 = "chr2L", matrix_file = Matrix_file, delim = " ", 
remove_prior = TRUE, resolution = 100000)

Brick_matrix_maxdist(Brick = My_BrickContainer, chr1 = "chr2L", 
chr2 = "chr2L", resolution = 100000)

Description

Return the value range of the matrix

Usage

Brick_matrix_minmax(Brick, chr1, chr2, resolution = NA)

Arguments

Value

Returns a numeric vector of length 2, specifying the minimum and maximum finite real values in the matrix.

Examples

Bintable.path <- system.file(file.path("extdata", "Bintable_100kb.bins"), 
package = "HiCBricks")

out_dir <- file.path(tempdir(), "matrix_minmax_test")
dir.create(out_dir)

My_BrickContainer <- Create_many_Bricks(BinTable = Bintable.path, 
    bin_delim = " ", output_directory = out_dir, file_prefix = "Test",
    experiment_name = "Vignette Test", resolution = 100000,
    remove_existing = TRUE)

Matrix_file <- system.file(file.path("extdata", 
"Sexton2012_yaffetanay_CisTrans_100000_corrected_chr2L.txt.gz"), 
package = "HiCBricks")

Brick_load_matrix(Brick = My_BrickContainer, chr1 = "chr2L", 
chr2 = "chr2L", matrix_file = Matrix_file, delim = " ", 
remove_prior = TRUE, resolution = 100000)

Brick_matrix_minmax(Brick = My_BrickContainer, chr1 = "chr2L", 
chr2 = "chr2L", resolution = 100000)

Description

Brick_mcool_normalisation_exists checks if a particular normalisation exists in an mcool file.

Usage

Brick_mcool_normalisation_exists(mcool, norm_factor = NULL, resolution = NULL)

Arguments

Value

A boolean vector of length 1

Examples

## Not run: 

require(curl)
out_dir <- file.path(tempdir(), "mcool_test_dir")
dir.create(path = out_dir)
curl_download(url = paste("https://data.4dnucleome.org/",
"files-processed/4DNFI7JNCNFB/",
"@download/4DNFI7JNCNFB.mcool", sep = ""),
destfile = file.path(out_dir, "H1-hESC-HiC-4DNFI7JNCNFB.mcool"))

mcool <- file.path(out_dir, "H1-hESC-HiC-4DNFI7JNCNFB.mcool")
Brick_mcool_normalisation_exists(mcool = mcool,
norm_factor = "Iterative-Correction",
resolution = 50000)


## End(Not run)

Description

Brick_rangekey_exists checks for the presence of a particular ranges with a certain name.

Usage

Brick_rangekey_exists(
    Brick,
    rangekey,
    resolution = NA,
    all_resolutions = FALSE
)

Arguments

Value

A logical vector of length 1 with either TRUE or FALSE values.

Examples

Bintable.path <- system.file(file.path("extdata", "Bintable_100kb.bins"), 
package = "HiCBricks")

out_dir <- file.path(tempdir(), "list_rangekeys_exists_test")

dir.create(out_dir)

My_BrickContainer <- Create_many_Bricks(BinTable = Bintable.path, 
    bin_delim = " ", output_directory = out_dir, file_prefix = "Test",
    experiment_name = "Vignette Test", resolution = 100000,
    remove_existing = TRUE)
Brick_rangekey_exists(Brick = My_BrickContainer, rangekey = "Bintable",
resolution = 100000)

Description

Brick_return_region_position takes as input a human-readable coordinate format of the form chr:start:end and outputs the overlapping bintable positions. This module does a "within" operation. So only bins which overlap completely with the region will be returned. This is not an iterable module, so the user has to make iterative calls to the module itself.

Usage

Brick_return_region_position(Brick, region, resolution = NA)

Arguments

Value

Returns a 1 dimensional vector containing the position of the overlapping regions in the bintable associated the Brick store.

Design choice

This may seem to be a poor design choice at first glance, but I do not think this to be the case. By not being iterable, this function circumvents the problem of how to structure the data for the user. If one more element was accepted, the return object would have become a list, which increases the data structure complexity significantly for users who are just starting out with R. Therefore this problem is left for the users themselves to deal with.

Examples

Bintable.path <- system.file(file.path("extdata", "Bintable_100kb.bins"),
package = "HiCBricks")

out_dir <- file.path(tempdir(), "region_position_test")
dir.create(out_dir)

My_BrickContainer <- Create_many_Bricks(BinTable = Bintable.path, 
    bin_delim = " ", output_directory = out_dir, file_prefix = "Test",
    experiment_name = "Vignette Test", resolution = 100000,
    remove_existing = TRUE)

Coordinate <- "chr2L:1:1000000"

Test_Run <- Brick_return_region_position(Brick = My_BrickContainer,
region = Coordinate, resolution = 100000)

Description

Brick_vizart_plot_heatmap creates various heatmaps and plots TADs.

Usage

Brick_vizart_plot_heatmap(
    File,
    Bricks,
    resolution,
    x_coords,
    y_coords,
    FUN = NULL,
    value_cap = NULL,
    distance = NULL,
    rotate = FALSE,
    x_axis = TRUE,
    x_axis_title = NULL,
    y_axis = TRUE,
    y_axis_title = NULL,
    title = NULL,
    legend_title = NULL,
    return_object = FALSE,
    x_axis_num_breaks = 5,
    y_axis_num_breaks = 5,
    palette,
    col_direction = 1,
    extrapolate_on = NULL,
    x_axis_text_size = 10,
    y_axis_text_size = 10,
    text_size = 10,
    legend_title_text_size = 8,
    legend_text_size = 8,
    title_size = 10,
    tad_ranges = NULL,
    group_col = NULL,
    tad_colour_col = NULL,
    colours = NULL,
    colours_names = NULL,
    cut_corners = FALSE,
    highlight_points = NULL,
    width = 10,
    height = 6,
    line_width = 0.5,
    units = "cm",
    legend_key_width = unit(3, "cm"),
    legend_key_height = unit(0.5, "cm")
)

Arguments

Details

This function provides the capability to plot various types of heatmaps from Hi-C data.

• One sample heatmap.

• Two sample heatmap (One sample on upper and other on lower).

• All of the above with 90 degree rotation.

• All of the above but with signal capped at a certain value.

• All of the above but filtered by distance.

• All of the above with TADs/TAD borders plotted on top.

Value

If return_object is set to TRUE, the constructed ggplot2 object will be returned. Else TRUE.

Examples

FailSafe_log10 <- function(x){
     x[is.na(x) | is.nan(x) | is.infinite(x)] <- 0
     return(log10(x+1))
}

Bintable.path <- system.file(file.path("extdata", "Bintable_100kb.bins"), 
package = "HiCBricks")

out_dir <- file.path(tempdir(), "vizart_test")
dir.create(out_dir)

My_BrickContainer <- Create_many_Bricks(BinTable = Bintable.path, 
    bin_delim = " ", output_directory = out_dir, file_prefix = "Test",
    experiment_name = "Vignette Test", resolution = 100000,
    remove_existing = TRUE)

Matrix_file <- system.file(file.path("extdata", 
"Sexton2012_yaffetanay_CisTrans_100000_corrected_chr3R.txt.gz"), 
package = "HiCBricks")

Brick_load_matrix(Brick = My_BrickContainer, chr1 = "chr3R", 
chr2 = "chr3R", matrix_file = Matrix_file, delim = " ",
remove_prior = TRUE, resolution = 100000)

Brick_vizart_plot_heatmap(File = "./chr3R-1-10000000.pdf", 
Bricks = list(My_BrickContainer), resolution = 100000, 
x_coords = "chr3R:1:10000000", palette = "Reds", 
y_coords = "chr3R:1:10000000", FUN = FailSafe_log10, 
value_cap = 0.99, width = 10, height = 11, legend_key_width = unit(3,"mm"),
legend_key_height = unit(0.3,"cm"))

Description

BrickContainer_change_experiment_name changes the location of name of the experiment

Usage

BrickContainer_change_experiment_name(Brick = NULL, experiment_name = NULL)

Arguments

Value

An object of class BrickContainer where the experiment_name has been changed

Examples

Bintable.path <- system.file("extdata",
"Bintable_100kb.bins", package = "HiCBricks")

out_dir <- file.path(tempdir(), "BrickContainer_expt_name_test")
dir.create(out_dir)

My_BrickContainer <- Create_many_Bricks(BinTable = Bintable.path, 
    bin_delim = " ", output_directory = out_dir, file_prefix = "Test", 
    experiment_name = "Vignette Test", resolution = 100000, 
    remove_existing = TRUE)

BrickContainer_change_experiment_name(Brick = My_BrickContainer, 
experiment_name = "I change my mind")

Description

BrickContainer_change_output_directory changes the location of associated HDF files

Usage

BrickContainer_change_output_directory(Brick = NULL, output_directory = NULL)

Arguments

Value

An object of class BrickContainer where the output_directory has been changed

Examples

Bintable.path <- system.file("extdata",
"Bintable_100kb.bins", package = "HiCBricks")

out_dir <- file.path(tempdir(), "BrickContainer_out_dir_test")
dir.create(out_dir)

My_BrickContainer <- Create_many_Bricks(BinTable = Bintable.path, 
    bin_delim = " ", output_directory = out_dir, file_prefix = "Test", 
    experiment_name = "Vignette Test", resolution = 100000, 
    remove_existing = TRUE)

BrickContainer_change_output_directory(Brick = My_BrickContainer, 
output_directory = tempdir())

Description

BrickContainer_get_path_to_file fetches the list of HDF file paths associated to a particular BrickContainer

Usage

BrickContainer_get_path_to_file(
    Brick = NULL,
    chr1 = NA,
    chr2 = NA,
    type = NA,
    resolution = NA
)

Arguments

Value

A vector containing filepaths

Examples

Bintable.path <- system.file("extdata",
"Bintable_100kb.bins", package = "HiCBricks")

out_dir <- file.path(tempdir(), "BrickContainer_list_filepath_test")
dir.create(out_dir)

My_BrickContainer <- Create_many_Bricks(BinTable = Bintable.path, 
  bin_delim = " ", output_directory = out_dir, file_prefix = "Test", 
  experiment_name = "Vignette Test", resolution = 100000, 
  remove_existing = TRUE)

BrickContainer_get_path_to_file(Brick = My_BrickContainer, chr1 = "chr2L",
chr2 = "chr2L", resolution = 100000)

Description

BrickContainer_list_chromosomes returns the chromosomes available in the BrickContainer

Usage

BrickContainer_list_chromosomes(Brick = NULL, lengths = FALSE)

Arguments

Value

If lengths is FALSE, only the chromosome names are returned. If lengths is TRUE, a data.frame containing the chromosome names and their lengths is provided.

Examples

Bintable.path <- system.file("extdata",
"Bintable_100kb.bins", package = "HiCBricks")

out_dir <- file.path(tempdir(), "BrickContainer_list_chromosome_test")
dir.create(out_dir)

My_BrickContainer <- Create_many_Bricks(BinTable = Bintable.path, 
    bin_delim = " ", output_directory = out_dir, file_prefix = "Test", 
    experiment_name = "Vignette Test", resolution = 100000, 
    remove_existing = TRUE)

BrickContainer_list_chromosomes(My_BrickContainer)

Description

BrickContainer_list_experiment_name returns the descriptive name of a BrickContainer

Usage

BrickContainer_list_experiment_name(Brick = NULL)

Arguments

Value

A character string specifying the descriptive name of the BrickContainer

Examples

Bintable.path <- system.file("extdata",
"Bintable_100kb.bins", package = "HiCBricks")

out_dir <- file.path(tempdir(), "BrickContainer_list_expt_name_test")
dir.create(out_dir)

My_BrickContainer <- Create_many_Bricks(BinTable = Bintable.path, 
    bin_delim = " ", output_directory = out_dir, file_prefix = "Test", 
    experiment_name = "Vignette Test", resolution = 100000, 
    remove_existing = TRUE)

BrickContainer_list_experiment_name(My_BrickContainer)

Description

BrickContainer_list_files fetches the list of HDF files associated to a particular BrickContainer

Usage

BrickContainer_list_files(
    Brick = NULL,
    chr1 = NA,
    chr2 = NA,
    type = NA,
    resolution = NA
)

Arguments

Value

A 5 column tibble containing chromosome pairs, Hi-C resolution, the type of Hi-C matrix and the path to a particular Hi-C matrix file.

Examples

Bintable.path <- system.file("extdata",
"Bintable_100kb.bins", package = "HiCBricks")
out_dir <- file.path(tempdir(), "BrickContainer_list_file_test")
dir.create(out_dir)
My_BrickContainer <- Create_many_Bricks(BinTable = Bintable.path, 
   bin_delim = " ", output_directory = out_dir, file_prefix = "Test", 
   experiment_name = "Vignette Test", resolution = 100000, 
   remove_existing = TRUE)

BrickContainer_list_files(Brick = My_BrickContainer, chr1 = "chr2L",
chr2 = NA)

Description

BrickContainer_list_output_directory returns the location of the associated HDF files

Usage

BrickContainer_list_output_directory(Brick = NULL)

Arguments

Value

A character string specifying the descriptive name of the BrickContainer

Examples

Bintable.path <- system.file("extdata",
"Bintable_100kb.bins", package = "HiCBricks")

out_dir <- file.path(tempdir(), "BrickContainer_list_out_dir_test")
dir.create(out_dir)

My_BrickContainer <- Create_many_Bricks(BinTable = Bintable.path, 
    bin_delim = " ", output_directory = out_dir, file_prefix = "Test", 
    experiment_name = "Vignette Test", resolution = 100000, 
    remove_existing = TRUE)

BrickContainer_list_output_directory(My_BrickContainer)

Description

BrickContainer_list_resolutions returns the resolutions available in the BrickContainer

Usage

BrickContainer_list_resolutions(Brick = NULL)

Arguments

Value

A character string specifying the descriptive name of the BrickContainer

Examples

Bintable.path <- system.file("extdata",
"Bintable_100kb.bins", package = "HiCBricks")

out_dir <- file.path(tempdir(), "BrickContainer_list_resolution_test")
dir.create(out_dir)

My_BrickContainer <- Create_many_Bricks(BinTable = Bintable.path, 
    bin_delim = " ", output_directory = out_dir, file_prefix = "Test", 
    experiment_name = "Vignette Test", resolution = 100000, 
    remove_existing = TRUE)

BrickContainer_list_resolutions(My_BrickContainer)

Description

BrickContainer_unlink_resolution removes links to all files associated to a given resolution

Usage

BrickContainer_unlink_resolution(Brick = NULL, resolution = NULL)

Arguments

Value

An object of class BrickContainer where the resolution and links to its associated files have been removed

Examples

Bintable.path <- system.file("extdata",
"Bintable_100kb.bins", package = "HiCBricks")

out_dir <- file.path(tempdir(), "BrickContainer_unlink_res_test")
dir.create(out_dir)

My_BrickContainer <- Create_many_Bricks(BinTable = Bintable.path, 
    bin_delim = " ", output_directory = out_dir, file_prefix = "Test", 
    experiment_name = "Vignette Test", resolution = 100000, 
    remove_existing = TRUE)

My_BrickContainer <- Create_many_Bricks(BinTable = Bintable.path, 
    bin_delim = " ", output_directory = out_dir, file_prefix = "Test", 
    experiment_name = "Vignette Test", resolution = 40000, 
    remove_existing = TRUE)

BrickContainer_unlink_resolution(Brick = My_BrickContainer, 
resolution = 40000)

Description

Create_many_Bricks creates the HDF file and returns a BrickContainer

Usage

Create_many_Bricks(
    BinTable,
    bin_delim = "\t",
    col_index = c(1, 2, 3),
    impose_discontinuity = TRUE,
    hdf_chunksize = NULL,
    output_directory = NA,
    file_prefix = NA,
    remove_existing = FALSE,
    link_existing = FALSE,
    experiment_name = NA,
    resolution = NA,
    type = c("both", "cis", "trans")
)

Arguments

Details

This function creates the complete HDF data structure, loads the binning table associated to the Hi-C experiment, creates a 2D matrix layout for all specified chromosome pairs and creates a json file for the project. At the end, this function will return a S4 object of class BrickContainer. Please note, the binning table must be a discontinuous one (first range end != secode range start), as ranges overlaps using the "any" form will routinely identify adjacent ranges with the same end and start to be in the overlap. Therefore, this criteria is enforced as default behaviour.

The structure of the HDF file is as follows: The structure contains three major groups which are then hierarchically nested with other groups to finally lead to the corresponding datasets.

• Base.matrices - group For storing Hi-C matrices

  • chromosome - group

  • chromosome - group

    • attributes - attribute

      • Filename - Name of the file

      • Min - min value of Hi-C matrix

      • Max - max value of Hi-C matrix

      • sparsity - specifies if this is a sparse matrix

      • distance - max distance of data from main diagonal

      • Done - specifies if a matrix has been loaded

    • matrix - dataset - contains the matrix

    • chr1_bin_coverage - dataset - proportion of row cells with values greater than 0

    • chr1_row_sums - dataset - total sum of all values in a row

    • chr2_col_sums - dataset - total sum of all values in a col

    • chr2_bin_coverage - dataset - proportion of col cells with values greater than 0

    • sparsity - dataset - proportion of non-zero cells near the diagonal

• Base.ranges - group, Ranges tables for quick and easy access. Additional ranges tables are added here under separate group names.

  • Bintable - group - The main binning table associated to a Brick.

    • ranges - dataset - Contains the three main columns chr, start and end.

    • offsets - dataset - first occurence of any given chromosome in the ranges dataset.

    • lengths - dataset - Number of occurences of that chromosome

    • chr.names - dataset - What chromosomes are present in the given ranges table.

• Base.metadata - group, A place to store metadata info

  • chromosomes - dataset - Metadata information specifying the chromosomes present in this particular Brick file.

  • other metadata tables.

Keep in mind that if the end coordinates and start coordinates of adjacent ranges are not separated by at least a value of 1, then impose.discontinuity = TRUE will likely cause an error to occur. This may seem obnoxious, but GenomicRanges by default will consider an overlap of 1 bp as an overlap. Therefore, to be certain that ranges which should not be, are not being targeted during retrieval operations, a check is initiated to make sure that adjacent ends and starts are not overlapping. To load continuous ranges, use impose.discontinuity = FALSE.

Also note, that col.index determines which columns to use for chr, start and end. Therefore, the original binning table may have 10 or 20 columns, but it only requires the first three in order of chr, start and end.

Value

This function will generate the target Brick file. Upon completion, the function will return an object of class BrickContainer.

Examples

Bintable.path <- system.file(file.path("extdata", "Bintable_100kb.bins"), 
package = "HiCBricks")
out_dir <- file.path(tempdir(), "Creator_test")
dir.create(out_dir)
My_BrickContainer <- Create_many_Bricks(BinTable = Bintable.path, 
    bin_delim = " ", output_directory = out_dir, file_prefix = "Test", 
    experiment_name = "Vignette Test", resolution = 100000, 
    remove_existing = TRUE)

Description

Create_many_Bricks_from_mcool is a wrapper on Create_many_Bricks which creates the Brick data structure from an mcool file.

Usage

Create_many_Bricks_from_mcool(
    output_directory = NA,
    file_prefix = NA,
    mcool = NULL,
    resolution = NULL,
    experiment_name = NA,
    remove_existing = FALSE
)

Arguments

Details

mcool are a standard 4D nucleome data structure for Hi-C data. Read more about the 4D nucleome project here.

Value

This function will generate the target Brick file. Upon completion, the function will provide the path to the created/tracked HDF file.

See Also

Brick_load_data_from_mcool to load data from the mcool to a Brick store.

Examples

## Not run: 
require(curl)
out_dir <- file.path(tempdir(),"mcool_test_dir")
dir.create(path = out_dir)
curl_download(url = paste("https://data.4dnucleome.org/",
"files-processed/4DNFI7JNCNFB/",
"@download/4DNFI7JNCNFB.mcool", sep = ""),
destfile = file.path(out_dir,"H1-hESC-HiC-4DNFI7JNCNFB.mcool"))

mcool <- file.path(out_dir,"H1-hESC-HiC-4DNFI7JNCNFB.mcool")

Create_many_Bricks_from_mcool(output_directory = out_dir,
file_prefix = "Test",
mcool = mcool,
resolution = 50000,
experiment_name = "A random 4DN dataset")


## End(Not run)

Description

HiCBricks is a package allowing users to flexibly import and work with Hi-C data

Details

Using HiCBricks users are able to import Hi-C matrices stored in various formats into an HDF structure. This is the Brick file. You can then access the Hi-C data using accessor functions. Since the data is stored in an HDF file, if you have the Brick (HDF) file, you can keep on accessing the same file an infinite number of times.

Users can also associate different ranges objects with the HDF file.

The HDF file must have the same structure as followed by HiCBricks

Users can then move forward and create analysis pipelines and statistical methods based on HiCBricks HDF files without worrying about the underlying data structure. To showcase this, Local score differentiator (LSD) our novel TAD calling procedure comes packaged with HiCBricks.

You are also able to plot Hi-C data using HiCBricks functions. There are a few types. You can create,

• a square heatmap

• a rotated heatmap

• two group square/rotated heatmaps

• both heatmaps until a certain distance

• plot TADs on both heatmaps

Brick creation

• Create_many_Bricks - Create the HDF data structures. We refer to the HDF files as Bricks

• Create_many_Bricks_from_mcool - Create the complete Brick data structure from an mcool file.

Matrix loaders

• Brick_load_matrix - Load a complete nxm dimensional matrix.

• Brick_load_cis_matrix_till_distance - Load a sam chromosome nxn dimensional matrix until a certain distance.

• Brick_load_data_from_mcool - Load parts of the data from the 4DN consortium generated mcool files.

Matrix Accessors

• Brick_get_matrix_within_coords - Fetches a matrix within the provided genomic coordinates.

• Brick_get_matrix - Fetches a matrix within the provided x and y coordinates.

• Brick_get_values_by_distance - Fetch all values corresponding to interactions between genomic loci separated by the corresponding value.

• Brick_fetch_row_vector - Fetch all values at a given row or column.

All of the functions above can be subsetted and contain further value transformations.

Ranges operators

• Brick_get_bintable - All HiCBricks Brick files contain a binning table containing the coordinate information of the matrix. This fetches the associated binning table.

• Brick_add_ranges - Add a ranges object to the Brick file.

• Brick_get_ranges - Get a ranges object associated to a Brick file.

• Brick_fetch_range_index - Provided a set of coordinate vectors, get the corresponding rows/cols overlapping with those coordinates.

• Brick_make_ranges - Create a granges object from provided vectors.

• Brick_return_region_position - Get the row/col number corresponding to coordinates spelled out in human readable format.

Other functions

• Brick_local_score_differentiator - Use the LSD TAD calling procedure to do some TAD calls.

• Brick_vizart_plot_heatmap - Plot pretty heatmaps.

Utility functions

• Brick_get_chrominfo - Get the basic information regarding the Brick file. Which chromosomes are present, dimension of the matrix and the total length of the chromosome.

• Brick_get_matrix_mcols - Get the matrix metadata information. Such as, row sums, coverage information and how sparse regions near the diagonal are.

• Brick_list_matrices - List all the matrices present in the Brick file. Alongside, also provide information such as if the matrix has been loaded or not, min max values, e.t.c

• Brick_list_rangekeys - List the names of the ranges present in the Brick file.

• Brick_rangekey_exists - Answers the question, is this rangekey present in the Brick file?

• Brick_list_ranges_mcols - List the names of metadata columns associated to a ranges object in the Brick file.

• Brick_matrix_dimensions - Get the dimensions of a given matrix.

• Brick_matrix_exists - Answers the question, has a matrix been created for this Brick store?

• Brick_matrix_filename - Answers the question, what is the name of the file used to load this particular matrix?

• Brick_matrix_isdone - Answers the question, has this matrix been loaded already?

• Brick_matrix_issparse - Answers the question, was this matrix defined as a sparse matrix while loading?

• Brick_matrix_maxdist - If Brick_load_cis_matrix_till_distance was used for loading data, then this function will tell you until what distance data was loaded.

• Brick_matrix_minmax - Outputs the value range of the matrix.

mcool utility functions

• Brick_list_mcool_normalisations - List the names of normalisation vectors that can be present in a mcool file.

• Brick_mcool_normalisation_exists - Check if a specific normalisation vector exists in an mcool file.

• Brick_list_mcool_resolutions - List the resolutions present in an mcool file.

Description

load_BrickContainer creates a BrickContainer object from a JSON file

Usage

load_BrickContainer(config_file = NULL, project_dir = NULL)

Arguments

Value

An object of class BrickContainer

Examples

Bintable.path <- system.file("extdata",
"Bintable_100kb.bins", package = "HiCBricks")
out_dir <- file.path(tempdir(), "BrickContainer_load_test")
dir.create(out_dir)
Create_many_Bricks(BinTable = Bintable.path, 
  bin_delim = " ", output_directory = out_dir, file_prefix = "Test", 
  experiment_name = "Vignette Test", resolution = 100000, 
  remove_existing = TRUE)
My_BrickContainer <- load_BrickContainer(project_dir = out_dir)