A container for an identified causal query. More...

#include <causalFormula.h>

Collaboration diagram for gum::CausalFormula< GUM_SCALAR >:

Public Member Functions
	CausalFormula (const CausalModel< GUM_SCALAR > &cm, std::unique_ptr< ASTtree< GUM_SCALAR > > root, const Set< std::string > &on, const Set< std::string > &doing, const Set< std::string > &knowing=Set< std::string >{}, std::string_view explanation="")
	Constructs a CausalFormula object (variables given by names).
	CausalFormula (const CausalModel< GUM_SCALAR > &cm, std::unique_ptr< ASTtree< GUM_SCALAR > > root, const NodeSet &on, const NodeSet &doing, const NodeSet &knowing=NodeSet{}, std::string_view explanation="")
	Constructs a CausalFormula object (variables given by node ids).
	CausalFormula (const CausalFormula &other)
	Copy constructor — performs a deep copy of the AST.
	CausalFormula (CausalFormula &&)=default
	Move constructor — defaulted (suppressed by the user-defined copy constructor above).
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).
std::unique_ptr< CausalFormula< GUM_SCALAR > >	copy () const
	Creates a deep copy of the CausalFormula (including its AST).
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 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

Private Member Functions
void	_ensureVariablesExist () const
	Verifies that all variables (_on, _knowing, _doing) exist in the BN.
void	_ensureNoVariablesOverlap () const
	Verifies that all variables (_on, _knowing, _doing) have no intersection.

Static Private Member Functions
static NodeSet	_toNodeSetFromNames_ (const CausalModel< GUM_SCALAR > &cm, const Set< std::string > &names)
	Convert a set of names to a set of node ids (validates existence).

Private Attributes
const CausalModel< GUM_SCALAR > &	_cm
std::unique_ptr< ASTtree< GUM_SCALAR > >	_root
const NodeSet	_on
const NodeSet	_doing
const NodeSet	_knowing
const std::string	_explanation

Detailed Description

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

A container for an identified causal query.

This class binds an identified formula (as an ASTtree) to the context of the query that produced it: the CausalModel and the sets of variables for on, doing, and knowing.

It provides methods to:

Evaluate the formula to get a numeric Tensor (eval).
Display the formula as a string (toString) or LaTeX (toLatex).
Display the original query that generated the formula (latexQuery).

Template Parameters

GUM_SCALAR The numeric type for tensor computations.

Definition at line 74 of file causalFormula.h.

Constructor & Destructor Documentation

◆ CausalFormula() [1/4]

template<GUM_Numeric GUM_SCALAR>

gum::CausalFormula< GUM_SCALAR >::CausalFormula	(	const CausalModel< GUM_SCALAR > &	cm,
		std::unique_ptr< ASTtree< GUM_SCALAR > >	root,
		const Set< std::string > &	on,
		const Set< std::string > &	doing,
		const Set< std::string > &	knowing = Set< std::string >{},
		std::string_view	explanation = "" )

Constructs a CausalFormula object (variables given by names).

Parameters

cm	The causal model against which the formula was identified.
root	The identified formula as an Abstract Syntax Tree (ownership moved).
on	The set of outcome variable names (the "Y" in P(Y\|...)).
doing	The set of intervention variable names (the "do(X)")).
knowing	The set of conditioning variable names (optional evidence).
explanation	A human-readable explanation of the identification method used (optional).

Definition at line 97 of file causalFormula_tpl.h.

                                                                                                 :
      _cm(cm), _root(std::move(root)), _on(_toNodeSetFromNames_(cm, on)),
      _doing(_toNodeSetFromNames_(cm, doing)), _knowing(_toNodeSetFromNames_(cm, knowing)),
      _explanation(explanation) {
    _ensureVariablesExist();
    _ensureNoVariablesOverlap();
  }

References _cm, _doing, _ensureNoVariablesOverlap(), _ensureVariablesExist(), _explanation, _knowing, _on, _root, _toNodeSetFromNames_(), cm(), doing(), explanation(), knowing(), on(), and root().

Referenced by CausalFormula(), and CausalFormula().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ CausalFormula() [2/4]

