margin-matrices¶
Counting and sampling integer matrices with given margins¶
Maximilian Jerdee¶
This package provides tools to count and sample integer matrices with given margins, or equivalently networks with given degree sequences. We can also impose a variety of additional constraints on the matrices, such as:
Matrix symmetry (directed vs undirected graphs).
Binary matrices (simple graphs).
Fixed total sum of diagonal entries (number of self edges).
Fixed sum of entries in blocks of matrix (number of edges between prescribed groups).
Dirichlet-multinomial matrix weighting (entry heterogeneity).
The implemented methods are based upon the moment-matching arguments described in Jerdee, Kirkley, Newman (2022).
Installation¶
margin-matrices may be installed through pip
pip install margin-matrices
or built locally by cloning this repository and running
pip install .
in the base directory.
Typical usage¶
Once installed, the package can be imported as
import margin_matrices as mm
Note that this is not import margin-matrices.
We can rapidly estimate the number of non-negative integer matrices with particular row and column sums as
row_sums = [3, 3, 2, 2, 2]
column_sums = [2, 2, 2, 2, 2, 1, 1]
log_estimate = mm.log_estimate(row_sums, column_sums)
print(log_estimate) # TODO: add example output
Given more time, we can also converge to the true number of such matrices
log_count, log_count_err = mm.log_count(row_sums, column_sums)
print(f"{log_count} ± {log_count_err}") # TODO: add example output
We can also obtain samples from the space of such matrices
samples = mm.sample(row_sums, column_sums, n_samples=5)
print(samples[0])
# TODO: add example output
We can similarly explore spaces of matrices under further constraints. For example, the number of binary symmetric matrices with given row sums (or simple graphs of given degree sequence)
row_sums = [3, 3, 2, 2, 2, 1, 1]
log_count, log_count_err = mm.log_count(row_sums, binary_matrix=True)
print(f"{log_count} ± {log_count_err}") # TODO: add example output
Further usage examples can be found in the examples directory of the
repository and the package documentation.