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)) Return type: 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 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.
-
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
.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.
-
-
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
, 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: 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
– Ifcheck_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
¶ 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)
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
.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 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.
-
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.
Returns: The phi-value of the maximal
CoarseGrain
.Return type: 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
andcoarse_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 toFalse
. - 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.