template<GUM_Numeric GUM_SCALAR>

gum::CausalFormula< GUM_SCALAR >::CausalFormula	(	const CausalModel< GUM_SCALAR > &	cm,
		std::unique_ptr< ASTtree< GUM_SCALAR > >	root,
		const NodeSet &	on,
		const NodeSet &	doing,
		const NodeSet &	knowing = NodeSet{},
		std::string_view	explanation = "" )

Constructs a CausalFormula object (variables given by node ids).

Parameters

cm	The causal model against which the formula was identified.
root	The identified formula as an Abstract Syntax Tree (ownership moved).
on	The set of outcome variable ids (the "Y" in P(Y\|...)).
doing	The set of intervention variable ids (the "do(X)")).
knowing	The set of conditioning variable ids (optional evidence).
explanation	A human-readable explanation of the identification method used (optional).

Definition at line 111 of file causalFormula_tpl.h.

                                                                                                 :
      _cm(cm), _root(std::move(root)), _on(on), _doing(doing), _knowing(knowing),
      _explanation(explanation) {
    _ensureVariablesExist();
    _ensureNoVariablesOverlap();
  }

References _cm, _doing, _ensureNoVariablesOverlap(), _ensureVariablesExist(), _explanation, _knowing, _on, _root, cm(), doing(), explanation(), knowing(), on(), and root().

Here is the call graph for this function:

◆ CausalFormula() [3/4]

template<GUM_Numeric GUM_SCALAR>

gum::CausalFormula< GUM_SCALAR >::CausalFormula ( const CausalFormula< GUM_SCALAR > & other )

Copy constructor — performs a deep copy of the AST.

Required so that types containing CausalFormula (e.g. CausalImpact) remain copy-constructible. SWIG's SwigValueWrapper<T> stores the wrapped return value via copy construction, so without this the Windows/MSVC CI fails to compile any binding that returns CausalImpact by value.

Definition at line 124 of file causalFormula_tpl.h.

                                                                       :
      _cm(other._cm), _root(other._root ? other._root->copy() : nullptr), _on(other._on),
      _doing(other._doing), _knowing(other._knowing), _explanation(other._explanation) {}

References CausalFormula(), _cm, _doing, _explanation, _knowing, _on, _root, and copy().

Here is the call graph for this function:

◆ CausalFormula() [4/4]

template<GUM_Numeric GUM_SCALAR>

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

default

Move constructor — defaulted (suppressed by the user-defined copy constructor above).

References CausalFormula(), _ensureNoVariablesOverlap(), _ensureVariablesExist(), _toNodeSetFromNames_(), cm(), doing(), doingNames(), explanation(), knowing(), knowingNames(), on(), onNames(), and root().

Here is the call graph for this function:

Member Function Documentation

◆ _ensureNoVariablesOverlap()

template<GUM_Numeric GUM_SCALAR>

void gum::CausalFormula< GUM_SCALAR >::_ensureNoVariablesOverlap ( ) const

private

Verifies that all variables (_on, _knowing, _doing) have no intersection.

Exceptions

gum::OperationNotAllowed if any variable appears in two roles.

Definition at line 80 of file causalFormula_tpl.h.

                                                                    {
    // Ensure pairwise disjointness: on ∩ doing = ∅, on ∩ knowing = ∅, doing ∩ knowing = ∅
    for (const auto& id: _on) {
      if (_doing.contains(id))
        GUM_ERROR(OperationNotAllowed, "Variable cannot be both in 'on' and 'doing'");
      if (_knowing.contains(id))
        GUM_ERROR(OperationNotAllowed, "Variable cannot be both in 'on' and 'knowing'");
    }
    for (const auto& id: _doing) {
      if (_knowing.contains(id))
        GUM_ERROR(OperationNotAllowed, "Variable cannot be both in 'doing' and 'knowing'");
    }
  }

References _doing, _knowing, _on, and GUM_ERROR.

Referenced by CausalFormula(), CausalFormula(), and CausalFormula().

Here is the caller graph for this function:

◆ _ensureVariablesExist()

template<GUM_Numeric GUM_SCALAR>

void gum::CausalFormula< GUM_SCALAR >::_ensureVariablesExist ( ) const

