lib5c.core.interactions module¶
-
class
lib5c.core.interactions.
InteractionMatrix
(matrix, locusmap=None)[source]¶ Bases:
lib5c.core.mixins.Picklable
,lib5c.core.mixins.Annotatable
,lib5c.core.mixins.Loggable
Class representing pairwise architectural contact frequencies between genomic loci. At its heart, this is a square, symmetric matrix whose \(ij\) th entry corresponds to the interaction frequency between the \(i\) th genomic locus and the \(j\) th genomic locus. Optionally, some metadata for the genomic loci may be included.
-
matrix
¶ The matrix of interaction frequencies.
- Type
square, symmetric numpy matrix
-
locusmap
¶ Metadata for the genomic loci in the form of a LocusMap object. The size of the LocusMap passed should be equal to the size of
matrix
.- Type
LocusMap, optional
Notes
Several accessor shortcuts are provided via this class’s implementation of
__getitem__()
. Consult that function’s docstring for more details.Some elements of the
matrix
of an InteractionMatrix may be set tonp.nan
in cases where data is not available or where interactions are impossible. Impossible interactions are those involving fragments with the same directionality. If a LocusMap whose constituent Locus objects havestrand
keys in theirdata
attribute is provided when an InteractionMatrix is created, the impossible interactions will be set tonp.nan
automatically.-
delete
(index, inplace=True)[source]¶ Delete a Locus and all its interaction information from this InteractionMatrix.
- Parameters
index (int) – The index of the Locus to delete.
inplace (bool, optional) – If True, the deletion is performed inplace, preserving the reference to the original InteractionMatrix, though the underlying
matrix
andlocusmap
attributes will be present as new objects. If False, the original InteractionMatrix object will be unaffected.
- Returns
The resulting InteractionMatrix. If the operation was performed in-place, this is just a reference to
this
.- Return type
Examples
>>> import numpy as np >>> from lib5c.core.interactions import InteractionMatrix >>> from lib5c.core.loci import Locus, LocusMap >>> X = np.arange(16, dtype=float).reshape((4, 4)) >>> counts = X + X.T >>> im = InteractionMatrix(counts, ... locusmap=LocusMap([ ... Locus('chr3', 34109023, 34113109, name='5C_329_Sox2_FOR_2', ... strand='+', region='Sox2'), ... Locus('chr3', 34113147, 34116141, name='5C_329_Sox2_REV_4', ... strand='-', region='Sox2'), ... Locus('chr3', 87282063, 87285636, name='5C_326_Nestin_REV_9', ... strand='-', region='Nestin'), ... Locus('chr3', 87285637, 87295935, name='5C_326_Nestin_FOR_10', ... strand='+', region='Nestin')])) ... >>> print(im) InteractionMatrix of size 4 [[nan 5. 10. nan] [ 5. nan nan 20.] [10. nan nan 25.] [nan 20. 25. nan]] Associated LocusMap: LocusMap comprising 4 loci Range: chr3:34109023-34113109 to chr3:87285637-87295935 Regions: ['Sox2', 'Nestin'] >>> deleted_im = im.delete(2, inplace=False) # non-in-place delete >>> deleted_im.print_log() InteractionMatrix created deleted locus at index 2 with name 5C_326_Nestin_REV_9 >>> print(deleted_im) InteractionMatrix of size 3 [[nan 5. nan] [ 5. nan 20.] [nan 20. nan]] Associated LocusMap: LocusMap comprising 3 loci Range: chr3:34109023-34113109 to chr3:87285637-87295935 Regions: ['Sox2', 'Nestin'] >>> im.size() # original object unaffected 4 >>> deleted_im['5C_329_Sox2_REV_4', '5C_326_Nestin_FOR_10'] 20.0 >>> deleted_im = im.delete(2) # in-place delete >>> deleted_im.print_log() InteractionMatrix created deleted locus at index 2 with name 5C_326_Nestin_REV_9 >>> print(im) # original object affected InteractionMatrix of size 3 [[nan 5. nan] [ 5. nan 20.] [nan 20. nan]] Associated LocusMap: LocusMap comprising 3 loci Range: chr3:34109023-34113109 to chr3:87285637-87295935 Regions: ['Sox2', 'Nestin']
-
extract_region
(region)[source]¶ Extract a submatrix of this Interaction Matrix corresponding to a specified region.
- Parameters
region (str) – The name of the region to extract.
- Returns
The submatrix of this InteractionMatrix corresponding to the specified region. This is returned as a new, independent InteractionMatrix object (see Examples below).
- Return type
Examples
>>> import numpy as np >>> from lib5c.core.interactions import InteractionMatrix >>> from lib5c.core.loci import Locus, LocusMap >>> X = np.arange(16, dtype=float).reshape((4, 4)) >>> counts = X + X.T >>> im = InteractionMatrix(counts, ... locusmap=LocusMap([ ... Locus('chr3', 34109023, 34113109, name='5C_329_Sox2_FOR_2', ... strand='+', region='Sox2'), ... Locus('chr3', 34113147, 34116141, name='5C_329_Sox2_REV_4', ... strand='-', region='Sox2'), ... Locus('chr3', 87282063, 87285636, name='5C_326_Nestin_REV_9', ... strand='-', region='Nestin'), ... Locus('chr3', 87285637, 87295935, name='5C_326_Nestin_FOR_10', ... strand='+', region='Nestin')])) ... >>> im.matrix matrix([[nan, 5., 10., nan], [ 5., nan, nan, 20.], [10., nan, nan, 25.], [nan, 20., 25., nan]]) >>> im.get_regions() ['Sox2', 'Nestin'] >>> sox2_im = im.extract_region('Sox2') >>> sox2_im.print_log() InteractionMatrix created extracted region Sox2 >>> sox2_im.matrix matrix([[nan, 5.], [ 5., nan]]) >>> nestin_im = im.extract_region('Nestin') >>> nestin_im.matrix matrix([[nan, 25.], [25., nan]])
>>> from lib5c.core.interactions import InteractionMatrix >>> im = InteractionMatrix.from_primerfile('test/primers.bed') >>> im.get_regions() ['Sox2', 'Nestin', 'Klf4', 'gene-desert', 'Nanog-V2', 'Olig1-Olig2', 'Oct4'] >>> im.size() 1551 >>> im['5C_329_Sox2_FOR_2', '5C_329_Sox2_REV_4'] = 1.0 >>> im['5C_329_Sox2_FOR_2', '5C_329_Sox2_REV_4'] 1.0 >>> sox2_im = im.extract_region('Sox2') >>> sox2_im.get_regions() ['Sox2'] >>> sox2_im.size() 265 >>> sox2_im['5C_329_Sox2_FOR_2', '5C_329_Sox2_REV_4'] 1.0 >>> sox2_im['5C_329_Sox2_FOR_2', '5C_329_Sox2_REV_4'] = 2.0 >>> im['5C_329_Sox2_FOR_2', '5C_329_Sox2_REV_4'] 1.0
-
extract_slice
(desired_slice)[source]¶ Gets a new InteractionMatrix object representing the interactions of a subset of the loci described in this InteractionMatrix as specified by a slice object.
- Parameters
desired_slice (slice) – The slice to use to subset this InteractionMatrix.
- Returns
The new InteractionMatrix.
- Return type
Notes
Since LocusMap objects are sorted, slices with negative steps will be reversed before being applied to the
matrix
attribute.Examples
>>> import numpy as np >>> from lib5c.core.interactions import InteractionMatrix >>> X = np.arange(16, dtype=float).reshape((4, 4)) >>> im = InteractionMatrix(X + X.T) >>> im.matrix matrix([[ 0., 5., 10., 15.], [ 5., 10., 15., 20.], [10., 15., 20., 25.], [15., 20., 25., 30.]]) >>> sliced_im = im[1:3] >>> sliced_im.print_log() InteractionMatrix created sliced out slice(1, 3, None) >>> sliced_im.matrix matrix([[10., 15.], [15., 20.]]) >>> reverse_sliced_im = im[3:1:-1] >>> reverse_sliced_im.matrix matrix([[10., 15.], [15., 20.]])
>>> from lib5c.core.interactions import InteractionMatrix >>> im = InteractionMatrix.from_primerfile('test/primers.bed') >>> i = im['5C_329_Sox2_FOR_33'] >>> j = im['5C_329_Sox2_REV_89'] >>> im[i, i+1] = 1.0 >>> im[j, j-1] = 2.0 >>> im[i, j] = 3.0 >>> sliced_im = im[i:j+1] >>> sliced_im[0, 1] 1.0 >>> sliced_im[-1, -2] 2.0 >>> sliced_im[0, -1] 3.0 >>> sliced_im.size() == 1 + j - i True >>> sliced_im.get_regions() ['Sox2'] >>> sliced_im.locusmap[0].get_name() '5C_329_Sox2_FOR_33' >>> sliced_im.locusmap[-1].get_name() '5C_329_Sox2_REV_89'
-
flatten
(discard_nan=True)[source]¶ Flattens the interaction values in this InteractionMatrix into a flat, non-redundant array.
- Parameters
discard_nan (bool, optional) – If True, nan’s will not be filtered out of the returned array.
- Returns
A flat, nonredundant array of the interaction values. The \((i, j)\) th element of this InteractionMatrix’s
matrix
attribute (for \(i >= j\) ) ends up at the \((i\times(i+1)/2 + j)\) th index of the flattened array. Ifdiscard_nan
was True, these indices will not necessarily match up and it will not be possible to unflatten the array.- Return type
1d numpy array
Notes
A more intuitive way to think about the ordering is to read down the columns of
matrix
from left to right, going to the next column whenever you reach the diagonal.Examples
>>> import numpy as np >>> from lib5c.core.interactions import InteractionMatrix >>> im = InteractionMatrix(np.matrix([[ 3.0, np.nan, 5.0], ... [np.nan, 6.0, np.nan], ... [ 5.0, np.nan, 8.0]])) ... >>> im.flatten() array([3., 6., 5., 8.]) >>> im.flatten(discard_nan=False) array([ 3., nan, 6., 5., nan, 8.])
-
flatten_cis
(discard_nan=True)[source]¶ Flattens only the cis interaction values in this InteractionMatrix into a flat, non-redundant array.
- Parameters
discard_nan (bool, optional) – If True, nan’s will not be filtered out of the returned array.
- Returns
The result of
flatten()
-ing each region separately and concatenating the results.- Return type
1d numpy array
Examples
>>> import numpy as np >>> from lib5c.core.interactions import InteractionMatrix >>> from lib5c.core.loci import Locus, LocusMap >>> X = np.arange(16, dtype=float).reshape((4, 4)) >>> counts = X + X.T >>> im = InteractionMatrix(counts, ... locusmap=LocusMap([ ... Locus('chr3', 34109023, 34113109, name='5C_329_Sox2_FOR_2', ... region='Sox2'), ... Locus('chr3', 34113147, 34116141, name='5C_329_Sox2_REV_4', ... region='Sox2'), ... Locus('chr3', 87282063, 87285636, name='5C_326_Nestin_REV_9', ... region='Nestin'), ... Locus('chr3', 87285637, 87295935, name='5C_326_Nestin_FOR_10', ... region='Nestin')])) ... >>> im[0, 1] = np.nan >>> im[3, 3] = np.nan >>> print(im) InteractionMatrix of size 4 [[ 0. nan 10. 15.] [nan 10. 15. 20.] [10. 15. 20. 25.] [15. 20. 25. nan]] Associated LocusMap: LocusMap comprising 4 loci Range: chr3:34109023-34113109 to chr3:87285637-87295935 Regions: ['Sox2', 'Nestin'] >>> im.flatten_cis() array([ 0., 10., 20., 25.]) >>> im.flatten_cis(discard_nan=False) array([ 0., nan, 10., 20., 25., nan])
-
classmethod
from_binfile
(binfile)[source]¶ Factory method that creates an InteractionMatrix object whose
matrix
attribute is initialized with all zeros and whose genomic loci are described by data parsed from a BED file containing bin information.- Parameters
binfile (str) – String reference to a BED file containing bin information to be parsed and used as metadata for the genomic loci.
- Returns
InteractionMatrix object.
- Return type
Examples
>>> from lib5c.core.interactions import InteractionMatrix >>> im = InteractionMatrix.from_binfile('test/bins_new.bed') >>> im.print_log() InteractionMatrix created source binfile: test/bins_new.bed >>> im.locusmap.size() 1807 >>> im.size() 1807 >>> im['gene-desert_BIN_047', 'Nestin_BIN_000'] 0.0
-
classmethod
from_countsfile
(countsfile, locusmap=None, primerfile=None, binfile=None)[source]¶ Factory method that creates an InteractionMatrix object from a .counts file.
- Parameters
countsfile (str) – String reference to the .counts file to parse.
locusmap (LocusMap, optional) – Metadata for the genomic loci in the form of a LocusMap object.
primerfile (str, optional) – String reference to a BED file containing primer information to be parsed and used as metadata for the genomic loci.
binfile (str, optional) – String reference to a BED file containing bin information to be parsed and used as metadata for the genomic loci.
- Returns
InteractionMatrix object parsed from the .counts file.
- Return type
Notes
At least one of
locusmap
,primerfile
, orbinfile
must be passed. Thematrix
attribute of the returned InteractionMatrix will have the same size as whichever of these was passed.Examples
>>> from lib5c.core.interactions import InteractionMatrix >>> im = InteractionMatrix.from_countsfile( ... 'test/test_raw.counts', primerfile='test/primers.bed') ... >>> im.print_log() InteractionMatrix created source countsfile: test/test_raw.counts source primerfile: test/primers.bed >>> im.locusmap.size() 1551 >>> im.size() 1551 >>> im['5C_325_Olig1-Olig2_FOR_38', '5C_331_gene-desert_REV_62'] 1.0 >>> im['5C_325_Olig1-Olig2_REV_237', '5C_325_Olig1-Olig2_REV_230'] nan
-
classmethod
from_list
(list_of_interaction_matrices)[source]¶ Factory method that creates an InteractionMatrix object via iterative addition of a list of InteractionMatrix objects.
- Parameters
list_of_interaction_matrices (list of InteractionMatrix) – The InteractionMatrix objects to concatenate.
- Returns
The resulting InteractionMatrix.
- Return type
Notes
This function operates via naive iterate addition and so the following are basically equivalent:
summed_im = InteractionMatrix.from_list(list_of_im) summed_im = sum(list_of_im, InteractionMatrix([]))
Neither implementation is particularly efficient. See the Examples section for details.
Examples
>>> import numpy as np >>> from lib5c.core.interactions import InteractionMatrix >>> im1 = InteractionMatrix(np.matrix([[1.0, 2.0], [2.0, 1.0]])) >>> im2 = InteractionMatrix(np.matrix([[3.0, 4.0], [4.0, 3.0]])) >>> summed_im = InteractionMatrix.from_list([im1, im2]) >>> summed_im.print_log() InteractionMatrix created created from addition created from list >>> summed_im.matrix matrix([[1., 2., 0., 0.], [2., 1., 0., 0.], [0., 0., 3., 4.], [0., 0., 4., 3.]])
>>> import numpy as np >>> from lib5c.core.interactions import InteractionMatrix >>> from lib5c.core.loci import Locus, LocusMap >>> im1 = InteractionMatrix(np.matrix([[np.nan, 1.0], [1.0, np.nan]]), ... locusmap=LocusMap([ ... Locus('chr3', 34109023, 34113109, name='5C_329_Sox2_FOR_2', ... strand='+'), ... Locus('chr3', 34113147, 34116141, name='5C_329_Sox2_REV_4', ... strand='-')])) ... >>> im2 = InteractionMatrix(np.matrix([[np.nan, 2.0], [2.0, np.nan]]), ... locusmap=LocusMap([ ... Locus('chr3', 87282063, 87285636, name='5C_326_Nestin_REV_9', ... strand='-'), ... Locus('chr3', 87285637, 87295935, name='5C_326_Nestin_FOR_10', ... strand='+')])) ... >>> summed_im = InteractionMatrix.from_list([im1, im2]) >>> summed_im.matrix matrix([[nan, 1., 0., nan], [ 1., nan, nan, 0.], [ 0., nan, nan, 2.], [nan, 0., 2., nan]])
-
classmethod
from_locusmap
(locusmap)[source]¶ Factory method that creates an InteractionMatrix object whose
matrix
attribute is initialized with all zeros and whose genomic loci are described by a LocusMap object.- Parameters
locusmap (LocusMap) – Metadata for the genomic loci in the form of a LocusMap object.
- Returns
InteractionMatrix object.
- Return type
Examples
>>> from lib5c.core.interactions import InteractionMatrix >>> from lib5c.core.loci import LocusMap, Locus >>> locus_list = [Locus('chr3', 34109023, 34113109), ... Locus('chr3', 34113147, 34116141)] ... >>> locus_map = LocusMap(locus_list) >>> im = InteractionMatrix.from_locusmap(locus_map) >>> im.print_log() InteractionMatrix created created from locusmap >>> im.matrix matrix([[0., 0.], [0., 0.]])
-
classmethod
from_primerfile
(primerfile)[source]¶ Factory method that creates an InteractionMatrix object whose
matrix
attribute is initialized with all zeros and whose genomic loci are described by data parsed from a BED file containing primer information.- Parameters
primerfile (str) – String reference to a BED file containing primer information to be parsed and used as metadata for the genomic loci.
- Returns
InteractionMatrix object.
- Return type
Examples
>>> from lib5c.core.interactions import InteractionMatrix >>> im = InteractionMatrix.from_primerfile('test/primers.bed') >>> im.print_log() InteractionMatrix created source primerfile: test/primers.bed >>> im.locusmap.size() 1551 >>> im.size() 1551 >>> im['5C_325_Olig1-Olig2_FOR_38', '5C_331_gene-desert_REV_62'] 0.0 >>> im['5C_325_Olig1-Olig2_REV_237', '5C_325_Olig1-Olig2_REV_230'] nan
-
classmethod
from_size
(size)[source]¶ Factory method that creates an InteractionMatrix object whose
matrix
attribute is initialized with all zeros and whose size is specified.- Parameters
size (int) – Size of the
matrix
attribute of the desired InteractionMatrix object.- Returns
InteractionMatrix object.
- Return type
Examples
>>> from lib5c.core.interactions import InteractionMatrix >>> im = InteractionMatrix.from_size(2) >>> im.print_log() InteractionMatrix created created from size 2 >>> im.matrix matrix([[0., 0.], [0., 0.]])
-
get_regions
()[source]¶ Get the regions covered by this InteractionMatrix, if this can be deduced from its metadata. For this to work, the metadata in this InteractionMatrix’s
locusmap
attribute must consist of Locus objects with'name'
keys in theirdata
attributes.- Returns
The ordered list of region names as strings.
- Return type
list of str
Examples
>>> from lib5c.core.interactions import InteractionMatrix >>> im = InteractionMatrix.from_primerfile('test/primers.bed') >>> im.get_regions() ['Sox2', 'Nestin', 'Klf4', 'gene-desert', 'Nanog-V2', 'Olig1-Olig2', 'Oct4']
-
size
()[source]¶ Get the size of the InteractionMatrix. This value is equal to either dimension of the
matrix
attribute as well as the number of Locus objects in the associated LocusMap, if present.- Returns
Size of this InteractionMatrix.
- Return type
long
Examples
>>> from lib5c.core.interactions import InteractionMatrix >>> im = InteractionMatrix.from_size(2) >>> im.matrix matrix([[0., 0.], [0., 0.]]) >>> im.size() 2
-
to_countsfile
(filename, omit_zeros=True)[source]¶ Write the interaction values in this InteractionMatrix to a countsfile.
- Parameters
filename (str) – String reference to file to write to.
omit_zeros (bool, optional) – If True, lines will not be written to the outfile if the counts for that line are zero.
Examples
>>> from lib5c.core.interactions import InteractionMatrix >>> from lib5c.core.loci import Locus, LocusMap >>> from lib5c.operators.standardization import Standardizer >>> s = Standardizer() >>> lm = LocusMap([ ... Locus('chr3', 34109023, 34113109, name='5C_329_Sox2_FOR_2', ... region='Sox2'), ... Locus('chr3', 34113147, 34116141, name='5C_329_Sox2_REV_4', ... region='Sox2'), ... Locus('chr3', 87282063, 87285636, name='5C_326_Nestin_REV_9', ... region='Nestin'), ... Locus('chr3', 87285637, 87295935, name='5C_326_Nestin_FOR_10', ... region='Nestin') ... ]) ... >>> im1 = InteractionMatrix([[ 0., 5., 10., 15.], ... [ 5., 10., 15., 20.], ... [ 10., 15., 20., 25.], ... [ 15., 20., 25., 30.]], locusmap=lm) ... >>> print(im1) InteractionMatrix of size 4 [[ 0. 5. 10. 15.] [ 5. 10. 15. 20.] [10. 15. 20. 25.] [15. 20. 25. 30.]] Associated LocusMap: LocusMap comprising 4 loci Range: chr3:34109023-34113109 to chr3:87285637-87295935 Regions: ['Sox2', 'Nestin'] >>> im1.to_countsfile('test/core_test.counts') >>> im2 = InteractionMatrix.from_countsfile('test/core_test.counts', ... locusmap=lm) ... >>> print(im2) InteractionMatrix of size 4 [[ 0. 5. 10. 15.] [ 5. 10. 15. 20.] [10. 15. 20. 25.] [15. 20. 25. 30.]] Associated LocusMap: LocusMap comprising 4 loci Range: chr3:34109023-34113109 to chr3:87285637-87295935 Regions: ['Sox2', 'Nestin']
-
unflatten
(values)[source]¶ Overwrite the
matrix
attribite of this InteractionMatrix object with values from a flat list, such as that created byInteractionMatrix.flatten()
.- Parameters
values (1d iterable of float) – A flat, nonredundant list of the interaction values. The \((i, j)\) th element of this InteractionMatrix’s
matrix
attribute (for \(i >= j\) ) will be set to the \((i\times(i+1)/2 + j)\) th value of the flattened list.
Examples
>>> import numpy as np >>> from lib5c.core.interactions import InteractionMatrix >>> im = InteractionMatrix(np.matrix([[ 3.0, np.nan, 5.0], ... [np.nan, 6.0, np.nan], ... [ 5.0, np.nan, 8.0]])) ... >>> values = im.flatten(discard_nan=False) >>> values array([ 3., nan, 6., 5., nan, 8.]) >>> values += 1 >>> values array([ 4., nan, 7., 6., nan, 9.]) >>> im.unflatten(values) >>> print(im) InteractionMatrix of size 3 [[ 4. nan 6.] [nan 7. nan] [ 6. nan 9.]]
-
unflatten_cis
(values)[source]¶ Overwrite only the cis interaction values of the
matrix
attribite of this InteractionMatrix object with values from a flat list, such as that created byInteractionMatrix.flatten_cis()
.- Parameters
values (1d list of float) – A flat, nonredundant list of the cis interaction values. The order should match what would be expected from
flatten()
-ing each region of the InteractionMatrix seperately and concatenating the results.
Examples
>>> import numpy as np >>> from lib5c.core.interactions import InteractionMatrix >>> from lib5c.core.loci import Locus, LocusMap >>> X = np.reshape(range(16), (4, 4)).astype(float) >>> counts = X + X.T >>> im = InteractionMatrix(counts, ... locusmap=LocusMap([ ... Locus('chr3', 34109023, 34113109, name='5C_329_Sox2_FOR_2', ... strand='+', region='Sox2'), ... Locus('chr3', 34113147, 34116141, name='5C_329_Sox2_REV_4', ... strand='-', region='Sox2'), ... Locus('chr3', 87282063, 87285636, name='5C_326_Nestin_REV_9', ... strand='-', region='Nestin'), ... Locus('chr3', 87285637, 87295935, name='5C_326_Nestin_FOR_10', ... strand='+', region='Nestin')])) ... >>> print(im) InteractionMatrix of size 4 [[nan 5. 10. nan] [ 5. nan nan 20.] [10. nan nan 25.] [nan 20. 25. nan]] Associated LocusMap: LocusMap comprising 4 loci Range: chr3:34109023-34113109 to chr3:87285637-87295935 Regions: ['Sox2', 'Nestin'] >>> values = im.flatten_cis(discard_nan=False) >>> values array([nan, 5., nan, nan, 25., nan]) >>> values += 1 >>> values array([nan, 6., nan, nan, 26., nan]) >>> im.unflatten_cis(values) >>> print(im) InteractionMatrix of size 4 [[nan 6. 10. nan] [ 6. nan nan 20.] [10. nan nan 26.] [nan 20. 26. nan]] Associated LocusMap: LocusMap comprising 4 loci Range: chr3:34109023-34113109 to chr3:87285637-87295935 Regions: ['Sox2', 'Nestin']
-