Aggregate module¶

class fanc.architecture.aggregate.AggregateMatrix(file_name=None, mode='r', tmpdir=None, x=None, y=None)¶

Bases: fanc.general.FileGroup

Construct and store aggregate matrices from matrix-based objects.

Methods in this class can be used to generate various kinds of aggregate matrices, constructed from averaging the signal from different regions of a Hi-C (or similar) matrix. Particularly useful is the creation of aggregate matrices from observed/expected data.

Class methods control how exactly an aggregate matrix is constructed:

AggregateMatrix.from_center() will aggregate Hi-C matrix regions along the diagonal in a fixed window around the region center. This is useful, for example, to observe the signal around TAD boundaries or other local features, such as the start of genes, enhancer locations, …
AggregateMatrix.from_regions() will extract sub-matrices using regions of variable size - such as TADs - and interpolate them to the same number of pixels before aggregating them.
AggregateMatrix.from_center_pairs() will extract arbitrary Hi-C submatrices from a list of region pairs (representing row and column of the matrix). Each submatrix is centered on each region, and a fixed number of pixels around the center is extracted. This is used, for example, to plot aggregate matrices around loops, using the loop anchors as input.

close(copy_tmp=True, remove_tmp=True)¶

Close this HDF5 file and run exit operations.

If file was opened with tmpdir in read-only mode: close file and delete temporary copy.

If file was opened with tmpdir in write or append mode: Replace original file with copy and delete copy.

Parameters

copy_tmp – If False, does not overwrite original with modified file.
remove_tmp – If False, does not delete temporary copy of file.

components(components=None)¶

Retrieve or store each individual submatrix composing the aggregate matrix.

Parameters: components – List of (masked) numpy arrays
Returns: List of (masked) numpy arrays

classmethod from_center(matrix, regions, window=200000, rescale=False, scaling_exponent=-0.25, keep_components=True, file_name=None, tmpdir=None, region_viewpoint='center', **kwargs)¶

Construct an aggregate matrix from square regions along the diagonal with a fixed window size.

By default, the submatrix that is extracted from matrix is centred on the region centre and has a window size specified by window. You can change where the window will be centered using region_viewpoint, which can be any of “center”, “start”, “end”, “five_prime”, or “three_prime”. The latter two may be particularly useful for genomic features such as genes.

Example for TAD boundaries:

import fanc
hic = fanc.load("/path/to/matrix.hic")
tad_boundaries = fanc.load("/path/to/tad_boundaries.bed")

# run aggregate analysis
am = fanc.AggregateMatrix.from_center(hic, tad_boundaries.regions,
                                      window=500000)
# extract matrix when done
m = am.matrix()

Parameters

matrix – An object of type RegionMatrixContainer, such as a Hic matrix
regions – A list of GenomicRegion objects
window – A window size in base pairs
rescale – If True, will use scaling_exponent to artificially rescale the aggregate matrix values using a power law
scaling_exponent – The power law exponent used if rescale is True
keep_components – If True (default) will store each submatrix used to generate the aggregate matrix in the AggregateMatrix object, which can be retrieved using AggregateMatrix.components()
file_name – If provided, stores the aggregate matrix object at this location.
tmpdir – If True will work in temporary directory until the object is closed
region_viewpoint – point on which window is centred. any of “center”, “start”, “end”, “five_prime”, or “three_prime”
kwargs – Keyword arguments passed to extract_submatrices()

Returns

aggregate matrix

classmethod from_center_pairs(hic, pair_regions, window=None, pixels=16, keep_components=True, file_name=None, tmpdir=None, region_viewpoint='center', **kwargs)¶

Construct an aggregate matrix from pairs of regions.

Parameters

hic – A compatible Hi-C matrix
pair_regions – A list of region pairs
window – A window size in base pairs
pixels – The dimension (in pixels) of the output matrix
keep_components – Keep all submatrices that make up the aggregate matrix
file_name – Optional path to an output file
tmpdir – Optional. If True, will work in temporary directory until file is closed
region_viewpoint – Location in each region that is used as anchor for the extracted matrix. ‘center’ by default, also valid are ‘start’, ‘end’, ‘five_prime’, and ‘three_prime’
kwargs – Keyword arguments passed on to extract_submatrices()

Returns

AggregateMatrix

classmethod from_regions(hic, tad_regions, pixels=90, rescale=False, scaling_exponent=-0.25, interpolation=0, boundary_mode='reflect', keep_mask=True, absolute_extension=0, relative_extension=1.0, keep_components=True, anti_aliasing=True, file_name=None, tmpdir=None, **kwargs)¶

Construct aggregate matrix from variable regions along the diagonal.

For each region in tad_regions, a submatrix is extracted and interpolated so that it is exactly pixels x pixels big. You can expand each region by a relative amount using relative_extension.

Example for aggregate TADs:

import fanc
hic = fanc.load("/path/to/matrix.hic")
tads = fanc.load("/path/to/tads.bed")

# run aggregate analysis
am = fanc.AggregateMatrix.from_regions(hic, tads.regions,
                                       relative_extension=3.)
# extract matrix when done
m = am.matrix()  # 90x90 matrix with aggregate TAD in the centre

Parameters

hic – An object of type RegionMatrixContainer, such as a Hic matrix
tad_regions – A list of GenomicRegion objects
pixels – Number of pixels along each dimension of the aggregate matrix
rescale – If True, will use scaling_exponent to artificially rescale the aggregate matrix values using a power law
scaling_exponent – The power law exponent used if rescale is True
interpolation – Type of interpolation used on each submatrix in range 0-5. 0: Nearest-neighbor (default), 1: Bi-linear, 2: Bi-quadratic, 3: Bi-cubic, 4: Bi-quartic, 5: Bi-quintic
boundary_mode – Points outside the boundaries of the input are filled according to the given mode. Options are constant, edge, symmetrix, reflect, and warp. Affects submatrix interpolation.
keep_mask – If True (default) maksed Hi-C regions will also be interpolated.
absolute_extension – Absolute number of base pairs by which to expand each region
absolute_extension – Amount by which to expand each region as a fraction of each region. Values smaller than 1 lead to region shrinking
keep_components – If True (default) will store each submatrix used to generate the aggregate matrix in the AggregateMatrix object, which can be retrieved using AggregateMatrix.components()
file_name – If provided, stores the aggregate matrix object at this location.
tmpdir – If True will work in temporary directory until the object is closed
kwargs – Keyword argumnts passed to extract_submatrices()

Returns

aggregate matrix

matrix(m=None)¶

Retrieve or set the aggregate matrix in this object.

Parameters: m – Numpy matrix
Returns: aggregate matrix

region_pairs(pairs=None)¶

Retrieve or set the regions used to generate the aggregate matrix.

Parameters: pairs – Iterable of region tuples of the form [(region1, region2), (region3, region4), …]. If None, simply return the region pairs in this object.
Returns: List of region pairs [(region1, region2), (region3, region4), …].