gum::DoCalculus< GUM_SCALAR > Class Template Reference

Instance-based do-calculus utilities bound to a single CausalModel. More...

#include <doCalculus.h>

Public Types
using	FormulaPtr = std::unique_ptr< ASTtree< GUM_SCALAR > >
	Owned pointer to an AST representing a probability expression.
using	NameList = std::vector< std::string >
	Convenience container for name-based overloads.

Public Member Functions
	DoCalculus (const CausalModel< GUM_SCALAR > &cm) noexcept
const CausalModel< GUM_SCALAR > &	model () const noexcept
FormulaPtr	getBackDoorTree (NodeId cause, NodeId effect, const NodeSet &zset) const
FormulaPtr	getBackDoorTree (std::string_view causeName, std::string_view effectName, const NameList &zNames) const
FormulaPtr	getFrontDoorTree (NodeId cause, NodeId effect, const NodeSet &zset) const
FormulaPtr	getFrontDoorTree (std::string_view causeName, std::string_view effectName, const NameList &zNames) const
FormulaPtr	identifyingIntervention (const NodeSet &Y, const NodeSet &X) const
	ID: identify P(Y | do(X)) (NodeId-based).
FormulaPtr	identifyingIntervention (const NameList &Y, const NameList &X) const
	ID: identify P(Y | do(X)) (name-based).
FormulaPtr	doCalculus (const NodeSet &on, const NodeSet &doing) const
	Thin wrapper around ID: doCalculus(on, doing).
FormulaPtr	doCalculus (const NameList &on, const NameList &doing) const
FormulaPtr	doCalculusWithObservation (const NodeSet &on, const NodeSet &doing, const NodeSet &knowing) const
	IDC: identify P(on | do(doing), knowing).
FormulaPtr	doCalculusWithObservation (const NameList &on, const NameList &doing, const NameList &knowing) const

Private Member Functions
std::vector< NodeSet >	_cDecomposition_ (const CausalModel< GUM_SCALAR > &cm) const
	c-decomposition (confounding components) among observed nodes.
std::vector< NodeSet >	_cDecompositionOn_ (const CausalModel< GUM_SCALAR > &sub) const
	c-decomposition on an induced submodel (observed nodes only).
std::vector< NodeId >	_topoObserved_ (const CausalModel< GUM_SCALAR > &cm) const
	Topological order over observed nodes (ignoring latent parents).
FormulaPtr	_ID_ (const CausalModel< GUM_SCALAR > &cm, const NodeSet &Y, const NodeSet &X, std::unique_ptr< ASTtree< GUM_SCALAR > > P) const
	ID core (recursive), with optional accumulated distribution P (AST) to carry in decompositions.

Static Private Member Functions
static NodeSet	_ancestorsIn_ (const DAG &g, const NodeSet &T)
	Ancestors (in DAG g) of a set T (including T).
static DAG	_removeIncomingInto_ (const DAG &dag, const NodeSet &X)
	DAG copy with all incoming arcs into X removed (G_{\overline X}).
static DAG	_removeInIntoDoing_outOfKnowing_ (const DAG &dag, const NodeSet &doing, const NodeSet &knowing)
	IDC helper: DAG copy with incoming into doing removed AND outgoing from knowing removed.
static std::string	_hedgeExceptionMsg (const CausalModel< GUM_SCALAR > &cm, const NodeSet &Y, const NodeSet &X, const NodeSet &V, const NodeSet &S)
	Format a hedge exception message.

Private Attributes
const CausalModel< GUM_SCALAR > &	_cm

Detailed Description

template<GUM_Numeric GUM_SCALAR>
class gum::DoCalculus< GUM_SCALAR >

Instance-based do-calculus utilities bound to a single CausalModel.

This class provides:

• AST builders for standard adjustment formulas:
  • Backdoor: \(\sum_{Z} P(y \mid x, z)\,P(z)\)
  • Frontdoor: \(\sum_{Z} P(z \mid x)\,\sum_{x} P(y \mid x, z)\,P(x)\)
• Public entry points for general identification (ID/IDC):
  • identifyingIntervention(Y, X)
  • doCalculus(on, doing)
  • doCalculusWithObservation(on, doing, knowing)

Returned ASTs are evaluated against the observational BN of the bound causal model.

Definition at line 78 of file doCalculus.h.

Member Typedef Documentation

FormulaPtr

template<GUM_Numeric GUM_SCALAR>

using gum::DoCalculus< GUM_SCALAR >::FormulaPtr = std::unique_ptr< ASTtree< GUM_SCALAR > >

Owned pointer to an AST representing a probability expression.

Definition at line 81 of file doCalculus.h.

NameList

template<GUM_Numeric GUM_SCALAR>

using gum::DoCalculus< GUM_SCALAR >::NameList = std::vector< std::string >

Convenience container for name-based overloads.

Definition at line 84 of file doCalculus.h.

Constructor & Destructor Documentation

DoCalculus()

template<GUM_Numeric GUM_SCALAR>

gum::DoCalculus< GUM_SCALAR >::DoCalculus ( const CausalModel< GUM_SCALAR > & cm )

inlineexplicitnoexcept

Definition at line 88 of file doCalculus.h.

: _cm{cm} {}

References _cm.

Member Function Documentation

_ancestorsIn_()

template<GUM_Numeric GUM_SCALAR>

