Builds a CausalFormula for a query (d-sep -> backdoor -> frontdoor -> (optional) do-calculus). More...

#include <causalImpact.h>

Collaboration diagram for gum::CausalImpact< GUM_SCALAR >:

Public Member Functions
Tensor< GUM_SCALAR >	eval () const
	Evaluates the formula's AST to compute the resulting probability distribution.
std::string	toString () const
	Generates a string representation of the formula's AST.
std::string	toLatex (std::string_view doOperatorPrefix="do(", std::string_view doOperatorSuffix=")") const
	Generates a full LaTeX equation: Query = Formula.
std::string	latexQuery (std::string_view doOperatorPrefix="do(", std::string_view doOperatorSuffix=")") const
	Generates a LaTeX representation of the original query, e.g., P(Y \| do(X), Z).
bool	isIdentified () const noexcept
	Whether the causal effect has been identified.
const ASTtree< GUM_SCALAR > &	root () const
	Access the root AST node of the identified formula.
const CausalFormula< GUM_SCALAR > &	getResult () const
	Access the underlying CausalFormula result.
const CausalModel< GUM_SCALAR > &	cm () const
const NodeSet &	on () const
const NodeSet &	doing () const
const NodeSet &	knowing () const
const std::string &	explanation () const
std::vector< std::string >	onNames () const
	Convenience: return names corresponding to stored node ids (sorted).
std::vector< std::string >	doingNames () const
std::vector< std::string >	knowingNames () const
	CausalImpact (const CausalModel< GUM_SCALAR > &cm, const Set< std::string > &on, const Set< std::string > &doing, const Set< std::string > &knowing=Set< std::string >(), bool directDoCalculus=false)
	Constructs a CausalImpact object using variable names.
	CausalImpact (const CausalModel< GUM_SCALAR > &cm, const NodeSet &on, const NodeSet &doing, const NodeSet &knowing=NodeSet(), bool directDoCalculus=false)
	Constructs a CausalImpact object using node IDs.
	CausalImpact (const CausalImpact &)=default
	Copy/move constructors — defaulted; require CausalFormula to be copy/move-constructible.
	CausalImpact (CausalImpact &&)=default

Static Private Member Functions
static Set< std::string >	_idsToNames_ (const CausalModel< GUM_SCALAR > &cm, const NodeSet &ids)
static NodeSet	_namesToIds_ (const CausalModel< GUM_SCALAR > &cm, const Set< std::string > &names)
static bool	_disjoint_ (const Set< std::string > &a, const Set< std::string > &b, const Set< std::string > &c)
static CausalFormula< GUM_SCALAR >	_buildFromNames_ (const CausalModel< GUM_SCALAR > &cm, const Set< std::string > &on, const Set< std::string > &doing, const Set< std::string > &knowing, bool directDoCalculus)
static CausalFormula< GUM_SCALAR >	_buildFromIds_ (const CausalModel< GUM_SCALAR > &cm, const NodeSet &on, const NodeSet &doing, const NodeSet &knowing, bool directDoCalculus)

Private Attributes
bool	_directDoCalculus_ = false
	If true, skip backdoor/frontdoor and use do-calculus directly.
CausalFormula< GUM_SCALAR >	_resultFormula_
	Identified symbolic formula. If not identifiable, its AST may be nullptr and its explanation string (6th ctor arg) will say so.

Detailed Description

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

Builds a CausalFormula for a query (d-sep -> backdoor -> frontdoor -> (optional) do-calculus).

With your CausalFormula’s API (no default ctor, non-assignable), we compute the AST first and initialize result in the initializer list (single shot).

Definition at line 82 of file causalImpact.h.

Constructor & Destructor Documentation

◆ CausalImpact() [1/4]

template<GUM_Numeric GUM_SCALAR>

gum::CausalImpact< GUM_SCALAR >::CausalImpact	(	const CausalModel< GUM_SCALAR > &	cm,
		const Set< std::string > &	on,
		const Set< std::string > &	doing,
		const Set< std::string > &	knowing = Set< std::string >(),
		bool	directDoCalculus = false )

Constructs a CausalImpact object using variable names.

Parameters

cm	The causal model to use for identification.
on	The set of variable names representing the outcome(s) of interest.
doing	The set of variable names representing the intervention(s) (do-variables).
knowing	The set of variable names representing observed covariates (optional).
directDoCalculus	If true, bypasses Backdoor and Frontdoor and directly uses the ID algorithm for identification.

Warning: Setting directDoCalculus = true is NOT advisable. This will bypass the Backdoor and Frontdoor criteria and use the ID algorithm directly.

