Module Documentation

matrix_count.count

matrix_count.count.count_log_symmetric_matrices(row_sums, *, binary_matrix=False, diagonal_sum=None, index_partition=None, block_sums=None, alpha=1.0, max_samples=1000, error_target=0.001, seed=None, timeout=60.0, verbose=False)[source]

Dirichlet-multinomial moment-matching estimate of the logarithm of the number of symmetric non-negative matrices with given row sums.

Parameters:

  • row_sums (ArrayLike) – Row sums of the matrix. Length n array-like of non-negative integers.

  • binary_matrix (bool, optional) – Whether the matrix is binary (0 or 1) instead of non-negative integer valued. Defaults to False.

  • diagonal_sum (int or None, optional) – What the sum of the diagonal elements should be constrained to. Either an integer greater than or equal to 0 or None, resulting in no constraint on the diagonal elements, defaults to None.

  • index_partition (list of int or None, optional) – A list of length n of integers ranging from 1 to q. index_partition[i] indicates the block which index i belongs to for the purposes of a block sum constraint. A value of None results in no block sum constraint, defaults to None.

  • block_sums (ArrayLike, optional) – A 2D (q, q) symmetric square NumPy array of integers representing the constrained sum of each block of the matrix. A value of None results in no block sum constraint, defaults to None.

  • alpha (float, optional) – Dirichlet-multinomial parameter greater than or equal to 0 to weigh the matrices in the sum. A value of 1 gives the uniform count of matrices, defaults to 1.

  • max_samples (int, optional) – Maximum number of samples to take. Defaults to 1000.

  • error_target (float, optional) – Target absolute error in the logarithm of the count. Defaults to 0.01.

  • seed (int, optional) – Seed for the random number generator. Defaults to None.

  • timeout (float, optional) – Timeout in seconds. Defaults to 60.0.

  • verbose (bool, optional) – Whether to print details of calculation. Defaults to False.

Returns:

log_count_est : The logarithm of the number of symmetric matrices under given conditions. err : The estimated absolute error in the logarithm of the count.

Return type:

tuple of (float, float)

matrix_count.sample

matrix_count.sample.sample_symmetric_matrix(row_sums, *, binary_matrix=False, diagonal_sum=None, index_partition=None, block_sums=None, alpha=1.0, verbose=False, seed=None)[source]

Sample a symmetric matrix with given row sums and diagonal sum.

Parameters:

  • row_sums (ArrayLike) – List of row sums.

  • binary_matrix (bool, optional) – Whether the matrix is binary (0 or 1) instead of non-negative integer valued, defaults to False.

  • diagonal_sum (int, optional) – Sum of the diagonal elements of the matrix.

  • index_partition (list of int or None, optional) – A list of length n of integers ranging from 1 to q. index_partition[i] indicates the block which index i belongs to for the purposes of a block sum constraint. A value of None results in no block sum constraint, defaults to None.

  • block_sums (ArrayLike, optional) – A 2D (q, q) symmetric square NumPy array of integers representing the constrained sum of each block of the matrix. A value of None results in no block sum constraint, defaults to None.

  • alpha (float, optional) – Dirichlet-multinomial parameter greater than or equal to 0 to weigh the matrices in the sum. A value of 1 gives the uniform count of matrices, defaults to 1.

  • verbose (bool, optional) – Whether to print verbose output, defaults to False.

  • seed (int, optional) – Seed for the random number generator, defaults to None.

Returns:

A symmetric matrix with given row sums and diagonal sum, and the log probability of the matrix.

Return type:

tuple of (ArrayLike, float)

matrix_count.estimate

matrix_count.estimate.alpha_symmetric_2(matrix_total, n, diagonal_sum=None, alpha=1.0)[source]

Dirichlet-Multinomial parameter alpha for the second order moment matching estimate of the number of symmetric matrices with given conditions.

Parameters:

  • matrix_total (int) – Matrix total (sum of all entries).

  • n (int) – Matrix size (n, n).

  • diagonal_sum (int or None, optional) – Sum of the diagonal elements of the matrix.

  • alpha (float, optional) – Dirichlet-multinomial parameter, defaults to 1.0.

Returns:

alpha

Return type:

float

matrix_count.estimate.alpha_symmetric_3(matrix_total, n, diagonal_sum=None, alpha=1.0)[source]

Dirichlet-Multinomial parameters alpha_plus and alpha_minus for the third order moment matching estimate of the number of symmetric matrices with given conditions.

Parameters:

  • matrix_total (int) – Matrix total (sum of all entries).

  • n (int) – Matrix size (n, n).

  • diagonal_sum (int or None, optional) – Sum of the diagonal elements of the matrix.

  • alpha (float, optional) – Dirichlet-multinomial parameter, defaults to 1.0.

Returns:

alpha_plus, alpha_minus

Return type:

tuple of (float, float)

matrix_count.estimate.alpha_symmetric_binary(matrix_total, n)[source]

Dirichlet-Multinomial parameter alpha for the second order moment matching estimate of the number of binary symmetric matrices. Note that this will typically be negative, and not a valid Dirichlet-Multinomial parameter.

Parameters:

  • matrix_total (int) – Matrix total (sum of all entries).

  • n (int) – Matrix size (n, n).

Returns:

alpha

Return type:

float

matrix_count.estimate.estimate_log_symmetric_matrices(row_sums, *, diagonal_sum=None, index_partition=None, block_sums=None, alpha=1.0, force_second_order=False, binary_matrix=False, binary_multinomial_estimate=False, verbose=False)[source]

Dirichlet-multinomial moment-matching estimate of the logarithm of the number of symmetric non-negative matrices with given row sums.

Parameters:

  • row_sums (ArrayLike) – Row sums of the matrix. Length n array-like of non-negative integers.

  • diagonal_sum (int or None, optional) – What the sum of the diagonal elements should be constrained to. Either an integer greater than or equal to 0 or None, resulting in no constraint on the diagonal elements, defaults to None.

  • index_partition (list of int or None, optional) – A list of length n of integers ranging from 1 to q. index_partition[i] indicates the block which index i belongs to for the purposes of a block sum constraint. A value of None results in no block sum constraint, defaults to None.

  • block_sums (ArrayLike, optional) – A 2D (q, q) symmetric square NumPy array of integers representing the constrained sum of each block of the matrix. A value of None results in no block sum constraint, defaults to None.

  • alpha (float, optional) – Dirichlet-multinomial parameter greater than or equal to 0 to weigh the matrices in the sum. A value of 1 gives the uniform count of matrices, defaults to 1.

  • force_second_order (bool, optional) – Whether to force the use of the second order estimate. Defaults to False.

  • binary_matrix (bool, optional) – Whether the matrix is binary (0 or 1) instead of non-negative integer valued. Defaults to False.

  • binary_multinomial_estimate (bool, optional) – Whether to use the Multinomial estimate for binary matrices instead of the pseudo Dirichlet-Multinomial estimate. Defaults to False.

  • verbose (bool, optional) – Whether to print details of calculation. Defaults to False.

Returns:

The logarithm of the estimate of the number of symmetric matrices with given row sums and conditions.

Return type:

float