NodeSet gum::DoCalculus< GUM_SCALAR >::_ancestorsIn_ ( const DAG & g, const NodeSet & T )

staticprivate

Ancestors (in DAG g) of a set T (including T).

Definition at line 378 of file doCalculus_tpl.h.

                                                                                {
    NodeSet res = T * g.nodes().asNodeSet();   // keep only nodes that actually exist in g
 
    std::queue< NodeId > q;
    for (auto t: res)
      q.push(t);
 
    while (!q.empty()) {
      NodeId u = q.front();
      q.pop();
      for (auto p: g.parents(u)) {
        if (!res.contains(p)) {
          res.insert(p);
          q.push(p);
        }
      }
    }
    return res;
  }

References gum::NodeGraphPart::asNodeSet(), gum::Set< Key >::contains(), gum::Set< Key >::insert(), gum::NodeGraphPart::nodes(), and gum::ArcGraphPart::parents().

Referenced by _ID_().

Here is the call graph for this function:

Here is the caller graph for this function:

_cDecomposition_()

template<GUM_Numeric GUM_SCALAR>

std::vector< NodeSet > gum::DoCalculus< GUM_SCALAR >::_cDecomposition_ ( const CausalModel< GUM_SCALAR > & cm ) const

private

c-decomposition (confounding components) among observed nodes.

Definition at line 286 of file doCalculus_tpl.h.

                                                                                          {
    // c-components: undirected connectivity among observed children of the same latent.
    const NodeSet lat = cm.latentVariablesIds();
    const NodeSet V   = cm.observationalBN().internalDag().nodes().asNodeSet();
 
    // adjacency among observed nodes, via latent co-children
    std::unordered_map< NodeId, std::vector< NodeId > > adj;
    for (auto v: V)
      adj[v];   // ensure key exists
 
    for (auto h: lat) {
      const auto& ch = cm.children(h);
      // connect all observed pairs of children with an undirected edge
      for (auto it1 = ch.begin(); it1 != ch.end(); ++it1) {
        if (lat.contains(*it1)) continue;
        auto it2 = it1;
        ++it2;
        for (; it2 != ch.end(); ++it2) {
          if (lat.contains(*it2)) continue;
          adj[*it1].push_back(*it2);
          adj[*it2].push_back(*it1);
        }
      }
    }
 
    // BFS/DFS over observed nodes
    std::vector< NodeSet >       comps;
    std::unordered_set< NodeId > seen;
    for (auto v: V) {
      if (seen.count(v)) continue;
      NodeSet              comp;
      std::queue< NodeId > q;
      q.push(v);
      seen.insert(v);
      comp.insert(v);
      while (!q.empty()) {
        auto u = q.front();
        q.pop();
        for (auto w: adj[u]) {
          if (!seen.count(w)) {
            seen.insert(w);
            comp.insert(w);
            q.push(w);
          }
        }
      }
      comps.push_back(std::move(comp));
    }
    return comps;
  }

References gum::CausalModel< GUM_SCALAR >::children(), gum::Set< Key >::contains(), gum::Set< Key >::insert(), gum::CausalModel< GUM_SCALAR >::latentVariablesIds(), and gum::CausalModel< GUM_SCALAR >::observationalBN().

Referenced by _cDecompositionOn_(), and _ID_().

Here is the call graph for this function:

Here is the caller graph for this function:

_cDecompositionOn_()

template<GUM_Numeric GUM_SCALAR>

std::vector< NodeSet > gum::DoCalculus< GUM_SCALAR >::_cDecompositionOn_ ( const CausalModel< GUM_SCALAR > & sub ) const

private

c-decomposition on an induced submodel (observed nodes only).

Definition at line 339 of file doCalculus_tpl.h.

                                                                                             {
    return _cDecomposition_(sub);
  }

References _cDecomposition_().

Referenced by _ID_().

Here is the call graph for this function:

Here is the caller graph for this function:

_hedgeExceptionMsg()

template<GUM_Numeric GUM_SCALAR>

std::string gum::DoCalculus< GUM_SCALAR >::_hedgeExceptionMsg ( const CausalModel< GUM_SCALAR > & cm, const NodeSet & Y, const NodeSet & X, const NodeSet & V, const NodeSet & S )

staticprivate

Format a hedge exception message.

Definition at line 252 of file doCalculus_tpl.h.

                                                                                               {
    // turn NodeSets into sorted name lists
    auto namesOf = [&](const NodeSet& Ns) {
      std::vector< std::string > out;
      out.reserve(Ns.size());
      for (auto id: Ns)
        out.push_back(cm.nameFromId(id));
      std::sort(out.begin(), out.end());
      return out;
    };
 
    const auto yN = namesOf(Y);
    const auto xN = namesOf(X);
    const auto vN = namesOf(V);
    const auto sN = namesOf(S);
 
    return std::format("Not identifiable: hedge detected. "
                       "Target P{} | do{}. Witness: V = {} is a single c-component and S = {} "
                       "is a c-component in both G and G\\X (forms a hedge). "
                       "Interpretation: unblocked confounding remains under intervention; "
                       "the effect cannot be expressed from the observational distribution "
                       "using current graph structure.",
                       _fmtBraceList_(yN),
                       _fmtBraceList_(xN),
                       _fmtBraceList_(vN),
                       _fmtBraceList_(sN));
  }

References gum::CausalModel< GUM_SCALAR >::nameFromId().

Referenced by _ID_().

Here is the call graph for this function:

Here is the caller graph for this function:

_ID_()

template<GUM_Numeric GUM_SCALAR>

DoCalculus< GUM_SCALAR >::FormulaPtr gum::DoCalculus< GUM_SCALAR >::_ID_ ( const CausalModel< GUM_SCALAR > & cm, const NodeSet & Y, const NodeSet & X, std::unique_ptr< ASTtree< GUM_SCALAR > > P ) const

private

ID core (recursive), with optional accumulated distribution P (AST) to carry in decompositions.

Definition at line 528 of file doCalculus_tpl.h.

                                                                                     {
    const NodeSet lat = cm.latentVariablesIds();
    const NodeSet V   = cm.observationalBN().internalDag().nodes().asNodeSet();
 
    // --- 1) if X is empty ---
    if (X.empty()) {
      if (!P) {
        // return P(Y)
        Set< std::string > Yn;
        for (auto y: Y)
          Yn.insert(cm.nameFromId(y));
        return std::make_unique< ASTjointProba< GUM_SCALAR > >(Yn);
      }
      // return sum_{V\Y} P
      NodeSet Vy = V - Y;
      if (Vy.empty()) return std::move(P);
      std::vector< std::string > tosum;
      tosum.reserve(Vy.size());
      for (auto v: Vy)
        tosum.push_back(cm.nameFromId(v));
      return std::make_unique< ASTsum< GUM_SCALAR > >(tosum, std::move(P));
    }
 
    // --- 2) restrict to ancestors of Y in G ---
    {
      DAG     g = cm.causalDAG();
      NodeSet A = _ancestorsIn_(g, Y);
      A += Y;
      // Only observed ancestors (V is observed-only)
      NodeSet Aobs = A - lat;
      if (Aobs.size() != V.size()) {
        // sum out V \ Aobs from P if present, recurse on induced submodel G[Aobs]
        if (P) {
          NodeSet VminusA = V - Aobs;
          if (!VminusA.empty()) {
            std::vector< std::string > tosum;
            tosum.reserve(VminusA.size());
            for (auto v: VminusA)
              tosum.push_back(cm.nameFromId(v));
            P = std::make_unique< ASTsum< GUM_SCALAR > >(tosum, std::move(P));
          }
        }
        auto    sub = cm.inducedCausalSubModel(cm, Aobs);
        NodeSet XA  = X * Aobs;
        return _ID_(sub, Y, XA, std::move(P));
      }
    }
 
 
    // --- 3) W := (V\X) \ An_{G_{\overline X}}(Y); if non-empty, move W to X and recurse ---
    {
      DAG     gXbar = _removeIncomingInto_(cm.causalDAG(), X);
      NodeSet AnY   = _ancestorsIn_(gXbar, Y);
      AnY += Y;
      NodeSet W = (V - X) - AnY;
      if (!W.empty()) { return _ID_(cm, Y, X + W, std::move(P)); }
    }
 
    // --- 4) c-decompose G[V\X]; if >1 component, multiply and sum ---
    {
      auto gvx   = cm.inducedCausalSubModel(cm, V - X);
      auto icomp = _cDecompositionOn_(gvx);
 
      if (icomp.size() > 1) {
        // t = Π_i ID(S_i, V \ S_i)
        std::unique_ptr< ASTtree< GUM_SCALAR > > t;
        for (size_t i = 0; i < icomp.size(); ++i) {
          NodeSet  Si = icomp[i];
          NameList Sn;
          for (auto s: Si)
            Sn.push_back(cm.nameFromId(s));
 
          std::unique_ptr< ASTtree< GUM_SCALAR > > Pcopy
              = P ? std::unique_ptr< ASTtree< GUM_SCALAR > >(P->copy()) : nullptr;
          auto term = _ID_(cm, Si, V - Si, std::move(Pcopy));
          if (!t) t = std::move(term);
          else t = std::make_unique< ASTmult< GUM_SCALAR > >(std::move(term), std::move(t));
        }
        NodeSet Vyx = V - (X + Y);
        if (Vyx.empty()) return t;
        std::vector< std::string > tosum;
        tosum.reserve(Vyx.size());
        for (auto v: Vyx)
          tosum.push_back(cm.nameFromId(v));
        return std::make_unique< ASTsum< GUM_SCALAR > >(tosum, std::move(t));
      }
 
      // Only one component:
      NodeSet S   = icomp.front();
      auto    cdg = _cDecomposition_(cm);
 
      // --- 5) Hedge check: if full graph is one c-component, not identifiable
      if (cdg.size() == 1) {
        NodeSet all = cdg.front();
        if (all.size() == V.size()) {
          // build names for message
          Set< std::string > Vn, Sn;
          for (auto v: V)
            Vn.insert(cm.nameFromId(v));
          for (auto s: S)
            Sn.insert(cm.nameFromId(s));
          auto msg = _hedgeExceptionMsg(cm, Y, X, V, S);
          GUM_ERROR(HedgeException, msg);
        }
      }
 
      // --- 6) If S is also a c-component in G: product of local conditionals over S
      {
        // test membership: S ∈ cdg ?
        bool sInCdg = false;
        for (const auto& comp: cdg) {
          if (comp == S) {
            sInCdg = true;
            break;
          }
        }
 
        if (sInCdg) {
          // P_new := Π_{v∈S in topo order} P(v | v_π) under current P (if provided),
          // otherwise P from the BN (chain rule)
          const auto& bn    = cm.observationalBN();
          auto        order = _topoObserved_(cm);
 
          std::unique_ptr< ASTtree< GUM_SCALAR > > prod;
 
          // Make a name lookup for quick topo prefix
          std::unordered_map< NodeId, Size > pos;
          for (Size i = 0; i < order.size(); ++i)
            pos[order[i]] = i;
 
          // build in topo order filtered to S
          std::vector< NodeId > ordering;
          ordering.reserve(S.size());
          for (auto v: order)
            if (S.contains(v)) ordering.push_back(v);
 
          for (Size j = 0; j < ordering.size(); ++j) {
            auto                                     v = ordering[j];
            std::unique_ptr< ASTtree< GUM_SCALAR > > term;
            if (!P) {
              // from BN: P(v | predecessors) using chain rule prefix
              Size               k = pos[v];
              Set< std::string > condNames;
              for (Size i = 0; i < k; ++i)
                condNames.insert(cm.nameFromId(order[i]));
              Set< std::string > lhs;
              lhs.insert(cm.nameFromId(v));
              if (condNames.empty()) term = std::make_unique< ASTjointProba< GUM_SCALAR > >(lhs);
              else term = std::make_unique< ASTposteriorProba< GUM_SCALAR > >(bn, lhs, condNames);
            } else {
              // from accumulated P: factorize Q[S] by full-order prefix marginals
              Size                       k = pos[v];
              std::vector< std::string > prefixNames;
              prefixNames.reserve(k + 1);
              for (Size i = 0; i <= k; ++i)
                prefixNames.push_back(cm.nameFromId(order[i]));
 
              // numerator = marginal of P on current prefix
              std::unique_ptr< ASTtree< GUM_SCALAR > > num(P->copy());
              std::vector< std::string >               sumNum;
              for (auto u: V) {
                const auto& un = cm.nameFromId(u);
                if (std::find(prefixNames.begin(), prefixNames.end(), un) == prefixNames.end()) {
                  sumNum.push_back(un);
                }
              }
              if (!sumNum.empty()) {
                num = std::make_unique< ASTsum< GUM_SCALAR > >(sumNum, std::move(num));
              }
 
              if (k == 0) {
                Set< std::string > lhs;
                lhs.insert(cm.nameFromId(v));
                term = std::make_unique< ASTjointProba< GUM_SCALAR > >(lhs);
 
              } else {
                // denominator = marginal of P on previous prefix
                std::unique_ptr< ASTtree< GUM_SCALAR > > den(P->copy());
                std::vector< std::string >               prevPrefix;
                prevPrefix.reserve(k);
                for (Size i = 0; i < k; ++i)
                  prevPrefix.push_back(cm.nameFromId(order[i]));
                std::vector< std::string > sumDen;
                for (auto u: V) {
                  const auto& un = cm.nameFromId(u);
                  if (std::find(prevPrefix.begin(), prevPrefix.end(), un) == prevPrefix.end()) {
                    sumDen.push_back(un);
                  }
                }
                if (!sumDen.empty()) {
                  den = std::make_unique< ASTsum< GUM_SCALAR > >(sumDen, std::move(den));
                }
                term = std::make_unique< ASTdiv< GUM_SCALAR > >(std::move(num), std::move(den));
              }
            }
 
            if (!prod) prod = std::move(term);
            else prod = std::make_unique< ASTmult< GUM_SCALAR > >(std::move(term), std::move(prod));
          }
 
          NodeSet Sy = S - Y;
          if (Sy.empty()) return prod;
          std::vector< std::string > tosum;
          tosum.reserve(Sy.size());
          for (auto v: Sy)
            tosum.push_back(cm.nameFromId(v));
          return std::make_unique< ASTsum< GUM_SCALAR > >(tosum, std::move(prod));
        }
      }
 
      // --- 7) Else: pick a c-component S' of G, build Q[S'] then recurse on G[S']
      {
        // choose the c-component of G that contains S (SP Step 7: S ⊆ S')
        NodeSet Spr;
        bool    found = false;
        for (const auto& comp: cdg) {
          if ((S - comp).empty()) {
            Spr   = comp;
            found = true;
            break;
          }
        }
        if (!found) {
          // Fallback should not happen; be conservative
          Spr = S;
        }
 
        const auto& bn    = cm.observationalBN();
        auto        order = _topoObserved_(cm);
 
        std::unique_ptr< ASTtree< GUM_SCALAR > > prod;
 
        std::unordered_map< NodeId, Size > pos;
        for (Size i = 0; i < order.size(); ++i)
          pos[order[i]] = i;
 
        std::vector< NodeId > ordering;
        ordering.reserve(Spr.size());
        for (auto v: order)
          if (Spr.contains(v)) ordering.push_back(v);
 
        for (Size j = 0; j < ordering.size(); ++j) {
          auto                                     v = ordering[j];
          std::unique_ptr< ASTtree< GUM_SCALAR > > term;
          if (!P) {
            Size               k = pos[v];
            Set< std::string > condNames;
            for (Size i = 0; i < k; ++i)
              condNames.insert(cm.nameFromId(order[i]));
            Set< std::string > lhs;
            lhs.insert(cm.nameFromId(v));
            if (condNames.empty()) term = std::make_unique< ASTjointProba< GUM_SCALAR > >(lhs);
            else term = std::make_unique< ASTposteriorProba< GUM_SCALAR > >(bn, lhs, condNames);
          } else {
            // from accumulated P: factorize Q[Spr] by full-order prefix marginals
            Size                       k = pos[v];
            std::vector< std::string > prefixNames;
            prefixNames.reserve(k + 1);
            for (Size i = 0; i <= k; ++i)
              prefixNames.push_back(cm.nameFromId(order[i]));
 
            // numerator = marginal of P on current prefix
            std::unique_ptr< ASTtree< GUM_SCALAR > > num(P->copy());
            std::vector< std::string >               sumNum;
            for (auto u: V) {
              const auto& un = cm.nameFromId(u);
              if (std::find(prefixNames.begin(), prefixNames.end(), un) == prefixNames.end()) {
                sumNum.push_back(un);
              }
            }
            if (!sumNum.empty()) {
              num = std::make_unique< ASTsum< GUM_SCALAR > >(sumNum, std::move(num));
            }
 
            if (k == 0) {
              Set< std::string > lhs;
              lhs.insert(cm.nameFromId(v));
              term = std::make_unique< ASTjointProba< GUM_SCALAR > >(lhs);
 
            } else {
              // denominator = marginal of P on previous prefix
              std::unique_ptr< ASTtree< GUM_SCALAR > > den(P->copy());
              std::vector< std::string >               prevPrefix;
              prevPrefix.reserve(k);
              for (Size i = 0; i < k; ++i)
                prevPrefix.push_back(cm.nameFromId(order[i]));
              std::vector< std::string > sumDen;
              for (auto u: V) {
                const auto& un = cm.nameFromId(u);
                if (std::find(prevPrefix.begin(), prevPrefix.end(), un) == prevPrefix.end()) {
                  sumDen.push_back(un);
                }
              }
              if (!sumDen.empty()) {
                den = std::make_unique< ASTsum< GUM_SCALAR > >(sumDen, std::move(den));
              }
              term = std::make_unique< ASTdiv< GUM_SCALAR > >(std::move(num), std::move(den));
            }
          }
 
          if (!prod) prod = std::move(term);
          else prod = std::make_unique< ASTmult< GUM_SCALAR > >(std::move(term), std::move(prod));
        }
 
        auto    sub  = cm.inducedCausalSubModel(cm, Spr);
        NodeSet Yspr = Y * Spr;   // <— important
        NodeSet Xspr = X * Spr;
 
        if (Yspr.empty()) {
          GUM_ERROR(OperationNotAllowed,
                    "Internal error in ID step 7: chosen C-component is disjoint from Y.");
        }
 
        return _ID_(sub, Yspr, Xspr, std::move(prod));
      }
    }
  }