private

Verifies that all variables (_on, _knowing, _doing) exist in the BN.

Exceptions

gum::NotFound if any variable id is not found.

Definition at line 68 of file causalFormula_tpl.h.

                                                                {
    const auto& bn = _cm.observationalBN();
    // Touch the variable object to ensure validity (throws NotFound if invalid)
    for (const auto& id: _on)
      (void)bn.variable(id);
    for (const auto& id: _doing)
      (void)bn.variable(id);
    for (const auto& id: _knowing)
      (void)bn.variable(id);
  }

References _cm, _doing, _knowing, and _on.

Referenced by CausalFormula(), CausalFormula(), and CausalFormula().

Here is the caller graph for this function:

◆ _toNodeSetFromNames_()

template<GUM_Numeric GUM_SCALAR>

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

staticprivate

Convert a set of names to a set of node ids (validates existence).

Definition at line 57 of file causalFormula_tpl.h.

                                                                                           {
    NodeSet     ids;
    const auto& bn = cm.observationalBN();
    for (const auto& n: names) {
      ids.insert(bn.idFromName(n));   // throws NotFound if unknown
    }
    return ids;
  }

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

Referenced by CausalFormula(), and CausalFormula().

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::CausalFormula< GUM_SCALAR >::cm ( ) const

Definition at line 275 of file causalFormula_tpl.h.

                                                                         {
    return _cm;
  }

References _cm.

Referenced by CausalFormula(), CausalFormula(), CausalFormula(), and _toNodeSetFromNames_().

Here is the caller graph for this function:

◆ copy()

template<GUM_Numeric GUM_SCALAR>

std::unique_ptr< CausalFormula< GUM_SCALAR > > gum::CausalFormula< GUM_SCALAR >::copy ( ) const

Creates a deep copy of the CausalFormula (including its AST).

Definition at line 229 of file causalFormula_tpl.h.

                                                                                       {
    return std::make_unique< CausalFormula< GUM_SCALAR > >(_cm,
                                                           _root->copy(),
                                                           _on,
                                                           _doing,
                                                           _knowing);
  }

References _cm, _doing, _knowing, _on, and _root.

Referenced by CausalFormula().

Here is the caller graph for this function:

◆ doing()

template<GUM_Numeric GUM_SCALAR>

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

Definition at line 285 of file causalFormula_tpl.h.

                                                          {
    return _doing;
  }

References _doing.

Referenced by CausalFormula(), CausalFormula(), and CausalFormula().

Here is the caller graph for this function:

◆ doingNames()

template<GUM_Numeric GUM_SCALAR>

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

Definition at line 251 of file causalFormula_tpl.h.

                                                                       {
    const auto&                bn = _cm.observationalBN();
    std::vector< std::string > out;
    out.reserve(_doing.size());
    for (const auto& id: _doing)
      out.emplace_back(bn.variable(id).name());
    std::sort(out.begin(), out.end());
    return out;
  }

References _cm, and _doing.

Referenced by CausalFormula(), and latexQuery().

Here is the caller graph for this function:

◆ eval()

template<GUM_Numeric GUM_SCALAR>

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

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

Definition at line 143 of file causalFormula_tpl.h.

                                                               {
    if (!_root) {
      GUM_ERROR(gum::OperationNotAllowed,
                "CausalFormula::eval() called on a non-identified formula.");
    }
    return _root->eval(_cm.observationalBN());
  }

References _cm, _root, and GUM_ERROR.

◆ explanation()

template<GUM_Numeric GUM_SCALAR>

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

Definition at line 295 of file causalFormula_tpl.h.

                                                                  {
    return _explanation;
  }

References _explanation.

Referenced by CausalFormula(), CausalFormula(), and CausalFormula().

Here is the caller graph for this function:

◆ isIdentified()

template<GUM_Numeric GUM_SCALAR>

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

noexcept

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 132 of file causalFormula_tpl.h.

                                                                {
    return static_cast< bool >(_root);
  }

References _root.

◆ knowing()

template<GUM_Numeric GUM_SCALAR>

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

Definition at line 290 of file causalFormula_tpl.h.

                                                            {
    return _knowing;
  }