Definition at line 151 of file causalImpact_tpl.h.

                                                                                              :
      _directDoCalculus_{directDoCalculus},
      _resultFormula_(_buildFromNames_(cm, on, doing, knowing, directDoCalculus)) {}

References _buildFromNames_(), _directDoCalculus_, _resultFormula_, cm(), doing(), knowing(), and on().

Referenced by CausalImpact(), and CausalImpact().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ CausalImpact() [2/4]

template<GUM_Numeric GUM_SCALAR>

gum::CausalImpact< GUM_SCALAR >::CausalImpact	(	const CausalModel< GUM_SCALAR > &	cm,
		const NodeSet &	on,
		const NodeSet &	doing,
		const NodeSet &	knowing = NodeSet(),
		bool	directDoCalculus = false )

Constructs a CausalImpact object using node IDs.

Parameters

cm	The causal model to use for identification.
on	The set of node IDs representing the outcome(s) of interest.
doing	The set of node IDs representing the intervention(s) (do-variables).
knowing	The set of node IDs representing observed covariates (optional).
directDoCalculus	If true, bypasses Backdoor and Frontdoor and directly uses the ID algorithm for identification.

Warning: Setting directDoCalculus = true is NOT advisable. This will bypass the Backdoor and Frontdoor criteria and use the ID algorithm directly.

Definition at line 160 of file causalImpact_tpl.h.

                                                                                              :
      _directDoCalculus_{directDoCalculus},
      _resultFormula_(_buildFromIds_(cm, on, doing, knowing, directDoCalculus)) {}

References cm().

Here is the call graph for this function:

◆ CausalImpact() [3/4]

template<GUM_Numeric GUM_SCALAR>

gum::CausalImpact< GUM_SCALAR >::CausalImpact ( const CausalImpact< GUM_SCALAR > & )

default

Copy/move constructors — defaulted; require CausalFormula to be copy/move-constructible.

References CausalImpact().

Here is the call graph for this function:

◆ CausalImpact() [4/4]

template<GUM_Numeric GUM_SCALAR>

gum::CausalImpact< GUM_SCALAR >::CausalImpact ( CausalImpact< GUM_SCALAR > && )

default

References CausalImpact().

Here is the call graph for this function:

Member Function Documentation

◆ _buildFromIds_()

template<GUM_Numeric GUM_SCALAR>

CausalFormula< GUM_SCALAR > gum::CausalImpact< GUM_SCALAR >::_buildFromIds_	(	const CausalModel< GUM_SCALAR > &	cm,
		const NodeSet &	on,
		const NodeSet &	doing,
		const NodeSet &	knowing,
		bool	directDoCalculus )

staticprivate

Definition at line 286 of file causalImpact_tpl.h.

                                                                        {
    // Reuse the names path to share logic/explanations
    const auto onN      = _idsToNames_(cm, on);
    const auto doingN   = _idsToNames_(cm, doing);
    const auto knowingN = _idsToNames_(cm, knowing);
    return _buildFromNames_(cm, onN, doingN, knowingN, directDoCalculus);
  }

References _buildFromNames_(), _idsToNames_(), cm(), doing(), knowing(), and on().

Here is the call graph for this function:

◆ _buildFromNames_()

template<GUM_Numeric GUM_SCALAR>

CausalFormula< GUM_SCALAR > gum::CausalImpact< GUM_SCALAR >::_buildFromNames_	(	const CausalModel< GUM_SCALAR > &	cm,
		const Set< std::string > &	on,
		const Set< std::string > &	doing,
		const Set< std::string > &	knowing,
		bool	directDoCalculus )

staticprivate