References _ancestorsIn_(), _cDecomposition_(), _cDecompositionOn_(), _hedgeExceptionMsg(), _ID_(), _removeIncomingInto_(), _topoObserved_(), gum::CausalModel< GUM_SCALAR >::causalDAG(), gum::Set< Key >::contains(), gum::Set< Key >::empty(), GUM_ERROR, gum::CausalModel< GUM_SCALAR >::inducedCausalSubModel(), gum::Set< Key >::insert(), gum::CausalModel< GUM_SCALAR >::latentVariablesIds(), gum::CausalModel< GUM_SCALAR >::nameFromId(), gum::CausalModel< GUM_SCALAR >::observationalBN(), and gum::Set< Key >::size().

Referenced by _ID_(), and identifyingIntervention().

Here is the call graph for this function:

Here is the caller graph for this function:

_removeIncomingInto_()

template<GUM_Numeric GUM_SCALAR>

DAG gum::DoCalculus< GUM_SCALAR >::_removeIncomingInto_ ( const DAG & dag, const NodeSet & X )

staticprivate

DAG copy with all incoming arcs into X removed (G_{\overline X}).

Definition at line 399 of file doCalculus_tpl.h.

                                                                                     {
    DAG g = dag;                // copy
    for (auto x: X) {
      auto ps = g.parents(x);   // snapshot
      for (auto p: ps)
        g.eraseArc(Arc(p, x));
    }
    return g;
  }

