Module Documentation

matrix_count.count

matrix_count.count.count_log_symmetric_matrices(row_sums, *, binary_matrix=False, diagonal_sum=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. Not available for block_sums or index_partition arguments.

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.

  • 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.count.log_count(row_sums, column_sums=None, *, binary_matrix=False, diagonal_sum=None, alpha=1.0, max_samples=1000, error_target=0.001, seed=None, timeout=60.0, verbose=False)[source]
Parameters:
Return type:

tuple[float, float]

matrix_count.count.log_estimate(row_sums, column_sums=None, *, binary_matrix=False, diagonal_sum=None, index_partition=None, block_sums=None, block_diagonal_sums=None, alpha=1.0, force_second_order=False, allow_pseudo=True, verbose=False)[source]
Parameters:
Return type:

float

matrix_count.count.sample(row_sums, column_sums=None, *, binary_matrix=False, diagonal_sum=None, alpha=1.0, num_samples=1, importance_sample=False, seed=None, verbose=False)[source]

Sample a symmetric matrix with given row sums and diagonal sum. Not available for block_sums or index_partition arguments.

Parameters:
Return type:

tuple[Union[Buffer, _SupportsArray[dtype[Any]], _NestedSequence[_SupportsArray[dtype[Any]]], complex, bytes, str, _NestedSequence[complex | bytes | str]], float | tuple[float, float]]

matrix_count.sample

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

Sample a symmetric matrix with given row sums and diagonal sum. Not available for block_sums or index_partition arguments.

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.

  • 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.estimate_log_symmetric_matrices(row_sums, *, diagonal_sum=None, index_partition=None, block_sums=None, block_diagonal_sums=None, alpha=1.0, force_second_order=False, binary_matrix=False, allow_pseudo=True, verbose=False)[source]

Dirichlet-multinomial moment-matching estimate of the logarithm of the number of symmetric 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) – Sum of the diagonal elements of the matrix, defaults to None, no constraint.

  • 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.

  • block_diagonal_sums (ArrayLike, optional) – A length q vector of integers representing the constrained sums of the diagonal elements of each block, defaults to None, no constraint.

  • 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.

  • allow_pseudo (bool, optional) – Whether to allow the use of negative alpha values when moment matching. Defaults to True.

  • 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