hic3defdr.util.banded_matrix module¶

class hic3defdr.util.banded_matrix.BandedMatrix(data, shape=None, copy=False, max_range=300, upper=None)[source]¶

Bases: scipy.sparse.dia.dia_matrix

classmethod align(*matrices)[source]¶

classmethod apply(f, *args, **kwargs)[source]¶

Applies a function that takes in raw banded matrices (rectangular dense arrays) and returns raw banded matrices to one or more BandedMatrices.

Parameters:	f (function) – The function to apply. At least its first positional arg (or as many as all of them) should be an `np.ndarray` corresponding to the `data` array of a BandedMatrix. It should return one `np.ndarray` or a tuple of `np.ndarray` corresponding to the `data` array(s) of the resulting BandedMatrix(ces). args (positional arguments) – Passed through to `f()`. Instances of BandedMatrix will be passed as just their `data` arrays. If multiple BandedMatrices are passed, no attempt will be made to align them - a ValueError will be raised if they are not aligned. kwargs (keyword arguments*) – Passed through to `f()`. No conversion from BandedMatrix will be attempted.
Returns:	If `f()` returns a single `np.ndarray`, `BandedMatrix.apply(f, arg1, ...)` will return one BandedMatrix, whose shape and offsets will be taken from `arg1` (which must always be an BandedMatrix) and whose data will be taken from `f(arg1.data, ...)`. If `f()` returns a tuple of `np.ndarray`, they will each be repackaged into an BandedMatrix in this fashion, and the tuple of new BandedMatrix will be returned.
Return type:	BandedMatrix or tuple of BandedMatrix

copy()[source]¶

Returns a copy of this matrix.

No data/indices will be shared between the returned value and current matrix.

data_indices(key)[source]¶

deconvolute(bias, invert=False)[source]¶

Applies a bias vector to both the rows and the columns of the BandedMatrix.

Parameters:	bias (np.ndarray) – Bias vector to apply. Should match size of BandedMatrix. invert (bool) – Pass True to invert the bias vector (divide the BandedMatrix by the the outer product of the bias vector with itself). Pass False to multiply the BandedMatrix by the outer product of the bias vector with itself.
Returns:	The result of the deconvolution.
Return type:	BandedMatrix

Examples

>>> import numpy as np
>>> from hic3defdr.util.banded_matrix import BandedMatrix
>>> a = np.arange(16).reshape(4, 4).astype(float)
>>> a += a.T
>>> bias = np.sqrt(np.sum(a, axis=0))
>>> b = ((a / bias).T / bias).T
>>> bm = BandedMatrix.from_ndarray(b, max_range=3)
>>> bm = bm.deconvolute(bias)
>>> np.allclose(bm.toarray(), a)
True

flatten()[source]¶

classmethod from_dia_matrix(dia_matrix, copy=True)[source]¶

classmethod from_ndarray(ndarray, max_range=300, upper=None)[source]¶

classmethod from_sparse(spmatrix, max_range=300, upper=None)[source]¶

Constructs a BandedMatrix from a scipy.spare.spmatrix instance.

Parameters:	spmatrix (scipy.spare.spmatrix) – The sparse matrix to convert to BandedMatrix. max_range (int) – Offdiagnals beyond the max_range’th offdiagonal will be discarded. upper (bool, optional) – Pass True to keep only the upper triangular entries. Pass False to keep all the entries. Pass None to guess what to do based on whether or not the input matrix is upper triangular.
Returns:	The new BandedMatrix.
Return type:	BandedMatrix

Notes

Mostly stolen from sparse.coo_matrix.todia(), plus nan padding from BandedMatrix.from_ndarray() and nan triangles from BandedMatrix.roll_matrix().

classmethod is_bandedmatrix(x)[source]¶

is_upper()[source]¶

classmethod load(fname, **kwargs)[source]¶

log()[source]¶

static make_mask(matrix, min_range=None, max_range=None, upper=False, nan=False)[source]¶

General-purpose function for creating masks for contact matrices.

Parameters:	matrix (np.ndarray) – Square contact matrix to make a mask for. max_range (min_range,) – Pass ints to specify a minimum and maximum allowed interaction range, in bin units. upper (bool) – Pass True to restrict the mask to the upper triangular entries. nan (bool) – Pass True to restrict the mask to non-NaN points.
Returns:	The mask. Same shape as `matrix`, with bool dtype.
Return type:	np.ndarray

make_upper(pad=True)[source]¶

classmethod max(*matrices)[source]¶

Returns the element-wise maximum of a list of BandedMatrices.

Parameters:	matrices (sequence of BandedMatrix*) – The matrices to compute the maximum of. Must already be aligned.
Returns:	The maximum.
Return type:	BandedMatrix

Notes

If the matrices aren’t aligned, consider:

BandedMatrix.max(BandedMatrix.align(bm_a, bm_b, bm_c, …))

max_range()[source]¶

ravel()[source]¶

reshape(self, shape, order='C', copy=False)[source]¶

Gives a new shape to a sparse matrix without changing its data.

Parameters:	shape (length-2 tuple of ints) – The new shape should be compatible with the original shape. order ({'C', 'F'}, optional) – Read the elements using this index order. ‘C’ means to read and write the elements using C-like index order; e.g. read entire first row, then second row, etc. ‘F’ means to read and write the elements using Fortran-like index order; e.g. read entire first column, then second column, etc. copy (bool, optional) – Indicates whether or not attributes of self should be copied whenever possible. The degree to which attributes are copied varies depending on the type of sparse matrix being used.
Returns:	reshaped_matrix – A sparse matrix with the given shape, not necessarily of the same format as the current object.
Return type:	sparse matrix