References gum::ArcGraphPart::eraseArc(), and gum::ArcGraphPart::parents().

Referenced by _ID_().

Here is the call graph for this function:

Here is the caller graph for this function:

_removeInIntoDoing_outOfKnowing_()

template<GUM_Numeric GUM_SCALAR>

DAG gum::DoCalculus< GUM_SCALAR >::_removeInIntoDoing_outOfKnowing_ ( const DAG & dag, const NodeSet & doing, const NodeSet & knowing )

staticprivate

IDC helper: DAG copy with incoming into doing removed AND outgoing from knowing removed.

Definition at line 410 of file doCalculus_tpl.h.

                                                                                         {
    DAG g = dag;   // copy
    for (auto x: doing) {
      auto ps = g.parents(x);
      for (auto p: ps)
        g.eraseArc(Arc(p, x));
    }
    for (auto z: knowing) {
      auto ch = g.children(z);
      for (auto c: ch)
        g.eraseArc(Arc(z, c));
    }
    return g;
  }

References gum::ArcGraphPart::children(), gum::ArcGraphPart::eraseArc(), and gum::ArcGraphPart::parents().

Referenced by doCalculusWithObservation().

Here is the call graph for this function:

Here is the caller graph for this function:

_topoObserved_()

template<GUM_Numeric GUM_SCALAR>