Definition at line 172 of file causalImpact_tpl.h.

                                                                          {
    if (!_disjoint_(on, doing, knowing)) {
      GUM_ERROR(InvalidArgument,
                "The 3 parts of the query (on, doing, knowing) must be pairwise disjoint.");
    }
 
    const NodeSet i_on      = _namesToIds_(cm, on);
    const NodeSet i_doing   = _namesToIds_(cm, doing);
    const NodeSet i_knowing = _namesToIds_(cm, knowing);
 
    NodeSet cond = i_knowing;
 
    if (!directDoCalculus) {
      // single-X, single-Y, empty-K: try BACKDOOR then FRONTDOOR
      if (doing.size() == 1 && on.size() == 1 && knowing.empty()) {
        const auto& Xname = *doing.begin();
        const auto& Yname = *on.begin();
        const auto  Xid   = cm.idFromName(Xname);
        const auto  Yid   = cm.idFromName(Yname);
 
        // --- Backdoor (Z may be empty; validate in G_{\underline X}) ---
        {
          auto optZ = cm.backDoor(Xid, Yid);   // nullopt = no set found
          if (optZ.has_value()
              && Separation::isBackdoorSeparated(cm.causalDAG(),
                                                 NodeSet{Xid},
                                                 NodeSet{Yid},
                                                 *optZ)) {
            NodeSet                  Z = *optZ;
            DoCalculus< GUM_SCALAR > dc(cm);
            auto                     ast = dc.getBackDoorTree(Xid, Yid, Z);
            return CausalFormula< GUM_SCALAR >(cm,
                                               std::move(ast),
                                               on,
                                               doing,
                                               knowing,
                                               std::string("backdoor ")
                                                   + _formatNodeSetNames_(cm, Z) + " found.");
          }
        }
 
        // --- Frontdoor (no trivial FD; require non-empty mediator set) ---
        {
          auto optZ = cm.frontDoor(Xid, Yid);
          if (optZ.has_value() && !optZ->empty()) {
            NodeSet                  Z = *optZ;
            DoCalculus< GUM_SCALAR > dc(cm);
            auto                     ast = dc.getFrontDoorTree(Xid, Yid, Z);
            return CausalFormula< GUM_SCALAR >(cm,
                                               std::move(ast),
                                               on,
                                               doing,
                                               knowing,
                                               std::string("frontdoor ")
                                                   + _formatNodeSetNames_(cm, Z) + " found.");
          }
        }
      }
 
      // fallback: no causal effect in G_bar(X)
      const DAG gXbar = _removeIncomingIntoLocal_(cm.causalDAG(), i_doing);
      if (Separation::isDSeparated(gXbar, i_doing, i_on, cond)) {
        // P(Y | K) in the observational BN
        auto ast = std::make_unique< ASTposteriorProba< GUM_SCALAR > >(cm.observationalBN(),
                                                                       on,
                                                                       knowing);
        return CausalFormula< GUM_SCALAR >(cm,
                                           std::move(ast),
                                           on,
                                           doing,
                                           knowing,
                                           _dsepExplanation_(on, doing, knowing));
      }
    }
 
    // general do-calculus (when available in your DoCalculus)
    try {
      DoCalculus< GUM_SCALAR >                 dc(cm);
      std::unique_ptr< ASTtree< GUM_SCALAR > > ast
          = knowing.empty()
              ? dc.doCalculus(i_on, i_doing)                              // NodeSet overload
              : dc.doCalculusWithObservation(i_on, i_doing, i_knowing);   // NodeSet overload
 
      return CausalFormula< GUM_SCALAR >(cm,
                                         std::move(ast),
                                         on,
                                         doing,
                                         knowing,
                                         "Identified via do-calculus (ID/IDC).");
    } catch (const NotImplementedYet&) {
      // Not identifiable with current methods: return a “null-AST” formula with a message.
      return CausalFormula< GUM_SCALAR >(
          cm,
          std::unique_ptr< ASTtree< GUM_SCALAR > >{},
          on,
          doing,
          knowing,
          "Effect not identifiable with available methods (do-calculus not yet implemented).");
    } catch (const HedgeException& e) {
      return CausalFormula< GUM_SCALAR >(cm,
                                         std::unique_ptr< ASTtree< GUM_SCALAR > >{},
                                         on,
                                         doing,
                                         knowing,
                                         std::string("Effect not identifiable: ") + e.what());
    }
  }

References _disjoint_(), _namesToIds_(), cm(), doing(), GUM_ERROR, knowing(), and on().

Referenced by CausalImpact(), and _buildFromIds_().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ _disjoint_()

template<GUM_Numeric GUM_SCALAR>

bool gum::CausalImpact< GUM_SCALAR >::_disjoint_	(	const Set< std::string > &	a,
		const Set< std::string > &	b,
		const Set< std::string > &	c )

staticprivate

Definition at line 132 of file causalImpact_tpl.h.

                                                                         {
    if (std::any_of(a.begin(), a.end(), [&b, &c](const auto& x) {
          return b.contains(x) || c.contains(x);
        })) {
      return false;
    }
    if (std::any_of(b.begin(), b.end(), [&c](const auto& x) { return c.contains(x); })) {
      return false;
    }
 
    return true;
  }

Referenced by _buildFromNames_().

Here is the caller graph for this function:

◆ _idsToNames_()

template<GUM_Numeric GUM_SCALAR>

gum::Set< std::string > gum::CausalImpact< GUM_SCALAR >::_idsToNames_	(	const CausalModel< GUM_SCALAR > &	cm,
		const NodeSet &	ids )

staticprivate

