`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.

Parameters:: node_tpms (Iterable[ExplicitTPM]) – The collection of node TPMs.
Returns:: The system TPM which comprises the input node TPMs.
Return type:: ExplicitTPM

pyphi.macro.remove_singleton_dimensions(tpm)¶

Remove singleton dimensions from the TPM.

Singleton dimensions are created by conditioning on a set of elements. This removes those elements from the TPM, leaving a TPM that only describes the non-conditioned elements.

Note that indices used in the original TPM must be reindexed for the smaller TPM.

pyphi.macro.run_tpm(system, steps, blackbox)¶

Iterate the TPM for the given number of timesteps.

Returns:: tpm * (noise_tpm^(t-1))
Return type:: ExplicitTPM

class pyphi.macro.SystemAttrs(tpm, cm, node_indices, state)¶

An immutable container that holds all the attributes of a subsystem.

Versions of this object are passed down the steps of the micro-to-macro pipeline.

Create new instance of SystemAttrs(tpm, cm, node_indices, state)

property node_labels¶: Return the labels for macro nodes.

property nodes¶

static pack(system)¶

apply(system)¶

class pyphi.macro.MacroSubsystem(network, state, nodes=None, cut=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.

property 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.

property cut_mechanisms¶

The mechanisms of this system that are currently cut.

Note that although cut_indices returns micro indices, this returns macro mechanisms.

Yields:: tuple[int]

property cut_node_labels¶

Labels for the nodes that can be cut.

These are the labels of the micro elements.

apply_cut(cut)¶

Return a cut version of this MacroSubsystem.

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

potential_purviews(direction, mechanism, purviews=False)¶: Override Subsystem implementation using Network-level indices.

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

macro2blackbox_outputs(macro_indices)¶: Given a set of macro elements, return the blackbox output elements which compose these elements.

__eq__(other)¶: Two macro systems are equal if each underlying Subsystem is equal and all macro attributes are equal.

class pyphi.macro.CoarseGrain(partition, grouping)¶

Represents a coarse graining of a collection of nodes.

partition¶

The partition of micro-elements into macro-elements.

Type:: tuple[tuple]

grouping¶

The grouping of micro-states into macro-states.

Type:: tuple[tuple[tuple]]

Create new instance of CoarseGrain(partition, grouping)

property micro_indices¶: Indices of micro elements represented in this coarse-graining.

property 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:: The state of the macro system, translated as specified by this coarse-graining.
Return type:: tuple[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_sbs(state_by_state_micro_tpm)¶

Create a state-by-state coarse-grained macro TPM.

Parameters:: micro_tpm (nd.array) – The state-by-state TPM of the micro-system.
Returns:: The state-by-state TPM of the macro-system.
Return type:: np.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 (bool) – Whether to check that the macro TPM is conditionally independent.

Raises:

ConditionallyDependentError – If check_independence is True and 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(partition, output_indices)¶

Class representing a blackboxing of a system.

partition¶

The partition of nodes into boxes.

Type:: tuple[tuple[int]]

output_indices¶

Outputs of the blackboxes.

Type:: tuple[int]

Create new instance of Blackbox(partition, output_indices)

property hidden_indices¶: All elements hidden inside the blackboxes.

property micro_indices¶: Indices of micro-elements in this blackboxing.

property macro_indices¶: Fresh indices of macro-elements of the blackboxing.

outputs_of(partition_index)¶

The outputs of the partition at partition_index.

Note that this returns a tuple of element indices, since coarse- grained blackboxes may have multiple outputs.

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:: The state of the output indices.
Return type:: tuple[int]

in_same_box(a, b)¶: Return True if nodes a and b` are in the same box.

hidden_from(a, b)¶: Return True if a is hidden in a different box than b.

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

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

pyphi.macro.all_coarse_grains_for_blackbox(blackbox)¶

Generator over all CoarseGrain 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¶

The network object of the macro-system.

Type:: Network

phi¶

The \(\Phi\) of the network’s major complex.

Type:: float

micro_network¶

The network object of the corresponding micro system.

Type:: Network

micro_phi¶

The \(\Phi\) of the major complex of the corresponding micro-system.

Type:: float

coarse_grain¶

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

Type:: CoarseGrain

time_scale¶

The time scale the macro-network run over.

Type:: int

blackbox¶

The blackboxing of micro elements in the network.

Type:: Blackbox

emergence¶

The difference between the \(\Phi\) of the macro- and the micro-system.

Type:: float

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

pyphi.macro.coarse_graining(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.

Returns:

The phi-value of the maximal CoarseGrain.

Return type:

tuple[int, CoarseGrain]

pyphi.macro.all_macro_systems(network, state, do_blackbox=False, do_coarse_grain=False, time_scales=None)¶: Generator over all possible macro-systems for the network.

pyphi.macro.emergence(network, state, do_blackbox=False, do_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 do_blackbox and do_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.
do_blackbox (bool) – Set to True to enable blackboxing. Defaults to False.
do_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.

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.

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`¶