2.2. Classes for labeled block matrices

This page contains information for the LabeledMatrix and LabeledBlockMatrix classes which are used heavily inside the cereeberus.distance.Interleaving class.

Note that these class can be imported as:

from cereeberus.distance.labeled_blocks import LabeledMatrix, LabeledBlockMatrix

class cereeberus.distance.labeled_blocks.LabeledMatrix(array=None, rows=None, cols=None, map_dict=None)[source]

A class to store a matrix with row and column labels. The matrix is stored as a numpy array, and the row and columns are stored as lists. For example, we could store the 2 x 3 matrix below as a LabeledMatrix.

	a	b	c
u	0	1	0
v	1	0	0

Where the matrix would be initialized by

Mat = LabeledMatrix([[0, 1, 0], [1, 0, 0]], ['u', 'v'], ['a', 'b', 'c'])

This class supports matrix multiplication, addition, and subtraction, as well as transposition and getting the maximum (absolute) value of the matrix. Note that calling for an entry in the matrix is done by the labels of the row and column, not the indices. For example, to get the entry in the first row and second column from the example above, you could call either of the following options.

Mat['u', 'b']
Mat.array[0, 1]

Visualization can be done with the draw method, which will draw the matrix with the row and column labels.

Mat.draw(colorbar = True)

__init__(array=None, rows=None, cols=None, map_dict=None)[source]

Initialize the LabeledMatrix with a numpy array, row labels, and column labels.

Parameters:

array (array-like) – The matrix data.
rows (list) – The labels for the rows.
cols (list) – The labels for the columns.

__matmul__(other)[source]

Multiply two LabeledMatrix objects using the @ operator.

Parameters:

other (LabeledMatrix) – The other LabeledMatrix to multiply with.

Returns:

The result of the matrix multiplication.

Return type:

LabeledMatrix

Raises:

ValueError – If the other object is not a LabeledMatrix.
ValueError – If the matrix sizes are incompatable, or if they are but the row labels of the first matrix do not match the column labels of the second (including ordering).

__add__(other)[source]

Add two LabeledMatrix objects using the + operator.

Parameters:: other (LabeledMatrix) – The other LabeledMatrix to add.
Returns:: The result of the matrix addition.
Return type:: LabeledMatrix
Raises:: ValueError – If the other object is not a LabeledMatrix.

__sub__(other)[source]

Subtract two LabeledMatrix objects using the - operator.

Parameters:: other (LabeledMatrix) – The other LabeledMatrix to subtract.
Returns:: The result of the matrix subtraction.
Return type:: LabeledMatrix
Raises:: ValueError – If the other object is not a LabeledMatrix.

__getitem__(key)[source]

Get an item from the matrix, where key = [row_key, col_key] are the labels of the row and columns respectively.

Parameters:: key – The keys for the row and column to get from the matrix.
Returns:: The item from the matrix.

__setitem__(key, value)[source]

Set an item in the matrix, where key = [row_key, col_key] are the labels of the row and columns respectively.

Parameters:

key – The row and column keys to set in the matrix.
value – The value to set.

get_array()[source]

Get the array of the matrix. Works on the big matrix as well as the blocks.

Returns:: The array of the matrix.
Return type:: np.array

max()[source]

Get the maximum value of the matrix.

Returns:: The maximum value of the matrix.
Return type:: float

absmax()[source]

Get the maximum absolute value of the matrix.

Returns:: The maximum absolute value of the matrix.
Return type:: float

min()[source]

Get the minimum value of the matrix.

Returns:: The minimum value of the matrix.
Return type:: float

shape()[source]

Return the shape of the matrix.

Returns:: The shape of the matrix (rows, columns).
Return type:: tuple

size()[source]

Return the size of the matrix.

Returns:: The size of the matrix.
Return type:: int

T()[source]

Transpose the matrix.

Returns:: The labeled transposed matrix.
Return type:: LabeledMatrix

to_labeled_block(row_val_to_verts, col_val_to_verts)[source]

Turns this matrix back into a block dictionary.

Note this assumes that the row and column labels are already in order from the block dictionary.

Parameters:

row_val_to_verts – dict A dictionary from function values to a list of row objects.
col_val_to_verts – dict A dictionary from function values to a list of column objects.

Returns:

LabeledBlockMatrix: A block matrix with the same data as the labeled matrix.

col_sum()[source]: Returns the sum of each column in the matrix.

is_col_sum_1()[source]

Check if the sum of each column is 1.

Returns:: True if the sum of each column is 1, False otherwise.
Return type:: bool

draw(ax=None, colorbar=False, **kwargs)[source]

Draw the matrix with row and column labels.

Parameters:

ax (matplotlib.axes.Axes) – The axes to draw the matrix on. If None, the current axes will be used.
colorbar (bool) – Whether to draw a colorbar.
**kwargs – Additional keyword arguments to pass to ax.matshow.

to_indicator()[source]

Convert the matrix to an indicator matrix.

Returns:: The indicator matrix.
Return type:: LabeledMatrix

class cereeberus.distance.labeled_blocks.LabeledBlockMatrix(map_dict=None, rows_dict=None, cols_dict=None, random_initialize=False, labled_matrix_dict=None, seed=None)[source]

A class to store a block matrix with row and column labels. This is built with the assumption that we have a function value for each object in the labels, and we initialize this with a dictionary for rows and columns that sends function value i to a list of row or column labels, respectively.

For example, we could store the block matrix below as a LabeledBlockMatrix. The outside rows give the function values of the vertices, and the inside rows and columns give the labels of the vertices.

		1		2
		a	b	c	d	e
0	u	0	0	0	0	0
1	v	1	1	0	0	0
1	w	0	0	0	0	0
2	x	0	0	1	1	1

The matrix is stored as a dictionary of LabeledMatrix objects, where the keys are the function values of the vertices. For example, we could store the block matrix below as a LabeledBlockMatrix

cols_dict = {1: ['a','b'], 2: ['c','d','e']}
rows_dict = {0: ['u'], 1: ['v','w'], 2: ['x']}
map_dict = {'a': 'v', 'b':'v', 'c': 'x', 'd':'x', 'e':'x'}
lbm = LabeledBlockMatrix(map_dict, rows_dict, cols_dict)

Note that this can either be drawn with entries filled with either 0’s or np.nan.

lbm.draw(colorbar = True)

../../_images/labeled_matrix_ex_BlockMat_0.png

lbm.draw(filltype = 'nan', colorbar = True)

../../_images/labeled_matrix_ex_BlockMat_nan.png

This class supports matrix multiplication, addition, and subtraction, as well as transposition and getting the maximum (absolute) value of the matrix. Note that calling for an item returns the i’th block as a LabeledMatrix. So we could get an entry in the matrix by first calling the block number, and then the row and column labels.

lbm[1]['v', 'b']

__init__(map_dict=None, rows_dict=None, cols_dict=None, random_initialize=False, labled_matrix_dict=None, seed=None)[source]

Initialize the LabeledBlockMatrix with LabeledMatrix objects for each integer.

rows_dict and cols_dict are dictionaries from integers to lists of row labels and column labels respectively. The keys of the dictionaries are the function values of the vertices.

If map_dict is provided, it is a dictionary from column objects to row objects. The matrix will be filled in with 1s where the column object maps to the row object. If map_dict is None, the matrix will be filled in with random 1s in each column if random_initialize is True. If none of these are provided, the matrix will be filled with zeros.

Parameters:

rows_dict – dict A dictionary from integers to lists of row labels.
cols_dict – dict A dictionary from integers to lists of column labels.
map_dict – dict A dictionary from column objects to row objects.
random_initialize – bool Whether to randomly initialize the matrix.
labeled_matrix_dict – bool Whether to initialize the block matrix from a dictionary of LabeledMatrix objects.
seed – int The seed for the random number generator.

__getitem__(key)[source]

Get the i’th block matrix.

Parameters:: key – The key to get from the block matrix.
Returns:: The item from the block matrix.

__setitem__(key, value)[source]

Set the i’th block matrix.

Parameters:

key – The key to set in the block matrix.
value – The value to set.

__matmul__(other)[source]

Multiply two LabeledBlockMatrix objects using the @ operator.

Parameters:: other (LabeledBlockMatrix) – The other LabeledBlockMatrix to multiply with.
Returns:: The result of the matrix multiplication.
Return type:: LabeledBlockMatrix
Raises:: ValueError – If the other object is not a LabeledBlockMatrix.

