Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions docs/api.rst
Original file line number Diff line number Diff line change
Expand Up @@ -52,6 +52,7 @@ Nodes and interpretation
.. automodule:: infoflow.nodes
.. automodule:: infoflow.interpret
.. automodule:: infoflow.contemporaneous
.. automodule:: infoflow.families
.. automodule:: infoflow.hyperedges
.. automodule:: infoflow.oinfo

Expand Down
110 changes: 110 additions & 0 deletions docs/families.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,110 @@
Lag-0 explanation families
==========================

With coarse sampling, processes interact within one sample, and time order no longer orients
those links. The PC-style lag-0 layer (:func:`infoflow.contemporaneous.contemporaneous_layer`)
reads adjacencies from dependence :cite:`Runge2020`. That assumes faithfulness
:cite:`Spirtes2000`: every independence in the data comes from a separation in the causal
graph. Synergy breaks it. If :math:`Z_t = X_t \oplus Y_t \oplus E_t`, every pair of the three
is independent, so the layer reports no link at all, although :math:`X_t` and :math:`Y_t`
together determine :math:`Z_t`.

``infer_multiplex(contemporaneous="family")``
(:func:`infoflow.contemporaneous.contemporaneous_families`) instead reports every explanation
that *weaker adjacency faithfulness* allows :cite:`Marx2021weaker,Hourican2026`. A link may
then be supported by a triple association, as in XOR, and the answer is a family of DAGs. For
the XOR above it is a collider at each of the three variables. Neither a single skeleton nor
the union of the three (a triangle) represents that answer.

.. code-block:: python

net = infoflow.infer_multiplex(data, names=["X", "Y", "Z"], contemporaneous="family", prng=0)
for family in net.contemporaneous_families:
print(family.describe(net.names))
# {X, Y, Z}: 3 explanations: {X -> Y, Z -> Y} | {X -> Z, Y -> Z} | {Y -> X, Z -> X}

Lagged links need no families: time order already leaves one explanation for them, and the
lagged search finds jointly informative parents with its pair search (:doc:`skeleton`).

Procedure
---------

1. **Screen.** Two processes are linked when their present values are dependent given the
lagged conditioning set, or given that set and the present value of one more process.
The lagged conditioning set holds both processes' selected pasts and lagged parents, as in
the PC-style layer. Linked processes form components.
2. **Decisions.** Each component of at most five processes is decided statement by statement.
Every pairwise statement :math:`X^i_t \perp X^j_t \mid X^S_t`, with :math:`S` a set of the
other processes in the component, is tested given the pair's lagged conditioning set. The
level is :math:`\alpha / m` for the component's :math:`m` statements (6 for three
processes, 24 for four, 80 for five).
3. **Family.** Every DAG on the component (25, 543 or 29,281 of them) is kept when it is

* *Markov*: every statement it implies by d-separation was decided independent;
* *weakly adjacency faithful*: at each endpoint :math:`x` of each edge :math:`x - w`, either
:math:`x` and :math:`w` are dependent given every conditioning set, or they form a strict
two-association with a third member :math:`z` of :math:`x`'s Markov blanket. Each of the
three pairs is then dependent given the remaining variable and any further set, while
neither :math:`x, w` nor :math:`x, z` is dependent given every set
(``convention="neither"``; ``"not_both"`` only requires that not both are);
* *SGS-minimal*: no DAG with one edge fewer is Markov;
* consistent with background knowledge: ``tiers`` (a known order within a sample) and
``forbidden`` arcs, passed through ``contemporaneous_settings``.

Reading the result
------------------

``network.contemporaneous_families`` lists one :class:`~infoflow.families.ExplanationFamily`
per component, with its explanations and a status:

``complete``
Every DAG was checked, and these are all that qualify.
``empty``
None qualifies: the assumptions fail for these processes, or the decisions contradict each
other.
``too_large``
The component has more than ``max_family_size`` processes.
``unavailable``
A statement's table has fewer than ``min_cell_count`` samples per cell on average, so not
rejecting it would be no evidence of independence.

The last two keep the PC-style layer's entries and make no further claim.

``dataset["contemporaneous"]`` marks only what every explanation shares: 2 for an arrow in
all of them, 1 for a link in all of them whose direction varies, 0 otherwise. A lag-0 XOR
therefore gives an all-zero matrix. ``dataset["contemporaneous_possible"]`` marks the links
that appear in at least one explanation.

Why the decisions are corrected
-------------------------------

A true DAG implies many independences, and one false rejection among them removes it from
the family. At an uncorrected level of 0.05 per statement, families are therefore often
empty, which is the finite-sample problem :cite:`Hourican2026` report for their family
estimator. We simulated four lag-0 motifs (XOR, XOR with a descendant, OR, and a
four-process chain) at 2000 and 10,000 samples:

* Uncorrected decisions returned exactly the population family in 55--90% of samples, and
an empty family in most of the rest.
* With the Bonferroni level, asymptotic tests returned it in all 20 samples of every motif.
Permutation tests (the default) returned it in all 20 samples of every motif at 2000
samples.

The price is power for weak lag-0 dependence.

Assumptions and limits
----------------------

The explanations assume:

* no hidden common causes of the measured processes within a sample;
* acyclic effects within a sample;
* no interaction between components;
* lag-0 permutation tests that are adequate despite serial dependence (they condition on the
lagged pasts).

Components of more than five processes are not enumerated.

:func:`infoflow.families.decisions_from_distribution` gives exact decisions for a known
distribution. With it, :func:`infoflow.families.explanation_family` computes the population
families that the tests are checked against.
1 change: 1 addition & 0 deletions docs/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,7 @@ and false-discovery-rate control.
spectral
backbone
interpretation
families
hyperedges
machines
channels
Expand Down
3 changes: 2 additions & 1 deletion docs/interpretation.rst
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,8 @@ Optional layers:

* a lag-0 layer with collider orientation in the style of PCMCI+
:cite:`Runge2020` (:mod:`infoflow.contemporaneous`), with an adapter to Tigramite
:cite:`Runge2018`;
:cite:`Runge2018`, or every lag-0 explanation that weaker adjacency faithfulness
allows, which also sees a lag-0 XOR (:doc:`families`);
* detected and classified partial-information-decomposition hyperedges over sets of
parents, with any of dit's PID measures (:doc:`hyperedges`).

Expand Down
16 changes: 16 additions & 0 deletions docs/literature.rst
Original file line number Diff line number Diff line change
Expand Up @@ -79,6 +79,19 @@ dependence by running selection on subsamples and aggregating with e-values
control through the e-BH procedure :cite:`Wang2022,Ren2024`. Stability selection
:cite:`Meinshausen2010` reports how often each variable is selected over subsamples.

**Faithfulness violations.** Constraint-based learners read adjacencies from dependences,
so they delete links whose dependence shows only jointly: an XOR target is independent of
each of its parents. Weaker adjacency faithfulness :cite:`Marx2021weaker` lets a link be
supported by a triple association instead. :cite:`Hourican2026` operationalise it in two
ways. One is a grow-shrink learner that vetoes a removal when one more conditioning variable
restores dependence, and protects links whose whole-minus-sum information exceeds 0.3 bits.
The other searches for the family of DAGs that are Markov, weakly adjacency faithful and
SGS-minimal. Without time order an XOR has three such explanations; with it, one. Their
finite-sample families are often empty, and their searches did not finish beyond eight
variables. ``infoflow`` already has the first idea in the lagged search (the pair search,
and pruning of each parent given the others). It applies the second at lag 0, where no time
order helps, with decisions corrected for the number of statements in a component.

**Higher-order structure.** The O-information rate :cite:`Faes2022` extends the
O-information :cite:`Rosas2019` to processes; its local version (for a link) and
gradients (for a node) :cite:`Scagliarini2023` give a network representation of
Expand Down Expand Up @@ -116,6 +129,9 @@ Regimes :func:`~infoflow.regimes.infer_regimes`,
:func:`~infoflow.regimes.compare_regimes`
Multiple datasets :func:`~infoflow.regimes.infer_with_context`
Stability selection / e-values :func:`~infoflow.stability.stability_selection`
Weaker adjacency faithfulness pair search for lagged parents (``synergy_search``);
lag-0 explanation families,
:func:`~infoflow.contemporaneous.contemporaneous_families`
Mixed-type CMI ``SkeletonSettings(estimator="mixed")``
Predictive (AGM-TE style) TE :func:`~infoflow.predictive.predictive_transfer_entropy`
O-information rate :mod:`infoflow.oinfo`
Expand Down
26 changes: 26 additions & 0 deletions docs/references.bib
Original file line number Diff line number Diff line change
Expand Up @@ -1145,3 +1145,29 @@ @article{Zhang2012
year = {2012},
doi = {10.1162/NECO_a_00266}
}

@inproceedings{Marx2021weaker,
author = {Marx, Alexander and Gretton, Arthur and Mooij, Joris M.},
title = {A weaker faithfulness assumption based on triple interactions},
booktitle = {Proceedings of the 37th Conference on Uncertainty in Artificial Intelligence (UAI)},
series = {Proceedings of Machine Learning Research},
volume = {161},
pages = {451--460},
year = {2021}
}

@misc{Hourican2026,
author = {Hourican, Cillian and Quax, Rick},
title = {Operationalising weaker faithfulness: recovery, ambiguity and computational limits},
year = {2026},
eprint = {2610.31724},
archivePrefix = {arXiv}
}

@book{Spirtes2000,
author = {Spirtes, Peter and Glymour, Clark and Scheines, Richard},
title = {Causation, Prediction, and Search},
edition = {2},
publisher = {MIT Press},
year = {2000}
}
Loading
Loading