std::vector< NodeId > gum::DoCalculus< GUM_SCALAR >::_topoObserved_ ( const CausalModel< GUM_SCALAR > & cm ) const

private

Topological order over observed nodes (ignoring latent parents).

Definition at line 345 of file doCalculus_tpl.h.

                                                                                        {
    const auto&   dag = cm.observationalBN().internalDag();
    const NodeSet V   = dag.nodes().asNodeSet();
 
    // indegree in the observed DAG
    std::unordered_map< NodeId, Size > indeg;
    for (auto v: V)
      indeg[v] = dag.parents(v).size();
 
    std::vector< NodeId > order;
    order.reserve(V.size());
 
    // Kahn on observed DAG only
    std::queue< NodeId > q;
    for (const auto& kv: indeg)
      if (kv.second == 0) q.push(kv.first);
 
    while (!q.empty()) {
      const NodeId u = q.front();
      q.pop();
      order.push_back(u);
 
      for (auto c: dag.children(u)) {
        if (indeg[c] > 0) {
          --indeg[c];
          if (indeg[c] == 0) q.push(c);
        }
      }
    }
    return order;
  }

References gum::CausalModel< GUM_SCALAR >::observationalBN(), and gum::Set< Key >::size().

Referenced by _ID_().

Here is the call graph for this function:

Here is the caller graph for this function:

doCalculus() [1/2]

template<GUM_Numeric GUM_SCALAR>

DoCalculus< GUM_SCALAR >::FormulaPtr gum::DoCalculus< GUM_SCALAR >::doCalculus	(	const NameList &	on,
		const NameList &	doing ) const

Definition at line 457 of file doCalculus_tpl.h.

                                                                                          {
    return identifyingIntervention(on, doing);
  }

References identifyingIntervention().

Here is the call graph for this function:

doCalculus() [2/2]

template<GUM_Numeric GUM_SCALAR>

DoCalculus< GUM_SCALAR >::FormulaPtr gum::DoCalculus< GUM_SCALAR >::doCalculus	(	const NodeSet &	on,
		const NodeSet &	doing ) const

Thin wrapper around ID: doCalculus(on, doing).

Definition at line 451 of file doCalculus_tpl.h.

                                                                                        {
    return identifyingIntervention(on, doing);
  }

References identifyingIntervention().

Here is the call graph for this function:

doCalculusWithObservation() [1/2]

template<GUM_Numeric GUM_SCALAR>

DoCalculus< GUM_SCALAR >::FormulaPtr gum::DoCalculus< GUM_SCALAR >::doCalculusWithObservation	(	const NameList &	on,
		const NameList &	doing,
		const NameList &	knowing ) const

Definition at line 509 of file doCalculus_tpl.h.

                                                                                         {
    NodeSet ON, DO, KN;
    for (const auto& s: on)
      ON.insert(_cm.idFromName(s));
    for (const auto& s: doing)
      DO.insert(_cm.idFromName(s));
    for (const auto& s: knowing)
      KN.insert(_cm.idFromName(s));
    return doCalculusWithObservation(ON, DO, KN);
  }

References _cm, doCalculusWithObservation(), and gum::Set< Key >::insert().

Here is the call graph for this function:

doCalculusWithObservation() [2/2]

template<GUM_Numeric GUM_SCALAR>

DoCalculus< GUM_SCALAR >::FormulaPtr gum::DoCalculus< GUM_SCALAR >::doCalculusWithObservation	(	const NodeSet &	on,
		const NodeSet &	doing,
		const NodeSet &	knowing ) const

IDC: identify P(on | do(doing), knowing).

Definition at line 463 of file doCalculus_tpl.h.

                                                                                        {
    // IDC reduction: try to promote any Z∈knowing to doing if Z ⟂ on | doing ∪ (knowing\{Z})
    // in the graph where incoming into doing and outgoing from knowing are removed.
    if (!knowing.empty()) {
      DAG gmod = _removeInIntoDoing_outOfKnowing_(_cm.causalDAG(), doing, knowing);
 
      for (auto z: knowing) {
        NodeSet Zi;
        Zi.insert(z);
        NodeSet Kminus = knowing - Zi;
        if (Separation::isDSeparated(gmod, Zi, on, doing + Kminus)) {
          // recurse with z moved to doing
          NodeSet doing2   = doing + Zi;
          NodeSet knowing2 = Kminus;
          return doCalculusWithObservation(on, doing2, knowing2);
        }
      }
    }
 
    // Fallback: ratio P(on ∪ knowing | do(doing)) / P(knowing | do(doing))
    NameList Yw, W;
    for (auto y: on)
      Yw.push_back(_cm.nameFromId(y));
    for (auto w: knowing)
      W.push_back(_cm.nameFromId(w));
 
    NameList Xn;
    for (auto x: doing)
      Xn.push_back(_cm.nameFromId(x));
 
    // numerator: ID on Y ∪ W ; denominator: ID on W (if W empty, denominator is 1)
    NodeSet onUkn = on + knowing;
 
    auto num = identifyingIntervention(onUkn, doing);
    if (knowing.empty()) {
      // P(Y|do(X)) when knowing is empty: just return numerator
      return num;
    }
    auto den = identifyingIntervention(knowing, doing);
    return std::make_unique< ASTdiv< GUM_SCALAR > >(std::move(num), std::move(den));
  }

References _cm, _removeInIntoDoing_outOfKnowing_(), doCalculusWithObservation(), gum::Set< Key >::empty(), identifyingIntervention(), gum::Set< Key >::insert(), and gum::Separation::isDSeparated().