Definition at line 113 of file causalImpact_tpl.h.

                                                                                     {
    Set< std::string > out;
    for (auto id: ids)
      out.insert(cm.nameFromId(id));
    return out;
  }

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

Referenced by _buildFromIds_().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ _namesToIds_()

template<GUM_Numeric GUM_SCALAR>

gum::NodeSet gum::CausalImpact< GUM_SCALAR >::_namesToIds_	(	const CausalModel< GUM_SCALAR > &	cm,
		const Set< std::string > &	names )

staticprivate

Definition at line 123 of file causalImpact_tpl.h.

                                                                                     {
    NodeSet out;
    for (const auto& n: names)
      out.insert(cm.idFromName(n));
    return out;
  }

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

Referenced by _buildFromNames_().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ cm()

template<GUM_Numeric GUM_SCALAR>

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

Definition at line 385 of file causalImpact_tpl.h.

                                                                        {
    return _resultFormula_.cm();
  }

References _resultFormula_.

Referenced by CausalImpact(), CausalImpact(), _buildFromIds_(), _buildFromNames_(), _idsToNames_(), and _namesToIds_().

Here is the caller graph for this function:

◆ doing()

template<GUM_Numeric GUM_SCALAR>

const NodeSet & gum::CausalImpact< GUM_SCALAR >::doing ( ) const

Definition at line 395 of file causalImpact_tpl.h.

                                                         {
    return _resultFormula_.doing();
  }

References _resultFormula_.

Referenced by CausalImpact(), _buildFromIds_(), and _buildFromNames_().

Here is the caller graph for this function:

◆ doingNames()

template<GUM_Numeric GUM_SCALAR>

std::vector< std::string > gum::CausalImpact< GUM_SCALAR >::doingNames ( ) const

Definition at line 415 of file causalImpact_tpl.h.

                                                                      {
    return _resultFormula_.doingNames();
  }

References _resultFormula_.

◆ eval()

template<GUM_Numeric GUM_SCALAR>

Tensor< GUM_SCALAR > gum::CausalImpact< GUM_SCALAR >::eval ( ) const

Evaluates the formula's AST to compute the resulting probability distribution.

Definition at line 348 of file causalImpact_tpl.h.

                                                              {
    return _resultFormula_.eval();
  }

References _resultFormula_.

Referenced by gum::causalImpact().

Here is the caller graph for this function:

◆ explanation()

template<GUM_Numeric GUM_SCALAR>

const std::string & gum::CausalImpact< GUM_SCALAR >::explanation ( ) const

Definition at line 405 of file causalImpact_tpl.h.

                                                                 {
    return _resultFormula_.explanation();
  }

References _resultFormula_.

Referenced by gum::causalImpact().

Here is the caller graph for this function:

◆ getResult()

template<GUM_Numeric GUM_SCALAR>

const CausalFormula< GUM_SCALAR > & gum::CausalImpact< GUM_SCALAR >::getResult ( ) const

Access the underlying CausalFormula result.

Returns: const reference to the identified CausalFormula.

Definition at line 380 of file causalImpact_tpl.h.

                                                                                 {
    return _resultFormula_;
  }

References _resultFormula_.

◆ isIdentified()

template<GUM_Numeric GUM_SCALAR>

bool gum::CausalImpact< GUM_SCALAR >::isIdentified ( ) const

nodiscardnoexcept

Whether the causal effect has been identified.

Returns true iff this formula has a valid AST (i.e., identification succeeded and evaluation is possible). When this returns false, calling root() or eval() will throw.

Returns: true if an identification AST exists, false otherwise.

Definition at line 370 of file causalImpact_tpl.h.

                                                               {
    return _resultFormula_.isIdentified();
  }

References _resultFormula_.

Referenced by gum::causalImpact().

Here is the caller graph for this function:

◆ knowing()

template<GUM_Numeric GUM_SCALAR>

const NodeSet & gum::CausalImpact< GUM_SCALAR >::knowing ( ) const

Definition at line 400 of file causalImpact_tpl.h.

                                                           {
    return _resultFormula_.knowing();
  }

References _resultFormula_.

Referenced by CausalImpact(), _buildFromIds_(), and _buildFromNames_().

Here is the caller graph for this function:

◆ knowingNames()

template<GUM_Numeric GUM_SCALAR>

std::vector< std::string > gum::CausalImpact< GUM_SCALAR >::knowingNames ( ) const

Definition at line 420 of file causalImpact_tpl.h.

                                                                        {
    return _resultFormula_.knowingNames();
  }

References _resultFormula_.

◆ latexQuery()

template<GUM_Numeric GUM_SCALAR>

