macro
¶
Methods for coarsegraining systems to different levels of spatial analysis.

pyphi.macro.
reindex
(indices)¶ Generate a new set of node indices, the size of indices.

pyphi.macro.
rebuild_system_tpm
(node_tpms)¶ Reconstruct the network TPM from a collection of node TPMs.

class
pyphi.macro.
MacroSubsystem
(network, state, nodes, cut=None, mice_cache=None, time_scale=1, blackbox=None, coarse_grain=None)¶ A subclass of
Subsystem
implementing macro computations.This subsystem performs blackboxing and coarsegraining of elements.
Unlike
Subsystem
, whose TPM has dimensionality equal to that of the subsystem’s network and represents nodes external to the system using singleton dimensions,MacroSubsystem
squeezes the TPM to remove these singletons. As a result, the node indices of the system are also squeezed to0..n
so they properly index the TPM, and the statetuple is reduced to the size of the system.After each macro update (temporal blackboxing, spatial blackboxing, and spatial coarsegraining) the TPM, CM, nodes, and state are updated so that they correctly represent the updated system.

cut_indices
¶ The indices of this system to be cut for \(\Phi\) computations.
For macro computations the cut is applied to the underlying microsystem.

apply_cut
(cut)¶ Return a cut version of this
MacroSubsystem
.Parameters: cut (Cut) – The cut to apply to this MacroSubsystem
.Returns: MacroSubsystem – The cut version of this MacroSubsystem
.

macro2micro
(macro_indices)¶ Returns all micro indices which compose the elements specified by
macro_indices
.


class
pyphi.macro.
CoarseGrain
¶ Represents a coarse graining of a collection of nodes.

partition
¶ tuple[tuple] – The partition of microelements into macroelements.

grouping
¶ tuple[tuple[tuple]] – The grouping of microstates into macrostates.
Create new instance of CoarseGrain(partition, grouping)

micro_indices
¶ Indices of micro elements represented in this coarsegraining.

macro_indices
¶ Indices of macro elements of this coarsegraining.

reindex
()¶ Reindex this coarse graining to use squeezed indices.
The output grouping is translated to use indices
0..n
, wheren
is the number of micro indices in the coarsegraining. Reindexing does not effect the state grouping, which is already indexindependent.Returns: CoarseGrain – A new CoarseGrain
object, indexed from0..n
.Example
>>> partition = ((1, 2),) >>> grouping = (((0,), (1, 2)),) >>> coarse_grain = CoarseGrain(partition, grouping) >>> coarse_grain.reindex() CoarseGrain(partition=((0, 1),), grouping=(((0,), (1, 2)),))

macro_state
(micro_state)¶ Translate a micro state to a macro state
Parameters: micro_state (tuple[int]) – The state of the micro nodes in this coarsegraining. Returns: tuple[int] – The state of the macro system, translated as specified by this coarsegraining. Example
>>> coarse_grain = CoarseGrain(((1, 2),), (((0,), (1, 2)),)) >>> coarse_grain.macro_state((0, 0)) (0,) >>> coarse_grain.macro_state((1, 0)) (1,) >>> coarse_grain.macro_state((1, 1)) (1,)

make_mapping
()¶ Return a mapping from microstate to the macrostates based on the partition and state grouping of this coarsegrain.
Returns: (nd.ndarray) – A mapping from microstates to macrostates. The \(i^{\textrm{th}}\) entry in the mapping is the macrostate corresponding to the \(i^{\textrm{th}}\) microstate.

macro_tpm
(micro_tpm, check_independence=True)¶ Create a coarsegrained macro TPM.
Parameters:  micro_tpm (nd.array) – The TPM of the microsystem.
 check_independence (bool) – If
True
, the method will raise aConditionallyDependentError
if the macro TPM is not conditionally independent.
Returns: np.ndarray – The statebynode TPM of the macrosystem.


class
pyphi.macro.
Blackbox
¶ Class representing a blackboxing of a system.

partition
¶ tuple[tuple[int]] – The partition of nodes into boxes.

output_indices
¶ tuple[int] – Outputs of the blackboxes.
Create new instance of Blackbox(partition, output_indices)
All elements hidden inside the blackboxes.

micro_indices
¶ Indices of microelements in this blackboxing.

macro_indices
¶ Fresh indices of macroelements of the blackboxing.

reindex
()¶ Squeeze the indices of this blackboxing to
0..n
.Returns: Blackbox – a new, reindexed Blackbox
.Example
>>> partition = ((3,), (2, 4)) >>> output_indices = (2, 3) >>> blackbox = Blackbox(partition, output_indices) >>> blackbox.reindex() Blackbox(partition=((1,), (0, 2)), output_indices=(0, 1))

