lib5c.core.interactions module¶
-
class
lib5c.core.interactions.
InteractionMatrix
(matrix, locusmap=None)[source]¶ Bases:
object
,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.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'] >>> 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: InteractionMatrix 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')])) ... >>> 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: InteractionMatrix 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.reshape(range(16), (4, 4)).astype(float) >>> 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.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', ... 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: InteractionMatrix 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: InteractionMatrix 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: InteractionMatrix 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: InteractionMatrix 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: InteractionMatrix 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']
-