Referenced by doCalculusWithObservation(), and doCalculusWithObservation().

Here is the call graph for this function:

Here is the caller graph for this function:

getBackDoorTree() [1/2]

template<GUM_Numeric GUM_SCALAR>

DoCalculus< GUM_SCALAR >::FormulaPtr gum::DoCalculus< GUM_SCALAR >::getBackDoorTree	(	NodeId	cause,
		NodeId	effect,
		const NodeSet &	zset ) const

Definition at line 92 of file doCalculus_tpl.h.

                                                                           {
    // Preconditions: cause/effect must be observed (non-latent), Z must not contain latents.
    const NodeSet lat = _cm.latentVariablesIds();
    if (lat.contains(cause) || lat.contains(effect)) {
      GUM_ERROR(InvalidArgument,
                "getBackDoorTree: 'cause' and 'effect' must be observed (non-latent).");
    }
    for (auto z: zset) {
      if (lat.contains(z)) {
        GUM_ERROR(InvalidArgument, "getBackDoorTree: zset contains a latent variable.");
      }
    }
 
    // ids -> names
    const auto&       dag   = _cm.causalDAG();
    auto              mapO  = _cm.id2name(/*includeLatentVariables=*/false);
    const std::string xName = _cm.nameFromId(cause);
    const std::string yName = _cm.nameFromId(effect);
 
    Set< std::string >         zNames;
    std::vector< std::string > zOrder;
    zOrder.reserve(zset.size());
    for (auto z: zset) {
      const std::string zn = _cm.nameFromId(z);
      zNames.insert(zn);
      zOrder.push_back(zn);
    }
    std::sort(zOrder.begin(), zOrder.end());
 
    // P(y | x, z)
    Set< std::string > lhsY;
    lhsY.insert(yName);
    Set< std::string > knw;
    knw.insert(xName);
    for (const auto& zn: zNames)
      knw.insert(zn);
    auto Pyxz = std::make_unique< ASTposteriorProba< GUM_SCALAR > >(dag, mapO, lhsY, knw);
 
    if (zNames.empty()) {
      // returns P(y | x)
      return Pyxz;
    }
 
    // P(z)
    auto Pz = std::make_unique< ASTjointProba< GUM_SCALAR > >(zNames);
 
    // P(y|x,z) * P(z), then sum over Z
    std::vector< std::unique_ptr< ASTtree< GUM_SCALAR > > > terms;
    terms.emplace_back(std::move(Pyxz));
    terms.emplace_back(std::move(Pz));
    auto prod = productOfTrees< GUM_SCALAR >(std::move(terms));
 
    return std::make_unique< ASTsum< GUM_SCALAR > >(zOrder, std::move(prod));
  }

References _cm, gum::Set< Key >::contains(), gum::Set< Key >::empty(), GUM_ERROR, gum::Set< Key >::insert(), gum::productOfTrees(), and gum::Set< Key >::size().

Referenced by gum::CausalImpact< GUM_ELEMENT >::_disjoint_(), and getBackDoorTree().

Here is the call graph for this function:

Here is the caller graph for this function:

getBackDoorTree() [2/2]

template<GUM_Numeric GUM_SCALAR>

DoCalculus< GUM_SCALAR >::FormulaPtr gum::DoCalculus< GUM_SCALAR >::getBackDoorTree	(	std::string_view	causeName,
		std::string_view	effectName,
		const NameList &	zNames ) const

Definition at line 151 of file doCalculus_tpl.h.

                                                                               {
    const NodeId x = _cm.idFromName(causeName);
    const NodeId y = _cm.idFromName(effectName);
 
    NodeSet Z;
    for (const auto& zn: zNames)
      Z.insert(_cm.idFromName(zn));
 
    return getBackDoorTree(x, y, Z);
  }

References _cm, getBackDoorTree(), and gum::Set< Key >::insert().

Here is the call graph for this function:

getFrontDoorTree() [1/2]

template<GUM_Numeric GUM_SCALAR>

DoCalculus< GUM_SCALAR >::FormulaPtr gum::DoCalculus< GUM_SCALAR >::getFrontDoorTree	(	NodeId	cause,
		NodeId	effect,
		const NodeSet &	zset ) const

