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.run_tpm(system, steps, blackbox)

Iterate the TPM for the given number of timesteps.

Returns

tpm * (noise_tpm^(t-1))

Return type

np.ndarray

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

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.