actual
¶
Methods for computing actual causation of subsystems and mechanisms.
If you use this module, please cite the following papers:
Albantakis L, Marshall W, Hoel E, Tononi G (2019). What Caused What? A quantitative Account of Actual Causation Using Dynamical Causal Networks. Entropy, 21 (5), pp. 459. https://doi.org/10.3390/e21050459
Mayner WGP, Marshall W, Albantakis L, Findlay G, Marchman R, Tononi G. (2018). PyPhi: A toolbox for integrated information theory. PLOS Computational Biology 14(7): e1006343. https://doi.org/10.1371/journal.pcbi.1006343
- class pyphi.actual.Transition(network, before_state, after_state, cause_indices, effect_indices, cut=None, noise_background=False)¶
A state transition between two sets of nodes in a network.
A
Transition
is implemented with twoSubsystem
objects: one representing the system at time \(t-1\) used to compute effect coefficients, and another representing the system at time \(t\) which is used to compute cause coefficients. These subsystems are accessed with theeffect_system
andcause_system
attributes, and are mapped to the causal directions via thesystem
attribute.- Parameters
network (Network) – The network the subsystem belongs to.
before_state (tuple[int]) – The state of the network at time \(t-1\).
after_state (tuple[int]) – The state of the network at time \(t\).
cause_indices (tuple[int] or tuple[str]) – Indices of nodes in the cause system. (TODO: clarify)
effect_indices (tuple[int] or tuple[str]) – Indices of nodes in the effect system. (TODO: clarify)
- Keyword Arguments
noise_background (bool) – If
True
, background conditions are noised instead of frozen.
- node_indices¶
The indices of the nodes in the system.
- Type
tuple[int]
- before_state¶
The state of the network at time \(t-1\).
- Type
tuple[int]
- after_state¶
The state of the network at time \(t\).
- Type
tuple[int]
- effect_system¶
The system in
before_state
used to compute effect repertoires and coefficients.- Type
- cause_system¶
The system in
after_state
used to compute cause repertoires and coefficients.- Type
- system¶
A dictionary mapping causal directions to the system used to compute repertoires in that direction.
- Type
dict
Note
During initialization, both the cause and effect systems are conditioned on
before_state
as the background state. After conditioning theeffect_system
is then properly reset toafter_state
.- property node_labels¶
- to_json()¶
Return a JSON-serializable representation.
- apply_cut(cut)¶
Return a cut version of this transition.
- cause_repertoire(mechanism, purview)¶
Return the cause repertoire.
- effect_repertoire(mechanism, purview)¶
Return the effect repertoire.
- unconstrained_cause_repertoire(purview)¶
Return the unconstrained cause repertoire of the occurence.
- unconstrained_effect_repertoire(purview)¶
Return the unconstrained effect repertoire of the occurence.
- repertoire(direction, mechanism, purview)¶
Return the cause or effect repertoire function based on a direction.
- Parameters
direction (str) – The temporal direction, specifiying the cause or effect repertoire.
- state_probability(direction, repertoire, purview)¶
Compute the probability of the purview in its current state given the repertoire.
Collapses the dimensions of the repertoire that correspond to the purview nodes onto their state. All other dimension are already singular and thus receive 0 as the conditioning index.
- Returns
A single probabilty.
- Return type
float
- probability(direction, mechanism, purview)¶
Probability that the purview is in it’s current state given the state of the mechanism.
- unconstrained_probability(direction, purview)¶
Unconstrained probability of the purview.
- purview_state(direction)¶
The state of the purview when we are computing coefficients in
direction
.For example, if we are computing the cause coefficient of a mechanism in
after_state
, the direction is``CAUSE`` and thepurview_state
isbefore_state
.
- mechanism_state(direction)¶
The state of the mechanism when computing coefficients in
direction
.
- mechanism_indices(direction)¶
The indices of nodes in the mechanism system.
- purview_indices(direction)¶
The indices of nodes in the purview system.
- cause_ratio(mechanism, purview)¶
The cause ratio of the
purview
givenmechanism
.
- effect_ratio(mechanism, purview)¶
The effect ratio of the
purview
givenmechanism
.
- partitioned_repertoire(direction, partition)¶
Compute the repertoire over the partition in the given direction.
- partitioned_probability(direction, partition)¶
Compute the probability of the mechanism over the purview in the partition.
- find_mip(direction, mechanism, purview, allow_neg=False)¶
Find the ratio minimum information partition for a mechanism over a purview.
- Parameters
- Keyword Arguments
allow_neg (boolean) – If true,
alpha
is allowed to be negative. Otherwise, negative values ofalpha
will be treated as if they were 0.- Returns
The irreducibility analysis for the mechanism.
- Return type
- potential_purviews(direction, mechanism, purviews=False)¶
Return all purviews that could belong to the
MaximallyIrreducibleCause
/MaximallyIrreducibleEffect
.Filters out trivially-reducible purviews.
- find_causal_link(direction, mechanism, purviews=False, allow_neg=False)¶
Return the maximally irreducible cause or effect ratio for a mechanism.
- Parameters
direction (str) – The temporal direction, specifying cause or effect.
mechanism (tuple[int]) – The mechanism to be tested for irreducibility.
- Keyword Arguments
purviews (tuple[int]) – Optionally restrict the possible purviews to a subset of the subsystem. This may be useful for _e.g._ finding only concepts that are “about” a certain subset of nodes.
- Returns
The maximally-irreducible actual cause or effect.
- Return type
- find_actual_cause(mechanism, purviews=False)¶
Return the actual cause of a mechanism.
- find_actual_effect(mechanism, purviews=False)¶
Return the actual effect of a mechanism.
- find_mice(*args, **kwargs)¶
Backwards-compatible alias for
find_causal_link()
.
- pyphi.actual.directed_account(transition, direction, mechanisms=False, purviews=False, allow_neg=False)¶
Return the set of all
CausalLink
of the specified direction.
- pyphi.actual.account(transition, direction=Direction.BIDIRECTIONAL)¶
Return the set of all causal links for a
Transition
.- Parameters
transition (Transition) – The transition of interest.
- Keyword Arguments
direction (Direction) – By default the account contains actual causes and actual effects.
- pyphi.actual.account_distance(A1, A2)¶
Return the distance between two accounts. Here that is just the difference in sum(alpha)
- pyphi.actual.sia(transition, direction=Direction.BIDIRECTIONAL)¶
Return the minimal information partition of a transition in a specific direction.
- Parameters
transition (Transition) – The candidate system.
- Returns
A nested structure containing all the data from the intermediate calculations. The top level contains the basic irreducibility information for the given subsystem.
- Return type
- class pyphi.actual.ComputeACSystemIrreducibility(iterable, *context)¶
Computation engine for AC SIAs.
- description = 'Evaluating AC cuts'¶
- empty_result(transition, direction, unpartitioned_account)¶
Return the default result with which to begin the computation.
- static compute(cut, transition, direction, unpartitioned_account)¶
Map over a single object from
self.iterable
.
- process_result(new_sia, min_sia)¶
Reduce handler.
Every time a new result is generated by
compute
, this method is called with the result and the previous (accumulated) result. This method compares or collates these two values, returning the new result.Setting
self.done
toTrue
in this method will abort the remainder of the computation, returning this final result.
- pyphi.actual.transitions(network, before_state, after_state)¶
Return a generator of all possible transitions of a network.
- pyphi.actual.nexus(network, before_state, after_state, direction=Direction.BIDIRECTIONAL)¶
Return a tuple of all irreducible nexus of the network.
- pyphi.actual.causal_nexus(network, before_state, after_state, direction=Direction.BIDIRECTIONAL)¶
Return the causal nexus of the network.
- pyphi.actual.nice_true_ces(tc)¶
Format a true
CauseEffectStructure
.
- pyphi.actual.events(network, previous_state, current_state, next_state, nodes, mechanisms=False)¶
Find all events (mechanisms with actual causes and actual effects).
- pyphi.actual.true_ces(subsystem, previous_state, next_state)¶
Set of all sets of elements that have true causes and true effects.
Note
Since the true
CauseEffectStructure
is always about the full system, the background conditions don’t matter and the subsystem should be conditioned on the current state.
- pyphi.actual.true_events(network, previous_state, current_state, next_state, indices=None, major_complex=None)¶
Return all mechanisms that have true causes and true effects within the complex.
- Parameters
network (Network) – The network to analyze.
previous_state (tuple[int]) – The state of the network at
t - 1
.current_state (tuple[int]) – The state of the network at
t
.next_state (tuple[int]) – The state of the network at
t + 1
.
- Keyword Arguments
indices (tuple[int]) – The indices of the major complex.
major_complex (AcSystemIrreducibilityAnalysis) – The major complex. If
major_complex
is given thenindices
is ignored.
- Returns
List of true events in the major complex.
- Return type
tuple[Event]
- pyphi.actual.extrinsic_events(network, previous_state, current_state, next_state, indices=None, major_complex=None)¶
Set of all mechanisms that are in the major complex but which have true causes and effects within the entire network.
- Parameters
network (Network) – The network to analyze.
previous_state (tuple[int]) – The state of the network at
t - 1
.current_state (tuple[int]) – The state of the network at
t
.next_state (tuple[int]) – The state of the network at
t + 1
.
- Keyword Arguments
indices (tuple[int]) – The indices of the major complex.
major_complex (AcSystemIrreducibilityAnalysis) – The major complex. If
major_complex
is given thenindices
is ignored.
- Returns
List of extrinsic events in the major complex.
- Return type
tuple(actions)