Definition at line 166 of file doCalculus_tpl.h.

                                                                            {
    // --- Preconditions ---
    const NodeSet lat = _cm.latentVariablesIds();
    if (lat.contains(cause) || lat.contains(effect)) {
      GUM_ERROR(InvalidArgument,
                "getFrontDoorTree: 'cause' and 'effect' must be observed (non-latent).");
    }
    if (zset.empty()) {
      GUM_ERROR(InvalidArgument, "getFrontDoorTree: zset must be non-empty for frontdoor.");
    }
    if (zset.contains(cause) || zset.contains(effect)) {
      GUM_ERROR(InvalidArgument, "getFrontDoorTree: zset must be disjoint from {cause,effect}.");
    }
    for (auto z: zset) {
      if (lat.contains(z)) {
        GUM_ERROR(InvalidArgument, "getFrontDoorTree: zset contains a latent variable.");
      }
    }
 
    // --- ids → names ---
    const std::string xName = _cm.nameFromId(cause);
    const std::string yName = _cm.nameFromId(effect);
 
    Set< std::string >         zNames;
    std::vector< std::string > zOrder;
    zOrder.reserve(zset.size());
    for (auto z: zset) {
      const auto zn = _cm.nameFromId(z);
      zNames.insert(zn);
      zOrder.push_back(zn);
    }
    std::sort(zOrder.begin(), zOrder.end());   // deterministic
 
    // --- Build P(Z | X) using DAG ctor (observed-only mapping inferred from model) ---
    const auto& dag  = _cm.causalDAG();
    auto        mapO = _cm.id2name(/*includeLatentVariables=*/false);
 
    Set< std::string > condX;
    condX.insert(xName);
    auto Pz_given_x = std::make_unique< ASTposteriorProba< GUM_SCALAR > >(dag, mapO, zNames, condX);
 
    // --- Build sum_x P(Y | X, Z) * P(X) ---
    Set< std::string > ySet;
    ySet.insert(yName);
 
    Set< std::string > condXZ = zNames;   // copy
    condXZ.insert(xName);
    auto Py_given_xz = std::make_unique< ASTposteriorProba< GUM_SCALAR > >(dag, mapO, ySet, condXZ);
 
    Set< std::string > xSet;
    xSet.insert(xName);
    auto Px = std::make_unique< ASTjointProba< GUM_SCALAR > >(xSet);
 
    auto inner_prod
        = std::make_unique< ASTmult< GUM_SCALAR > >(std::move(Py_given_xz), std::move(Px));
    auto inner_sum = std::make_unique< ASTsum< GUM_SCALAR > >(std::vector< std::string >{xName},
                                                              std::move(inner_prod));
 
    // --- P(Z|X) * (sum_x ...) then sum over Z ---
    auto outer_prod
        = std::make_unique< ASTmult< GUM_SCALAR > >(std::move(Pz_given_x), std::move(inner_sum));
    return std::make_unique< ASTsum< GUM_SCALAR > >(zOrder, std::move(outer_prod));
  }

References _cm, gum::Set< Key >::contains(), gum::Set< Key >::empty(), GUM_ERROR, gum::Set< Key >::insert(), and gum::Set< Key >::size().

Referenced by getFrontDoorTree().

Here is the call graph for this function:

Here is the caller graph for this function:

getFrontDoorTree() [2/2]

template<GUM_Numeric GUM_SCALAR>

DoCalculus< GUM_SCALAR >::FormulaPtr gum::DoCalculus< GUM_SCALAR >::getFrontDoorTree	(	std::string_view	causeName,
		std::string_view	effectName,
		const NameList &	zNames ) const

Definition at line 234 of file doCalculus_tpl.h.

                                                                                {
    const NodeId x = _cm.idFromName(causeName);
    const NodeId y = _cm.idFromName(effectName);
 
    NodeSet Z;
    for (const auto& zn: zNames)
      Z.insert(_cm.idFromName(zn));
 
    return getFrontDoorTree(x, y, Z);
  }

References _cm, getFrontDoorTree(), and gum::Set< Key >::insert().

Here is the call graph for this function:

identifyingIntervention() [1/2]

template<GUM_Numeric GUM_SCALAR>

DoCalculus< GUM_SCALAR >::FormulaPtr gum::DoCalculus< GUM_SCALAR >::identifyingIntervention	(	const NameList &	Y,
		const NameList &	X ) const

ID: identify P(Y | do(X)) (name-based).

Definition at line 439 of file doCalculus_tpl.h.

                                                                                 {
    NodeSet YY, XX;
    for (const auto& s: Y)
      YY.insert(_cm.idFromName(s));
    for (const auto& s: X)
      XX.insert(_cm.idFromName(s));
    return identifyingIntervention(YY, XX);
  }

References _cm, identifyingIntervention(), and gum::Set< Key >::insert().

Here is the call graph for this function:

identifyingIntervention() [2/2]

template<GUM_Numeric GUM_SCALAR>

DoCalculus< GUM_SCALAR >::FormulaPtr gum::DoCalculus< GUM_SCALAR >::identifyingIntervention	(	const NodeSet &	Y,
		const NodeSet &	X ) const

ID: identify P(Y | do(X)) (NodeId-based).

Definition at line 433 of file doCalculus_tpl.h.

                                                                                                {
    return _ID_(_cm, Y, X, nullptr);
  }

References _cm, and _ID_().

Referenced by doCalculus(), doCalculus(), doCalculusWithObservation(), and identifyingIntervention().

Here is the call graph for this function:

Here is the caller graph for this function:

model()

template<GUM_Numeric GUM_SCALAR>

const CausalModel< GUM_SCALAR > & gum::DoCalculus< GUM_SCALAR >::model ( ) const

noexcept

Definition at line 82 of file doCalculus_tpl.h.

                                                                                  {
    return _cm;
  }

References _cm.

Member Data Documentation

_cm

template<GUM_Numeric GUM_SCALAR>

const CausalModel< GUM_SCALAR >& gum::DoCalculus< GUM_SCALAR >::_cm

private

Definition at line 127 of file doCalculus.h.

Referenced by DoCalculus(), doCalculusWithObservation(), doCalculusWithObservation(), getBackDoorTree(), getBackDoorTree(), getFrontDoorTree(), getFrontDoorTree(), identifyingIntervention(), identifyingIntervention(), and model().

---

The documentation for this class was generated from the following files:

• agrum/CM/tools/doCalculus.h
• agrum/CM/tools/doCalculus_tpl.h