utils

Functions used by more than one PyPhi module or class, or that might be of external use.

pyphi.utils.state_of(nodes, network_state)

Return the state-tuple of the given nodes.

pyphi.utils.all_states(n)

Return all binary states for a system.

Parameters:n (int) – The number of elements in the system.
Yields:tuple (int) – The next state of an n-element system, in LOLI order.
pyphi.utils.sparse(matrix, threshold=0.1)
pyphi.utils.sparse_time(tpm, time_scale)
pyphi.utils.dense_time(tpm, time_scale)
pyphi.utils.run_tpm(tpm, time_scale)

Iterate a tpm by the specified number of time steps.

Parameters:
  • tpm (np.ndarray) – A state-by-node tpm.
  • time_scale (int) – The number of steps to run the tpm.
Returns:

tpm (np.ndarray)
pyphi.utils.run_cm(cm, time_scale)

Iterate a connectivity matrix the specified number of steps.

Parameters:
  • cm (np.ndarray) – A \(N \times N\) connectivity matrix
  • time_scale (int) – The number of steps to run.
Returns:

tpm (np.ndarray)
pyphi.utils.state_by_state(tpm)

Return True if the tpm is in state-by-state form, otherwise False.

pyphi.utils.condition_tpm(tpm, fixed_nodes, state)

Return a TPM conditioned on the given fixed node indices, whose states are fixed according to the given state-tuple.

The dimensions of the new TPM that correspond to the fixed nodes are collapsed onto their state, making those dimensions singletons suitable for broadcasting. The number of dimensions of the conditioned TPM will be the same as the unconditioned TPM.

pyphi.utils.expand_tpm(tpm)

Broadcast a state-by-node TPM so that singleton dimensions are expanded over the full network.

pyphi.utils.apply_cut(cut, connectivity_matrix)

Return a modified connectivity matrix where the connections from one set of nodes to the other are destroyed.

pyphi.utils.fully_connected(connectivity_matrix, nodes1, nodes2)

Test connectivity of one set of nodes to another.