macro_state
(micro_state)¶ Compute the macrostate of this blackbox.
This is just the state of the blackbox’s output indices.
Parameters: micro_state (tuple[int]) – The state of the microelements in the blackbox. Returns: tuple[int] – The state of the output indices.

in_same_box
(a, b)¶ Returns
True
if nodesa
andb`
are in the same box.


pyphi.macro.
all_partitions
(indices)¶ Return a list of all possible coarse grains of a network.
Parameters: indices (tuple[int]) – The micro indices to partition. Yields: tuple[tuple] – A possible partition. Each element of the tuple is a tuple of microelements which correspond to macroelements.

pyphi.macro.
all_groupings
(partition)¶ Return all possible groupings of states for a particular coarse graining (partition) of a network.
Parameters: partition (tuple[tuple]) – A partition of microelements into macro elements.
Yields: tuple[tuple[tuple]] –
 A grouping of microstates into macro states of
system.
TODO: document exactly how to interpret the grouping.

pyphi.macro.
all_coarse_grains
(indices)¶ Generator over all possible CoarseGrains of these indices.
Parameters: indices (tuple[int]) – Node indices to coarse grain. Yields: CoarseGrain – The next CoarseGrain
forindices
.

pyphi.macro.
all_coarse_grains_for_blackbox
(blackbox)¶ Generator over all CoarseGrains for the given blackbox.
If a box has multiple outputs, those outputs are partitioned into the same coarsegrain macroelement.

pyphi.macro.
all_blackboxes
(indices)¶ Generator over all possible blackboxings of these indices.
Parameters: indices (tuple[int]) – Nodes to blackbox. Yields: Blackbox – The next Blackbox
ofindices
.

class
pyphi.macro.
MacroNetwork
(network, system, macro_phi, micro_phi, coarse_grain, time_scale=1, blackbox=None)¶ A coarsegrained network of nodes.
See the Emergence (coarsegraining and blackboxing) example in the documentation for more information.

network
¶ Network – The network object of the macrosystem.

phi
¶ float – The \(\Phi\) of the network’s main complex.

micro_network
¶ Network – The network object of the corresponding micro system.

micro_phi
¶ float – The \(\Phi\) of the main complex of the corresponding microsystem.

coarse_grain
¶ CoarseGrain – The coarsegraining of microelements into macroelements.

time_scale
¶ int – The time scale the macronetwork run over.

blackbox
¶ Blackbox – The blackboxing of micro elements in the network.

emergence
¶ float – The difference between the \(\Phi\) of the macro and the microsystem.

emergence
Difference between the \(\Phi\) of the macro and micro systems


pyphi.macro.
coarse_grain
(network, state, internal_indices)¶ Find the maximal coarsegraining of a microsystem.
Parameters:  network (Network) – The network in question.
 state (tuple[int]) – The state of the network.
 internal_indices (tuple[int]) – Nodes in the microsystem.
Returns: tuple[int, CoarseGrain] – The phivalue of the maximal
CoarseGrain
.

pyphi.macro.
all_macro_systems
(network, state, blackbox, coarse_grain, time_scales)¶ Generator over all possible macrosystems for the network.

pyphi.macro.
emergence
(network, state, blackbox=False, coarse_grain=True, time_scales=None)¶ Check for the emergence of a microsystem into a macrosystem.
Checks all possible blackboxings and coarsegrainings of a system to find the spatial scale with maximum integrated information.
Use the
blackbox
andcoarse_grain
args to specifiy whether to use blackboxing, coarsegraining, or both. The default is to just coarsegrain the system.Parameters:  network (Network) – The network of the microsystem under investigation.
 state (tuple[int]) – The state of the network.
 blackbox (bool) – Set to
True
to enable blackboxing. Defaults toFalse
.  coarse_grain (bool) – Set to
True
to enable coarsegraining. Defaults toTrue
.  time_scales (list[int]) – List of all time steps over which to check for emergence.
Returns: MacroNetwork – The maximal macrosystem generated from the microsystem.

pyphi.macro.
phi_by_grain
(network, state)¶

pyphi.macro.
effective_info
(network)¶ Return the effective information of the given network.
Note
For details, see:
Hoel, Erik P., Larissa Albantakis, and Giulio Tononi. “Quantifying causal emergence shows that macro can beat micro.” Proceedings of the National Academy of Sciences 110.49 (2013): 1979019795.
Available online: doi: 10.1073/pnas.1314922110.