References _knowing.

Referenced by CausalFormula(), CausalFormula(), and CausalFormula().

Here is the caller graph for this function:

◆ knowingNames()

template<GUM_Numeric GUM_SCALAR>

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

Definition at line 262 of file causalFormula_tpl.h.

                                                                         {
    const auto&                bn = _cm.observationalBN();
    std::vector< std::string > out;
    out.reserve(_knowing.size());
    for (const auto& id: _knowing)
      out.emplace_back(bn.variable(id).name());
    std::sort(out.begin(), out.end());
    return out;
  }

References _cm, and _knowing.

Referenced by CausalFormula(), and latexQuery().

Here is the caller graph for this function:

◆ latexQuery()

template<GUM_Numeric GUM_SCALAR>

std::string gum::CausalFormula< 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 181 of file causalFormula_tpl.h.

                                                                                             {
    const auto& bn = _cm.observationalBN();
 
    auto namesSorted = [&](const NodeSet& S) {
      std::vector< std::string > res;
      res.reserve(S.size());
      for (const auto& id: S)
        res.emplace_back(bn.variable(id).name());
      std::sort(res.begin(), res.end());
      return res;
    };
 
    const auto onNames      = namesSorted(_on);
    const auto doingNames   = namesSorted(_doing);
    const auto knowingNames = namesSorted(_knowing);
 
    std::stringstream ss;
    ss << "P\\left(";
 
    for (size_t i = 0; i < onNames.size(); ++i) {
      ss << onNames[i];
      if (i + 1 < onNames.size()) ss << ",";
    }
 
    if (!doingNames.empty() || !knowingNames.empty()) {
      ss << " \\mid ";
 
      if (!doingNames.empty()) {
        ss << doOperatorPrefix << doingNames.front();
        for (size_t i = 1; i < doingNames.size(); ++i)
          ss << "," << doingNames[i];
        ss << doOperatorSuffix;
      }
 
      if (!knowingNames.empty()) {
        if (!doingNames.empty()) ss << ",";
        ss << knowingNames.front();
        for (size_t i = 1; i < knowingNames.size(); ++i)
          ss << "," << knowingNames[i];
      }
    }
 
    ss << "\\right)";
    return ss.str();
  }

References _cm, _doing, _knowing, _on, doingNames(), knowingNames(), and onNames().

Referenced by toLatex().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ on()

template<GUM_Numeric GUM_SCALAR>

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

Definition at line 280 of file causalFormula_tpl.h.

                                                       {
    return _on;
  }

References _on.

Referenced by CausalFormula(), CausalFormula(), and CausalFormula().

Here is the caller graph for this function:

◆ onNames()

template<GUM_Numeric GUM_SCALAR>

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

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

Definition at line 240 of file causalFormula_tpl.h.

                                                                    {
    const auto&                bn = _cm.observationalBN();
    std::vector< std::string > out;
    out.reserve(_on.size());
    for (const auto& id: _on)
      out.emplace_back(bn.variable(id).name());
    std::sort(out.begin(), out.end());
    return out;
  }

References _cm, and _on.

Referenced by CausalFormula(), and latexQuery().

Here is the caller graph for this function:

◆ root()

template<GUM_Numeric GUM_SCALAR>

const ASTtree< GUM_SCALAR > & gum::CausalFormula< 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 137 of file causalFormula_tpl.h.

                                                                       {
    if (!_root) GUM_ERROR(OperationNotAllowed, "No AST: effect not identified.");
    return *_root;
  }

References _root, and GUM_ERROR.

Referenced by CausalFormula(), CausalFormula(), and CausalFormula().

Here is the caller graph for this function:

◆ toLatex()

template<GUM_Numeric GUM_SCALAR>

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

Generates a full LaTeX equation: Query = Formula.