Parameters:
  • connectivity_matrix (np.ndarrray) – The connectivity matrix
  • nodes1 (tuple(int) – The nodes whose outputs to nodes2 will be tested.
  • nodes2 (tuple(int) – The nodes whose inputs from nodes1 will be tested.
Returns:

Returns True if all elements in nodes1 output to

some element in nodes2 AND all elements in nodes2 have an input from some element in nodes1. Otherwise return False. Return True if either set of nodes is empty.
Return type:

bool
pyphi.utils.apply_boundary_conditions_to_cm(external_indices, connectivity_matrix)

Return a connectivity matrix with all connections to or from external nodes removed.

pyphi.utils.get_inputs_from_cm(index, connectivity_matrix)

Return a tuple of node indices that have connections to the node with the given index.

pyphi.utils.get_outputs_from_cm(index, connectivity_matrix)

Return a tuple of node indices that the node with the given index has connections to.

pyphi.utils.causally_significant_nodes(cm)

Returns a tuple of all nodes indices in the connectivity matrix which are causally significant (have inputs and outputs).

pyphi.utils.np_hash(a)

Return a hash of a NumPy array.

pyphi.utils.phi_eq(x, y)

Compare two phi values up to constants.PRECISION.

pyphi.utils.normalize(a)

Normalize a distribution.

Parameters:a (np.ndarray) – The array to normalize.
Returns:a normalized so that the sum of its entries is 1.
Return type:np.ndarray
pyphi.utils.combs(a, r)

NumPy implementation of itertools.combinations.

Return successive \(r\)-length combinations of elements in the array a.

Parameters:
  • a (np.ndarray) – The array from which to get combinations.
  • r (int) – The length of the combinations.
Returns:

combinations – An array of combinations.
Return type:

np.ndarray
pyphi.utils.comb_indices(n, k)

N-D version of itertools.combinations.

Parameters:
  • a (np.ndarray) – The array from which to get combinations.
  • k (int) – The desired length of the combinations.
Returns:

combination_indices –

Indices that give the

\(k\)-combinations of \(n\) elements.
Return type:

np.ndarray

Example

>>> n, k = 3, 2
>>> data = np.arange(6).reshape(2, 3)
>>> data[:, comb_indices(n, k)]
array([[[0, 1],
        [0, 2],
        [1, 2]],

       [[3, 4],
        [3, 5],
        [4, 5]]])
pyphi.utils.powerset(iterable)

Return the power set of an iterable (see itertools recipes).

Parameters:iterable (Iterable) – The iterable from which to generate the power set.
Returns:chain – An chained iterator over the power set.
Return type:Iterable

Example

>>> ps = powerset(np.arange(2))
>>> print(list(ps))
[(), (0,), (1,), (0, 1)]
pyphi.utils.uniform_distribution(number_of_nodes)

Return the uniform distribution for a set of binary nodes, indexed by state (so there is one dimension per node, the size of which is the number of possible states for that node).

Parameters:nodes (np.ndarray) – A set of indices of binary nodes.
Returns:distribution –
The uniform distribution over the set of
nodes.
Return type:np.ndarray
pyphi.utils.marginalize_out(index, tpm, perturb_value=0.5)

Marginalize out a node from a TPM.

Parameters:
  • index (list) – The index of the node to be marginalized out.
  • tpm (np.ndarray) – The TPM to marginalize the node out of.
Returns:

tpm –

A TPM with the same number of dimensions, with

the node marginalized out.
Return type:

np.ndarray
pyphi.utils.max_entropy_distribution(node_indices, number_of_nodes, perturb_vector=None)

Return the maximum entropy distribution over a set of nodes.

This is different from the network’s uniform distribution because nodes outside node_indices are fixed and treated as if they have only 1 state.

Parameters:
  • node_indices (tuple(int) – The set of node indices over which to take the distribution.
  • number_of_nodes (int) – The total number of nodes in the network.
Returns:

distribution –

The maximum entropy distribution over

the set of nodes.
Return type:

np.ndarray
pyphi.utils.hamming_emd(d1, d2)

Return the Earth Mover’s Distance between two distributions (indexed by state, one dimension per node).

Singleton dimensions are sqeezed out.

pyphi.utils.l1(d1, d2)

Return the L1 distance between two distributions.

Parameters:
  • d1 (np.ndarray) – The first distribution.
  • d2 (np.ndarray) – The second distribution.
Returns:

The sum of absolute differences of d1 and d2.
Return type:

float
pyphi.utils.bipartition(a)

Return a list of bipartitions for a sequence.

Parameters:a (Iterable) – The iterable to partition.
Returns:bipartition –
A list of tuples containing each
of the two partitions.
Return type:``list(tuple(tuple

Example

>>> from pyphi.utils import bipartition
>>> bipartition((1,2,3))
[((), (1, 2, 3)), ((1,), (2, 3)), ((2,), (1, 3)), ((1, 2), (3,))]
pyphi.utils.directed_bipartition(a)

Return a list of directed bipartitions for a sequence.

Parameters:a (Iterable) – The iterable to partition.
Returns:bipartition –
A list of tuples containing each
of the two partitions.
Return type:``list(tuple(tuple

Example

>>> from pyphi.utils import directed_bipartition
>>> directed_bipartition((1, 2, 3))
[((), (1, 2, 3)), ((1,), (2, 3)), ((2,), (1, 3)), ((1, 2), (3,)), ((3,), (1, 2)), ((1, 3), (2,)), ((2, 3), (1,)), ((1, 2, 3), ())]
pyphi.utils.directed_bipartition_of_one(a)

Return a list of directed bipartitions for a sequence where each bipartitions includes a set of size 1.

Parameters:a (Iterable) – The iterable to partition.
Returns:bipartition –
A list of tuples containing each
of the two partitions.
Return type:``list(tuple(tuple

Example

>>> from pyphi.utils import directed_bipartition_of_one
>>> directed_bipartition_of_one((1,2,3))
[((1,), (2, 3)), ((2,), (1, 3)), ((1, 2), (3,)), ((3,), (1, 2)), ((1, 3), (2,)), ((2, 3), (1,))]
pyphi.utils.directed_bipartition_indices(N)

Return indices for directed bipartitions of a sequence.

The directed bipartion

Parameters:N (int) – The length of the sequence.
Returns:bipartition_indices –
A list of tuples containing the indices
for each of the two partitions.
Return type:list

Example

>>> from pyphi.utils import directed_bipartition_indices
>>> N = 3
>>> directed_bipartition_indices(N)
[((), (0, 1, 2)), ((0,), (1, 2)), ((1,), (0, 2)), ((0, 1), (2,)), ((2,), (0, 1)), ((0, 2), (1,)), ((1, 2), (0,)), ((0, 1, 2), ())]
pyphi.utils.bipartition_indices(N)

Return indices for bipartitions of a sequence.

Parameters:N (int) – The length of the sequence.
Returns:bipartition_indices –
A list of tuples containing the indices
for each of the two partitions.
Return type:list

Example

>>> from pyphi.utils import bipartition_indices
>>> N = 3
>>> bipartition_indices(N)
[((), (0, 1, 2)), ((0,), (1, 2)), ((1,), (0, 2)), ((0, 1), (2,))]
pyphi.utils.load_data(dir, num)

Load numpy data from the data directory.

The files should stored in data/{dir} and named 0.npy, 1.npy, ... {num - 1}.npy.

Returns
list: A list of loaded data, such that list[i] contains the the contents of i.npy.
pyphi.utils.submatrix(cm, nodes1, nodes2)

Return the submatrix of connections from nodes1 to nodes2.

Parameters:
  • cm (np.ndarray) – The matrix
  • nodes1 (tuple(int) – Source nodes
  • nodes2 (tuple(int) – Sink nodes
pyphi.utils.relevant_connections(n, _from, to)

Construct a connectivity matrix.

Returns an \(N \times N\) connectivity matrix with the \(i,j^{\textrm{th}}\) entry set to 1 if \(i\) is in _from and \(j\) is in to.

Parameters:
  • n (int) – The dimensions of the matrix
  • _from (tuple(int) – Nodes with outgoing connections to to
  • to (tuple(int) – Nodes with incoming connections from _from
pyphi.utils.block_cm(cm)

Return whether cm can be arranged as a block connectivity matrix.

If so, the corresponding mechanism/purview is trivially reducible. Technically, only square matrices are “block diagonal”, but the notion of connectivity carries over.

We test for block connectivity by trying to grow a block of nodes such that:

  • ‘source’ nodes only input to nodes in the block
  • ‘sink’ nodes only receive inputs from source nodes in the block

For example, the following connectivity matrix represents connections from nodes1 = A, B, C to nodes2 = D, E, F, G (without loss of generality—note that nodes1 and nodes2 may share elements):

   D  E  F  G
A [1, 1, 0, 0]
B [1, 1, 0, 0]
C [0, 0, 1, 1]

Since nodes \(AB\) only connect to nodes \(DE\), and node \(C\) only connects to nodes \(FG\), the subgraph is reducible; the cut

AB   C
-- X --
DE   FG

does not change the structure of the graph.

pyphi.utils.block_reducible(cm, nodes1, nodes2)

Return whether connections from nodes1 to nodes2 are reducible.

Parameters:
  • cm (np.ndarray) – The network’s connectivity matrix.
  • nodes1 (tuple(int) – Source nodes
  • nodes2 (tuple(int) – Sink nodes
pyphi.utils.strongly_connected(cm, nodes=None)

Return whether the connectivity matrix is strongly connected.

Parameters:cm (np.ndarray) – A square connectivity matrix.
Keyword Arguments:
 nodes (tuple(int) – An optional subset of node indices to test strong connectivity over.
pyphi.utils.print_repertoire(r)

Print a vertical, human-readable cause/effect repertoire.

pyphi.utils.print_repertoire_horiz(r)

Print a horizontal, human-readable cause/effect repertoire.