Aggregate module — FAN-C 0.9.1-beta documentation

# 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), …].