__add__(other)[source]

Add two LabeledBlockMatrix objects using the + operator.

Parameters:: other (LabeledBlockMatrix) – The other LabeledBlockMatrix to add.
Returns:: The result of the matrix addition.
Return type:: LabeledBlockMatrix
Raises:: ValueError – If the other object is not a LabeledBlockMatrix.

__sub__(other)[source]

Subtract two LabeledBlockMatrix objects using the - operator.

Parameters:: other (LabeledBlockMatrix) – The other LabeledBlockMatrix to subtract.
Returns:: The result of the matrix subtraction.
Return type:: LabeledBlockMatrix
Raises:: ValueError – If the other object is not a LabeledBlockMatrix.

shape()[source]

Return the shape of the block matrix.

Returns:: The shape of the block matrix.
Return type:: tuple

T()[source]

Transpose the block matrix.

Returns:: The labeled transposed block matrix.
Return type:: LabeledBlockMatrix

get_array(block_index)[source]

Get the array of the block matrix at the given block index.

Parameters:: block_index (int) – The block index to get the array from.
Returns:: The array of the block matrix at the given block index.
Return type:: np.array

max()[source]

Get the maximum value of the block matrix.

Returns:: The maximum value of the block matrix.
Return type:: float

absmax()[source]

Get the maximum absolute value of the block matrix.

Returns:: The maximum absolute value of the block matrix.
Return type:: float

min()[source]

Get the minimum value of the block matrix.

Returns:: The minimum value of the block matrix.
Return type:: float

get_all_block_indices()[source]

Get all the block indices in order.

Returns:: The block indices.
Return type:: list

min_block_index()[source]

Get the minimum block index.

Returns:: The minimum block index.
Return type:: int

max_block_index()[source]

Get the maximum block index.

Returns:: The maximum block index.
Return type:: int

get_all_rows()[source]

Get all the row labels of the block matrix in order.

Returns:: The row labels.
Return type:: list

get_all_cols()[source]

Get all the col labels of the block matrix in order .

Returns:: The col labels.
Return type:: list

get_all_labels()[source]

Get all the row and column of the block matrix in function value order.

Returns:: The row and column labels.
Return type:: tuple

block_diag_NaN(*arrs)[source]

Create a single matrix from provided arrays on the blocks. Modified from scipy.linalg.block_diag to put np.nan in the off-diagonal blocks instead of 0’s.

Parameters:: *arrs – array-like The arrays to put on the diagonal.
Returns:: The block diagonal matrix.
Return type:: np.array

to_labeled_matrix(filltype='zero')[source]

Convert to a single block diagonal matrix.

Returns:: A labeled matrix with the same data as the block matrix.
Return type:: LabeledMatrix

to_indicator()[source]

Convert the block matrix to an indicator matrix.

Returns:: The indicator matrix.
Return type:: LabeledBlockMatrix

to_shifted_blocks(shift)[source]

Shift the blocks in the block matrix.

Parameters:: shift (int) – The amount to shift the blocks.
Returns:: The block matrix with shifted blocks.
Return type:: LabeledBlockMatrix

col_sum()[source]

Returns the sum of each column in the block matrix.

Returns:: The sum of each column in the block matrix.
Return type:: np.array

check_column_sum(verbose=False)[source]

Check that the sum of each column is 1.

Parameters:

verbose (bool) – Prints information on which matrices have columns that do not sum to 1 if True. The default is False.

Returns:

bool: True if the columns sum to 1, False otherwise.

draw(ax=None, colorbar=False, filltype='zero', **kwargs)[source]

Draw the block matrix with row and column labels.

Parameters:

ax (matplotlib.axes.Axes) – The axes to draw the matrix on. If None, the current axes will be used.
colorbar (bool) – Whether to draw a colorbar.
filltype (str) – Either zeros or nan. If zeros, the off-diagonal blocks will be filled with zeros prior to drawing. If nan, the off-diagonal blocks will be filled with np.nan, resulting in them showing up white.
**kwargs – Additional keyword arguments to pass to ax.matshow.

get_rows_dict()[source]

Get the rows dictionary.

Returns:: The rows dictionary.
Return type:: dict

get_cols_dict()[source]

Get the columns dictionary.

Returns:: The columns dictionary.
Return type:: dict