Finding Examples with Hypothesis

What if you’d like to find a distribution that has a particular property? For example, what if I’d like to find a distribution with a Co-Information less than \(-0.5\)? This is where Hypothesis comes in (install it with the test extra, pip install "dit[test]"):

In [1]: from hypothesis import find

In [2]: from dit.utils.testing import distributions

In [3]: find(distributions(alphabets=3), lambda d: dit.multivariate.coinformation(d) < -0.5)
Out[3]: <Distribution p(X0,X1,X2)>

What hypothesis has done is use the distributions() strategy to randomly test distributions. Once it finds a distribution satisfying the criteria we specified (coinformation less than \(-0.5\)) it then simplifies the example as much as possible. Here, we see that even though it could have found any distribution, it found the exclusive or distribution, and simplified the probabilities to be uniform.

The same strategies drive dit’s own property-based test suite, and are equally useful for testing conjectured inequalities between measures.

Strategies

dit.utils.testing provides the following Hypothesis strategies:

distributions(alphabets=(2, 2, 2), nondegenerate=False, zeros=True) → SearchStrategy[source]

Generate distributions for use with hypothesis.

Parameters:

  • draw (function) – A sampling function passed in by hypothesis.

  • alphabets (int, tuple of ints, tuple of pairs of ints) – If an int, it is the length of the outcomes and each variable is assumed to be binary. If a tuple of ints, the ints are assumed to be the size of each variable. If a tuple of pairs of ints, each pair represents the min and max alphabet size of each variable.

Returns:

dist – A distribution with variable sizes.

Return type:

Distribution

distribution_structures(size=(2, 4), alphabet=(2, 4), uniform=False, min_events=1) → SearchStrategy[source]

A hypothesis strategy for generating distributions.

Parameters:

  • draw (function) – A sampling function passed in by hypothesis.

  • size (int) – The size of outcomes desired. Defaults to a 3 or 4, randomly.

  • alphabet (int) – The alphabet size for each variable. Defaults to 2, 3, or 4, randomly.

  • uniform (bool) – Whether the probabilities should be uniform or random. Defaults to random.

Returns:

dist – A random distribution.

Return type:

Distribution

markov_chains(alphabets=((2, 4), (2, 4), (2, 4))) → SearchStrategy[source]

Generate Markov chains for use with hypothesis.

Parameters:

  • draw (function) – A sampling function passed in by hypothesis.

  • alphabets (int, tuple of ints, tuple of pairs of ints) – If an int, it is the length of the chain and each variable is assumed to be binary. If a tuple of ints, the ints are assumed to be the size of each variable. If a tuple of pairs of ints, each pair represents the min and max alphabet size of each variable.

Returns:

dist – A Markov chain with variable sizes.

Return type:

Distribution

channel_inputs(input_size=(2, 6), output_size=(2, 6)) → SearchStrategy[source]

Generate two pmfs (p, q) over a common alphabet and a stochastic matrix T whose input alphabet is that alphabet. Zero probabilities are allowed in p, q, and T.

Parameters:

  • draw (function) – Hypothesis sampling function.

  • input_size (int or (int, int)) – Size (or range) of the common input alphabet |X|.

  • output_size (int or (int, int)) – Size (or range) of the channel output alphabet |Y|.

Returns:

  • p (ndarray, shape (|X|,)) – The first pmf.

  • q (ndarray, shape (|X|,)) – The second pmf.

  • T (ndarray, shape (|X|, |Y|)) – Channel P(Y|X).

channel_pairs(input_size=(2, 4), output_y_size=(2, 4), output_z_size=(2, 4)) → SearchStrategy[source]

Generate a pair of stochastic matrices (mu, kappa) with a common input alphabet.

Parameters:

  • draw (function) – Hypothesis sampling function.

  • input_size (int or (int, int)) – Size (or range) of the input alphabet |S|.

  • output_y_size (int or (int, int)) – Size (or range) of the kappa output alphabet |Y|.

  • output_z_size (int or (int, int)) – Size (or range) of the mu output alphabet |Z|.

Returns:

  • mu (ndarray, shape (|S|, |Z|)) – Channel P(Z|S).

  • kappa (ndarray, shape (|S|, |Y|)) – Channel P(Y|S).

degraded_channel_pairs(input_size=(2, 4), output_z_size=(2, 4), output_y_size=(2, 4)) → SearchStrategy[source]

Generate (mu, kappa) where kappa = lambda . mu for a random lambda, so that mu output-degrades to kappa (Blackwell order holds).

Parameters:

  • draw (function) – Hypothesis sampling function.

  • input_size (int or (int, int)) – Size (or range) of the input alphabet |S|.

  • output_z_size (int or (int, int)) – Size (or range) of the mu output alphabet |Z|.

  • output_y_size (int or (int, int)) – Size (or range) of the kappa output alphabet |Y|.

Returns:

  • mu (ndarray, shape (|S|, |Z|)) – The dominating channel.

  • kappa (ndarray, shape (|S|, |Y|)) – The degraded channel, kappa = mu @ lam.