`macro`¶

Methods for coarse-graining systems to different levels of spatial analysis.

exception pyphi.macro.ConditionallyDependentError¶

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.
Returns:	subsystem (MacroSubsystem)

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

__eq__(other)¶

Two macro systems are equal if the underlying |Subsystems| are 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.

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:	A new CoarseGrain object, indexed from 0..n
Return type:	CoarseGrain

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.
Returns:	tuple – The state of the macro system, translated as specified by this coarse-graining.
Return type:	int

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:	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.
Return type:	(nd.ndarray)

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 (boolean) – If True, the method will raise a `ConditionallyDependentError` if the macro tpm is not conditionally independent.
Returns:	The state-by-node TPM of the macro-system.
Return type:	(np.ndarray)

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.

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:	a new, reindexed `Blackbox`.
Return type:	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.
Returns:	tuple – The state of the output indices.
Return type:	int

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.

Yields:

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.

Yields:

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 CoarseGrains of these indices.

Parameters:	indices (tuple(int) – Node indices to coarse grain.
Yields:	CoarseGrain – The next coarse-grain for `indices`.

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 coarse-grain macro-element.

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 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(indices) – Nodes in the micro-system.
Returns:	tuple – The phi-value of the maximal CoarseGrain.
Return type:	int, 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 (boolean) – Set to True to enable blackboxing. Defaults to False. coarse_grain (boolean) – 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.
Returns:	The maximal macro-system generated from the micro-system.
Return type:	MacroNetwork

pyphi.macro.phi_by_grain(network, state)¶

pyphi.macro.effective_info(network)¶

Return the effective information of the given network.

This is equivalent to the average of the effect_info() (with the entire network as the mechanism and purview) over all posisble states of the network. It can be interpreted as the “noise in the network’s TPM,” weighted by the size of its state space.

Warning

If config.VALIDATE_SUBSYSTEM_STATES is enabled, then unreachable states are omitted from the average.

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.

macro¶

`macro`¶