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

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.node_labels(indices)

Return the labels for macro nodes.

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

Iterate the TPM for the given number of timesteps.

Returns: tpm * (noise_tpm^(t-1)) np.ndarray
class pyphi.macro.SystemAttrs

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)

nodes
static pack(system)
apply(system)
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.

cut_mechanisms

The mechanisms of this system that are currently cut.

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

apply_cut(cut)

Return a cut version of this MacroSubsystem.

Parameters: cut (Cut) – The cut to apply to this MacroSubsystem. The cut version of this MacroSubsystem. 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

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: A new CoarseGrain object, indexed from 0..n. 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. The state of the macro system, translated as specified by this coarse-graining. 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. (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. The state-by-state TPM of the macro-system. 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. ConditionallyDependentError – If check_independence is True and the macro TPM is not conditionally independent. The state-by-node TPM of the macro-system. 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.

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.

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. 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. The state of the output indices. 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. 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 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 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 major complex.

micro_network

Network – The network object of the corresponding micro system.

micro_phi

float – The $$\Phi$$ of the major 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. The phi-value of the maximal CoarseGrain. tuple[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 (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. The maximal macro-system generated from the micro-system. 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.