Definition at line 158 of file causalFormula_tpl.h.

                                                                                          {
    if (!_root) return "[unidentifiable]";
 
    // Track variable name occurrences for prime management in AST LaTeX
    HashTable< std::string, int > nameOccur;
 
    const auto& bn       = _cm.observationalBN();
    auto        addNames = [&](const NodeSet& S) {
      for (const auto& id: S) {
        const auto& v    = bn.variable(id);
        const auto& name = v.name();
        if (!nameOccur.exists(name)) nameOccur.insert(name, 1);
      }
    };
    addNames(_on);
    addNames(_doing);
    addNames(_knowing);
 
    return latexQuery(doOperatorPrefix, doOperatorSuffix) + " = " + _root->toLatex(nameOccur);
  }

References _cm, _doing, _knowing, _on, _root, gum::HashTable< Key, Val >::exists(), gum::HashTable< Key, Val >::insert(), and latexQuery().

Here is the call graph for this function:

◆ toString()

template<GUM_Numeric GUM_SCALAR>

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

Generates a string representation of the formula's AST.

Definition at line 152 of file causalFormula_tpl.h.

                                                        {
    if (!_root) return "[unidentifiable]";
    return _root->toString();
  }

References _root.

Member Data Documentation

◆ _cm

template<GUM_Numeric GUM_SCALAR>

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

private

Definition at line 200 of file causalFormula.h.

Referenced by CausalFormula(), CausalFormula(), CausalFormula(), _ensureVariablesExist(), cm(), copy(), doingNames(), eval(), knowingNames(), latexQuery(), onNames(), and toLatex().

◆ _doing

template<GUM_Numeric GUM_SCALAR>

const NodeSet gum::CausalFormula< GUM_SCALAR >::_doing

private

Definition at line 203 of file causalFormula.h.

Referenced by CausalFormula(), CausalFormula(), CausalFormula(), _ensureNoVariablesOverlap(), _ensureVariablesExist(), copy(), doing(), doingNames(), latexQuery(), and toLatex().

◆ _explanation

template<GUM_Numeric GUM_SCALAR>

const std::string gum::CausalFormula< GUM_SCALAR >::_explanation

private

Definition at line 205 of file causalFormula.h.

Referenced by CausalFormula(), CausalFormula(), CausalFormula(), and explanation().

◆ _knowing

template<GUM_Numeric GUM_SCALAR>

const NodeSet gum::CausalFormula< GUM_SCALAR >::_knowing

private

Definition at line 204 of file causalFormula.h.

Referenced by CausalFormula(), CausalFormula(), CausalFormula(), _ensureNoVariablesOverlap(), _ensureVariablesExist(), copy(), knowing(), knowingNames(), latexQuery(), and toLatex().

◆ _on

template<GUM_Numeric GUM_SCALAR>

const NodeSet gum::CausalFormula< GUM_SCALAR >::_on

private

Definition at line 202 of file causalFormula.h.

Referenced by CausalFormula(), CausalFormula(), CausalFormula(), _ensureNoVariablesOverlap(), _ensureVariablesExist(), copy(), latexQuery(), on(), onNames(), and toLatex().

◆ _root

template<GUM_Numeric GUM_SCALAR>

std::unique_ptr< ASTtree< GUM_SCALAR > > gum::CausalFormula< GUM_SCALAR >::_root

private

Definition at line 201 of file causalFormula.h.

Referenced by CausalFormula(), CausalFormula(), CausalFormula(), copy(), eval(), isIdentified(), root(), toLatex(), and toString().

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

agrum/CM/tools/causalFormula.h
agrum/CM/tools/causalFormula_tpl.h

Public Member Functions

Private Member Functions

Static Private Member Functions

Private Attributes

Detailed Description

Constructor & Destructor Documentation

◆ CausalFormula() [1/4]

◆ CausalFormula() [2/4]

◆ CausalFormula() [3/4]

◆ CausalFormula() [4/4]

Member Function Documentation

◆ _ensureNoVariablesOverlap()

◆ _ensureVariablesExist()

◆ _toNodeSetFromNames_()

◆ cm()

◆ copy()

◆ doing()

◆ doingNames()

◆ eval()

◆ explanation()

◆ isIdentified()

◆ knowing()

◆ knowingNames()

◆ latexQuery()

◆ on()

◆ onNames()

◆ root()

◆ toLatex()

◆ toString()

Member Data Documentation

◆ _cm

◆ _doing

◆ _explanation

◆ _knowing

◆ _on

◆ _root