# macro¶

Methods for coarse-graining 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 coarse-graining 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 to 0..n so they properly index the TPM, and the state-tuple is reduced to the size of the system.

After each macro update (temporal blackboxing, spatial blackboxing, and spatial coarse-graining) 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 micro-system.

apply_cut(cut)

Return a cut version of this MacroSubsystem.

Parameters: cut (Cut) – The cut to apply to this MacroSubsystem. MacroSubsystem – The cut version of this MacroSubsystem.
macro2micro(macro_indices)

Returns all micro indices which compose the elements specified by macro_indices.

__eq__(other)

Two macro systems are equal if each underlying Subsystem is equal and all macro attributes are equal.

TODO: handle cases where a MacroSubsystem is identical to a micro Subsystem, e.g. the macro has no timescale, hidden indices, etc.

class pyphi.macro.CoarseGrain

Represents a coarse graining of a collection of nodes.

partition

tuple[tuple] – The partition of micro-elements into macro-elements.

grouping

tuple[tuple[tuple]] – The grouping of micro-states into macro-states.

Create new instance of CoarseGrain(partition, grouping)

micro_indices

Indices of micro elements represented in this coarse-graining.

macro_indices

Indices of macro elements of this coarse-graining.

reindex()

Re-index this coarse graining to use squeezed indices.

The output grouping is translated to use indices 0..n, where n is the number of micro indices in the coarse-graining. Re-indexing does not effect the state grouping, which is already index-independent.

Returns: CoarseGrain – A new CoarseGrain object, indexed from 0..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 coarse-graining. tuple[int] – The state of the macro system, translated as specified by this coarse-graining.

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 micro-state to the macro-states based on the partition and state grouping of this coarse-grain.

Returns: (nd.ndarray) – A mapping from micro-states to macro-states. The $$i^{\textrm{th}}$$ entry in the mapping is the macro-state corresponding to the $$i^{\textrm{th}}$$ micro-state.
macro_tpm(micro_tpm, check_independence=True)

Create a coarse-grained macro TPM.

Parameters: micro_tpm (nd.array) – The TPM of the micro-system. check_independence (bool) – If True, the method will raise a ConditionallyDependentError if the macro TPM is not conditionally independent. np.ndarray – The state-by-node TPM of the macro-system.
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)

hidden_indices

All elements hidden inside the blackboxes.

micro_indices

Indices of micro-elements in this blackboxing.

macro_indices

Fresh indices of macro-elements 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 macro-state of this blackbox.

This is just the state of the blackbox’s output indices.

Parameters: micro_state (tuple[int]) – The state of the micro-elements in the blackbox. tuple[int] – The state of the output indices.
in_same_box(a, b)

Returns True if nodes a and b 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. tuple[tuple] – A possible partition. Each element of the tuple is a tuple of micro-elements which correspond to macro-elements.
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 micro-elements into macro elements. tuple[tuple[tuple]] – A grouping of micro-states into macro states of system.

TODO: document exactly how to interpret the grouping.

pyphi.macro.all_coarse_grains(indices)

Generator over all possible |CoarseGrain|s of these indices.

Parameters: indices (tuple[int]) – Node indices to coarse grain. CoarseGrain – The next CoarseGrain for indices.
pyphi.macro.all_coarse_grains_for_blackbox(blackbox)

Generator over all |CoarseGrain|s for the given blackbox.

If a box has multiple outputs, those outputs are partitioned into the same coarse-grain macro-element.

pyphi.macro.all_blackboxes(indices)

Generator over all possible blackboxings of these indices.

Parameters: indices (tuple[int]) – Nodes to blackbox. Blackbox – The next Blackbox of indices.
class pyphi.macro.MacroNetwork(network, system, macro_phi, micro_phi, coarse_grain, time_scale=1, blackbox=None)

A coarse-grained network of nodes.

See the Emergence (coarse-graining and blackboxing) example in the documentation for more information.

network

Network – The network object of the macro-system.

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 micro-system.

coarse_grain

CoarseGrain – The coarse-graining of micro-elements into macro-elements.

time_scale

int – The time scale the macro-network run over.

blackbox

Blackbox – The blackboxing of micro elements in the network.

emergence

float – The difference between the $$\Phi$$ of the macro- and the micro-system.

emergence

Difference between the $$\Phi$$ of the macro and micro systems

pyphi.macro.coarse_grain(network, state, internal_indices)

Find the maximal coarse-graining of a micro-system.

Parameters: network (Network) – The network in question. state (tuple[int]) – The state of the network. internal_indices (tuple[int]) – Nodes in the micro-system. tuple[int, CoarseGrain] – The phi-value of the maximal CoarseGrain.
pyphi.macro.all_macro_systems(network, state, blackbox, coarse_grain, time_scales)

Generator over all possible macro-systems for the network.

pyphi.macro.emergence(network, state, blackbox=False, coarse_grain=True, time_scales=None)

Check for the emergence of a micro-system into a macro-system.

Checks all possible blackboxings and coarse-grainings of a system to find the spatial scale with maximum integrated information.

Use the blackbox and coarse_grain args to specifiy whether to use blackboxing, coarse-graining, or both. The default is to just coarse-grain the system.

Parameters: network (Network) – The network of the micro-system under investigation. state (tuple[int]) – The state of the network. blackbox (bool) – Set to True to enable blackboxing. Defaults to False. coarse_grain (bool) – Set to True to enable coarse-graining. Defaults to True. time_scales (list[int]) – List of all time steps over which to check for emergence. MacroNetwork – The maximal macro-system generated from the micro-system.
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): 19790-19795.

Available online: doi: 10.1073/pnas.1314922110.