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 to0..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
- 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.
- 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
, wheren
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 from0..n
.- Return type
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
isTrue
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)
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
.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 nodesa
andb`
are in the same box.
Return True if
a
is hidden in a different box thanb
.
- 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
forindices
.
- 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
ofindices
.
- 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.
- phi¶
The \(\Phi\) of the network’s major complex.
- Type
float
- 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
- time_scale¶
The time scale the macro-network run over.
- Type
int
- 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
anddo_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 toFalse
.do_coarse_grain (bool) – Set to
True
to enable coarse-graining. Defaults toTrue
.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
- 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.