std::string gum::CausalImpact< GUM_SCALAR >::latexQuery	(	std::string_view	doOperatorPrefix = "do(",
		std::string_view	doOperatorSuffix = ")" ) const

Generates a LaTeX representation of the original query, e.g., P(Y | do(X), Z).

Note: This version does not yet support specific variable values.

Definition at line 364 of file causalImpact_tpl.h.

                                                                                            {
    return _resultFormula_.latexQuery(doOperatorPrefix, doOperatorSuffix);
  }

References _resultFormula_.

◆ on()

template<GUM_Numeric GUM_SCALAR>

const NodeSet & gum::CausalImpact< GUM_SCALAR >::on ( ) const

Definition at line 390 of file causalImpact_tpl.h.

                                                      {
    return _resultFormula_.on();
  }

References _resultFormula_.

Referenced by CausalImpact(), _buildFromIds_(), and _buildFromNames_().

Here is the caller graph for this function:

◆ onNames()

template<GUM_Numeric GUM_SCALAR>

std::vector< std::string > gum::CausalImpact< GUM_SCALAR >::onNames ( ) const

Convenience: return names corresponding to stored node ids (sorted).

Definition at line 410 of file causalImpact_tpl.h.

                                                                   {
    return _resultFormula_.onNames();
  }

References _resultFormula_.

◆ root()

template<GUM_Numeric GUM_SCALAR>

const ASTtree< GUM_SCALAR > & gum::CausalImpact< GUM_SCALAR >::root ( ) const

Access the root AST node of the identified formula.

Use this to inspect the symbolic structure of the identified effect.

Warning: This raises an exception if the effect is not identified.

Exceptions

gum::OperationNotAllowed if no AST is available (i.e., the effect is not identifiable with the current methods).

Returns: const ASTtree<GUM_SCALAR>& reference to the AST root.

Definition at line 375 of file causalImpact_tpl.h.

                                                                      {
    return _resultFormula_.root();
  }

References _resultFormula_.

◆ toLatex()

template<GUM_Numeric GUM_SCALAR>

std::string gum::CausalImpact< GUM_SCALAR >::toLatex	(	std::string_view	doOperatorPrefix = "do(",
		std::string_view	doOperatorSuffix = ")" ) const

Generates a full LaTeX equation: Query = Formula.

Definition at line 358 of file causalImpact_tpl.h.

                                                                                         {
    return _resultFormula_.toLatex(doOperatorPrefix, doOperatorSuffix);
  }

References _resultFormula_.

◆ toString()

template<GUM_Numeric GUM_SCALAR>

std::string gum::CausalImpact< GUM_SCALAR >::toString ( ) const

Generates a string representation of the formula's AST.

Definition at line 353 of file causalImpact_tpl.h.

                                                       {
    return _resultFormula_.toString();
  }

References _resultFormula_.

Member Data Documentation

◆ _directDoCalculus_

template<GUM_Numeric GUM_SCALAR>

bool gum::CausalImpact< GUM_SCALAR >::_directDoCalculus_ = false

private

If true, skip backdoor/frontdoor and use do-calculus directly.

Definition at line 191 of file causalImpact.h.

Referenced by CausalImpact().

◆ _resultFormula_

template<GUM_Numeric GUM_SCALAR>

CausalFormula< GUM_SCALAR > gum::CausalImpact< GUM_SCALAR >::_resultFormula_

private

Identified symbolic formula. If not identifiable, its AST may be nullptr and its explanation string (6th ctor arg) will say so.

Definition at line 195 of file causalImpact.h.

Referenced by CausalImpact(), cm(), doing(), doingNames(), eval(), explanation(), getResult(), isIdentified(), knowing(), knowingNames(), latexQuery(), on(), onNames(), root(), toLatex(), and toString().

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

agrum/CM/causalImpact.h
agrum/CM/causalImpact_tpl.h

Public Member Functions

Static Private Member Functions

Private Attributes

Detailed Description

Constructor & Destructor Documentation

◆ CausalImpact() [1/4]

◆ CausalImpact() [2/4]

◆ CausalImpact() [3/4]

◆ CausalImpact() [4/4]

Member Function Documentation

◆ _buildFromIds_()

◆ _buildFromNames_()

◆ _disjoint_()

◆ _idsToNames_()

◆ _namesToIds_()

◆ cm()

◆ doing()

◆ doingNames()

◆ eval()

◆ explanation()

◆ getResult()

◆ isIdentified()

◆ knowing()

◆ knowingNames()

◆ latexQuery()

◆ on()

◆ onNames()

◆ root()

◆ toLatex()

◆ toString()

Member Data Documentation

◆ _directDoCalculus_

◆ _resultFormula_