API

API for the methods in the bipcm module.

class bipcm.BiPCM(bin_mat, constraint)

Bipartite Partial Configuration Model for binary bipartite networks.

This class implements the Bipartite Partial Configuration Model (BiPCM), which can be used as a null model for the analysis of undirected and binary bipartite networks. The class provides methods to calculate the biadjacency matrix of the null model and to quantify node similarities in terms of p-values.

static check_constraint(constraint)

Check that the constraint parameter is either True of False.

Parameters:constraint (bool) – constrains the degrees of either the row-nodes (True) or column-nodes (False) Raises:AssertionError – raise an error if the constraint is neither True nor False

check_input_matrix_is_binary()

Check that the entries of the input matrix are 0 or 1.

Raises:AssertionError – raise an error if the input matrix is not binary

get_edge_prob_seq()

Return an array with the link probabilities of the BiPCM null model.

In the first part of the array, the row degrees are fixed. In the second part, the column degrees are fixed.

Returns:array of link probabilities Return type:numpy.array

get_lambda_motif_matrix(mm, bip_set=False)

Return the number of \(\Lambda\)-motifs as found in mm.

Given the binary input matrix mm, count the number of \(\Lambda\)-motifs between node couples of the bipartite layer specified by bip_set.

Parameters:

• mm (numpy.array) – binary matrix
• bip_set (bool) – selects row-nodes (True) or column-nodes (False)

Returns:

square matrix of observed \(\Lambda\)-motifs

Return type:

numpy.array

Raises:

• NameError – raise an error if the parameter bip_set is neither True nor False
• AssertionError – raise an error if shape of the probability matrix is not correct

get_lambda_pvalues(plam_mat, nlam_mat, bip_set=False)

Return the p-values for the \(\Lambda\)-motifs in nlam_mat.

Calculate the p-values for the numbers of observed \(\Lambda\)-motifs as given in the parameter nlam_mat for the bipartite node layer bip_set. The probabilities for the single \(\Lambda\)-motifs are given in plam_mat.

If bip_set corresponds to the constrained bipartite node set, the \(\Lambda\)-motifs follow a Binomial probability distribution. Otherwise, all the node pairs follow the same Poisson Binomial probability distribution. The p-values are calculated as

\[\begin{split}p_{val}(k) = Pr(X >= k) = 1 - Pr(X < k) = 1 - cdf(k) + pmf(k)\end{split}\]

Note

The lower triangular part (including the diagonal) of the returned matrix is set to zero.

Parameters:

• plam_mat (numpy.array) – matrix of \(\Lambda\)-motif probabilities
• nlam_mat (numpy.array) – matrix of observed number of Lambda motifs
• bip_set (bool) – selects row-nodes (True) or column-nodes (False)

Returns:

matrix of the p-values for the \(\Lambda\)-motifs

Return type:

numpy.array

Raises:

• NameError – raise an error if the parameter bip_set is neither True nor False
• AssertionError – raise an error if shapes of the probability matrix and the matrix with the number of \(\Lambda\)-motifs are not equal

get_plambda_matrix()

Return the \(\Lambda\)-motif probability matrix.

Return a square matrix \(M\) of Lambda probabilities for the nodes given the degree constraints on the node set self.const_set.

Note

If \(N_i\) are the nodes with constrained degrees, \(M_{ij} = p(\Lambda_{ij})\) is the probability of nodes \(i, j \in N_i\) sharing one common neighbor, whereas \(M_{ii}\) is the probability that two nodes of the opposite layer have node \(i \in N_i\) as a common neighbor. The lower triangular part of \(M\) excluding the diagonal is set to 0 since the matrix is symmetric.

Returns:\(\Lambda\)-motif probability matrix Return type:numpy.array

get_proj_pmat(plam_mat, nlam_mat, bip_set=False)

Return the probabilities of the observed \(\Lambda\)-motifs.

The probabilities of the \(\Lambda\)-motifs between the nodes specified by bip_set in the input matrix are calculated and returned.

If the node set bip_set is the same as the constrained one, the \(\Lambda\)-motifs follow a Binomial probability distribution. Otherwise, all the node pairs follow the same Poisson Binomial distribution.

The probability mass function is given by

\[pmf(k) = Pr(X = k)\]

Note

The lower triangular part including the diagonal is set to 0 since the matrix is symmetric.

Parameters:

• plam_mat (numpy.array) – matrix of Lambda motif probabilities
• nlam_mat (numpy.array) – matrix of observed number of Lambda motifs
• bip_set (bool) – select row-nodes (True) or column-nodes (False)

Returns:

matrix containing the probabilities of the \(\Lambda\)-motifs

Return type:

numpy.array

Raises:

• NameError – raise an error if the parameter bip_set is neither True nor False
• AssertionError – raise an error if shapes of the probability matrix and the matrix with the number of \(\Lambda\)-motifs are not equal

lambda_loglike(bip_set=False)

Return the log-likelihood of the number of \(\Lambda\)-motifs.

The total log-likelihood of the number of observed \(\Lambda\)-motifs in the input matrix is calculated according to the BiPCM null model.

Parameters:bip_set (bool) – analyze \(\Lambda\)-motifs of row-nodes (True) or column-nodes (False)

lambda_motifs_main(bip_set=False, write=True, filename=None, delim='\t')

Calculate and save the p-values of the \(\Lambda\)-motifs.

For each node couple in the bipartite layer specified by bip_set, \(\Lambda\)-motifs and calculate the corresponding p-value.

Parameters:

• bip_set (bool) – select row-nodes (True) or column-nodes (False)
• write (bool) – if True, the p-values are saved in the specified file
• filename (str) – name of the file which will contain the p-values, default is pval_constr_<constraint>_proj_<rows OR columns>.csv
• delim (str) – delimiter between entries in file, default is tab

Returns:

matrix of p-values if write==True

Return type:

numpy.array

Raises:

NameError – raise an error if the parameter bip_set is neither True nor False

static save_matrix(mat, filename, delim='\t', binary=False)

Save the matrix mat in the file filename.

The matrix can either be saved as a binary NumPy .npy file or as a human-readable CSV file.

Note

The relative path has to be provided in the filename, e.g. ../data/pvalue_matrix.csv

Parameters:

• mat (numpy.array) – two-dimensional matrix
• filename (str) – name of the output file
• delim (str) – delimiter between values in file
• binary (bool) – if True, save as binary .npy, otherwise as a CSV file

set_degree_seq()

Return the node degree sequence of the input matrix.

Returns:node degree sequence [degrees row-nodes, degrees column-nodes] Return type:numpy.array Raises:AssertionError – raise an error if the length of the returned degree sequence does not correspond to the total number of nodes

static triumat2flat_idx(i, j, n)

Convert an matrix index couple to a flattened array index.

Given a square matrix of dimension \(n\) and an index couple \((i, j)\) of the upper triangular part of the matrix, the function returns the index which the matrix element would have in a flattened array.

Note

• \(i \in [0, ..., n - 1]\)
• \(j \in [i + 1, ..., n - 1]\)
• returned index \(\in [0,\, n (n - 1) / 2 - 1]\)

Parameters:

• i (int) – row index
• j (int) – column index
• n (int) – dimension of the square matrix

Returns:

flattened array index

Return type:

int