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 statetuple 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 statebynode tpm.
 time_scale (int) – The number of steps to run the tpm.
Returns: 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: np.ndarray

pyphi.utils.
state_by_state
(tpm)¶ Return
True
iftpm
is in statebystate form, otherwiseFalse
.

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 statetuple.
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 statebynode TPM so that singleton dimensions are expanded over the full network.

pyphi.utils.
fully_connected
(cm, nodes1, nodes2)¶ Test connectivity of one set of nodes to another.
Parameters:  cm (
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: bool – Returns
True
if all elements innodes1
output to some element innodes2
AND all elements innodes2
have an input from some element innodes1
. Otherwise returnFalse
. ReturnTrue
if either set of nodes is empty. cm (

pyphi.utils.
apply_boundary_conditions_to_cm
(external_indices, cm)¶ Return a connectivity matrix with all connections to or from external nodes removed.

pyphi.utils.
get_inputs_from_cm
(index, cm)¶ Return a tuple of node indices that have connections to the node with the given index.

pyphi.utils.
get_outputs_from_cm
(index, cm)¶ Return a tuple of node indices that the node with the given index has connections to.

pyphi.utils.
causally_significant_nodes
(cm)¶ Return 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: np.ndarray – a
normalized so that the sum of its entries is 1.

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: np.ndarray – An array of combinations.

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: np.ndarray – Indices that give the \(k\)combinations of \(n\) elements.
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: generator – An chained generator over the power set. 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: np.ndarray – The uniform distribution over the set of nodes.

pyphi.utils.
marginalize_out
(indices, tpm)¶ Marginalize out a node from a TPM.
Parameters:  indices (list[int]) – The indices of nodes to be marginalized out.
 tpm (np.ndarray) – The TPM to marginalize the node out of.
Returns: np.ndarray – A TPM with the same number of dimensions, with the nodes marginalized out.

pyphi.utils.
marginal_zero
(repertoire, node_index)¶ Return the marginal probability that the node is off.

pyphi.utils.
marginal
(repertoire, node_index)¶ Get the marginal distribution for a node.

pyphi.utils.
independent
(repertoire)¶ Check whether the repertoire is independent.

pyphi.utils.
purview
(repertoire)¶ The purview of the repertoire.
Parameters: repertoire (np.ndarray) – A repertoire Returns: tuple[int] – The purview that the repertoire was computed over.

pyphi.utils.
purview_size
(repertoire)¶ Return the size of the purview of the repertoire.
Parameters: repertoire (np.ndarray) – A repertoire Returns: int – The size of purview that the repertoire was computed over.

pyphi.utils.
repertoire_shape
(purview, N)¶ Return the shape a repertoire.
Parameters:  purview (tuple[int]) – The purview over which the repertoire is computed.
 N (int) – The number of elements in the system.
Returns: list[int] – The shape of the repertoire. Purview nodes have two dimensions and nonpurview nodes are collapsed to a unitary dimension.
Example
>>> purview = (0, 2) >>> N = 3 >>> repertoire_shape(purview, N) [2, 1, 2]

pyphi.utils.
max_entropy_distribution
(node_indices, number_of_nodes)¶ 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: np.ndarray – The maximum entropy distribution over the set of nodes.

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: float – The sum of absolute differences of
d1
andd2
.

pyphi.utils.
kld
(d1, d2)¶ Return the KullbackLeibler Divergence (KLD) between two distributions.
Parameters:  d1 (np.ndarray) – The first distribution.
 d2 (np.ndarray) – The second distribution.
Returns: float – The KLD of
d1
fromd2
.

pyphi.utils.
bipartition
(a)¶ Return a list of bipartitions for a sequence.
Parameters: a (Iterable) – The iterable to partition. Returns: list[tuple[tuple]] – A list of tuples containing each of the two partitions. Example
>>> 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: list[tuple[tuple]] – A list of tuples containing each of the two partitions. Example
>>> 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: list[tuple[tuple]] – A list of tuples containing each of the two partitions. Example
>>> 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.
Parameters: N (int) – The length of the sequence. Returns: list – A list of tuples containing the indices for each of the two partitions. Example
>>> 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 undirected bipartitions of a sequence.
Parameters: N (int) – The length of the sequence. Returns: list – A list of tuples containing the indices for each of the two partitions. Example
>>> N = 3 >>> bipartition_indices(N) [((), (0, 1, 2)), ((0,), (1, 2)), ((1,), (0, 2)), ((0, 1), (2,))]

pyphi.utils.
directed_tripartition_indices
(N)¶ Return indices for directed tripartitions of a sequence.
Parameters: N (int) – The length of the sequence. Returns: list[tuple] – A list of tuples containing the indices for each partition. Example
>>> N = 1 >>> directed_tripartition_indices(N) [((0,), (), ()), ((), (0,), ()), ((), (), (0,))]

pyphi.utils.
directed_tripartition
(seq)¶ Generator over all directed tripartitions of a sequence.
Parameters: seq (Iterable) – a sequence. Yields: tuple[tuple] – A tripartition of seq
.Example
>>> seq = (2, 5) >>> list(directed_tripartition(seq)) [((2, 5), (), ()), ((2,), (5,), ()), ((2,), (), (5,)), ((5,), (2,), ()), ((), (2, 5), ()), ((), (2,), (5,)), ((5,), (), (2,)), ((), (5,), (2,)), ((), (), (2, 5))]

pyphi.utils.
load_data
(dir, num)¶ Load numpy data from the data directory.
The files should stored in
data/{dir}
and named0.npy, 1.npy, ... {num  1}.npy
.Returns: list – A list of loaded data, such that list[i]
contains the the contents ofi.npy
.

pyphi.utils.
relevant_connections
(n, _from, to)¶ Construct a connectivity matrix.
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
Returns: np.ndarray – An \(N \times N\) connectivity matrix with the \(i,j^{\textrm{th}}\) entry set to
1
if \(i\) is in_from
and \(j\) is into
.

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
tonodes2 = D, E, F, G
(without loss of generality—note thatnodes1
andnodes2
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
tonodes2
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.
weakly_connected
(cm, nodes=None)¶ Return whether the connectivity matrix is weakly connected.
Parameters: cm (np.ndarray) – A square connectivity matrix. Keyword Arguments: nodes (tuple[int]) – An optional subset of node indices to test weak connectivity over.

pyphi.utils.
print_repertoire
(r)¶ Print a vertical, humanreadable cause/effect repertoire.

pyphi.utils.
print_repertoire_horiz
(r)¶ Print a horizontal, humanreadable cause/effect repertoire.